create import set - openmpp/openmpp.github.io GitHub Wiki
Home > Model Development Topics > Create Import Set
This topic contains detailed information on the OpenM++ create_import_set utility. create_import_set creates a zip file suitable for upload to a downstream model, using results from an upstream model.
- Introduction and overview
- Windows Quick start
- Linux or MacOS Quick start
- Arguments and Options
- Worked Example: Creating an OncoSim parameter set from an HPVMM model run
- Technical Requirements: Technical information for model developers
Users familiar with linked models may wish to jump directly to the Worked Example subtopic.
A downstream model can use, as input, the output from a different upstream model. By specializing functionality in two models rather than one, a two-model design can enable analyses which would otherwise be infeasible. In particular, a time-based (interacting population) model can simulate a large population of simplified entities and feed statistical results downstream to a case-based model with more complex entities and events to simulate downstream consequences. For example, an upstream model of an infectious disease can simulate the effects of vaccination and herd immunity using an interacting population of entities to project incidence of infection over time in response to a given vaccination roll-out. That upstream model can feed aggregate results on incidence of infection over time to a more detailed downstream model with a non-interacting population to simulate health consequences, treatment, and costs.
In such a two-model design, the downstream model has input parameters whose values can be supplied by corresponding output tables from an upstream model.
The pairing of output tables from the upstream model to the corresponding input parameters of the downstream model is specified by import statements in the source code of the downstream model. For example, the import statement
import IncidenceRatesHPV (HPVMM.IM_Incidence) sample_dimension=on;
in a downstream model (in this example, a model named OncoSim) specifies that the input parameter IncidenceRatesHPV of OncoSim can be provided by the output table IM_Incidence of the upstream model HPVMM.
Multiple output tables from an upstream model can supply values to multiple parameters in the downstream model, with each such linkage specified by an import statement in the downstream model source code. For logical coherence, every such linked table from the same run of the upstream model needs to be used as input in the corresponding parameter in the downstream model. For example, the upstream model HPVMM supplies 11 output tables which match 11 input parameters in the downstream model OncoSim. It is essential that each of the 11 output tables from the same HPVMM run be copied to the corresponding input parameter for an OncoSim run.
The create_import_set utility supports the propagation of results from an upstream model to a downstream model by building a partial parameter set for the downstream model from a run of the upstream model. A user 1) downloads a run from the upstream model to their workstation, 2) runs the create_import_set utility, and finally 3) uploads the resulting set for use by the downstream model. Once uploaded, the set can be used to construct one or more scenarios for the downstream model.
A Windows executable version of create_import_set is distributed with OpenM++ at OM_ROOT/bin/create_import_set.exe, where OM_ROOT stands for the OpenM++ installation directory.
To test installation and operation of create_import_set, open a command prompt, change the current directory to OM_ROOT/bin, and type the command
create_import_set -v
Output should be similar to the following:
create_import_set version 1.0
create_import_set is written in the Perl language, and distributed with OpenM++ at OM_ROOT/Perl/create_import_set.pl. Examples in this topic may invoke test_models using the Perl interpreter from the OM_ROOT/Perl directory, for example
perl create_import_set.pl -v
On Windows, unless you have Perl and the required Perl components installed, invoke the executable version of create_import_set from the OM_ROOT/bin directory with a command like
create_import_set -v
create_import_set is a Perl script distributed with OpenM++ at OM_ROOT/Perl/create_import_set.pl, where OM_ROOT stands for the OpenM++ installation directory.
To test installation and operation of create_import_set, open a command prompt, change the current directory to OM_ROOT\Perl, and type the command
perl create_import_set.pl -v
Output should be similar to the following:
create_import_set version 1.0
Depending on your operating system version and installation history, Perl may ask you to install missing Perl modules required by create_import_set.pl.
If so, it will name them explicitly when you invoke create_import_set.pl.
We do recommend to use cpanm for Perl modules installation. Typical scenario is:
cpan App::cpanminus # initialize cpanm, if not done before
cpanm Getopt::Long::Descriptive
cpanm Capture::Tiny
cpanm Config::Tiny
cpanm File::Copy::Recursive
cpanm File::Which
Above list of modules can be different and depends on your current Perl configuration, and on the version of create_import_set.
This subtopic describes the command line options and arguments of create_import_set.
A complete list of options is displayed by issuing the command
perl create_import_set.pl -h
Output should be similar to the following:
create_import_set [-dhiruvw] [long options...]
-h --help print usage message and exit
-v --version print version and exit
-i STR --imports STR path of model imports csv file
-u STR --upstream STR name of upstream model
-r STR --run STR name of upstream model run
-d STR --downstream STR name of downstream model
-w STR --workdir STR path of working directory for zips
(default is current directory)
--keep keep and propagate all subs
--verbose verbose log output
A value is required for the following arguments:
- -i imports file: The model imports csv file for the downstream model
- -u upstream model name: The name of the upstream model
- -r upstream run name: The name of the upstream model run
- -d downstream model name: The name of the downstream model
Each of these 4 arguments is described below. Or jump to the Worked Example for a concrete illustration.
The -w argument is optional. It specifies the directory where the input zip downloaded from the upstream model run is found. It is also the directory where the output zip for the downstream model will be constructed. By default, the working directory is the current working directory of the terminal session in which create_import_set is invoked.
The --keep option is an experimental option intended for linked models which use OpenM++ architecture for parameter uncertainty. It is not compatible with linked models in Modgen.
The --verbose option outputs detailed diagnostics of no interest to an end user.
The model imports csv file contains information about the pairing of tables in an upstream model with the parameters in a downstream model. It has a name of the form MODEL.imports.csv where MODEL is the name of the downstream model. This file contains all import information for the downstream model, which might include imports from multiple upstream models. For example, a downstream model OncoSimX might import parameters from an upstream model HPVMM as well as an upstream model GMM. The downstream model developer can provide a copy of this file. The file is generated by the OpenM++ compiler when the downstream model is built. It is located in the output src directory in the model build directory structure.
[back to arguments and options]
[back to topic contents]
A downstream model can be linked to more than one upstream model. The -u option specifies which upstream model is to be used by create_import_set to create the parameter set for the downstream model. Valid model names are in a column of the model imports csv file and come from the source code of the downstream model.
[back to arguments and options]
[back to topic contents]
The tables from an upstream model run are in a zip file downloaded previously using the OpenM++ UI. The name of that zip file is constructed automatically from the model name and run name when the run is downloaded, for example HPVMM.run.DefaultVaccination.zip for a run named DefaultVaccination of the HPVMM model.
[back to arguments and options]
[back to topic contents]
The name of the downstream model is required and must match the name of a model in the target OpenM++ database. create_import_set will construct a partial parameter set ready for upload using this name and the name of the upstream model run, for example OncoSimX.set.DefaultVaccination.zip for -d OncoSimX. Note that the partial parameter set for the downstream model has the same name as the upstream model run, DefaultVaccination in this example.
[back to arguments and options]
[back to topic contents]
This worked example, in Windows, uses an upstream model named HPVMM and a downstream model named OncoSimX. Note that these models are not distributed with OpenM++. The example assumes a remote server houses an instance of the upstream and downstream models, but works equally well for models on a workstation. This example could also have been done without the OpenM++ UI by using the dbcopy utility.
Step 0a: Create a staging directory on your workstation to manage downloaded runs and construct parameter sets for upload, for example C:\Analysis\runs.
Step 0b: Get a copy of the create_import_set utility on your workstation. For Windows users, a stand-alone executable version can be found in the OpenM++ distribution in the bin sub-folder. The Perl version is located in the perl sub-folder. If you use OpenM++ on your desktop for model development, you can invoke the utility using the environment variable OM_ROOT, e.g. %OM_ROOT%\bin\create_import_set. If you do not use OpenM++ for development, you may find it more convenient to just copy the utility executable to your staging directory.
Step 0c: Copy the imports file for the downstream model to the staging directory. In this example, the imports file for OncoSimX is named OncoSimX.imports.csv. The file is generated by the OpenM++ compiler in a model build folder named OncoSimX\ompp\src. Ask the model developer for a copy of this file if you don't build the model yourself.
Step 1: Do a run of the upstream model (HPVMM in this example), and give it a short but meaningful name. In this example, the run is named DefaultVaccination.
Step 2: In the UI, make sure that the option Full, compatible with desktop model is checked in the Model Downloads section of the options panel.
Step 3: In the UI, select the run and click the download button. Wait for the server to construct the download zip for the run, then click it to download it to the downloads folder on your workstation. In this example, the file is named HPVMM.run.DefaultVaccination.zip. Copy or move the file to the staging directory.
Step 4: Open a command prompt and navigate to the staging directory in the terminal window.
Step 5: Issue the command
create_import_set -i OncoSimX.imports.csv -u HPVMM -d OncoSimX -r DefaultVaccination
The arguments name the upstream model with -u, the downstream model with -d, the name of the upstream run with -r, and specify the imports file OncoSimX.imports.csv which create_import_set uses to identify and transform each imported upstream table to the corresponding downstream parameter. create_input_set uses the arguments to construct the names of the input and output zip files.
The utility may take 10 or more seconds to run. When it completes, it writes something like the following to the terminal window to indicate success.
11 downstream OncoSimX parameters created from upstream HPVMM tables
If you examine the staging directory, you'll notice a new file named OncoSimX.set.DefaultVaccination.zip. It contains the 11 OncoSimX parameters with values from the 11 corresponding HPVMM tables in the HPVMM run named DefaultVaccination.
Step 6: Use the UI to upload the set to the server.
The set is uploaded as a read-only partial scenario. You can use the UI to combine it with a previous OncoSim run or scenario to incorporate the results of the HPVMM DefaultVaccination run.
To make clear the provenance of downstream parameters, create_import_set generates, for each imported parameter, a parameter value description indicating the upstream model name and run name, e.g. HPVMM: DefaultVaccination. That description will follow each generated parameter value in any downstream OncoSimX run which uses, directly or indirectly, the partial parameter set generated by create_import_set.
The following restrictions apply:
The input run zip must contain only a single run.
The classification levels in each parameter / table pair must match, for each dimension.
The upstream table dimensions must be named Dim0, Dim1, ...
Each imported table can contain only a single measure named Value.
The downstream target parameter dimensions must be named Dim0, Dim1, ...
For robustness, provide explicit names to dimensions in the upstream and downstream models to respect the name requirements. For example, the upstream model could have a source code module ExplicitNames.ompp with content like:
// Table IM_ClearanceHazard: Inter-model: Clearance hazard
//NAME IM_ClearanceHazard.Dim0 Dim0
//NAME IM_ClearanceHazard.Dim1 Dim1
//NAME IM_ClearanceHazard.VALUE Value
// Table IM_PersistentProportion: Inter-model: Persistent proportion
//NAME IM_PersistentProportion.Dim0 Dim0
//NAME IM_PersistentProportion.VALUE Value
// Table IM_Incidence: Inter-model: Incidence
//NAME IM_Incidence.Dim0 Dim0
//NAME IM_Incidence.Dim1 Dim1
//NAME IM_Incidence.Dim2 Dim2
//NAME IM_Incidence.Dim3 Dim3
//NAME IM_Incidence.Dim4 Dim4
//NAME IM_Incidence.Dim5 Dim5
//NAME IM_Incidence.VALUE Valueand the downstream model could have a source code module named ExplicitNames.ompp with content like:
// Parameter HpvClearanceHazard: HPV infection clearance rates
// from HPVMM Table IM_ClearanceHazard: Inter-model: Clearance hazard
// leading dimension Dim0 is parameter set
//NAME HpvClearanceHazard.Dim0 Dim0
//NAME HpvClearanceHazard.Dim1 Dim1
//NAME HpvClearanceHazard.Dim2 Dim2
// Parameter HpvPersistentProportion: Proportion who cannot naturally clear HPV infection
// from HPVMM Table IM_PersistentProportion: Inter-model: Persistent proportion
// leading dimension Dim0 is parameter set
//NAME HpvPersistentProportion.Dim0 Dim0
//NAME HpvPersistentProportion.Dim1 Dim1
// Parameter IncidenceRatesHPV: Incidence rates of HPV
// from HPVMM Table IM_Incidence: Inter-model: Incidence
// leading dimension Dim0 is parameter set
//NAME IncidenceRatesHPV.Dim0 Dim0
//NAME IncidenceRatesHPV.Dim1 Dim1
//NAME IncidenceRatesHPV.Dim2 Dim2
//NAME IncidenceRatesHPV.Dim3 Dim3
//NAME IncidenceRatesHPV.Dim4 Dim4
//NAME IncidenceRatesHPV.Dim5 Dim5
//NAME IncidenceRatesHPV.Dim6 Dim6