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

exception CEROIndexConflict

exception EmptyCERO

exception InvalidCERO

static combine_ceros(ceros: list, overwrite=True, verify_cero=True) → pandas.core.frame.DataFrame

Combine multiple CEROs (provided as a list) into a common CERO. If overwrite is True, a CERO that is later in ceros (i.e. has a higher index) will overwrite the merger of all preceding CEROs. If overwrite is False and duplicate indices are detected, an CERO.CEROIndexConflict exception will be raised.

If verify_cero is True, 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 to pandas.DataFrames as well.

static create_cero_index(values: List[str, tuple])

Creates pandas.Index object that adheres to CERO constraints.

static create_empty()

Returns empty CERO.

static is_cero(obj, raise_exception=True, empty_ok=True)

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)

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)

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)

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:

class to_cero.ToCERO(conf: dict, *args, parent: dict = None, **kwargs) → pandas.core.frame.DataFrame

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()

Create a CERO from the configuration (defined by self).

Return pd.DataFrame:  A CERO is returned.

static is_valid(conf, raise_exception=True)

Performs static validity checks on conf as a ToCERO object.

Parameters:

• conf (dict) – An object, which may or may not suitable as a ToCERO object.
• raise_exception (bool) – If True (the default) an exception will be raised in the event a test is failed. Otherwise (in this event) an error message is printed to stdout and False is returned.

Return bool:

A bool indicating the validity of conf as a ToCERO object.

static load_config(conf, parent: dict = None)

Parameters:

• conf ('Union[dict,str]') – A configuration dictionary, or a str to a path containing a configuration dictionary.
• parent (dict) – A dict from which to inherit.

Return dict:

The configuration dictionary (suitable as a ToCERO object).

static run_checks(conf, raise_exception=True)

Performs dynamic validity checks on conf as a ToCERO object.

Parameters:

• conf (dict) – An object, which may or may not suitable as a ToCERO object.
• raise_exception (bool) – If True (the default) an exception will be raised in the event a test is failed. Otherwise (in this event) an error message is printed to stdout and False is returned.

Return bool:

A bool indicating the validity of conf as a ToCERO object.

class from_cero.FromCERO(conf: dict, *args, parent=None, **kwargs)

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)

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)

Performs static checks on conf to verify if conf 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:

• conf (dict) – The object to check the validity of.
• raise_exception (bool) – If True (the default) then an exception will be raised on failure. Otherwise an error message will be printed to stdout and False returned.

Return bool:

True if conf passes all static checks.

static load_config(conf, parent=None)

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)

Performs runtime checks on conf, given cero.

Parameters:

• conf (dict) – The object to check the validity of.
• raise_exception (bool) – If True (the default) then an exception will be raised on failure. Otherwise an error message will be printed to stdout and False returned.

Return bool:

True if conf passes all runtime checks.

class model.Model(model: dict, *args, parent: Union[model.Model, NoneType] = None, **kwargs)

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)

Checks the validity of self as a Model object. Method does not ensure runtime issues will not occur. :param bool raise_exception: :return bool: Returns True if self is a valid Model.

run(cero) → concero.cero.CERO

Executes all data import/export operations (defined by input_conf and output_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)

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:

class scenario.Scenario(sc_def: dict, *args, parent: dict = None, **kwargs)

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()

Return “List[‘ScenariosSet’]”:  A list of linked ScenariosSet.

get_name(long_form: bool = True, raise_exception=False) → str

Returns the name of the Scenario, which is dependent on the first linked ScenariosSet object. :param long_form: If True (default) return a long-form of the name. If False, return a short form. :return: The name of the Scenario.

is_valid(raise_exception=True) → bool

Performs static checks on self to ensure it is a valid Scenario object.

static load_scenario(scen_def: str, parent=None)

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)

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 of Scenario s.

run() → None

Execute a scenario run.

run_checks(raise_exception=True)

Performs runtime checks on self to ensure it is a valid Scenario object. Failure of runtime checks indicates that the scenario is not ready to run.

Parameters:raise_exception (bool) – Returns:

libfuncs_wrappers.dataframe_op(func)

This decorator is designed to provide func (the encapsulated function) with a restricted form of df (a CERO). A restricted df is the original df limited to a subset of rows and/or columns. Note that a restriction on df.columns will be compact (the mathematical property), but this is not necessarily the case for restriction on df.index.

libfuncs_wrappers.series_op(func)

This decorator provides func (the encapsulated function) with the first pandas.Series in a pandas.DataFrame (i.e. the first row in df). Note that this wrapper is encapsulated within the dataframe_op wrapper.

libfuncs_wrappers.recursive_op(func)

Applies the encapsulated function (func) iteratively to the elements of array from left to right, with init prepended to array and post postpended.

libfuncs_wrappers.log_func(func)

Logging decorator - for debugging purposes. To apply to function func:

@log_func
def func(*args, **kwargs):
    ...

main.run(scenario, **kwargs)

modfuncs.replace_file_in_zip(new_file: str, *old_file, tmp_dir: str = 'tmp_zipfile') → str

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 folder a_folder in the zip archive a_zip.zip, then the function signature is replace_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.