Quickstart: Common ConCERO-Related Commands¶
This page serves to present the most simple case of downloading, installing and using ConCERO. It is assumed that your python interpreter is version 3.5 or above (see Other Commands to identify your python version).
Installing ConCERO¶
Download and extract the archive containing the source files
From the command line, change into the source file directory:
cd DIRInstall ConCERO (which may require administrator privileges):
python setup.py install
Example: Import a CSV file, export an XLSX file¶
Note that this example assumes the CSV is in the default format - one header row labelling the years the data refers to, the first column names the data, with all following columns containing floating-point (or integer) numbers (corresponding to each year labelled in the header). More complex files (for example, HAR files) require more specification - please see Converting TO the Collins Economics Result Object (CERO) format and Converting FROM the Collins Economics Result Object (CERO) format for a complete outline.
Create the import file
import_data.yaml
, to import the fileimport_data.csv
:files: - file: import_data.csvNote that correct indentation, and the use of spaces for indentation, is critical. The file must be in YAML format - a very simple and easy to understand format. See Converting TO the Collins Economics Result Object (CERO) format for more information about the YAML format and links to resources.
Create the export file
data_export.yaml
, to export to the filexslx_file.xlsx
:procedures: - file: export_data.xlsxThe definition of files/data to be imported and exported is now complete. To create
export_data.xlsx
:Then run the command (from the comand line):
concero convert import_data.yaml export_data.yaml
In the working directory, you will find that export_data.xlsx
has been created.
Example: Run a Model¶
Anything that can be run from the command line can be run by ConCERO. Let’s assume a model model.py
is a python code defining the model we want to run.
First, we create the scenario definition file,
"example_scenario.yaml"
:models: - cmds: python model.pyThen, from the command line:
concero run example_scenario.yaml
Alternatively (to step 2), running the scenario could be accomplished in the python interpreter by executing the code:
import concero s = concero.Scenario.load_scenario("example_scenario.yaml") # Loads the scenario from file s.run() # run the scenario
Example: Combining data import/export with model execution¶
For this example - which builds on the previous 2 examples - let’s consider that model.py
requires export_data.xlsx
to run successfully, and that file needs to be created from import_data.csv
(as per the first example). Let’s also assume that model.py
will generate interesting_data.xlsx
and that we wish to plot that data after the scenario has executed. ConCERO handles this operation by converting interesting_data.xlsx
to a CERO and then combining that CERO with the CERO already stored in memory (which was created from import_data.csv
using import_data.yaml
). The combined CERO then replaces the CERO stored in memory. Plots can then be generated by using the relevant data from the updated CERO (in an identical process to the import/export example).
Let’s assume that model_output.yaml
defines the import of interesting_data.xlsx
and scenario_output.yaml
defines the creation of interesting plots (and any other files we want to generate). We can change example_scenario.yaml
(the YAML file created in the last example) to look like:
input_conf: import_data.yaml models: - input_conf: data_export.yaml cmds: python model.py output_conf: model_output.yaml output_conf: scenario_output.yaml
And the scenario run from the command line with:
concero run example_scenario.yaml
This file defines the process:
- Any input data that you (the user of ConCERO) wishes to convert (so to provide models with input data) is imported and kept in an object referred to as a CERO. The line in the scenario definition,
input_conf: import_data.yaml
, defines the file containing the import definition.- Data for the first model is exported by converting the relevant parts of the CERO into the appropriate files. The line in the model definition,
input_conf: data_export.yaml
, defines the file containing the export definition.- Any data generated from the first model for which subsequent models require as input data must be imported (and stored in memory as a CERO). The model definition line
output_conf: model_output.yaml
defines the file containing the import definition.- The previous 2 steps are repeated for any subsequent models that you wish to execute. If this was the case, additional model definitions would follow underneath the definition for the first model.
- Finally, any data stored in memory (as a CERO) that is of interest to the user is exported into files. The line
output_conf: scenario_output.yaml
defines the file containing the export definition.
It should hopefully be clear to the reader that there are 3 types of YAML files necessary to use the full functionality of ConCERO:
- YAML files that define
Scenario
s.- YAML files that define the conversion of data to a CERO.
- YAML files that define the conversion of data from a CERO.
Other Commands¶
Note the for this example, the parent directory is chosen as the directory to run the tests. In practice, this could be any directory. Whatever directory is chosen, you must have write permissions.
Find help on how to use the ConCERO program:
concero --helpRun the ConCERO scenario defined in
scenario.yaml
:concero run scenario.yamlPerform a fake-run of the scenario defined in scenario.yaml (useful to check if there has not any ‘obvious’ errors with configuration files) …
concero run --fake_run scenario.yamlNote that no runtime checks are performed (because successful operation may rely on the creation of some files that do not currently exist).
Test installation has been successful by running tests:
cd .. python -m concero.tests.test_conceroNOTE: You will need write permissions to the current working directory. As long as their are no failures, then ConCERO has been installed correctly.
Clone the source directory into
DIR
using git:git clone https://github.com/charlie0389/ConCERO DIRCheck version of your python interpreter:
python --version