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]
exception CEROIndexConflict[source]
exception EmptyCERO[source]
exception InvalidCERO[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. 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])[source]

Creates pandas.Index object that adheres to CERO constraints.

static create_empty()[source]

Returns empty CERO.

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:

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 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)[source]
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)[source]

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)[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 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)[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, 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)[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 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[source]

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)[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:
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 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[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 of Scenario s.
run() → None[source]

Execute a scenario run.

run_checks(raise_exception=True)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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

@log_func
def func(*args, **kwargs):
    ...
main.run(scenario, **kwargs)[source]
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 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.