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.

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.Param(100)
    # Parameter "DEBUG" of type "xi.boolean" with default value False.
    DEBUG: xi.Param(False)
    # Parameter "PI" of type "xi.real" with default value 3.14.
    PI: xi.Param(3.14)
    # Parameter "STR_PARAM" of type xi.string with default value 'My String Param'.
    STR_PARAM: xi.Param('My String Param')

    # Examples where data type is explicitly given.
    BOOL_PARAM: xi.Param(dtype=xi.boolean)   # Default value False.
    INT_PARAM: xi.Param(dtype=xi.integer)    # Default value 0.
    REAL_PARAM: xi.Param(dtype=xi.real)      # Default value 0.0.
    STRING_PARAM: xi.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.Scalar(100, manage=xi.Manage.INPUT)
    # Result scalar "IsOn" of type "xi.boolean" with default value True.
    IsOn: xi.Scalar(True, manage=xi.Manage.RESULT)

    # Examples where data type is explicitly given.
    StringScalar: xi.Scalar(dtype=xi.string)  # Input scalar with default value "".
    RealScalar: xi.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.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..

Data Model Classes

>>> my_bool: xi.Scalar(dtype=xi.boolean)
... my_bool: xi.Scalar(False)
... my_bool: xi.Scalar(True)		

>>> my_int: xi.Scalar(dtype=xi.integer)
... my_int: xi.Scalar(0)
... my_int: xi.Scalar(100)
... my_int: xi.Scalar(-10)		

>>> my_real: xi.Scalar(dtype=xi.real)
>>> my_real: xi.Scalar(100.0)
>>> my_real: xi.Scalar(123.456)		

>>> my_string: xi.Scalar(dtype=xi.string)
... my_string: xi.Scalar("Hello World!")		

>>> @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 default value
...     # Scalar "NumFactory" of type "xi.integer"; default value 10
...     NumFactory: xi.Scalar(10)
...     # Scalar "IsOn" of type "xi.boolean"; default value True
...     IsOn: xi.Scalar(True)
...
...     # Examples where data type is explicitly given.
...     RealScalar: xi.Scalar(dtype=xi.real)      # default value 0.0
...     StringScalar: xi.Scalar(dtype=xi.string)  # default value ""		

>>> @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
...     # Param "P" of type "xi.integer" with default value 100
...     P: xi.Param(100)
...     # Param "DEBUG" of type "xi.boolean" with default value False
...     DEBUG: xi.Param(False)
...     # Param "PI" of type "xi.real" with default value 3.14
...     PI: xi.Param(3.14)
...     # Param "STR_PARAM" of type xi.string with a default value
...     STR_PARAM: xi.Param('My String Param')
...
...     # examples where data type is explicitly given
...     BOOL_PARAM: xi.Param(dtype=xi.boolean)  # default value False
...     INT_PARAM: xi.Param(dtype=xi.integer)  # default value 0
...     REAL_PARAM: xi.Param(dtype=xi.real)  # default value 0.0
...     STRING_PARAM: xi.Param(dtype=xi.string)  # default value ""		

>>> Indices: xi.Index(dtype=xi.integer, alias='Array Indices')		

>>> Indices: xi.Index(...) # previous declaration
... Result: xi.Series(index=['Indices'], dtype=xi.real,
...                   manage=xi.Manage.RESULT, alias='Result Array')		

>>> xi.Column("IntCol", dtype=xi.integer, alias="Input Integer Column")		

>>> MixedTable: xi.DataFrame(index='Years', columns=[
...     xi.Column("IntCol", dtype=xi.integer,
...               alias="Input Integer Column"),
...     xi.Column("StrCol", dtype=xi.string,
...               alias="Input String Column",
...               update_after_execution=True),
...     xi.Column("ResultCol", dtype=xi.real,
...               alias="Result Real Column",
...               manage=xi.Manage.RESULT)
... ])		

>>> MyInteger: xi.Scalar(dtype=xi.integer,
...                      alias='My Integer',
...                      manage=xi.Manage.INPUT)		

>>> MyInteger: xi.Scalar(dtype=xi.integer,
...                      alias='My Integer',
...                      hidden=xi.Hidden.ALWAYS)