Data Model

Topics covered in this chapter:

All entities in the data model must be declared with the help of type hints for the class attributes.

The data model consists of container classes (xpressinsight.Param, xpressinsight.Scalar, xpressinsight.Index, xpressinsight.Series, xpressinsight.Column and xpressinsight.DataFrame), which hold the configuration of a given entity. But rather than instantiate these classes directly, you will apply type hints to a class definition using the xpressinsight.types or xpressinsight.data sub-modules.

When configuring the entities of your application, use xpressinsight.types, e.g.:

import xpressinsight as xi

@xi.AppConfig(name="My First Insight Python App", version=xi.AppVersion(0, 1, 2))
class MyApp(xi.AppBase):
    MY_PARAM: xi.types.Param(100)
    MyScalar: xi.types.Scalar(dtype=xi.integer)
    MyIndex: xi.types.Index(dtype=xi.integer)
    MySeries: xi.types.Series(dtype=xi.real, index='MyIndex')
    MyDataFrame: xi.types.DataFrame(
        columns=[
            xi.types.Column('col1', dtype=xi.integer),
            xi.types.Column('col2', dtype=xi.real)
        ], index='MyIndex')

When configuring the entities of another application that you will be reading, use xpressinsight.types, e.g.:

import xpressinsight as xi

@xi.ScenarioData()
class AnotherApp:
    MyScalar: xi.data.Scalar(dtype=xi.integer)
    MyIndex: xi.data.Index(dtype=xi.integer)
    MySeries: xi.data.Series(dtype=xi.real, index='MyIndex')
    MyDataFrame: xi.data.DataFrame(
        columns=[
            xi.data.Column('col1', dtype=xi.integer),
            xi.data.Column('col2', dtype=xi.real)
        ], index='MyIndex')

Parameters

Parameters are scalar values that can be used to configure an Insight scenario. When parameters are declared, their name, data type, and default value must be specified. The data type can be omitted if the default value is specified and vice versa. Parameter values are automatically passed from the scenario to Insight app such that their value from the scenario is available in all execution modes. In particular, the parameter values are available in the standard load mode. Within the Insight execution mode, parameters should be treated as runtime constants. They can only be changed in the Insight user interface and any changes in an execution mode will not be transferred back to the Insight server, i.e., the scenario parameters remain unchanged. Some examples include:

import xpressinsight as xi

@xi.AppConfig(name="My First Insight Python App", version=xi.AppVersion(0, 1, 2))
class MyApp(xi.AppBase):

    # Examples where data type is inferred from the default value.
    # Parameter "P" of type "xi.integer" with default value 100.
    P: xi.types.Param(100)
    # Parameter "DEBUG" of type "xi.boolean" with default value False.
    DEBUG: xi.types.Param(False)
    # Parameter "PI" of type "xi.real" with default value 3.14.
    PI: xi.types.Param(3.14)
    # Parameter "STR_PARAM" of type xi.string with default value 'My String Param'.
    STR_PARAM: xi.types.Param('My String Param')

    # Examples where data type is explicitly given.
    BOOL_PARAM: xi.types.Param(dtype=xi.boolean)   # Default value False.
    INT_PARAM: xi.types.Param(dtype=xi.integer)    # Default value 0.
    REAL_PARAM: xi.types.Param(dtype=xi.real)      # Default value 0.0.
    STRING_PARAM: xi.types.Param(dtype=xi.string)  # Default value "".

    # TODO: Define execution modes here.

Parameters are typically read-only.

Scalars

Scalar values are used to represent single-valued entities in the data model. Like parameters, when scalars are declared, their name, data type, and default value must be specified. The data type can be omitted if the default value is specified and vice versa. Scalars can either be input values or result values. By default, scalars are treated as input values. Some examples include:

import xpressinsight as xi

@xi.AppConfig(name="My First Insight Python App", version=xi.AppVersion(0, 1, 2))
class MyApp(xi.AppBase):

    # Examples where data type is inferred from the default value.
    # Input scalar "NumFactory" of type "xi.integer" with default value 100.
    NumFactory: xi.types.Scalar(100, manage=xi.Manage.INPUT)
    # Result scalar "IsOn" of type "xi.boolean" with default value True.
    IsOn: xi.types.Scalar(True, manage=xi.Manage.RESULT)

    # Examples where data type is explicitly given.
    StringScalar: xi.types.Scalar(dtype=xi.string)  # Input scalar with default value "".
    RealScalar: xi.types.Scalar(dtype=xi.real)      # Input scalar with default value 0.0.

    # TODO: Define execution modes here.

General Notes

In the data model, entities may be assigned an alias, which allows to specify a more "user-friendly" label for the entity which will be used in the Insight UI. For example:

MyInteger: xi.types.Scalar(dtype=xi.integer, alias='My Integer')

An entity MyInteger is declared, but will appear as My Integer in the Insight app UI such as table column headers, entity explorer, etc..

To separate the data model across multiple files, you can declare entities in superclasses of your application class.

Legacy Syntax

In earlier versions of the xpressinsight package (pre-1.4.0), entities were declared in a slightly different syntax that didn't use the xi.types.* functions, e.g:

MyInteger: xi.Scalar(dtype=xi.integer, alias='My Integer')

This syntax is now deprecated. It will continue to work in Python versions up to 3.11 but will not be supported in Python 3.12 and later. Additionally, the legacy syntax is incompatible with the Python deferred annotation functionality (from __future__ import annotations) and with declaring entities in a superclass.

The legacy and current syntaxes may not be used in the same class.