Description API

This file describes the Description API interface of the Online Prediction Framework (OPF).

The Description API interface encapsulates the following two important sets of configuration parameters in OPF

  1. model creation parameters (via getDescription)
  2. task control parameters (via getExperimentTasks)

The description class objects instantiated in description.py implements the functionality by subclassing the Description API interface.

This allows description.py to be generic and oblivious to the specific experiments.

See OPF Description Template for more details.

class nupic.frameworks.opf.exp_description_api.DescriptionIface(modelConfig, control)

This is the base interface class for description API classes which provide OPF configuration parameters.

This mechanism abstracts description API from the specific description objects created by the individual users.

TODO: logging interface?

Parameters:
  • modelConfig – (dict) Holds user-defined settings for model creation. See OPF here for config dict documentation.
  • control – (dict) How the model is to be run. The schema of this dictionary depends on the ‘environment’ parameter, which specifies the context in which the model is being run.
convertNupicEnvToOPF()

Converts the control element from Nupic format to a default OPF format with 1 task. This is useful when you have a base description file that you want to run both permutations on (which requires the Nupic environment format) and single OPF experiments on (which requires the OPF format).

getModelControl()

Returns the task instances of the experiment description.

Returns:(dict) describing how the model is to be run
getModelDescription()
Returns:the model creation parameters based on the settings in the config dictionary.
normalizeStreamSources()

Inspects the control task and updates any stream sources it finds that are not absolute paths into paths generated by pkg_resources relative to nupic.datafiles.

class nupic.frameworks.opf.exp_description_api.ExperimentDescriptionAPI(modelConfig, control)

Bases: nupic.frameworks.opf.exp_description_api.DescriptionIface

Interface for specifying OPF experiments.

This class is used to specify the model and control parameters for an OPF experiment. The model config includes the necessary information for constructing an OPF model and the control includes information about the environment, where to get the data from, etc.

The experiment_runner takes an instance of this class as the description of the experiment to run. Similarly, scripts/run_opf_experiment.py looks for an instance of this class in a variable called “descriptionInterface” in the experiment files that are passed to it.

Parameters:
  • modelConfig –

    (dict) a specification of the model to use, including the following keys:

    • model: the name of the OPF model to create
    • version: the config format version to use
    • modelParams: parameters to pass to the OPF model

    There may be other required fields such as predictionSteps, predictedField, and numRecords

  • control –

    (dict): a specification of the experimental setup, including the following keys:

    • environment: the environment that the model will be run in
    • dataset: input specification as defined in
      src/nupic/frameworks/opf/jsonschema/stream_def.json
    • iterationCount: maximum number of iterations, or -1 to iterate
      until the data source is exhausted
    • inferenceArgs: a dict containing all the supplementary parameters
      for inference, including “predictedField” and “predictionSteps”
    • metrics: a list of MetricSpec instances that specify the metrics to
      compute during this experiment
    • loggedMetrics: a sequence of regular expression strings that
      specify which metrics should be logged at each iteration of the experiment
convertNupicEnvToOPF()

TODO: document

normalizeStreamSource(stream)

TODO: document :param stream:

normalizeStreamSources()

TODO: document