Command Line Interface (CLI)

Introduction

The MCRA core library comes with a command line interface (CLI) utility to run MCRA actions using input files and producing output files. Data files and specification of sequences of modules and settings are supplied in an action template. An action template is a local disk folder with a defined structure which is described in Action template structure. A new empty action template can be created by the CLI as demonstrated in Create a new action template. Alternatively, the template can also be a compressed (zip) file format. Running an action via the CLI is described in Run an action. This generates results in local disk output files that can be accessed via, for instance, a web browser as described in Action template structure.

The latest release of the CLI utility of MCRA Core is available as a download from GitHub (https://github.com/rivm-syso/mcra-core/releases) or can be built from the sources.

Action template structure

The CLI can process either folders or zip files as input. This paragraph explains the structure of the files and subfolders inside the input folder or zip file which the CLI needs to run an MCRA action correctly. This structure is the same for both the contents of a zip file and the contents of a folder. The term base folder will be used to refer to either the zip file or the folder containing the settings and data of the action. The base folder must contain the following XML files:

  • _ActionData.xml: contains the configuration of the input data for the action

  • _ActionSettings.xml: contains the configuration for the action

The data for the action may be included as CSV files containing MCRA table data directly in the base folder together with the settings files. In this case the _ActionData.xml file is optional. The other option is to put the input data files in a subfolder named Data. In this case the following file formats are accepted:

  • Excel files: files with an XLS or XLSX extension;

  • Access files: files with an ACCDB or MDB extension;

  • Zipped CSV: zip files containing the MCRA data in one CSV file per table.

The files mentioned above must adhere to the data formats of MCRA available in the documentation.

Action settings XML file structure

The model settings XML file must be named ‘_ActionSettings.xml’ (with a leading underscore ‘_’ character). A simple example, configuring a ‘Foods’ action, is:

<Project>
  <Name>ExampleFoodsAction</Name>
  <ActionType>Foods</ActionType>
</Project>

The Project tag is the root element of the XML file; it is named Project for historic reasons. This configuration file is an example of a minimalistic configuration in which all other settings have been omitted. By using the Create a new action template option, a configuration file will be automatically generated that contains all possible options for the action.

Data configuration

As mentioned before, MCRA accepts Excel, Access and zipped CSV data files as input when they are included in the Data subfolder. For simple actions there is also the option to include CSV files directly in the root of the folder or zip file. In this case the folder or zip file itself becomes the single input file for the action. The next section lists all possible options. Data for running an action with the CLI is accepted in the following ways: 1. As CSV (comma separated values) files directly in the root of the folder or zip file. In this case, the zip file or folder is itself the single data file, containing the MCRA tables. A data configuration XML file is optional, but it can still be used to filter the table groups that are loaded during the run. 2. A Data subfolder containing one or more of the accepted MCRA file types. In this case a data configuration XML file is necessary to link the MCRA table groups and data files to use.

Data configuration XML file structure

The data configuration XML file must be named _ActionData.xml (with the leading underscore ‘_’ character) and must be placed in the root of the zip file or folder. It describes the links between the modules and data. The link is made based on a so-called MCRA table group definition. A data file can contain data for one or more table groups. An example of a simple data configuration file is as follows:

<DataSourceConfiguration xmlns:xsd=http://www.w3.org/2001/XMLSchema
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <DataSourceMappingRecords>
    <DataSourceMappingRecord>
      <SourceTableGroup>Foods</SourceTableGroup>
      <Name>InputData.xls</Name>
    </DataSourceMappingRecord>
    <DataSourceMappingRecord>
      <SourceTableGroup>Compounds</SourceTableGroup>
      <Name>InputData.xls</Name>
    </DataSourceMappingRecord>
    <DataSourceMappingRecord>
      <SourceTableGroup>Survey</SourceTableGroup>
      <Name>Consumptions.mdb</Name>
    </DataSourceMappingRecord>
    <DataSourceMappingRecord>
      <SourceTableGroup>FoodConsumptions</SourceTableGroup>
      <Name>Consumptions.mdb</Name>
    </DataSourceMappingRecord>
  </DataSourceMappingRecords>
</DataSourceConfiguration>

The data source configuration contains one collection of DataSourceMappingRecords. Each DataSourceMappingRecord must contain at least the SourceTableGroup. The Name element refers to the file name in the Data subfolder when data files are used. If the zip file or folder contains CSV table files in the root itself, the name is optional. In this case the name of the zip file itself is used.

Create a new action template

The CLI can generate an empty action template for any type of action that is supported by MCRA. This generated template consists of the correct files and folder structure for the action, with all default settings, and Excel data files with empty tables as a starting point to fill in your own input data.

Use the following command to create a new action of a given type:

mcra.exe create '<name_of_new_action>' -a <action type>

where the option -a specifies the type of action to be created. For example, to create a basic skeleton for analysing your own single value risk estimate with the name MySingleValueRisk, run the command,

mcra.exe create MySingleValueRisk  -a SingleValueRisk

The name of the action type, SingleValueRisk in the example above, is a reserved keyword and must match with one of the supported action types. To get a list of all supported action types, run the command,

mcra.exe create -u

This will print out a list of reserved names of all action types. After creating this template, you can start filling in the input data in the Excel files and adjusting the calculation settings in the _ActionSettings.xml file.

Run an action

The most basic use of the CLI is to specify a folder name or a zip file containing the settings and data for the action that you want to run (see section Action template structure for a detailed description). In a terminal window. e.g. PowerShell or the command prompt, run the command:

mcra.exe run '<path to action folder>' [options]
or:
mcra.exe run '<name_of_action>.zip' [options]

As an example, assume that an action folder has been composed for doing a calculation on the retrospective Tier 2 of cumulative exposure to pesticides. This model can be run by the command:

mcra.exe run 'EU acute cumulative exposure assessment (2018) Tier 2'

The name of the action in this example is equal to the name of the folder that contains the data and settings as input for the CLI, so in this example there is a folder with the name ‘EU acute cumulative exposure assessment (2018) Tier 2’. To get an overview of the available options for running the command line interface, run the following command:

mcra.exe help run

The output of this command lists the options for the run command as shown below (exact details maybe different, depending on the version of the CLI utility).

Table 384 command-line parameters for running an action

Parameter

Description

task input name

(pos. 0, required) Name of the input zip file or base folder containing the simulation task to be processed.

-o, --output

Base folder for output. Project output will be written to a subfolder, using the project name.

--overwrite

(Default: false) Overwrite existing output. If set to false, the output will be written to a uniquely named folder, otherwise the project name is used as output folder

--skipreport

(Default: false) Don’t render the full output report.

--skiptables

(Default: false) Don’t generate CSV output tables.

--skipcharts

(Default: false) Don’t generate SVG charts.

--keeptempfiles

(Default: false) Keep temporary (intermediate) files.

-r, --randomseed

Use this value as the Monte Carlo random seed for the project.

-i, --interactive

(Default: false) Set to true to run in interactive mode.

-s, --silent

(Default: false) Set to true to run in silent mode.

--dbType

(Default: Csv) Database type. Possible options: - csv: Intermediate data will be written to CSV files during the run

--help

Display this help screen.

--version

Display version information.

Output

By default the CLI utility creates the output files in a subfolder in the location where the CLI command is run, use the ‘--output’ command line option to specify a different output folder.

Output files and folder structure

The output of an action performed with the CLI is saved to a folder, which by default has the name of the action suffixed with date and time to create a unique folder name. The output of the action consists of metadata, data and image (chart) files. The CLI options ‘--skipreport’, ‘--skiptables’ and/or ‘--skipcharts’ are available to limit the output if desired. The contents of the output folder are as follows.

Table 385 Output file and folders of an action run

File

Description

Metadata files

_CsvFileIndex.txt

Tab delimited text file containing lookup data for the output CSV data files. It contains the name of the file and the path to the file in the full MCRA output.

_MCRAVersion.txt

Contains detailed MCRA version information of the CLI that was used.

_TOC.txt

Contains a detailed internal table of contents of references to report sections.

_TOC-Charts.txt

Contains a detailed table of contents of the output charts (if any).

_TOC-CsvData.txt

Contains a detailed table of contents of the output CSV files.

_TOC-XmlData.txt

Contains a detailed table of contents of any output data in XML format.

ProjectOriginalSettings.xml

A copy of the original action settings file (_ActionSettings.xml)

ProjectSimulatedSettings.xml

A fully populated XML file containing all settings that were used in the run. This includes the defaults of all other settings that are available in MCRA.

Data files

FoodsTable.csv

Foods output data table

SubstancesTable.csv

Substances output data table

Reports

_Report.html

The MCRA report in HTML format. This report contains all output sections with tables and charts in one page.

Tables/charts

The tables and charts in the HTML file are included in this folder and are referenced from the HTML file.