Guides

Algorithm Builder

elements.sdk.builder.algorithm

This is a basic builder to help build factories in a safe way instead of managing JSON configuration files. This includes all the methods to incrementally build out an Algorithm Manifest and Algorithm Config proto struct that can be used in API calls.

Enums

  • DataType
  • DataSource
  • ReleaseStatus
  • InterfaceType
  • ParallelType
  • PermissionType

AlgorithmManifest

Required Methods:

AlgorithhmManifest.metadata_required()

  • description (str) - description of the Algorithm Manifest
  • version (str) - the version of the Algorithm

AlgorithhmManifest.interface_required()

  • interface_type (InterfaceType) - the type of command the manifest employs - one of:
    • InterfaceType.SYNCHRONOUS_TASK_HTTP_WORKER
    • InterfaceType.FILESYSTEM_TASK_WORKER
    • InterfaceType.NO_OP_WORKER

AlgorithhmManifest.container_parameters_required()

  • image (str) - the Docker image your command runs on (if necessary)
  • command (List[str]) - the parsed command to run the Algorithm script (["python", "./my_algo.py"] e.g.)

AlgorithhmManifest.inputs_add_data_type() (can call this more than once, need AT LEAST 1)

  • data_type_name (DataType) - the Data Type the manifest uses
  • [Optional] min_count (int) - minimum number of observations
  • [Optional] max_count (int) - maximum number of observations

AlgorithhmManifest.outputs_add_data_types() (can call more than once, need AT LEAST 1)

  • output_data_types (List[str]) - the type of output the Algorithm produces
  • observation_value_columns (List[str]) - the name of the column in the dataframe that contains the Y values for a time series chart

Optional Methods:

AlgorithhmManifest.parameter_add() Parameters are the configurable inputs to your Algorithm. They can do anything, like filter for devices that stayed within a certain dwell time range, set a maximum cloud cover percentage, or define a lookback window for Traceability.

  • name (str) - the name of the parameter
  • type (str) - the data type the parameter accepts (integer, double, boolean, etc.)
  • unit (str) - the measurement units of the parameter (seconds, meters, etc.)
  • description (str) - description of the parameter
  • default - default value of the parameter
  • [Optional] min (int) - minimum allowed value for the parameter
  • [Optional] max (int) - maximum allowed value for the parameter
  • [Optional] allowed_values (List[str]) - discrete list of allowed values for the parameter

AlgorithhmManifest.manifest_version(manifest_version: str)

AlgorithhmManifest.metadata_description(description: str)

AlgorithhmManifest.metadata_version(version: str)

AlgorithhmManifest.metadata_indicator(indicator: str)

AlgorithhmManifest.metadata_tags(tags: List[str]) - provide descriptive tags for the manifest

AlgorithhmManifest.interface_interface_type(InterfaceType)

AlgorithhmManifest.interface_adapter(adapter: str)

AlgorithhmManifest.container_parameters_image(image: str)

AlgorithhmManifest.container_parameters_command(command: List[str])

AlgorithhmManifest.container_parameters_resource_request() More information on Kubernetes resources can be foundhere.

  • gpu (int) - the number of GPUs required to run the Algorithm
  • memory_gb (int) - the amount of memory (in gigabytes) required to run the Algorithm
  • cpu_millicore (int) - the number of fractional CPU required (1 core = 1,000 millicores)

AlgorithhmManifest.grouping_frequency(frequency: str, value: 1)

AlgorithhmManifest.parallelization_add_entry(and_set: List[str])

AlgorithhmManifest.restriction_spatial(permission_type: PermissionType, overridable: bool, geometry: str)

AlgorithhmManifest.restriction_temporal_restriction(tois: List[TOI])

AlgorithhmManifest.outputs_add_data_types(output_data_types: List[str], observation_value_columns: List[str])

AlgorithhmManifest.get() - return the full manifest

from elements.sdk.elements_sdk as TerraScopeSDK
from elements.sdk.builder.algorithm import AlgorithmManifest, DataType, Interfacetype

# Construct Algorithm Manifest
manifest = AlgorithmManifest()
manifest.metadata_required(description="Algorithm Manifest Description", version="0.0.1")
manifest.interface_required(interface_type=InterfaceType.FILESYSTEM_TASK_WORKER)
manifest.inputs_add_data_type(data_type_name=DataType.PINGS)
manifest.container_parameters_required(image="orbitalinsight/raw_foottraffic:84c76f7f",
                                       command=["python", "/orbital/base/algorithms/raw_foottraffic/src/py/raw_foottraffic/simple_foottraffic.py"])
manifest.outputs_add_data_types(output_data_types=["device_visits"],
                                observation_value_columns=["unique_device_count"])
        
# Used with sdk.algorithm_version.create(), requires algorithm_id to be known
sdk = ElementsSDK()
await sdk.algorithm_version.create(algorithm_id="79625d29-c139-4041-8562-ddc6d5816d5d", algorithm_manifest=manifest)

AlgorithmConfiguration

AlgorithmConfiguration.add_data_source()

  • data_type (DataType) - specify DataType to use
  • data_source (DataSource) - specify DataSource to use
  • [Optional] data_parameters (dict) - specify any DataSource-specific parameters to use

AlgorithmConfiguration.add_algorithm_parameter()

  • key (str) - parameter name
  • value (str) - parameter value to set

AlgorithmConfiguration.grouping_frequency()

  • frequency (Frequency) - frequency at which to group results
  • value (int) - recurrence of frequency (every X days, weeks, etc.)

AlgorithmConfiguration.get() - return the full configuration

from elements.sdk.elements_sdk as TerraScopeSDK
from elements.sdk.builder.algorithm import AlgorithmConfiguration, DataType, DataSource
from elements.sdk.builder.toi import Frequency

# Construct Algorithm Config
configuration = AlgorithmConfiguration()
# At least one Required
configuration.add_data_source(DataType.PINGS, DataSource.WEJO)
# At least one Required
configuration.grouping_frequency(Frequency.WEEKLY, 1)

# Create Algorithm Config
sdk = ElementsSDK()
await sdk.algorithm_config.create(
  algorithm_version_id="5ee03b8e-ab45-4553-b5f4-a5029254a9de",
  name="Algorithm Version Config Name",
  description="A test configuration.",
  algorithm_config=configuration)

Updated 6 months ago