Helpers

Additional variables are available for each model run. In Python, these are accessible through the akumen_api module, e.g.

import akumen_api

def akumen():
    print(akumen_api.AKUMEN_URL)

In R, these are included when you add source('akumen_api.r') to your code:

akumen <- function(...) {
    paste(AKUMEN_URL)
}
Variable Description
AKUMEN_URL The base Akumen url
AKUMEN_API_URL The base url of the Akumen API - this is the most commonly used URL for API access
API_KEY The api token for API access - this is set based on the context of the current user of Akumen OR the runas user for a scheduled app
MODEL_NAME The name of the currently executed application
STUDY_NAME The name of the currently executing study
CLIENT_NAME The name of the client the currently executing user belongs to
STUDY_ID The unique identifier of the study, useful when creating customized databases in Akumen and linking to a study
SCENARIO_NAME The name of the current executing scenario
SCENARIO_ID The unique identifier of the scenario, useful when creating customized databases in Akumen and linking to a study
SCENARIO_CONFIGURATION JSON dictionary of scenario configuration - can be anything required by an application, and set through scenario properties
IS_BASELINE True or False flag indicating if this is the baseline scenario for the study
MODEL_START_DATE The configured start date of the model
MODEL_END_DATE The configured end date of the model
SCENARIO_START_DATE The configured start date of the scenario
SCENARIO_END_DATE The configured end date of the scenario
-
Python only:
progress(message) Function to provide a progress indicator. Each message provides the time in the logs it took to execute the message, and is constantly updated (and returned) back to Akumen

API Helpers

Python models are also able to access a number of helper functions that are designed to ease the use of the Akumen API and other endpoints in modelling. These functions are described below.

get_results_views(model_name)

Retrieve a list of all data views associated with a model, for use with get_results().

Parameters:
  • model_name: string: name of the model
Returns:
  • list: list of view names

get_model(model_name)

Returns metadata about the model, including study and scenario details.

Parameters:
  • model_name: string: name of the model
Returns:
  • dict: model details

get_results(source, view_name, scope='scenario', query='')

Get the results of a source model/study/scenario and return as a dataframe.

Parameters:
  • source: Akumen Scenario input {"model_name":"...","study_name":"...","scenario_name":"..."}
  • view_name: Name of the results view
  • scope: Scope of results to retrieve [model, study, scenario]
  • query: Filter query string
Returns:
  • DataFrame: Pandas DataFrame containing results

The following helpers are not included in the akumen api to allow them to be modified. Rather, create a file called cloud_storage.py and it will be automatically populated with the imports and functions documented below. The code can then be modified to suit your needs.

save_to_cloud(provider, filepath, bucket, object='', **kwargs)

Save a file to a cloud container. Supports S3 and Azure.

Parameters:
  • provider: [s3, azure]
  • filepath: path to local file to upload
  • bucket: name of destination bucket or container
  • object: name of destination object, or None to use existing filename
Additional Parameters:

If using S3:

  • key: string: AWS Access Jey
  • secret: string: AWS Secret Key
  • region: string: AWS Region (e.g. ap-southeast-2)

If using Azure:

  • account: string: Azure account name
  • key: string: Azure account key

get_from_cloud(provider, object, bucket, filepath='', **kwargs)

Retrieve a file from a cloud container. Supports S3 and Azure.

Parameters:
  • provider: [s3, azure]
  • object: name of remote object
  • bucket: name of remote bucket or container
  • filepath: path to save file to (or None for object name)
Additional Parameters:

If using S3:

  • key: string: AWS Access Jey
  • secret: string: AWS Secret Key
  • region: string: AWS Region (e.g. ap-southeast-2)

If using Azure:

  • account: string: Azure account name
  • key: string: Azure account key