Technical Reference¶
This page serves as ‘one place’ to find all technical reference documentation. Other documentation pages provide examples (unlike this page).
-
class
cero.
CERO
[source]¶ -
-
static
combine_ceros
(ceros: list, overwrite=True, verify_cero=True) → pandas.core.frame.DataFrame[source]¶ Combine multiple CEROs (provided as a
list
) into a common CERO. Ifoverwrite
is True, a CERO that is later inceros
(i.e. has a higher index) will overwrite the merger of all preceding CEROs. Ifoverwrite
is False and duplicate indices are detected, anCERO.CEROIndexConflict
exception will be raised.If
verify_cero
isTrue
, then a check is performed before and after combination to ensure that only CEROs are combined with other CEROs, to form a CERO. By disabling this,combine_ceros
can be applied topandas.DataFrames
as well.
-
static
create_cero_index
(values: List[str, tuple])[source]¶ Creates pandas.Index object that adheres to CERO constraints.
-
static
is_cero
(obj, raise_exception=True, empty_ok=True)[source]¶ Parameters: - obj – The object that may or may not be a CERO.
- raise_exception – If True will raise an exception on the event that obj is not a CERO.
- empty_ok – If True,
obj
must have at least one value that is not an NaN to qualify as a CERO. False by default.
Returns:
-
static
read_csv
(csv_file)[source]¶ Reads CEROs that have been exported to csv file. It is assumed that ‘;’ are used to seperate the fields (if more than one) of the identifier.
Parameters: csv_file (str) – Path to the file containing the CERO. Return pandas.DataFrame: The imported CERO.
-
static
read_xlsx
(xlsx_file, *args, **kwargs)[source]¶ Reads CEROs that have been exported to xlsx files.
Parameters: file ((str)) – Name of xlsx file that CERO resides in.
-
static
rename_index_values
(cero: pandas.core.frame.DataFrame, map_dict: dict, inplace: bool = True)[source]¶ Parameters: - cero – The CERO object to rename the index values of. The order of the CERO.index imposes order on the mapping operation - that is, the CERO retains its original order.
- map_dict – A dict of (old name, new name) are (key, value) pairs.
Returns:
-
static
-
class
to_cero.
ToCERO
(conf: dict, *args, parent: dict = None, **kwargs) → pandas.core.frame.DataFrame[source] Loads a ToCERO configuration, suitable for creating CEROs from data files.
Parameters: - conf ('Union[dict,str]') – The configuration dictionary, or a path to a YAML file containing the configuration dictionary. If a path, it must be provided as an absolute path, or relative to the current working directory.
- args – Passed to the superclass (dict) at initialisation.
- kwargs – Passed to the superclass (dict) at initialisation.
-
create_cero
()[source] Create a CERO from the configuration (defined by
self
).Return pd.DataFrame: A CERO is returned.
-
static
is_valid
(conf, raise_exception=True)[source] Performs static validity checks on
conf
as aToCERO
object.Parameters: Return bool: A bool indicating the validity of
conf
as aToCERO
object.
-
static
load_config
(conf, parent: dict = None)[source] Parameters: Return dict: The configuration dictionary (suitable as a ToCERO object).
-
static
run_checks
(conf, raise_exception=True)[source] Performs dynamic validity checks on
conf
as aToCERO
object.Parameters: Return bool: A bool indicating the validity of
conf
as aToCERO
object.
-
class
from_cero.
FromCERO
(conf: dict, *args, parent=None, **kwargs)[source] Any additional arguments and keyword arguments are passed to the superclass at initialisation (i.e. the dict class).
Parameters: - conf ("Union[str,dict]") – A dictionary containing the configuration. If a str is provided, it is interpreted as a file (in YAML format) containing a configuration dictionary (relative to the current working directory).
- parent (dict) – If provided, the created object will inherit from
parent
(a dict).
-
exec_procedures
(cero)[source] Execute all the procedures of the FromCERO object . :param pandas.DataFrame cero: A CERO to serve as input for the procedures. The argument is not mutated/modified.
-
static
is_valid
(conf: dict, raise_exception=True)[source] Performs static checks on
conf
to verify ifconf
can be converted to a FromCERO object.- Checks include:
- Valid type.
- Valid procedures.
- If
file
given, that the user has write permissions in that directory.
Parameters: Return bool: True if
conf
passes all static checks.
-
static
load_config
(conf, parent=None)[source] Loads configuration of FromCERO. If conf is a str, this is interpreted as a file (in YAML format) containing a configuration dictionary (relative to the current working directory). Otherwise conf must be a dictionary.
Parameters: conf ('Union[str,dict]') – Return dict:
-
static
run_checks
(conf: dict, cero: pandas.core.frame.DataFrame, raise_exception=True)[source] Performs runtime checks on
conf
, givencero
.Parameters: Return bool: True if
conf
passes all runtime checks.
-
class
model.
Model
(model: dict, *args, parent: Union[model.Model, NoneType] = None, **kwargs)[source] Parameters: - model – A dict containing
Model
options. - args – Passed to superclass (dict) at initialisation.
- parent ("Model") – If provided, inherits all key-value pairs from
parent
. - kwargs – Passed to superclass (dict) at initialisation.
-
is_valid
(raise_exception=True)[source] Checks the validity of
self
as aModel
object. Method does not ensure runtime issues will not occur. :param bool raise_exception: :return bool: Returns True ifself
is a validModel
.
-
run
(cero) → concero.cero.CERO[source] Executes all data import/export operations (defined by
input_conf
andoutput_conf
respectively) and the execution of any commands.Parameters: cero (pandas.DataFrame) – A CERO that contains all necessary data for conversion to input files (for model execution). Return pandas.DataFrame: A CERO of relevant output data (‘relevant’ is defined by output_conf
).
-
run_checks
(raise_exception=True)[source] Performs runtime checks on
self
to ensure it is a valid Model object. Failure of runtime checks indicates that the model is not ready to run.Parameters: raise_exception (bool) – If True, an exception is raised on check failure (as opposed to returning False). Return bool:
- model – A dict containing
-
class
scenario.
Scenario
(sc_def: dict, *args, parent: dict = None, **kwargs)[source] Parameters: - sc_def – A scenario definition object.
- args – Passed to the superclass (dict) as positional arguments at initialisation.
- kwargs – Passed to the superclass (dict) as keyword arguments at initialisation.
-
get_linked_scenarios
()[source] Return “List[‘ScenariosSet’]”: A list of linked ScenariosSet
.
-
get_name
(long_form: bool = True, raise_exception=False) → str[source] Returns the name of the
Scenario
, which is dependent on the first linkedScenariosSet
object. :param long_form: IfTrue
(default) return a long-form of the name. IfFalse
, return a short form. :return: The name of theScenario
.
-
is_valid
(raise_exception=True) → bool[source] Performs static checks on
self
to ensure it is a valid Scenario object.
-
static
load_scenario
(scen_def: str, parent=None)[source] Parameters: scen_def – The file containing a single scenario definition, or a scenario definition dict . Return ‘Scenario’: A single Scenario
object.
-
static
load_scenarios
(scen_def: str, parent=None)[source] Load one or more scenarios from a file.
Parameters: scen_def – The file containing one or more scenario definitions. Return “Union[‘Scenario’,List[‘Scenario’]]”: Either a single Scenario
, or a list ofScenario
s.
-
run
() → None[source] Execute a scenario run.
-
libfuncs_wrappers.
dataframe_op
(func)[source]¶ This decorator is designed to provide
func
(the encapsulated function) with a restricted form ofdf
(a CERO). A restricteddf
is the originaldf
limited to a subset of rows and/or columns. Note that a restriction ondf.columns
will be compact (the mathematical property), but this is not necessarily the case for restriction ondf.index
.
-
libfuncs_wrappers.
series_op
(func)[source]¶ This decorator provides
func
(the encapsulated function) with the firstpandas.Series
in apandas.DataFrame
(i.e. the first row indf
). Note that this wrapper is encapsulated within thedataframe_op
wrapper.
-
libfuncs_wrappers.
recursive_op
(func)[source]¶ Applies the encapsulated function (
func
) iteratively to the elements ofarray
from left to right, withinit
prepended toarray
andpost
postpended.
-
libfuncs_wrappers.
log_func
(func)[source]¶ Logging decorator - for debugging purposes. To apply to function
func
:@log_func def func(*args, **kwargs): ...
-
modfuncs.
replace_file_in_zip
(new_file: str, *old_file, tmp_dir: str = 'tmp_zipfile') → str[source]¶ Replaces a file in a zip archive with a
new_file
.Parameters: - new_file (str) – The file to add to the archive.
- old_file ("List[str]") – Arguments, in order, that identify the old file. For example, if the file to be replaced is
a_file.txt
in the foldera_folder
in the zip archivea_zip.zip
, then the function signature isreplace_file_in_zip("new_file.txt", "a_zip.zip", "a_folder", "a_file.txt")
. - tmp_dir (str) – The directory in which the contents of the zip file are temporarily extracted to.
Return str: The new zip file.