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¶

  1. Download and extract the archive containing the source files

  2. From the command line, change into the source file directory:

    cd DIR
    
  3. Install 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.

  1. Create the import file import_data.yaml, to import the file import_data.csv:

    files:
       - file: import_data.csv
    

    Note 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.

  2. Create the export file data_export.yaml, to export to the file xslx_file.xlsx:

    procedures:
       - file: export_data.xlsx
    

    The definition of files/data to be imported and exported is now complete. To create export_data.xlsx:

  3. 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.

  1. First, we create the scenario definition file, "example_scenario.yaml":

    models:
        - cmds: python model.py
    
  2. Then, 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:

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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:

  1. YAML files that define Scenario s.
  2. YAML files that define the conversion of data to a CERO.
  3. 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 --help
    
  • Run the ConCERO scenario defined in scenario.yaml:

    concero run scenario.yaml
    
  • Perform 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.yaml
    

    Note 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_concero
    

    NOTE: 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 DIR
    
  • Check version of your python interpreter:

    python --version
    

Table Of Contents

  • Quickstart: Common ConCERO-Related Commands
    • Installing ConCERO
    • Example: Import a CSV file, export an XLSX file
    • Example: Run a Model
    • Example: Combining data import/export with model execution
    • Other Commands

Related Topics

  • Documentation overview
    • Previous: Technical Reference
    • Next: ConCERO’s Design Philosophy

This Page

  • Show Source

Quick search

©2018, CSIRO. | Powered by Sphinx 1.7.5 & Alabaster 0.7.9 | Page source