Running a model in a command line workflow

Requires Analytica 6.0 or later.

This page details how you can launch an Analytica model from a command line or batch file for the purpose of having it automatically run your model and exit, for example as part of an automated computational pipeline.

Use case example

You have an R program that outputs data files that serve as input to your Analytica model.
Your Analytica model reads and processes these, and writes some output files.
Those output files are then used as input to a Python program that does some final calculations and transmits the final results

You want to automate this computational workflow so that in Step 2, Analytica launches, processes the data, and exits automatically without human intervention.

When to use

In general, it works best to use the Analytica Decision Engine (ADE) for programmatic automation. ADE runs as a component without a graphical user interface, and provides a rich API for flexible transfer of input and output data and full control over calculations and all other aspects of the engine. ADE requires a separate license from desktop Analytica.

However, you can do some simple batch processing as described in the use case example with Analytica itself. These limitations generally apply:

The Analytica graphical user interface appears on the screen (So you also need to be logged into a console). You can't suppress the GUI during processing.
Events that require user interaction could cause your batch process to halt as it waits for a user's response. This could include error messages, warnings, and evaluation of UI functions such as MsgBox.
The features required to make this plausible require Analytica 6.0 or later.
Although the core functionality to run in this fashion doesn't require any minimal edition, in most cases an Analytica Enterprise edition or better, or Analytica Power Player edition or better will likely be necessary. This is because you will probably configure your model to read and write data from and from external sources like databases or data files while it is running in batch mode, which are Enterprise-edition-level features.
The process runs in batch, in which in runs and terminates without any automated interactions in between. This can be contrasted to the case where a master program makes repeated calls to a child (Analytica) model, so that state within the child process is preserved between calls. For this latter pattern, you'd need to use ADE.

How to batch a model calculation

When configuring your model to be run in a batch mode, you need to address these considerations:

How to pass input data to the model that will be specific for the current run
How to launch the Analytica process
How to launch the calculation(s) of interest
How to export any computed results from the model, so that it they can be read by the next stage in the calculation workflow.
How to exit the Analytica process

Passing input data to your model

There will be inputs to your model that change from batch run to batch run. You can pass this data to the model in several ways, including:

Through a file on your computer, such as a CSV file.
From a URL data source.
Through a database.
Through command line parameters.

If you are passing large amounts of data, then it works best to pass it though file or databases. If you are passing just a few scalar inputs, then you might consider passing it over a command line parameter. You might also use the command line to communicate a filename that contains the data itself.

When you read data from files, you'll use functions like ReadTextFile for CSV, XML, JSON, or flat file data (see Parsing and formatting data), ReadBinaryFile, or the Spreadsheet functions.

When you read input data from a database, you'll use DbQuery (see also Database access in the User Guide).

When reading from a web-source, you'll use ReadFromURL. At the current time, it IS possible to call web services using ReadFromURL, but you have to deal with some low-level details of the HTTP protocol, which is some cases is easy, but in other cases is not convenient.

To pass information on the command line, you can use as assignment operator in an expression to the /eval parameter. For example:

Analytica.exe /eval:"Src_csv_filename:=\"incoming.csv\"" "myModelFile.ana"

which sets an input variable named Src_csv_filename to "incoming.csv", which in this case would be a file containing the bulk of the input data.

Note: The Analytica process does not have a stdin or stdout stream, so piping data through these streams is not an option.

Launching the Analytica process

You'll launch the Analytica process from the command line (or *.bat script), as:

Analytica.exe /eval:"expression" "modelFile.ana"

where expression and modelFile.ana are replaced as appropriate.

Launch the calculations of interest

We recommend that you create a button in your model that runs the calculations that should be carried out in a batch run. The button should also export any results of interest, for example to data files or to an external data base.

When you launch the Analytica process, include the button identifier in the /eval expression, e.g.,

Analytica.exe /eval:"Src_csv_datafile=\"incoming.csv\";Run_Batch" "MyModelFile.ana"

Export calculations results

In your button's OnClick expression, you should export any results of interest to data files or databases. For example, your button OnClick might include code such as

WriteTextFile("Results.csv",MakeCSV(main_result))

Exit the Analytica process

After your calculation completes, you need to explicitly tell the process to terminate. This is accomplished by using the typescript command Bye.

If you execute the Bye command from your OnClick expression or from the /eval: command line parameter, you have to run it using EvaluateScript. From the /eval parameter, this would look like:

Analytica.exe /eval:"Src_csv_datafile='incoming.csv';Run_Batch;EvaluateScript('Bye -')" "MyModelFile.ana"

The minus parameter to Bye causes it to exit without asking whether to save any changes. Without the -, EvaluateScript('Bye') would ask you if you want to save changes in the event that your model has been dirtied, which would cause your batch process to pause until your responded, thus ruining the automation.

A more elegant method is to add a button to your model named Exit. (Be careful, pressing this button when using Analytica would exit without saving changes). Set its OnClick expression to EvaluateScript('Bye -'), so that your command line is simplified to

Analytica.exe /eval:"Src_csv_datafile='incoming.csv';Run_Batch;Exit" "MyModelFile.ana"