Parameters

Multiple files and folders can be created in the file explorer to the left. To specify the main entry point for Akumen, one of the files must be specified as the execution file. The first file created is set by default as execution file. It can be changed to an other suitable file from the context menu in the file explorer. The execution file must contain the Akumen function called “akumen”.

Python and R applications in R utilise code comments in the execution file to define the inputs and outputs required for the model. Note a sample is automatically created when a new model is created.

Python Applications

Python applications in Akumen are run “headless”, i.e. without a GUI. That means, if libraries like matplotlib are used in the app code, a non-interactive backend has to be chosen. For example:

import matplotlib
matplotlib.use("Agg") 	 # This selects the non-interactive backend "Agg" for plotting
import matplotlib.pyplot as plt

When the first file is created in the new app, the akumen function is created. The top section contains code comments, which are used to construct the inputs and outputs required to “wire” the parameters into Akumen. These follow a specific format, as shown below.

Python applications require a function in the form def akumen(first, second, **kwargs).

For example:

def akumen(first, second, **kwargs):
	 # !! use arguments by name
	 print(first)

Or:

def akumen(**kwargs):
	 # !! use arguments through kwargs
	 print(kwargs.get("first"))

R Applications

R applications require a function in the form akumen <- function(first, second, ...) {}.

For example:

akumen <- function(first, second, ...) {
    paste(first)
}

Parameter Types

All parameters are defined in code comments at the beginning of the akumen function in the execution file.

Inputs

Input parameters are defined must be defined in one of the following ways:

• Input: name [float]
• Input: name [int]
• Input: name [string]
• Input: name [datetime]
• Input: name [json]
• Input: name [tabular]
• Input: name [file] (csv)
• Input: name [enum] (enumTypeName)
• Input: name [list]
• Input: name [assetview] (optionaltype)
• Input: name [assettemplate]
• Input: name [scenario]
• Input: name [datasource]

Parameter names must be unique (whether input or output) per application. Inputs are copied to outputs and are available in reporting and analytics.

Data Types

Setting the correct datatype will change the editor in the research tab to the appropriate editor for that datatype.

Outputs

Output parameters must be labelled like one of the following, and will be outputted to the AppOutput table (unless there is a ParameterGroup defined):

• Output: name [float]
• Output: name [file] (file_name.csv) {fieldname:datatype[,fieldname2:datatype2...]}
• Output: name [file] (file_name.csv) {Column1:string,Column2:float,Column3:int}

Note that (file_name.csv) is now optional.

• Output: name [tabular] {fieldname:datatype[,fieldname2:datatype2...]}

is equivalent to

• Output: name [file] {fieldname:datatype[,fieldname2:datatype2...]}

To mark a generated file for import into Akumen the output parameter would be declared as:

• Output: fileparam [file] (hourly_data.csv) {fieldname1:float, fieldname2:boolean}

This will load the values from the file hourly_data.csv into the table hourly_data.

Tabular and Scenario outputs can both select scenarios from other applications. This list by default pulls all apps and studies, however it can be controlled by adding in the following configuration items:

• {allowed_app_list=comma separated list of app names}
• {allowed_study_list=comma separated list study names}

Controlling whether or not parameters appearing in the research grid can be setup using the following syntax:

{publishtoresearch=true} or {publishtoresearch=false}

For example, an output parameter may be included using:

- Output: name [float] {publishtoresearch=true}

The default for Python/R models is that all parameters appear on the research grid.

Controlling whether Akumen based outputs appear in the AppOutput structures can be set up using the following syntax:

{publishtoappoutput=true} or {publishtoappoutput=false}

For example, an input parameter may not be required in the AppOutput,

- Input: name [float] {publishtoappoutput=false}

Controlling the grouping of parameters into different AppOutput “tables” can be setup using the following syntax:

{parametergroup=groupname}

All parameters with the same group will be loaded into a table called AppOutput_ParameterGroup. Use this when there are too many parameters to be realistically used on the research grid (> 1000).

Controlling whether results are persisted, rather than deleted, are controlled using the following syntax:

{persist=true} or {persist=false}

This provides the ability to retain results between runs, rather than clearing results.

When using the persist flag and if there is a chance of duplicates when running the app as a scheduled app, the duplicate column key can be defined using the following syntax:

{duplicatekey=col1,col2}

In other words, a comma separated list of column names in the expected data set.

The friendly name of the parameter (displayed in any templated pages) is configured using the following syntax:

{description=friendlyname}

Finally, the outputs must be returned from the R/Python specific return function.