View source for 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 [[ADE User Guide|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 User Guide|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 [[Analytica Command Line|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 [[Read and Write Spreadsheets|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 <code>/eval</code> parameter.  For example:
:<code>Analytica.exe /eval:"Src_csv_filename:=\"incoming.csv\"" "myModelFile.ana"</code>
which sets an input variable named <code>Src_csv_filename</code> to <code>"incoming.csv"</code>, 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 <code>/eval</code> expression, e.g.,
 Analytica.exe /eval:"Src_csv_datafile=\"incoming.csv\"<span style="background-color:yellow">;Run_Batch</span>" "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 
:<code>[[WriteTextFile]]("Results.csv",[[MakeCSV]](main_result))</code>

=== Exit the Analytica process ===

After your calculation completes, you need to explicitly tell the process to terminate. This is accomplished by using the [[:Category:Typescript Commands|typescript command]] [[Bye]].

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

 Analytica.exe /eval:"Src_csv_datafile='incoming.csv';Run_Batch<span style="background-color:yellow">;EvaluateScript('Bye -')</span>" "MyModelFile.ana"

The minus parameter to [[Bye]] causes it to exit without asking whether to save any changes. Without the -, <code>[[EvaluateScript]]('[[Bye]]')</code> 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 <code>EvaluateScript('Bye -')</code>, so that your command line is simplified to

 Analytica.exe /eval:"Src_csv_datafile='incoming.csv';Run_Batch<span style="background-color:yellow">;Exit</span>" "MyModelFile.ana"

== See Also ==
* [[Analytica Command Line]]
* [[Buttons]]
* [[DbQuery]], [[DbWrite]] -- for data base exchange of data
* [[Parsing and formatting data]]
* [[ReadTextFile]], [[WriteTextFile]], [[ReadUrl]], [[Read and Write Spreadsheets]]
* [[MakeCSV]], [[ParseCSV]]