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.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.10 but will not be supported in Python 3.11 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.
Data Model Functions
|
Creates an annotation for a DataFrame entity.
|
|
|
Creates an annotation for an index entity. To be used in conjunction with xpressinsight.types.Series or xpressinsight.types.DataFrame entities.
|
|
|
Creates an annotation for a parameter entity. Parameters can be used to configure an Xpress Insight app. When parameters are declared, their name, data type, and default value must be specified. Parameters are typically read-only.
|
|
|
Creates an annotation for a scalar entity,.
|
|
|
Creates an annotation for a Series entity, a declaration of a pandas Series datastructure. Every series must have at least one index.
|
Data Model Classes
|
Declare the entity to be (or to contain) boolean (True or False) values. If not specified, the default value is False.
|
|
|
Represent a single column within a DataFrame entity. Outside the Python model (e.g. VDL, Tableau), the column will be represented as a separate entity whose name combines the names of the DataFrame and the Column, concatenated by an underscore, i.e. MyDataFrame_MyColumnName
|
|
|
Initializes Column.
|
|
|
The configuration of a DataFrame entity. Use the helper function xpressinsight.types.DataFrame to declare a DataFrame entity in an app, rather than instantiating xpressinsight.DataFrame directly.
|
|
|
Initializes DataFrame.
|
|
|
Abstract base class of all Insight entities, including composed entities like DataFrames.
|
|
|
Possible values of whether the UI should hide an entity where appropriate.
|
|
|
The configuration of an index entity. Use the helper function xpressinsight.types.Index to declare an index entity in an app, rather than instantiating xpressinsight.Index directly.
|
|
|
The constructor.
|
|
|
Declare the entity to be (or to contain) integer (whole number) values. Each value must fit into a signed 32-bit integer. If not specified, the default value is 0.
|
|
|
How and whether Insight handles an entity.
|
|
|
The configuration of a parameter entity. Parameters can be used to configure an Xpress Insight app. When parameters are declared, their name, data type, and default value must be specified. Parameters are typically read-only. Use the helper function xpressinsight.types.Param to declare a parameter entity in an app, rather than instantiating xpressinsight.Param directly.
|
|
|
Initializes Param with the data type or a default value (in which case data type is inferred).
|
|
|
Declare the entity to be (or to contain) floating-point (whole number) values. If not specified, the default value is 0.0.
|
|
|
The configuration of a scalar entity. Use the helper function xpressinsight.types.Scalar to declare a scalar entity in an app, rather than instantiating xpressinsight.Scalar directly.
|
|
|
The constructor.
|
|
|
The configuration of a Series entity, a declaration of a pandas Series datastructure. Use the helper function xpressinsight.types.Series to declare a Series entity in an app, rather than instantiating xpressinsight.Series directly.
|
|
|
Initializes Series.
|
|
|
Declare the entity to be (or to contain) string (UTF-8 encoded) values. The length (in bytes) of a string scalar (Scalar or Param) must not exceed 1,000,000 bytes. The length of a string in a container (Index, Series, or DataFrame) must not exceed 250,000 characters. A string must not contain the null character. If not specified, the default value of a string scalar is the empty string "".
|
© 2001-2023 Fair Isaac Corporation. All rights reserved. This documentation is the property of Fair Isaac Corporation (“FICO”). Receipt or possession of this documentation does not convey rights to disclose, reproduce, make derivative works, use, or allow others to use it except solely for internal evaluation purposes to determine whether to purchase a license to the software described in this documentation, or as otherwise set forth in a written software license agreement between you and FICO (or a FICO affiliate). Use of this documentation and the software described in it must conform strictly to the foregoing permitted uses, and no other use is permitted.