2. Web API

Our Web API may be used to access the Xplain Data Backend. The following methods are currently available:

addAggregation

Add an aggregation to an already existing request.

Example SUM:

{
     "method": "addAggregation",
     "requestName": "My Request",
     "aggregation": {
         // An aggregation as JSON object
         "aggregationType": "SUM",
         "object": "Customer",
         "dimension": "Income"
     }
}

The examples for AVG, COUNT, COUNTENTITY, MIN, MAX, VAR and STDEV are similar to the example SUM from above.

Example COUNTDISTINCT:

{
     "method": "addAggregation",
     "requestName": "My Request",
     "aggregation": {
         // An aggregation as JSON object
         "aggregationType": "COUNTDISTINCT",
         "object": "Customer",
         "dimension": "Income",
         "attribute": "income"
     }
}

The aggregationType can be any of SUM, AVG, COUNT, COUNTDISTINCT, COUNTENTITY, MIN, MAX, VAR, STDEV. For QUANTILE, additionally, the desired quantiles have to be specified, for example:

{
    "aggregationType": "QUANTILE",
    "aggregationName": "Quantile",
    "type": "QUANTILE",
    "dimension": "Rx Gross costs",
    "object": "Prescriptions",
    "quantiles" : [0.1, 0.3, 0.5, 0.7, 0.9]
}

Moreover, custom computed measures may be used as well. Example for adding a computed measure:

{
    "method" : "addAggregation",
    "requestName": "Request with Computed Measure",
    "aggregation" : {
        "aggregationName": "Normalized Measure",
        "aggregationType": "COMPUTED_MEASURE",
        "expression": " {SUM(Rx Gross costs)} / {# Person}"
    }
}

The “expression” argument contains a string which encodes a mathematical function. The argument for that function are given in curly braces “{…}”. Those refer to aggregations which are already defined in the query.

Request

POST /xplainsession

Returns

Current status of the session as JSON.

JSON Schema

addAggregation
type	object
properties
method	type	string
	default	addAggregation
requestName	The name of the request to which an aggregation should be added.
	type	string
aggregation	A JSON object representing an aggregation.
	type	object

addAggregationDimension

addAggregationDimension adds an aggregation dimension to the given target dimension. The aggregation dimension aggregates data from a child object (or any deeper descendant objects) according to the given aggregation definition.

Example:

{
     "method": "addAggregationDimension",
     "targetObject": "Patient",
     "dimensionName": "Costs of diabetes",
     "aggregation": {
           "aggregationType": "SUM",
           "object": "Prescription",
           "dimension": "Price"
     },
     "selections": [
           {
              "attribute": { "object": "Prescription", "dimension": "Product", "attribute": "Drug Category" },
              "selectedStates": ["Anti-diabetic drugs"]
          }
     ]
}

Adding an aggregation dimension to an object basically is equivalent to an SQL statement which includes a group by <targetObject> clause. The above example computes for each patient the cost associated with diabetes treatment (see the selections argument). After this method call a new dimension is available on the level of the target object (in the above example the Patient). You can use this new dimension like any other dimension on patient level, e.g. use it in a query.

In case the selections argument is omitted, the selections for the generated aggregation dimension are pulled from the current global selections. I.e. the selections of the aggregation dimension correspond to the selections valid at the time when the aggregation dimension has been generated and are henceforth fixed (they define a fixed semantics of the aggregation dimension).

In addition the argument floatingSemantics may be given and set to true. In this case, the generated aggregation dimension does not have its own selections (no copy is made) but selections point to the global selections (i.e. the aggregation dimension is aggregating whatever is currently selected according to the global selections).

You may as well explicitly specify selections for some attributes and use the flag floatingSemantics=true in combination with that. In this case only selections for attributes which are given explicitly are kept constant, while selections for other attributes are pulled from the global selections.

Request

POST /xplainsession

Returns

{Object} Current status of the session as JSON with the additional aggregation dimension

JSON Schema

addAggregationDimension
type	object
properties
method	type	string
	default	addAggregationDimension
targetObject	Name of the target object.
	type	string
dimension	The name of the new dimension. If omitted the name will be generated.
	type	string
dimensionName	An alias for the parameter dimension.
	type	string
aggregation	An aggregation in json object format.
	type	object
selections	The set of selections that will be applied as the where clause during aggregation.
	type	array of selections
fixExplicitSelections=none	This parameter may have one of the three values none (the default), all or only_propagate_upward. In case of none the selections for the aggregation dimension are kept as they are, which means that the resulting dimension hasnt necessarily a fixed semantics (may change in case the selections refer to a dimension which itself has floating semantics - this includes propagate upward dimensions). The given selections are sometimes also called fixed selections, which may be miss-leading in that case. If the parameter is set to all, all semantics will be fixed (indeed recursively, i.e., if the floating semantics emerges from a chain of references). In case of only_propagate_upward only propagate upward dimensions are fixed and are replaced by their non-floating counterpart (in this case non-recursively). This parameter offers an heuristics how to deal with the given selections before they are used as a part of the definition of the new dimension (it is not a part of the final definition of the resulting dimension). See also the equivalent parameter in #pin, # addRelativeTimeDimensions and #buildSortedSequence.
	type	enum
selectionSet	If specified, the aggregation dimension will use the selections from the given set as the selections applied during aggregation, thereby implementing a floating semantics concept. This means, whenever the selections in the corresponding set change, the aggregation dimension will have a different where clause, i.e. the selections of the aggregation dimension point to the given selection set. (As an exception to that see the parameter floatingSemantics, which you may set to false.) If, in addition to the parameter selectionSet, explicit selection are provided for a number of attributes (the argument selections), selection on those attributes are kept fix, however selections on other attributes are pulled dynamically from the given selection set.
	type	string
floatingSemantics	If, in case of a specified selectionSet (and if no explicit selections are specified), this parameter is given as false, then the current selections of the given selection set copied from there and henceforth used as the fixed selections of the aggregation dimension. This parameter is deprecated - dont use it any more. This parameter it deprecated - dont use it any more.
	type	boolean

addAttribute

Loads or generates an attribute and adds the attribute to the specified dimension. The attribute definition can either be read from the given file in the config folder defined by the environment variable xplainpath, or is generated by specification of the bin boundaries of the values of a numeric dimension. Instead of specifying a dimension, you can also specify a dimension pattern - the attribute is added to any dimension where the name meets the regular expression. In addition a dimension exclusion pattern can be specified.

Example:

{
    "method": "addAttribute",
    "object": "Customer",
    "dimension": "ZIP-Code",
    "attribute": "Sales Regions",
    "fileName": "Sales Regions.xattribute"
}

Loads an attribute from file "Sales Regions.xattribute" and adds the attribute to the dimension "ZIP-Code". See the section “Loading Data …” on how to generate an attribute from a database table (or an Excel file). The attribute can also be generated directly from a database or Excel table without persisting the attribute to an .xattribute file. The keys in the new attribute need to match the keys/values of the dimension to which the attribute is attached to.

Example:

{
    "method": "addAttribute",
    "object": "Customer",
    "dimensionPattern": ".*Revenue.*",
    "binBoundaries": [ 0.0, 100.0, 1000.0 ],
    "newAttributeNameSuffix": " - Class"
}

Adds a new attribute (categorization into numeric ranges) to all dimension of the object "Customer" which contain the string "Revenue". The name of the attribute will be identical to that of the dimension with the suffix " - Class" added to the name.

Request

POST /xplainsession

Returns

The current status of the session as JSON with the additional attribute(s).

JSON Schema

addAttribute
type	object
properties
method	type	string
	default	addAttribute
object	The target object.
	type	string
dimension	The target dimension. (Might be replaced by dimensionPattern and/or dimensionExclusionPattern.)
	type	string
dimensionPattern	Might be used instead of dimension.
	type	string
dimensionExclusionPattern	Might be used instead of dimension.
	type	string
attribute=dimension name	The name of the new attribute to be created.
	type	string
newAttributeNamePrefix	Prefix for new attribute name(s).
	type	string
newAttributeNameSuffix	Suffix for new attribute name(s).
	type	string
fileName	The filename of an attribute file to be loaded (usually with filename extension .xattribute).
	type	string
xlsFile	The file descriptor of a Microsoft Excel file (usually with filename extension .xls or .xlsx) to be loaded as an attribute.
	type	string
xlsFileName	DEPRECATED. The filename of a Microsoft Excel file (usually with filename extension .xls or .xlsx) to be loaded as an attribute.
	type	string
sheetName	The name of the sheet in the specified Microsoft Excel file where the attribute shall be loaded from.
	type	string
csvFile	The file descriptor of a CSV file (usually with filename extension .csv) to be loaded as an attribute.
	type	string
properties	A map of properties for the JDBC driver to import the data from files (only for CSV files at the moment).
	type	string
hierarchyLevelColumnNames	The names of the columns in the specified sheet of the Microsoft Excel file that make up the attribute hierarchy to be loaded.
	type	string[]
binBoundaries	The bin boundaries / interval endpoints / split keys (this is a deprecated variant with just one level).
	type	number[]
upperBinBoundaryIncluded=true	Signals whether the intervals are left-open and right-closed (true), or left-closed and right-open (false). (Current default is true. This might be changed.)
	type	boolean

addBooleanLogicDimension

Add a dimension as the boolean logic of two other boolean dimensions. All involved dimensions need to be dimensions from the same object.

Example:

{
    "method": "addBooleanLogicDimension",
    "object": "Patients",
    "dimension1": "Male Patients",
    "dimension2": "Old Patients",
    "type": "OR",
    "name": "Male Or Old Patients"
}

Request

POST /xplainsession

Returns

The current status of the session as JSON with the additional boolean dimension.

JSON Schema

addBooleanLogicDimension
type	object
properties
method	type	string
	default	addBooleanLogicDimension
object	The object which holds the input dimensions and which will also hold the result dimension.
	type	string
type	One of the boolean logic operations AND or OR (others soon supported XOR, 1NOT2, 2NOT1)
	type	string
name	Name of the new boolean dimension.
	type	string

addDateTimeElementDimension

Add a computed dimension for a date/time element such as day-of-week, hour-of-day, or minute-of-hour.

Example:

{
    "method": "addDateTimeElementDimension",
    "object": "Operation",
    "sourceDimension": "Operation DateTime (ms)",
    "targetDimension": "Operation Day of Week",
    "dateTimeElement": "DAY_OF_WEEK",
    "zoneId": "Europe/Berlin"
}

Request

POST /xplainsession

Returns

The current status of the session as JSON with the additional date/time element dimension and a suitable attribute.

JSON Schema

addDateTimeElementDimension
type	object
properties
method	type	string
	default	addDateTimeElementDimension
object	The target object.
	type	string
sourceDimension	The name of the source dimension storing points in time in milliseconds.
	type	string
targetDimension	The name of the new dimension to be created.
	type	string
dateTimeElement	The date/time element to be computed. Valid values are NANO_OF_SECOND, NANO_OF_DAY, MICRO_OF_SECOND, MICRO_OF_DAY, MILLI_OF_SECOND, MILLI_OF_DAY, SECOND_OF_MINUTE, SECOND_OF_DAY, MINUTE_OF_HOUR, MINUTE_OF_DAY, HOUR_OF_AMPM, CLOCK_HOUR_OF_AMPM, HOUR_OF_DAY, CLOCK_HOUR_OF_DAY, AMPM_OF_DAY, DAY_OF_WEEK, ALIGNED_DAY_OF_WEEK_IN_MONTH, ALIGNED_DAY_OF_WEEK_IN_YEAR, DAY_OF_MONTH, DAY_OF_YEAR, EPOCH_DAY, ALIGNED_WEEK_OF_MONTH, ALIGNED_WEEK_OF_YEAR, MONTH_OF_YEAR, PROLEPTIC_MONTH, YEAR_OF_ERA, YEAR, ERA, INSTANT_SECONDS, OFFSET_SECONDS.
	type	string
zoneId=null (default time zone of the server system)	A string representing the time zone.
	type	string
dataType	Usually, this parameter should be omitted; then the suitable type is chosen automatically. Valid values are BYTE, SHORT, INT, and LONG.
	type	string

addElapsedTimeAttribute

Add an ElapsedTimeAttribute. This is a multi-level interval attribute where the endpoints are numbers representing units of time elapsed since a certain reference date/time.

Request

POST /xplainsession

Returns

The current status of the session as JSON with the additional ElapsedTimeAttribute.

JSON Schema

addElapsedTimeAttribute
type	object
properties
method	type	string
	default	addElapsedTimeAttribute
object	The target object.
	type	string
dimension	The target dimension. (Might be replaced by dimensionPattern and/or dimensionExclusionPattern.)
	type	string
dimensionPattern	Might be used instead of dimension.
	type	string
dimensionExclusionPattern	Might be used instead of dimension.
	type	string
attribute=dimension name	The name of the new attribute to be created.
	type	string
newAttributeNamePrefix	Prefix for new attribute name(s).
	type	string
newAttributeNameSuffix	Suffix for new attribute name(s).
	type	string
upperBinBoundaryIncluded=true	Signals whether the intervals are left-open and right-closed (true), or left-closed and right-open (false). (Current default is true. This might be changed.)
	type	boolean
levelNames	The level names. (The default is Level 1, Level 2, and so on.)
	type	string[]
refDateTime	The reference date/time.
	type	string
intervalNameScheme=HALFOPEN_INTERVALS	The naming scheme for the attribute states: HALFOPEN_INTERVALS, FROM_TO, FROM_TO_PLUS, or ONLY_FROM.
	type	string
baseTimeUnit=MILLISECOND	The base time unit.
	type	string
outputTimeUnit=YEAR	The output time unit.
	type	string
binBoundaries	The bin boundaries / interval endpoints / split keys, one array per level.
	type	number[][]

addFlagExtractionDimension

Adds a flag extraction dimension to an object. The new dimension takes a number from a numeric input dimension and extracts a bit for a fixed position (the bit index, where index i stands for value 2^i, i.e., the lowest possible index is 0).

Example:

{
    "method": "addFlagExtractionDimension",
    "object": "Step",
    "dimension": "Error code",
    "bitIndex": 3,
    "outputDimension": "Error 4"
}

Request

POST /xplainsession

Returns

{Object} The current status of the session as JSON with the additional dimension.

JSON Schema

addFlagExtractionDimension
type	object
properties
method	type	string
	default	addFlagExtractionDimension
object	The name of the object where the new dimension is to be added.
	type	string
dimension	The dimension of the given object that holds the numeric values where the boolean flag is to be extracted from.
	type	string
bitIndex	The index of the bit to be extracted.
	type	number
outputDimension	The name of the dimension to be created.
	type	string

addGroupBy

Add a group-by to a given request. For instance, the following example groups data in “My Request” by customers’ gender.

Example:

{
    "method": "addGroupBy",
    "requestName": "My Request",
    "groupBy": {
        "attribute": { // A group-by as JSON object
            "object": "Customer",
            "dimension": "Gender",
            "attribute": "Gender"
        }
    }
}

Request

POST /xplainsession

Returns

Current status of the session as JSON.

JSON Schema

addGroupBy
type	object
properties
method	type	string
	default	addGroupBy
requestName	The name/ID of the request to which a group-by should be added.
	type	string
groupBy	A group-by as JSON object.
	type	object

addLinearSumDimension

Add a dimension as the linear sum of other numeric dimensions. The summand dimensions need to be all within one object branch. The resulting sum dimension will be put into the object at the end of that branch (farthest away from the root object).

Example:

{
    "method": "addLinearSumDimension",
    "dimensionName": "Difference",
    "dimensions": [
        {
            "object": "Patients",
            "dimension": "marginalReturn"
        },
        {
            "object": "Prescriptions",
            "dimension": "Costs (est.)"
        }
    ],
    "betas": [1.0, -2.0],
    "dataType": "FLOAT"
}

Request

POST /xplainsession

Returns

The current status of the session as JSON with the linear sum dimension.

JSON Schema

addLinearSumDimension
type	object
properties
method	type	string
	default	addLinearSumDimension
dimensions	the to be summed dimensions given as an XElementPath
	type	string[]
dataType=DOUBLE	The data type.
	type	string
betas	An array of numbers of same length as the input dimensions (if not given it will be a simple sum).
	type	number[]
constant	An addition constant to the linear sum.
	type	number
dimensionName	The name of the new dimension, if null the name will be generated.
	type	string

addMaxNumberDimension

Add a dimension as the maximum of other numeric dimensions. The input dimensions need to be all within one object branch. The resulting maximum dimension will be put into the object at the end of that branch (farthest away from the root object).

Example:

{
    "method": "addMaxNumberDimension",
    "outputDimension": "Maximum",
    "inputDimensions": [
        {
            "object": "Object 1",
            "dimension": "Dimension 1"
        },
        {
            "object": "Object 2",
            "dimension": "Dimension 2"
        }
    ],
    "constant": 1000
}

Request

POST /xplainsession

Returns

The current status of the session as JSON with the maximum number dimension.

JSON Schema

addMaxNumberDimension
type	object
properties
method	type	string
	default	addMaxNumberDimension
inputDimensions	The dimensions to be used for calculating the maximum, given as array of XElementPath.
	type	string[]
constant	A constant that shall be used in calculating the maximum value (i.e. a lower bound).
	type	number
outputDimension	The name of the new dimension, if null the name will be generated.
	type	string

addMinNumberDimension

Add a dimension as the minimum of other numeric dimensions. The input dimensions need to be all within one object branch. The resulting minimum dimension will be put into the object at the end of that branch (farthest away from the root object).

Example:

{
    "method": "addMinNumberDimension",
    "outputDimension": "Minimum",
    "inputDimensions": [
        {
            "object": "Object 1",
            "dimension": "Dimension 1"
        },
        {
            "object": "Object 2",
            "dimension": "Dimension 2"
        }
    ],
    "constant": 1000
}

Request

POST /xplainsession

Returns

The current status of the session as JSON with the minimum number dimension.

JSON Schema

addMinNumberDimension
type	object
properties
method	type	string
	default	addMinNumberDimension
inputDimensions	The dimensions to be used for calculating the minimum, given as array of XElementPath.
	type	string[]
constant	A constant that shall be used in calculating the minimum value (i.e. an upper bound).
	type	number
outputDimension	The name of the new dimension, if null the name will be generated.
	type	string

addNumberRangesAttribute

Add a NumberRangesAttribute. This is a multi-level interval attribute where the endpoints are numbers.

The following example creates an irregular attribute, where the interval endpoints (bin boundaries) are given explicitly. Note that "binBoundaries" is an array consisting of two arrays, each of which contains the interval endpoints of the two levels of the state hierarchy.

Example:

{
    "method": "addNumberRangesAttribute",
    "object": "Patient",
    "dimension": "# Prescription",
    "attribute": "# Prescription Explicit",
    "creationMode": "IRREGULAR",
    "binBoundaries": [
        [0, 1,       10,         100,           1000],
        [0, 1, 2, 5, 10, 20, 50, 100, 200, 500, 1000]
    ],
    "upperBinBoundaryIncluded": false
}

The following example creates an attribute, where the intervals have a constant size on each of the three levels. Note that "endpointRepresentation": "DECIMAL" means that the numbers are given in string form with quotes. (This setting is recommended in general because some numbers such as 0.1 are not representable by the usual binary-based number types and processing such decimal-based endpoints requires special treatment.)

Example:

{
    "method": "addNumberRangesAttribute",
    "object": "Process",
    "dimension": "Measure",
    "attribute": "Measure Equidistant Intervals",
    "creationMode": "EQUIDISTANT",
    "endpointRepresentation": "DECIMAL",
    "lowerLimit": "-10.0",
    "upperLimit": "10.0",
    "equidistantCreationBinSizePerLevel": ["10.0", "1.0", "0.1"],
    "upperBinBoundaryIncluded": false
}

The following example creates an attribute, where the interval endpoints are created by repeatedly multiplying a base value with a factor. Note that the value of "lowerLimit" causes also the creation of intervals within the negative part.

Example:

{
    "method": "addNumberRangesAttribute",
    "object": "Process",
    "dimension": "Measure",
    "attribute": "Measure Exponential Intervals",
    "creationMode": "EXPONENTIAL",
    "endpointRepresentation": "DECIMAL",
    "lowerLimit": "-2.0",
    "upperLimit": "30.0",
    "exponentialCreationBaseValue": "0.1",
    "exponentialCreationFactor": "2.0",
    "upperBinBoundaryIncluded": true
}

Request

POST /xplainsession

Returns

The current status of the session as JSON with the additional NumberRangesAttribute(s).

JSON Schema

addNumberRangesAttribute
type	object
properties
method	type	string
	default	addNumberRangesAttribute
object	The target object.
	type	string
dimension	The target dimension. (Might be replaced by dimensionPattern and/or dimensionExclusionPattern.)
	type	string
dimensionPattern	Might be used instead of dimension.
	type	string
dimensionExclusionPattern	Might be used instead of dimension.
	type	string
attribute=dimension name	The name of the new attribute to be created.
	type	string
newAttributeNamePrefix	Prefix for new attribute name(s).
	type	string
newAttributeNameSuffix	Suffix for new attribute name(s).
	type	string
upperBinBoundaryIncluded=true	Signals whether the intervals are left-open and right-closed (true), or left-closed and right-open (false). (Current default is true. This might be changed.)
	type	boolean
endpointClass	The fully qualified name of the class for the interval endpoints, such as java.lang.Long, java.lang.Integer, java.lang.Short, java.lang.Byte, java.lang.Double, or java.lang.Float. (Default is automatic detection from the dimension type.)
	type	string
creationMode=IRREGULAR	The creation mode, either IRREGULAR, EQUIDISTANT, or EXPONENTIAL.
	type	irregular/equidistant/exponential
endpointRepresentation=BINARY	The endpoints representation mode, either BINARY or DECIMAL. (Default is BINARY for backward compatibility, but in most practical situations, we recommend DECIMAL.)
	type	string
levelNames	The level names. (The default is Level 1, Level 2, and so on.)
	type	string[]
intervalNameScheme=HALFOPEN_INTERVALS	The naming scheme for the attribute states: HALFOPEN_INTERVALS, FROM_TO, FROM_TO_PLUS, or ONLY_FROM.
	type	string
binBoundaries=null	The bin boundaries / interval endpoints / split keys, one array per level.
	type	number[][]
stateNames=null	The interval names, one array per level. (Must be one element more than binBoundaries.)
	type	string[][]
stateDisplayNames=null	The interval display names, one array per level. (Must be one element more than binBoundaries.)
	type	string[][]
lowerLimit	The lower limit for the intervals. (Mandatory if creationMode is EQUIDISTANT or EXPONENTIAL.)
	type	number
upperLimit	The upper limit for the intervals. (Mandatory if creationMode is EQUIDISTANT or EXPONENTIAL.)
	type	number
equidistantCreationBinSizePerLevel	The interval sizes (one per level) for equidistant creation. (Mandatory if creationMode is EQUIDISTANT.)
	type	number[]
exponentialCreationBaseValue	The base value for the exponential creation. (Mandatory if creationMode is EXPONENTIAL.)
	type	number
exponentialCreationFactor	The factor for the exponential creation. (Mandatory if creationMode is EXPONENTIAL.)
	type	number

addNumericDimensions

Adds numeric dimensions to an object, whereby keys and values are given in terms of columns in an Excel file.

Example:

{
   "method": "addNumericDimensions",
   "object": "Prescription",
   "keyDimensionName": "Product ID",
   "xlsFile": "New Product Prices.xlsx",
   "sheet": "sheet1",
   "keyFieldName": "Product_ID",
   "valueFieldNames": ["Price_Provider_1", "Price_Provider_2"],
   "dimensionNames": ["Price 1", "Price 2"],
   "valueDataTypes": ["INT", "DOUBLE"]
}

This example adds two new dimensions to the Prescription object with name Price 1 and Price 2. Those new prices are given in terms of the columns of the specified Excel sheet, headed with name Price_Provider_1 and Price_Provider_2. The column Product_ID holds the keys (product IDs) thereby defining a mapping from a product ID to new prices.

Request

POST /xplainsession

Returns

{Object} The current status of the session as JSON with the additional dimensions.

JSON Schema

addNumericDimensions
type	object
properties
method	type	string
	default	addNumericDimensions
object	Name of object where the new dimensions are to be added.
	type	string
keyDimensionName	A dimension of the given object - the values of that are used as a key which maps to the given values in the Excel file.
	type	string
attribute	If given, the states on first level of this attribute are used as keys (instead of the values of the dimension) to map to the values in the Excel file.
	type	string
attributeLevel	If given in combination with the attribute parameter, states on the specified level are used as keys.
	type	integer
xlsFile	Excel file name which defines the numeric dimension / the mapping from keys to values.
	type	string
sheet	Sheet name in Excel file where the dimension is defined.
	type	string
keyFieldName	The name of the column in the Excel sheet which holds the key values.
	type	string
valueFieldNames	The names of the columns in Excel sheet which hold the values of the new dimensions.
	type	string[]
dimensionNames	Names of the new dimensions which should be added.
	type	string[]
valueDataTypes	Data types of the new dimensions.
	type	string[]

addObject

Load an XTable for a sub-object from a file and add it to an object view. The new object is appended to the given parent object.

Request

POST /xplainsession

Returns

The current status of the session as JSON with the additional sub-object.

JSON Schema

addObject
type	object
properties
method	type	string
	default	addObject
fileName	The file name where the object has been persisted.
	type	string
parentObject	The name of the parent object. Example: { method: addObject, fileName: Diagnosis.xtable, parentObject: Patient }
	type	string

addPointInTimeAttribute

Add a PointInTimeAttribute. This is a multi-level interval attribute where the endpoints are numbers representing certain points in time.

Example:

{
    "method":"addPointInTimeAttribute",
    "object" : "Prescription",
    "dimension" : "Date",
    "attribute": "Date",
    "startDateTime": "2018-01-01T00:00:00",
    "stopDateTime": "2023-01-01T00:00:00",
    "dateTimeLevels": ["YEAR", "HALFYEAR", "QUARTER", "MONTH", "DAY"],
    "zoneId": "Europe/Berlin"
}

The following example creates an attribute, where the naming format for the state names of the quarter level and the month level is explicitly given. In particular, the “QQQQ” part of the quarter format requests the text form, which is also influenced by the format locale “en-US”. This means, we request this part to be American English (“1st quarter”, 2nd quarter”, …). If the format locale is not specified, the default locale of Java VM is used, which could be German for instance (“1. Quartal”, “2. Quartal”, …). The month format part “MMM” means the short form of the month names (“Jan”, “Feb”, “Mar”, …). The state names for the levels of years, half-years, and days use the defaults formats, since no explicit format is given for them.

Example:

{
    "method":"addPointInTimeAttribute",
    "object" : "Prescription",
    "dimension" : "Date",
    "attribute": "Date",
    "startDateTime": "2018-01-01T00:00:00",
    "stopDateTime": "2023-01-01T00:00:00",
    "dateTimeLevels": ["YEAR", "HALFYEAR", "QUARTER", "MONTH", "DAY"],
    "formatLocale": "en-US",
    "formatQuarter": "yyyy QQQQ",
    "formatMonth": "MMM yyyy",
    "zoneId": "Europe/Berlin"
}

Request

POST /xplainsession

Returns

The current status of the session as JSON with the additional PointInTimeAttribute.

JSON Schema

addPointInTimeAttribute
type	object
properties
method	type	string
	default	addPointInTimeAttribute
object	The target object.
	type	string
dimension	The target dimension. (Might be replaced by dimensionPattern and/or dimensionExclusionPattern.)
	type	string
dimensionPattern	Might be used instead of dimension.
	type	string
dimensionExclusionPattern	Might be used instead of dimension.
	type	string
attribute=``dimension name``	The name of the new attribute to be created.
	type	string
newAttributeNamePrefix	Prefix for new attribute name(s).
	type	string
newAttributeNameSuffix	Suffix for new attribute name(s).
	type	string
upperBinBoundaryIncluded=``true``	Signals whether the intervals are left-open and right-closed (true), or left-closed and right-open (false).
	type	boolean
startDateTime	A string representing the start of the first local date/time interval.
	type	string
stopDateTime	A string representing the end of the last local date/time interval.
	type	string
dateTimeLevels	An array of time units (e.g., DECADE, YEAR, HALFYEAR, QUARTER, MONTH, WEEK, DAY, HOUR) representing the levels of the state hierarchy. (Note that WEEK is still experimental and that the behavior w.r.t. this option might change in the future.)
	type	string
formatLocale=``null`` (default format locale of the Java VM)	A string defining the locale to be used for formatting the date/time instances (e.g., de-DE or en-US).
	type	string
formatYear=``yyyy``	A string defining the format for the state names of years.
	type	string
formatQuarter=``yyyy QQQ``	A string defining the format for the state names of quarters.
	type	string
formatMonth=``yyyy-MM``	A string defining the format for the state names of months.
	type	string
formatWeek	A string defining the format for the state names of weeks. (The default depends on the other levels. It is one of the following formats: yyyy-MM / YYYY-Www / yyyy QQQ / YYYY-Www / yyyy / YYYY-Www / YYYY-Www.)
	type	string
formatDay=``yyyy-MM-dd``	A string defining the format for the state names of days.
	type	string
formatHour=``yyyy-MM-dd HH``	A string defining the format for the state names of hours.
	type	string
zoneId=``null`` (default time zone of the server system)	A string representing the time zone.
	type	string
dimensionTimeUnit=``MILLISECOND``	The time unit (MILLISECOND, SECOND, DAY, or MONTH) characterizing the units of the underlying dimension. (The former name baseTimeUnit is deprecated.)
	type	string
endpointClass	The fully qualified name of the class for the interval endpoints, such as java.lang.Long, java.lang.Integer, java.lang.Short, java.lang.Byte, java.lang.Double, or java.lang.Float. (Default is automatic detection from the dimension type.)
	type	string

addQuotientDimension

Add a dimension as the quotient of two other numeric dimensions. The input dimensions need to be all within one object branch. The resulting quotient dimension will be put into the object at the end of that branch (farthest away from the root object).

Example:

{
    "method": "addQuotientDimension",
    "outputDimension": "Quotient",
    "numeratorDimension": {
        "object": "Object 1",
        "dimension": "Numerator"
    },
    "denominatorDimension": {
        "object": "Object 2",
        "dimension": "Denominator"
    },
    "dataType": "FLOAT"
}

Request

POST /xplainsession

Returns

The current status of the session as JSON with the quotient dimension.

JSON Schema

addQuotientDimension
type	object
properties
method	type	string
	default	addQuotientDimension
numeratorDimension	The dimension to be used as the numerator for calculating the quotient.
	type	string
denominatorDimension	The dimension to be used as the denominator for calculating the quotient.
	type	string
outputDimension	The name of the new dimension, if null the name will be generated.
	type	string
dataType=DOUBLE	The output data type of the quotient dimension.
	type	string

addRelativeTimeDimensions

Construct one or more relative time dimension(s).

If referenceExentSelections are given, those selections define the fixed part of the relative time axis.

If in addition a reference to an external selection set is given (the parameter externalSelections), any selections on attributes not a part of the referenceExentSelections will be pulled dynamically from the specified set (i.e. the time axis well have a floating semantics).

If no referenceEventSelections are given, the currents selections are used as the referenceEventSelections. As a result the time axis has as a fixed part of the semantics the current selections (whereby “current selections” refers to the selections valid a the point of time when creating the time axis, as a default from the globalSelections or any other selection set if specified). This applies in both cases, with and without externalSelections (floating semantics): For example, if no referenceEventSelections are given and the externalSelections are set to externalSelections = “globalSelections”, the current global selections are used as the fixed ones but nevertheless any additional selections added to the global selection set will impact the semantics relative time axis.

Request

POST /xplainsession

Returns

A new XplainSession with added relative time dimensions.

JSON Schema

addRelativeTimeDimensions
type	object
properties
method	type	string
	default	addRelativeTimeDimensions
timeDimensions	An array of element paths (each consisting of object and dimension name).
	type	array of element path
referenceTimeDimension	An element path (object and dimension name).
	type	array
intervalEndTimeDimension	An element path (object and dimension name), optional coding an interval in combination with referenceTimeDimension
	type	array
baseObject=rootObject	The name of the base object. If the baseObject is not given, the root object used as baseObject.
	type	string
relativeTimeType	The reference type (TO_FIRST, TO_LAST, TO_NEAREST, TO_NEXT, TO_PREVIOUS).
	type	string
names	The names of the new relative time dimensions (must be of same cardinality as timeDimensions).
	type	string[]
referenceEventSelections	The reference event selections.
	type	array of selections
fixExplicitSelections=none	This parameter may have one of the three values none (the default), all or only_propagate_upward. In case of none the referenceEventSelections for the relative time dimension are kept as they are, which means that the resulting dimension hasnt necessarily a fixed semantics (may change in case the selections refer to a dimension which itself has floating semantics - this includes propagate upward dimensions). The given selections are sometimes also called fixed selections, which may be miss-leading in that case. If the parameter is set to all, all semantics will be fixed (indeed recursively, i.e., if the floating semantics emerges from a chain of references). In case of only_propagate_upward only propagate upward dimensions are fixed and are replaced by their non-floating counterpart (in this case non-recursively). This parameter offers an heuristics how to deal with the given referenceEventSelections before they are used as a part of the definition of the new dimension (it is not a part of the final definition of the resulting dimension). See also the equivalent parameter in #addAggregationDimension, #pin and #buildSortedSequence.
	type	enum
timeUnit	The time unit (NANOSECOND, MILLISECOND, SECOND, MINUTE, HOUR, DAY, WEEK, MONTH, QUARTER, HALFYEAR, YEAR, DECADE, CENTURY).
	type	xtimeunit
calendarBased=false	Decides whether the time difference is based on the calendar or not. (Calendar-based means: the difference between 31.12.2020 00:55 and 01.01.2021 00:05 is ONE year/month/day although it is actually just 10 minutes, and thus ZERO years/months/days in the non-calendar-based setting.)
	type	boolean
cacheReferenceTime=false	Decides whether caching should be applied.
	type	boolean
materializedReferenceTime	This parameter is a beta feature - ask the Xplain Data team how to use this.
	type	string
randomShiftsWhereNoReferenceTimeExists=false	This parameter is a beta feature - ask the Xplain Data team how to use this.
	type	boolean
selectionSet	If specified, the relative time axis will use the selections from the given set as the reference event selections (= zero point of time of the relative time axis), thereby implementing a floating semantics concept. This means, whenever the selections in the corresponding set change, the relative time axis will have a different zero point, i.e. the reference event selections of the time axis point to the given selection set. (As an exception to that see the parameter floatingSemantics, which you may set to false.) If, in addition to the parameter selectionSet, explicit reference event selections are provided for a number of attributes (the argument referenceEventSelections), selections on those attributes are kept fix, however selections on other attributes are pulled dynamically from the given selection set.
	type	string
floatingSemantics	If, in case of a specified selectionSet (and if no explicit selections are specified), this parameter is given as false, then the current selections of the given selection set copied from there and henceforth used as the fixed selections of the time axis. This parameter it deprecated - dont use it any more.
	type	boolean

addSampleDimension

Adds a random segment dimension to an object, i.e. a dimension which randomly assigns object instances to a given number of segments. The assignment is “pseudo random” based on a hash value of the corresponding key such that same objects are repeatedly assigned to same random segment.

Example:

{
     "method": "addSampleDimension",
     "dimension": "Random Customer Segment",
     "numberOfSegments": 3,
     "sampleObject": "Customer"
}

Request

POST /xplainsession

Returns

The current status of the session as JSON with the additional sample dimension.

JSON Schema

addSampleDimension
type	object
properties
method	type	string
	default	addSampleDimension
dimension=Random Segment	Name of the new dimension.
	type	string
name=Random Segment	Name of the new dimension (deprecated argument name - use dimension instead).
	type	string
numberOfSegments=10	The number of random segments.
	type	integer
sampleObject	The object whichs instances are assigned to random segments (root object if not given).
	type	string

addSelectionSet

Adds a new selection set with given name (ID).

Request

POST /xplainsession

Returns

Current status of the session as JSON with the additional selection set.

JSON Schema

addSelectionSet
type	object
properties
method	type	string
	default	addSelectionSet
name	The name (ID) of the set which is to be added.
	type	string

addThresholdDimension

Adds a threshold dimension to an object. The new dimension uses a comparable dimension and a threshold to construct a boolean dimension that signals whether the threshold was reached or not. The comparison can be configured to be strict. (In this case, the result is true only if the value of the underlying comparable dimension is strictly greater than the threshold.) After the actual comparison, the boolean result value can be negated if necessary. It is also possible to define the resulting boolean value for the case where the underlying comparable dimension returns a null entry.

Example:

{
    "method": "addThresholdDimension",
    "object": "Person",
    "dimension": "Number of prescriptions",
    "threshold": 5,
    "strict": false,
    "negate": false,
    "outputDimension": "Threshold reached"
}

Request

POST /xplainsession

Returns

{Object} The current status of the session as JSON with the additional dimension.

JSON Schema

addThresholdDimension
type	object
properties
method	type	string
	default	addThresholdDimension
object	The name of the object where the new dimension is to be added.
	type	string
dimension	The dimension of the given object that holds the values to be compared with the threshold.
	type	string
threshold	The threshold to be compared with the dimension values.
	type	number|string
strict=false	Signals whether the dimension values have to be strictly greater (instead of greater or equal) than the threshold.
	type	boolean
negate=false	Signals whether the boolean result should be negated.
	type	boolean
booleanValueForNull=false	Defines the Boolean value for the case of null in the input dimension.
	type	boolean
outputDimension	The name of the dimension to be created.
	type	string

addTimeDifferenceDimension

Add a dimension as the time difference of two other (point in time) dimensions. The input dimensions need to be all within one object branch. The resulting time difference dimension will be put into the object at the end of that branch (farthest away from the root object). NOTE: This function has BETA status. You can use it on your own risk, e.g. for testing, but there is no guarantee to continue this method in future versions. It might be removed again or changed in any way. An analysis that uses this feature might not load in future versions and could produce an error instead.

Example:

{
    "method": "addTimeDifferenceDimension",
    "outputDimension": "Time Difference",
    "minuendDimension": {
        "object": "Object 1",
        "dimension": "Minuend"
    },
    "subtrahendDimension": {
        "object": "Object 2",
        "dimension": "Subtrahend"
    },
    "dataType": "LONG",
    "timeUnit": "YEAR",
    "calendarBased": true,
    "ageBased": true,
    "zoneId": "Europe/Berlin"
}

Request

POST /xplainsession

Returns

The current status of the session as JSON with the time difference dimension.

JSON Schema

addTimeDifferenceDimension
type	object
properties
method	type	string
	default	addTimeDifferenceDimension
minuendDimension	The dimension to be used as the minuend for calculating the time difference.
	type	string
subtrahendDimension	The dimension to be used as the subtrahend for calculating the time difference.
	type	string
outputDimension	The name of the new dimension, if null the name will be generated.
	type	string
dataType=DOUBLE	The output data type of the time difference dimension.
	type	string
timeUnit	The output time unit of the new dimension. (If ageBased is true, then only YEAR and MONTH are allowed.)
	type	string
calendarBased	Signals whether the time difference should be based on a calendar (and a certain time zone). If calendarBased is false, then it is assumed that all units have a defined constant length (a day has 24 hours, a month has 30 days, and a year has 365 days).
	type	boolean
ageBased	Signals whether a calendar-based time difference should follow the style of the usual age computation. If ageBased is false, then there is a difference of ONE MONTH between 2024 Jan 27 23:55h and 2024 Feb 1 00:05h. If ageBased is true, these points in time would have a difference of ZERO MONTHS. (If we changed the second date to Feb 28, both would have a difference of ONE MONTH.)
	type	boolean
zoneId=null	The time zone (e.g., Europe/Berlin). If null, then the default of the JVM is used.
	type	string

addTimeDurationAttribute

Add a TimeDurationAttribute. This is a multi-level interval attribute where the endpoints are numbers representing units of time.

The following example creates an irregular attribute, where the interval endpoints (bin boundaries) are given explicitly.

Example:

{
    "method":"addTimeDurationAttribute",
    "object" : "Example Object Name",
    "dimension" : "Example Relative Time Dimension Name",
    "attribute": "Example Irregular/Explicit Attribute",
    "creationMode": "IRREGULAR",
    "intervalNameScheme": "FROM_TO",
    "baseUnit": "DAY",
    "binBoundariesInBaseUnits" : [[0, 1, 2, 5, 10, 20, 50, 100, 200, 500, 1000]],
    "upperBinBoundaryIncluded" : true
}

The following example creates an attribute, where the state names for the 3 resulting intervals are given explicitly.

Example:

{
    "method":"addTimeDurationAttribute",
    "object" : "Example Object Name",
    "dimension" : "Example Relative Time Dimension Name",
    "attribute": "Example attribute with given state names",
    "creationMode": "EQUIDISTANT",
    "intervalNameScheme": "FROM_TO",
    "baseUnit": "DAY",
    "minBaseUnits": -240,
    "maxBaseUnits": 0,
    "equidistantCreationTimeUnitBinSizes": [240],
    "stateNames": [["less", "interval", "more"]],
    "upperBinBoundaryIncluded" : true
}

The following example creates an attribute, where the intervals have a constant size on each of the 4 levels.

Example:

{
    "method":"addTimeDurationAttribute",
    "object" : "Example Object Name",
    "dimension" : "Example Relative Time Dimension Name",
    "attribute": "Example Equidistant Attribute",
    "creationMode": "EQUIDISTANT",
    "intervalNameScheme": "FROM_TO",
    "baseUnit": "DAY",
    "minBaseUnits": -360,
    "maxBaseUnits": 360,
    "equidistantCreationTimeUnitBinSizes": [360, 180, 90, 30],
    "upperBinBoundaryIncluded" : true
}

The following example creates an attribute, where the interval endpoints are created by multiplying with a given factor.

Example:

{
    "method":"addTimeDurationAttribute",
    "object" : "Example Object Name",
    "dimension" : "Example Relative Time Dimension Name",
    "attribute": "Example Exponential Attribute",
    "creationMode": "EXPONENTIAL",
    "intervalNameScheme": "FROM_TO",
    "baseUnit": "DAY",
    "minBaseUnits": 1,
    "maxBaseUnits": 128,
    "exponentialCreationTimeUnitBaseValue": 1,
    "exponentialCreationFactor": 2,
    "upperBinBoundaryIncluded" : true
}

Request

POST /xplainsession

Returns

The current status of the session as JSON with the additional TimeDurationAttribute.

JSON Schema

addTimeDurationAttribute
type	object
properties
method	type	string
	default	addTimeDurationAttribute
object	The target object.
	type	string
dimension	The target dimension. (Might be replaced by dimensionPattern and/or dimensionExclusionPattern.)
	type	string
dimensionTimeUnit	The time unit that the values of this dimension are measured in. Note: this is different from the time unit to be used to specify the intervals, see baseUnit below, and different from the time unit(s) to be shown in the state names of the attribute to be constructed. If not given, the default value depends on the data type of the dimension (for LONG/INT/SHORT it is MILLISECOND/DAY/MONTH, resp.).
	type	string
dimensionPattern	Might be used instead of dimension.
	type	string
dimensionExclusionPattern	Might be used instead of dimension.
	type	string
attribute=dimension name	The name of the new attribute to be created.
	type	string
newAttributeNamePrefix	Prefix for new attribute name(s).
	type	string
newAttributeNameSuffix	Suffix for new attribute name(s).
	type	string
upperBinBoundaryIncluded=true	Signals whether the intervals are left-open and right-closed (true), or left-closed and right-open (false). (Current default is true. This might be changed.)
	type	boolean
creationMode=IRREGULAR	The creation mode, either IRREGULAR, EQUIDISTANT, or EXPONENTIAL.
	type	irregular/equidistant/exponential
binBoundariesInBaseUnits	The bin boundaries / interval endpoints / split keys, measured in the time units specified in baseUnit, one array per level. (Applies only to creation mode IRREGULAR.)
	type	number[][]
binBoundaries	The bin boundaries / interval endpoints / split keys, measured in the time units of the underlying dimension, one array per level. (Applies only to creation mode IRREGULAR.)
	type	number[][]
stateNames	The interval names, one array per level. (Applies only to creation mode IRREGULAR. Must be one element more than binBoundaries.)
	type	string[][]
stateDisplayNames	The interval display names, one array per level. (Applies only to creation mode IRREGULAR. Must be one element more than binBoundaries.)
	type	string[][]
levelNames	The level names. (The default is Level 1, Level 2, and so on.)
	type	string[]
intervalNameScheme=HALFOPEN_INTERVALS	The naming scheme for the attribute states: HALFOPEN_INTERVALS, FROM_TO, FROM_TO_PLUS, or ONLY_FROM.
	type	string
baseUnit=null	Specifies in which units the bin sizes are given. (At the moment, this applies only to creation modes EQUIDISTANT and EXPONENTIAL, not to IRREGULAR.)
	type	string
minBaseUnits	Specifies the minimum value (measured in baseUnits). (This applies only to creation modes EQUIDISTANT and EXPONENTIAL, not to IRREGULAR.)
	type	long
maxBaseUnits	Specifies the maximum value (measured in baseUnits). (This applies only to creation modes EQUIDISTANT and EXPONENTIAL, not to IRREGULAR.)
	type	long
equidistantCreationTimeUnitBinSizes	The interval sizes (one per level) for equidistant creation. (Mandatory if creationMode is EQUIDISTANT.)
	type	number[]
exponentialCreationTimeUnitBaseValue	The base value for the exponential creation. (Mandatory if creationMode is EXPONENTIAL.)
	type	number
exponentialCreationFactor	The factor for the exponential creation. (Mandatory if creationMode is EXPONENTIAL.)
	type	number
reduceUnits=true	Signals whether larger numbers of smaller units should be reduced to smaller numbers of larger units (e.g. 180min would be reduced to 3h). Note that, in this case, it is assumed that 1 month = 30 days and 1 year = 365 days.
	type	boolean

addVariable

Once a causal discovery model has been built, you can force an additional variable into the model to see whether this variable has an additional benefit relative to the existing ones (an contribution parameter > 0). It serves to understand why this variable is not amongst the variables which the causal discovery search has generated (“Xplain Why Not”).

This method is a first beta implementation. It might change in future versions.

Example:

{
     "method" : "addVariable",
     "modelName" : "Glaucoma",
     "selections" : [
         {
            "attribute": {"attribute" : "MP PCN ATC", "dimension" : "Rx PCN", "object" : "Prescriptions"},
            "selectedStates" : ["G04CB01 - Finasteride"]
         }
     ],
     "threshold" : 1
}

Request

POST /xplainsession

Returns

Current status of the session as JSON with the updated model.

JSON Schema

addVariable
type	object
properties
method	type	string
	default	addVariable
modelName	The name of the model
	type	string
selections	A set of selections which define the semantics of the variable.
	type	array of selection
threshold	The threshold of the binary aggregation variable.
	type	number
aggregation	An optional aggregation which defines the aggregation variable (default is a simple COUNT of the corresponding object).
	type	aggregation

buildModel

Starts the model building process.

Example:

{
    "method": "buildModel",
    "modelName": "Breast Cancer",
    "xmodelConfigurationFileName": "Causal Discovery Model Configuration.xmodel",
    "targetEventObject": "Diagnoses",
    "significance": 0.9
}

Builds a model which is named “Breast Cancer”. The configuration is read from “Causal Discovery Model Configuration.xmodel”. The target is defined by the selections currently set in the object “Diagnoses” (the global selections displayed yellow in the Object Explorer). Thereby the parameter “significance” is set to 0.9, and will override a corresponding parameter given in the given configuration (“Causal Discovery Model Configuration.xmodel”).

Request

POST /xplainsession

Returns

The session document including the new model.

JSON Schema

buildModel
type	object
properties
method	type	string
	default	buildModel
modelName	Name of the model - also serves as an ID.
	type	string
xmodelConfigurationFileName	The file name where detailed model configurations are given. For the parameters and the JSON schema of such a configuration see the corresponding documentation. Instead of xmodelConfigurationFileName you may also use xmodelConfigurationName or fileName as an alias.
	type	string
xmodelConfigurationName	Alias for the parameter xmodelConfigurationFileName.
	type	string
fileName	Alias for the parameter xmodelConfigurationFileName.
	type	string
configuration	Instead of providing the file name for a configuration (see parameter xmodelConfigurationName), an explicit JSON object can be given as a configuration. For the parameters and the JSON schema of such a configuration see the corresponding documentation.
	type	jsonobject
targetEventObject	If this object is given, the selections on that object define the target selections.
	type	string
significance=0.9	See the corresponding parameter in the documentation of the Causal Discovery model configuration schema. If this parameter is given explicitly when calling buildMethod, it will override the corresponding parameter in the configuration file.
	type	float
maxIndependentVariables	See the corresponding parameter in the documentation of the Causal Discovery model configuration schema. If this parameter is given explicitly when calling buildMethod, it will override the corresponding parameter in the configuration file.
	type	integer
minSupport	See the corresponding parameter in the documentation of the Causal Discovery model configuration schema. If this parameter is given explicitly when calling buildMethod, it will override the corresponding parameter in the configuration file.
	type	integer
primaryTargetSelectionAttributes	See the corresponding parameter in the documentation of the Causal Discovery model configuration schema. If this parameter is given explicitly when calling buildMethod, it will override the corresponding parameter in the configuration file.
	type	string[]
oneModelPerStateAttribute	If given multiple models will be built, one for each state currently selected in the given attribute.
	type	attribute
trainingScope	An optional array of selections on root object level. If given, training of the model will be restricted correspondingly. If evaluation results are written to files, those will have results for the training set as well as the validation set. The validation set implicitly is the model scope without the training scope.
	type	jsonarray

buildMostFrequentStatesAttribute

buildMostFrequentStatesAttribute computes the most frequent states (or most important states according to a measure) for an attribute on an given hierarchy level of the attribute, and builds a new attribute, where those states are added on the root level and all other states are moved to an “other state”.

Example:

{
    "method" : "buildMostFrequentStatesAttribute",
    "attribute" : {"object": "Prescriptions", "dimension": "Rx PCN", "attribute": "MP PCN ATC"},
    "aggregation" : { "aggregationType": "SUM", "object":"Prescriptions", "dimension":"Dosage"},
    "newAttributeName" : "Frequent Rx",
    "levelNumber" : 5,
    "numberStates" : 100,
    "othersState" : "Less Frequent Rx"
}

In this example, for all states on level 5 the summed Dosage for that state is computed. The 100 states with the highest sum are exposed on root level of the new attribute. If the aggregation argument is not give the importance of states is based on a simple count of the corresponding object (frequency of the occurance of the states).

Request

POST /xplainsession

Returns

Current status of the session as JSON with updated object tree

JSON Schema

buildMostFrequentStatesAttribute
type	object
properties
method	type	string
	default	buildMostFrequentStatesAttribute
attribute	Path of the attribute which is to be re-organised
	type	attribute
newAttributeName	Name of the new attribute
	type	string
levelNumber=1	Hierarchy level of the attribute on which the most frequent states are computed
	type	integer
aggregation	The optional aggregation (measure) by which importance of a state is measured / by which the stated are sorted
	type	aggregation
selections	Optional selection which are used to compute a importance of a state
	type	array of selection
numberStates=100	The number of most frequent states
	type	integer
othersState=Others / Null	Name of the state where all the other states are moved to
	type	string

buildPredictiveModel

The method “buildPredictiveModel” is an alias for “buildModel” - see this method.

Request

POST /xplainsession

JSON Schema

buildPredictiveModel
type	object
properties
method	type	string
	default	buildPredictiveModel

buildSortedSequence

buildSortedSequence adds a dimension of a given “rank” to an object (or multiple ones). “Rank” there by means it add the i-th occurrence of a number of selected events as a new dimension to an object (whereby the sorting can be defined by some other dimension - typically a time dimension). As an example: the root object might be the “Patient”, and the Patient has “Diagnosis” attached as a sub-object. To understand the sequence of diagnoses you may add 3 additional dimensions to the object Patient with the semantics “first diagnosis (of a certain type)”, “second diagnosis”, “third diagnosis”. You may do this with reverse ordering and/or relative to a different point in time, e.g. you may add dimensions like “last diagnosis before death”, “last but one diagnosis before death”, … Furthermore, it may also be other objects (not just the root object) where those dimension are added. You may as well add additional dimensions to the object “Diagnosis” with semantics like “first prescription after diagnosis (of a certain type)”, “second prescription after diagnosis”, …

Example:

{
   "method": "buildSortedSequence",
   "sortDimension" : {"object" : "Prescription", "dimension" : "Date"},
   "dimensionsToReplicate" : [
         {"object" : "Prescription", "dimension" : "Rx Code"}
   ],
   "ranks" : [1, 2, 3],
   "names": [
         ["First prescribed drug", "Second prescribed drug", "Third prescribed drug"]
   ]
}

This example will generate three new dimensions attached to the root object (= Patient).

{
  "method" : "buildSortedSequence",
  "sortDimension" : {"object" : "Prescription", "dimension" : "Date"},
   "dimensionsToReplicate" : [
         {"object" : "Prescription", "dimension" : "Rx Code"}
   ],
  "ranks" : [-2, -1, 1, 2],
  "targetObject" : "Diagnosis",
  "zeroPointDimension": {"object" : "Diagnosis", "dimension" : "Date"},
  "floatingSemantics" : true,
  "sequenceNames" : ["Rx Sequence relative to Diagnosis"]
}

This example will generate four new dimension which describe each diagnosis: the first two drugs prescribed before the diagnosis and the two prescriptions after the diagnosis. As the floatingSemantics is set, it will be sensitive to further selections set in Prescriptions object. I.e. you may select “pain killers” to see the first two pain killers before and after a certain diagnosis. The generated dimensions will be grouped into a sequence with name “Rx Sequence relative to Diagnosis”.

Request

POST /xplainsession

Returns

{Object} Current status of the session as JSON with the additional rank dimensions

JSON Schema

buildSortedSequence
type	object
properties
method	type	string
	default	buildSortedSequence
targetObject=rootObject	Name of the target object (optional - if not given the root object is assumed, or guessed otherwise). In case of a RankDimension this parameter is irrelevant. (The object of the sortDimension is used.)
	type	string
ranks	The ranks of the new dimension (position when sorted according to sortDimension)
	type	array of integer
reverse=false	For the case of reverse sorting / counting
	type	boolean
names	Names of the new dimensions - if not give a names will be generated. There needs to be one array of names for each dimensionToReplicate, and each array needs to be of same size as the number of given ranks (or a null array).
	type	array of array of string
namePostfixes	When given instead of names, the names will be generated based on those post-fixes.
	type	array of string
dimensionsToReplicate	The dimensions which should be replicated (unfolded in time). Those need to be from the same source object.
	type	array of dimension
sortDimension	The dimension which defines the sorting (typically a time dimension, but could by any numeric dimension)
	type	dimension
baseObject=targetObject	The embracing object within which events are sorted (if not given the target object is assumed if this not in a different object branch, otherwise the root object). You might for example sort all events of a patient and find events of a certain rank, or you might want to sort events within a hospital case to define ranks within a case.
	type	xobject
zeroPointDimension	An optional dimension relative to which the sorting / ranking is done
	type	dimension
selections	The set of selections that will be applied as the where clause to the to be sorted/ranked events
	type	array of selections
fixExplicitSelections=none	This parameter may have one of the three values none (the default), all or only_propagate_upward. In case of none the given selections are kept as they are, which means that the resulting dimension hasnt necessarily a fixed semantics (may change in case the selections refer to a dimension which itself has floating semantics - this includes propagate upward dimensions). The given selections are sometimes also called fixed selections, which may be miss-leading in that case. If the parameter is set to all, all semantics will be fixed (indeed recursively, i.e., if the floating semantics emerges from a chain of references). In case of only_propagate_upward only propagate upward dimensions are fixed and are replaced by their non-floating counterpart (in this case non-recursively). This parameter offers an heuristics how to deal with the given selections before they are used as a part of the definition of the new dimension (it is not a part of the final definition of the resulting dimension).
	type	enum
selectionSet	If specified, the selections from the given set will be used as the selections (= the parameter selections), thereby implementing a floating semantics concept. This means, whenever the selections in the corresponding set change, the where clause in the definition of the ranks changes: the selections point to the given selection set. (As an exception to that see the parameter floatingSemantics, which you may set to false.) If, in addition to the parameter selectionSetDefiningRank, explicit reference event selections are provided for a number of attributes (the argument selections), selection on those attributes are kept fix, however selections on other attributes are pulled dynamically from the given selection set.
	type	string
selectionSetDefiningRank	An old deprecated parameter which may be used instead of selectionSet.
	type	string
floatingSemantics	If, in case of a specified selection set (and if no explicit selections are specified), this parameter is given as false, then the current selections of the given selection set copied from there and henceforth used as the explicit selections and kept fix. This parameter it deprecated - dont use it any more.
	type	boolean
attributesToCopy	A list of attribute names amongst the attributes attached to the dimensionsToReplicate which are copied to the new dimensions. If not given all attributes will be copied. Otherwise, there needs to be one array for each dimensionsToReplicate.
	type	array of array of string
sequenceNames	If given the dimensions will be grouped into a sequence (see the corresponding methods for more details, e.g. openSequence ).
	type	array of string
rankDimensionName	If this parameter is given, an additional rank dimension is added to the source object (the object where the dimensionsToReplicate come from), which assigns a number (the rank) to each instance.
	type	string
rankZeroIsFirstInstanceEqualOrGreaterZeroPoint=false	if true this means that the first instance in the array of sorted instances which is = zero point receives the rank 0, i.e. starting from the first equal (or greater) instance the numbering goes upward 0, 1, 2, …
	type	boolean
transitionAttribute	If non-null, only the transitions will be coded in the sequence, i.e. only if the value of this attribute on the given transitionLevel changes a new entry in the ranked sequence is made.
	type	attribute
onlySegmentStarts=false	If set to true, only the first occurrence of a segment is assigned a rank, i.e. only if a new value of the transitionAttribute appears, whereby new is defined by the transitionLevel.
	type	boolean
transitionLevel=1	See the parameter transitionAttribute: the hierarchy level of the attribute which is used to detect transitions.
	type	integer

cacheAggregationDimensions

Caches all aggregation dimension which are currently not cached (and which do not have floating semantics).

Request

POST /xplainsession

Returns

void

JSON Schema

cacheAggregationDimensions
type	object
properties
method	type	string
	default	cacheAggregationDimensions
dimensions	An optional list of dimensions - if not given all aggregation dimensions will be considered for caching.
	type	array of dimension

cleanObjectTree

Removes all dynamically generated artifacts (dimensions) from the object tree which are currently not used - which means that dimensions are not removed if a) they are physical dimensions from XTables in the startup configuration or b) currently used elsewhere, e.g. in some request, in definition of aggregation dimensions or selections … and therefore cannot be removed.

Request

POST /xplainsession

Returns

Current status of the session as JSON with the corresponding dimensions removed.

JSON Schema

cleanObjectTree
type	object
properties
method	type	string
	default	cleanObjectTree

clearAllSelectionSets

clearAllSelectionSets clears all selections for all selection sets. All open requests are re-computed with no selections set.

Request

POST /xplainsession

Returns

Current status of the session as JSON with all global selections cleared and correspondingly updated results.

JSON Schema

clearAllSelectionSets
type	object
properties
method	type	string
	default	clearAllSelectionSets

clearAllSelections

clearAllSelections clears all selections from the current global selections of the session. If the optional parameter selectionSet is not given, the default globalSelections are cleared. To clear all selection sets, use the method clearAllSelectionSets All open requests are re-computed with no selections set.

Request

POST /xplainsession

Returns

Current status of the session as JSON with all global selections cleared and correspondingly updated results.

JSON Schema

clearAllSelections
type	object
properties
method	type	string
	default	clearAllSelections

clearResultsFolder

Delete all files in the result files directory.

Example:

{
    "method": "clearResultsFolder"
}

Request

POST /xplainsession

JSON Schema

clearResultsFolder
type	object
properties
method	type	string
	default	clearResultsFolder

clearSelections

clearSelections removes the selections for the specified attributes from the global selections. Either the parameters object/dimension/attribute or the parameter attributes has to be given. If only the parameter object is given, all selections of that object are cleared. If only the parameter object and dimension is given, all selections for attributes at that dimension are cleared.

Request

POST /xplainsession

Returns

Current status of the session as JSON with updated results.

JSON Schema

clearSelections
type	object
properties
method	type	string
	default	clearSelections
object	The object for which selections are to be cleared.
	type	string
dimension	The dimension for which selections are to be cleared.
	type	string
attribute	The attribute for which selections are to be cleared.
	type	string
attributes	An explicit list of attributes in terms of their path.
	type	array of xelementpath
selectionSet=globalSelections	The selection set for which to clear selections - if not given globalsSelections is cleared.
	type	string

clearSelectionsForSequence

clearSelectionsForSequence clears all selection set on one of the attributes the sequence is built upon.

Request

POST /xplainsession

Returns

{Object} Current status of the session as JSON

JSON Schema

clearSelectionsForSequence
type	object
properties
method	type	string
	default	clearSelectionsForSequence
sequenceName	Name of the sequence
	type	string

collapse

The reverse to the method expand: Recursively removes all children states from the first group-by of a query. See also the method expand. Collapsing states for which information for sub-states is no longer needed helps to not waste resources: Information for those sub-states is no longer computed and sent to the client.

Example:

{
    "method": "collapse",
    "requestName": "Customers/DoB/Age",
    "stateName": "10-19"
}

Request

POST /xplainsession

Returns

Current status of the session as JSON which no longer holds information for sub-states of the collapsed state.

JSON Schema

collapse
type	object
properties
method	type	string
	default	collapse
requestName	The name (ID) of the request (query) which holds the state which is to be collapsed.
	type	string
stateName	The name of the state which should be collapsed.
	type	string

computeRequest

(Re-)compute a given request, for example after aggregations, group-bys or selections have been added. The results are returned with the next session JSON document.

Example:

{
    "method": "computeRequest",
    "requestName": "My Request",
}

Request

POST /xplainsession

Returns

Current status of the session as JSON.

JSON Schema

computeRequest
type	object
properties
method	type	string
	default	computeRequest
requestName	The name/ID of the request which should be (re-)computed.
	type	string

copyTable

Copy a table (or a subset of the table according to current selections) and save as a new table and/or add the subset into the current object model. This method can be used to cut a subset from an extremely big object for quicker analysis. Another purpose of this method is to pull a sample and simultaneously randomized the data. With that you might be allowed to pull randomized data from a customer installation into you local environment for debugging purposes.

CAVEAT: If you create a sub-set of a big table and use it in an analysis, then this analysis will not reload correctly as the sub-set is not automatically re-generated. You have to manually ensure that the corresponding sub-sample is available before re-loading the analysis. Also, only physical dimensions of the underlying XTable will/can be copied (e.g. no dimensions such as aggregation dimensions can be copied).

MISSING (ask the Xplain team if you need this): Explicitly provide a selection for defining the sub-set (in replacement of the current selections of the current Xplain session).

Request

POST /xplainsession

Returns

A new XplainSession with the new object added (in case addAsSubObject = true, otherwise the session remains unchanged)

JSON Schema

copyTable
type	object
properties
method	type	string
	default	copyTable
sourceObject	the object from which to generate a copy
	type	string
newTableName	the name of the new XTable resp. the name of the new XObject when added into the object model
	type	string
newTableFileName	file name where the new XTable will be written to - if not give the new table will not be persisted
	type	string
addAsSubObject	if true the new table will immediately be added into the object tree
	type	boolean
dimensionsToCopy	if given only those dimensions are copied
	type	array of string
samplingFactor	if given only a corresponding sample is written, whereby sampling is done on root object level. A value of x means only each x-th root object is written.
	type	integer
dimensionsToRandomize	values in those dimensions are randomly scrambled
	type	array of string
randomizeAll	all values are randomly scrambled
	type	boolean
packageSize	the package size of the new table
	type	integer

createRequest

Create a request without immediately computing the results. Once created, additional aggregations, selections or groupbys can be added.

Example:

{
    "method": "createRequest",
    "requestName": "My Request"
}

This example creates an empty request.

Example:

{
    "method": "createRequest",
    "requestName": "My Request",
    "request": {
        // A request as JSON - see the section on the generic artifacts
    }
}

Request

POST /xplainsession

Returns

Current status of the session as JSON.

JSON Schema

createRequest
type	object
properties
method	type	string
	default	createRequest
requestName	The ID of the request to be created.
	type	string
request	A JSON object representing a request.
	type	object

deleteAllOpenRequests

deleteAllOpenRequests deletes all “open requests/queries”, i.e. all queries which have been initiated with the openRequest/openQuery method. Delete thereby means those queries will no longer be existing in the current session (no results for those available in the current session document).

Request

POST /xplainsession

Returns

Current status of the session as JSON.

JSON Schema

deleteAllOpenRequests
type	object
properties
method	type	string
	default	deleteAllOpenRequests

deleteAllRequests

During a session, many requests might have been created, executed or opened. This method cleans up (removes) all requests.

Example:

{
    "method": "deleteAllRequests"
}

See also #deleteRequest

Request

POST /xplainsession

Returns

Current status of the session as JSON.

JSON Schema

deleteAllRequests
type	object
properties
method	type	string
	default	deleteAllRequests

deleteModel

Delete the model from the current session. Results will be lost if model has not been saved.

Example:

{
    "method": "deleteModel",
    "modelName": "My Causal Discovery Model"
}

Request

POST /xplainsession

Returns

The session document as JSON.

JSON Schema

deleteModel
type	object
properties
method	type	string
	default	deleteModel
modelName	Mandatory model name.
	type	string

deleteRequest

Deletes a requests - it will no longer be available in the session.

Example:

{
    "method": "deleteRequest",
    "requestName": "My Request"
}

See also #deleteAllRequests

Request

POST /xplainsession

Returns

Current status of the session as JSON.

JSON Schema

deleteRequest
type	object
properties
method	type	string
	default	deleteRequest
requestName	The name/ID of the request to be removed.
	type	string

deleteSequence

deleteSequence deletes a sequence previously opened with openSequence. Any selections on attribute of the sequence are cleared, all opened queries are deleted (see method deleteSequenceQueries) and all dimensions related to the sequence are deleted.

Request

POST /xplainsession

Returns

{Object} Current status of the session as JSON

JSON Schema

deleteSequence
type	object
properties
method	type	string
	default	deleteSequence
sequenceName	Name of the sequence
	type	string

deleteSequenceQueries

deleteSequenceQueries as compared to deleteSequence deletes only the currently open queries which are associated with the sequence. Those can be re-opened with the method openSequenceQueries.

Request

POST /xplainsession

Returns

{Object} Current status of the session as JSON

JSON Schema

deleteSequenceQueries
type	object
properties
method	type	string
	default	deleteSequenceQueries
sequenceName	Name of the sequence
	type	string
openMarginalQueries=true	If true, queries for the marginal distributions for each sequence step will be deleted (one-dimensional).
	type	boolean
openTransitionQueries=true	If true, queries which describe the transitions between each step will be deleted (two-dimensional).
	type	boolean

disableCaching

Sets the flag cachingEnabled = false. As a result aggregation dimension built henceforth will not be cached any more.

Request

POST /xplainsession

Returns

Current status of the session as JSON.

JSON Schema

disableCaching
type	object
properties
method	type	string
	default	disableCaching

downloadSelections

Download (all or specified) selections. See also #exportSelections and #importSelections

Example:

{
    "method": "downloadSelections",
    "objects": ["Patient", "Prescription", "Hospitalization"]
}

Request

POST /xplainsession

Returns

The requested selections as JSON.

JSON Schema

downloadSelections
type	object
properties
method	type	string
	default	downloadSelections
objects	An array of object names. If present, the selections of the listed objects are exported. Otherwise the selections of all objects are exported.
	type	string[]

dropAggregationDimensionCaches

Drops all existing caches of aggregation dimensions.

Request

POST /xplainsession

Returns

void

JSON Schema

dropAggregationDimensionCaches
type	object
properties
method	type	string
	default	dropAggregationDimensionCaches

enableCaching

Sets whether the user / the current session allows to swap data.

Request

POST /xplainsession

Returns

Current status of the session as JSON.

JSON Schema

enableCaching
type	object
properties
method	type	string
	default	enableCaching
hotSwapEnabled	Values true or false code whether data swaps are allowed.
	type	boolean

evaluatePerformance

measure the server performance by performing a method call with different maxThreads. The output will be stored in an excel file which can be downloaded via URL <host>:<port>/downloadfile?type=RESULT&filename=performance.xlsx e.g. http://localhost:8080/downloadfile?type=RESULT&filename=performance.xlsx

Request

POST /xplainsession

JSON Schema

evaluatePerformance
type	object
properties
method	type	string
	default	evaluatePerformance
threads	The list of maximal threads to be tested
	type	array of string
methodCall	The method Call that needs to be performed .
	type	json
fileName	Output Excel filename, default is performance.xlsx
	type	string
repeats	number of repeats to calculate the average measurements
	type	int

executeAndExportQuery

Just an alias name for the method executeAndExportRequest. See the method executeAndExportRequest for details.

Request

POST /xplainsession

JSON Schema

executeAndExportQuery
type	object
properties
method	type	string
	default	executeAndExportQuery

executeAndExportRequest

executeAndExportRequest executes the given request and immediately exports the results to the specified file. The request (query) is then deleted immediately from the session such that no results are stored in the session document and no data transported via the web-interface. Therefore this method allows to export very large amounts of result data into a file (or a zipped file), which then can be more easily uploaded or copied elsewhere.

The method accepts the same parameters as the executeRequest and exportRequest method - basically it executes those two methods in succession and then deletes the request. For more details see executeRequest and exportRequest.

Request

POST /xplainsession

Returns

The current status of the session as JSON.

JSON Schema

executeAndExportRequest
type	object
properties
method	type	string
	default	executeAndExportRequest
request	The statistics request in JSON object format.
	type	string
requests	An array of statistics request in JSON object format. One of the two parameters, request or requests, needs to be given.
	type	string
templateXLS	The filename of an Excel template.
	type	string
resultXLS	The name of the result (Excel) file.
	type	string
columnHeaders	The array of column names overwrites the default column headers in the result Excel file.
	type	string
useDisplayNames	Signals whether the display names of the states shall be used in the Excel file instead of the technical state names.
	type	boolean

executeBatch

Execute multiple requests in one batch.

Example:

{
    "method": "executeBatch",
    "methodCalls": [
        {
            "method": "deleteAllRequests"
        },
        {
            "method": "executeRequest",
            "request": {
                // A group by as JSON object
            }
        }
    ]
}

A synonym is #executeScript

Request

POST /xplainsession

Returns

Current status of the session as JSON.

JSON Schema

executeBatch
type	object
properties
method	type	string
	default	executeBatch
file	The file descriptor of a script file to be executed.
	type	string
fileName	The filename of a script file to be executed. This is a deprecated parameter (replaced by file)!
	type	string
methodCalls	The array of requests in JSON format. (A synonym is script.)
	type	object[]
script	The array of requests in JSON format. (A synonym of methodCalls.)
	type	object[]
recomputeRequestsAfterBatch=true	Signals whether the requests should be recomputed after executing the batch.
	type	boolean
batchMode=true	Work in batch mode.
	type	boolean
terminateOnException=true	Decides whether the run is cancelled after an exception.
	type	boolean

executeQuery

Execute the specified statistics request and immediately returns the result in the session JSON document. The result of this request are “static”, that means as compared to openRequest (see the following section) the request will not be affected by any changes in global selections. If you want to change selections, group-bys or aggregations, you need to do that with the above methods and re-compute the request.

See also the synonym #executeRequest

Example:

{
    "method": "executeQuery",
    "request": {
        // A request as JSON object
    }
}

Request

POST /xplainsession

Returns

The current status of the session as JSON

JSON Schema

executeQuery
type	object
properties
method	type	string
	default	executeQuery
request	The statistics request in JSON object format.
	type	string

executeRequest

Execute the specified statistics request and immediately returns the result in the session JSON document. The result of this request are “static”, that means as compared to openRequest (see the following section) the request will not be affected by any changes in global selections. If you want to change selections, group-bys or aggregations, you need to do that with the above methods and re-compute the request.

See also the synonym #executeQuery

Example:

{
    "method": "executeRequest",
    "request": {
        // A request as JSON object
    }
}

Request

POST /xplainsession

Returns

The current status of the session as JSON

JSON Schema

executeRequest
type	object
properties
method	type	string
	default	executeRequest
request	The statistics request in JSON object format.
	type	string

executeScript

A synonym of #executeBatch

Request

POST /xplainsession

JSON Schema

executeScript
type	object
properties
method	type	string
	default	executeScript

expand

Adds the children states of the specified state into the first group-by of the given statistics request / query. The specified state needs to be a state of the first group-by as it exists so far. All the states of the first group-by need to form a hierarchy. Basically this operation is expanding one of the nodes of the hierarchy of states of an attribute and computes the necessary additional results.

For instance, the attribute “Age Group” might consist of an hierarchy of states as follows:

State hierarchy:

• ‘0-9’ - ‘0-3’ - ‘4-7’ - ‘8-9’

• ‘10-19’ - ‘10-13’ - ‘14-17’ - ‘18-19’

• ‘20-40’ - ‘20-23’ - ‘24-27’ - ‘28-29’

• ‘> 40’

In an initial openRequest statement only the first level states might have been put into the group-by. The expand method enables you to drill into one of the first level states, e.g. to drill into the state ‘10-19’.

Example:

   {
       "method": "expand",
       "requestName": "Customers/DoB/Age",
       "stateName": "10-19"
   }

Technically, ``expand`` adds the children of a state of an open attribute to the group-by of the corresponding request.
The ``expand`` method will work only if all the states of the initial group-by form a hierarchy/tree, and ``expand`` refers to the first group-by
of a potentially multi-dimensional group-by.

Request

POST /xplainsession

Returns

Current status of the session as JSON with additional results for the expanded state.

JSON Schema

expand
type	object
properties
method	type	string
	default	expand
requestName	The name (ID) of the request (query) which holds the state which is to be expanded.
	type	string
stateName	The name of the state which should be expanded.
	type	string

expandToLevel

Adds all states up to the given level into the group-by of the given statistics request / query. The specified level name needs to be a level of the first group-by attribute. Basically this operation is expanding an “open attribute” up to some level, e.g. expanding a calendar hierarchy up to the month level to break down results by all hierarchy levels, years, quarter and month.

Request

POST /xplainsession

Returns

Current status of the session as JSON with additional results up to the given level.

JSON Schema

expandToLevel
type	object
properties
method	type	string
	default	expandToLevel
requestName	The name (ID) of the request (query) which holds as a first group-by attribute a hierarchy of states with the given level name.
	type	string
levelName	The name of the hierarchy level of the attribute to which all states should be added into the group-by of the query.
	type	string
maxStates	Optional argument to limit the expansion only up to the level with less then this max number of states.
	type	integer

exportResults

Export the results of a set of performed statistics requests to an Excel file.

Example:

{
    "method": "exportResults",
    "requestNames": ["requestName1", "requestName2"],
    "templateXLS": "My Excel Template.xlsx",
    "resultXLS": "My Result Excel.xlsx",
    "round": false,
    "columnHeaders": {
        "requestName1": ["Age Group", "Gender", "Segment", "# Patients", "# TRX"],
        "requestName2": ["Specialty", "Region", "# Patients", "# TRX"]
    },
    "useDisplayNames": true
}

Request

POST /xplainsession

JSON Schema

exportResults
type	object
properties
method	type	string
	default	exportResults
requestNames	The names of the requests to be exported.
	type	string
templateXLS	The filename of an Excel template.
	type	string
resultXLS	The name of the result (Excel) file.
	type	string
sheetNames	An optional array of names, one for each request. If given, those names are used as sheetNames instead of the request names.
	type	string
columnHeaders	The array of column names overwrites the default column headers in the result Excel file.
	type	string
useDisplayNames	Signals whether the display names of the states shall be used in the Excel file instead of the technical state names.
	type	boolean
ignoreZeroResultLines=true	Result lines (aggregation cells) where all exported measures are 0 are omitted.
	type	boolean
fixInvalidSheetName=false	Fix invalid sheet names if for instance the name is longer than 31 characters or contains forbidden characters like colon (:), backslash (\), asterisk (*), question mark (?), slash (/) or square brackets ([,]), or if it starts or ends with a single quote character (). Otherwise, an exception is thrown with an appropriate error message.
	type	boolean
excelFonts	A mapping of self-defined font names to font setting objects, each of which may contain the entries bold, italic, strikeout (all boolean), underlineStyleIndex (byte), colorIndex, themeColor (short), fontName (string), fontFamilyIndex (integer), fontHeight (double), and typeOffset (short).
	type	object
excelCellStyles	A mapping of self-defined cell style names to cell style setting objects, each of which may contain the entries dataFormatIndex, indentation (short), font (string), horizontalAlignment (GENERAL | LEFT | CENTER | RIGHT | FILL | JUSTIFY | CENTER_SELECTION | DISTRIBUTED), verticalAlignment (TOP | CENTER | BOTTOM | JUSTIFY | DISTRIBUTED), rotation (short), fillPattern (NO_FILL | SOLID_FOREGROUND | FINE_DOTS | ALT_BARS | SPARSE_DOTS | THICK_HORZ_BANDS | THICK_VERT_BANDS | THICK_BACKWARD_DIAG | THICK_FORWARD_DIAG | BIG_SPOTS | BRICKS | THIN_HORZ_BANDS | THIN_VERT_BANDS | THIN_BACKWARD_DIAG | THIN_FORWARD_DIAG | SQUARES | DIAMONDS | LESS_DOTS | LEAST_DOTS), fillBackgroundColor, fillForegroundColor (short), borderStyleTop, borderStyleBottom, borderStyleLeft, borderStyleRight (NONE | THIN | MEDIUM | DASHED | DOTTED | THICK | DOUBLE | HAIR | MEDIUM_DASHED | DASH_DOT | MEDIUM_DASH_DOT | DASH_DOT_DOT | MEDIUM_DASH_DOT_DOT | SLANTED_DASH_DOT), borderColorTop, borderColorBottom, borderColorLeft, borderColorRight (short), hidden, locked, quotePrefixed, shrinkToFit, wrapText (boolean).
	type	object
mapRequestToExcelHeaderCellStyles	A mapping from request names to arrays of cell style names for the header cells.
	type	object
mapRequestToExcelDataCellStyles	A mapping from request names to arrays of cell style names for the data cells.
	type	object

exportSelections

Export selections (save to a file) for the global selections or an explicitly specified other selection set (all selections of those for given objects). Any floating semantics of the selections are fixed prior to the export, i.e., if a selections explicitly or implicitly refers to a dimension with floating semantics (e.g. an aggregation dimension which refers with its where-clause to a selection set), then this dimension is replaced by an equivalent dimension with fixed semantics according to the current state of the corresponding selection set. See also #importSelections and #downloadSelections

Example:

{
    "method": "exportSelections",
    "objects": ["Patient", "Prescription", "Hospitalization"], // Leave out to export selections on all objects
    "file": {
        "fileType": "XSELECTION",
        "ownership": "PUBLIC", // or "TEAM", or "USER" + the corresponding entry below
        // "team": "example_team",
        // "user": "example_user",
        "filePath": ["My_selection.xselection"]
    }
}

Request

POST /xplainsession

Returns

The current status of the session as JSON.

JSON Schema

exportSelections
type	object
properties
method	type	string
	default	exportSelections
objects	An array of object names. If present, the selections of the listed objects are exported. Otherwise the selections of all objects are exported.
	type	string[]
selectionSet=globalSelections	The selection set for which the selections should be exported.
	type	string
file	The file descriptor of the destination file.
	type	object

getAnalysis

See also the method saveAnalysis with similar / identical parameters. The difference is that getAnalysis does not save but return the current session as JSON object. If a fileName is given, the method simply returns the file content as JSON.

Request

POST /xplainsession

Returns

Current status of the session as JSON, whereby optionally user data and/or results are dropped, or a script which can be used to re-build the analysis.

JSON Schema

getAnalysis
type	object
properties
method	type	string
	default	getAnalysis
file	The file descriptor of the file from where to pull the JSON content.
	type	object
rebuildAllDimensionsWhenLoading=false	If set to true all dimensions in the object tree will be added to the required artefacts script, even if not required for the current analysis (in any queries or selections).
	type	boolean
dropResults=true	Optional parameter which may be used to drop results before returning the analysis as JSON so to only return the query structure without results.
	type	boolean
keepOnlyArtefactDefinitions=true	Optional parameter which may be used to drop all data except artefact definitions (e.g. drop data the user has added to the session, formatting data of the frontend, …) before returning the analysis as JSON.
	type	boolean
getAsScript=false	Optional parameter: in case this parameter is set to true, the session/analysis is not returned in the usual format (with a requiredArtifactsScript and additional fields coding the queries and selections), but one single script is returned which re-builds just everything. Executing this script will result in the original analysis (except any formatting). You may edit this script to adjust the parameters of this analysis.
	type	boolean

getAvailableCharsets

Retrieve a list of all charsets (e.g., "UTF-8", "ISO-8859-1", "US-ASCII") supported by the backend.

Request

POST /xplainsession

Returns

{String[]} return.charsets A JSON array containing the names of the supported charsets.

JSON Schema

getAvailableCharsets
type	object
properties
method	type	string
	default	getAvailableCharsets

getCachingEnabled

Provides information whether caching is currently enabled or not.

Request

POST /xplainsession

Returns

The flag cachingEnabled

JSON Schema

getCachingEnabled
type	object
properties
method	type	string
	default	getCachingEnabled

getChildren

Get all children states of a given state or all children states of the states of a given list.

Example:

{
    "method": "getChildren",
    "object": "Patient",
    "dimension": "Age",
    "attribute": "Age Group",
    "state": "Teenager"
}

or

Example:

{
    "method": "getChildren",
    "list" : [
        {
            "object": "Patient",
            "dimension": "Age",
            "attribute": "Age Group",
            "state": "Teenager"
        },
        {
            "object": "Patient",
            "dimension": "Age",
            "attribute": "Age Group",
            "state": "Adult"
        }
    ]
}

Request

POST /xplainsession

Returns

{String[]} return.children An array containing the state names of the requested children.

JSON Schema

getChildren
type	object
properties
method	type	string
	default	getChildren
list	Array of JSON objects (list of object, dimension, attribute, state combinations).
	type	object[]
object	The name of the object.
	type	string
dimension	The name of the dimension.
	type	string
attribute	The name of the attribute.
	type	string
state	The name of the state for which you would like to get the children. (If this argument is not given, the children of the root state of the attribute are returned.)
	type	string

getDefinition

getDefinition returns information about how the referred artifact (a dimension, an attribute or a query/request) is defined, e.g. the method call you need to run to generate the artifact or other information about the configuration of the artifact. One of the arguments "dimension", "attribute" or "request" (alternatively "query") needs to be given.

Example:

{
     "method": "getDefinition",
     "dimension": {"object": "Person", "dimension": "# Diagnoses"}
}

Request

POST /xplainsession

Returns

{JSONObject} Definition or configuration information as a JSON object.

JSON Schema

getDefinition
type	object
properties
method	type	string
	default	getDefinition
dimension	The dimension for which to get definitions specified as an XElementPath ({object: …, dimension: …}).
	type	xelementpath
attribute	The attribute for which to get definitions specified as an XElementPath ({object: …, dimension: …, attribute: …}).
	type	xelementpath
request	The name/ID of the request for which to get definitions.
	type	string

getFileContentAsJSON

Retrieve the content of a (server) file (as JSON).

Request

POST /xplainsession

Returns

The content of the specified file as JSON.

JSON Schema

getFileContentAsJSON
type	object
properties
method	type	string
	default	getFileContentAsJSON
fileName	The filename.
	type	string
fileType	The type of file (CONFIG, DATA, RESULT, SESSION, TEMP, USER_CONFIG, SCRIPT, SELECTION, APPLICATION). (This type determines the directory, where the file resides.)
	type	string
charset=UTF-8	A charset (e.g., UTF-8, ISO-8859-1, US-ASCII).
	type	string

getFilesWithDetails

Get information about certain files on the server.

Example:

{
    "method": "getFilesWithDetails",
    "fileType": "SCRIPT",
    "fileExtention": ".xscript",
    "caseSensitive": true
}

Request

POST /xplainsession

Returns

{Object[]} return.files A JSON array containing entries with properties "name" and "lastModified".

JSON Schema

getFilesWithDetails
type	object
properties
method	type	string
	default	getFilesWithDetails
fileType	The file type (implying a certain sub-folder of the xplainpath. This can be one of CONFIG_FILE, DATA_FILE, RESULT_FILE, SESSION_FILE, TEMP_FILE, USER_CONFIG_FILE, SCRIPT_FILE, SELECTION_FILE, APPLICATION_FILE or the short form CONFIG, DATA, RESULT, SESSION, TEMP, USER_CONFIG, SCRIPT, SELECTION, APPLICATION.
	type	string
fileExtension	The filename extension. Restricts the filenames in the result set to those that match the given extension (e.g., .json).
	type	string
caseSensitive=false	Signals whether the file extension should be matched case-sensitive (e.g., if false, .json returns also .JSON files).
	type	boolean
subfolder	Specifies a certain subfolder.
	type	string

getModelDifference

‘getModelDifference’ compares two models (or a model with the corresponding “stashed” model). The method returns a JSONObject which has three entries: ‘additionalVariables’, ‘changedVariables’, and ‘removedVariables’. The first list contains new variables which are not existing in the original model. “New” thereby means those variables have a different semantics relative to the existing ones (but might statistically be equivalent). Vice versa ‘removedVariables’ lists variables which have dropped out. The list ‘changedVariables’ holds variables which have changed significantly according to the parameters which control comparison.

Request

POST /xplainsession

Returns

A JSONOnject with the three elements ‘additionalVariables’, ‘changedVariables’, and ‘removedVariables’.

JSON Schema

getModelDifference
type	object
properties
method	type	string
	default	getModelDifference
modelName	The name of the model which serves as a basis for comparison.
	type	string
compareToModelName	The name of the model which is compared to the base model. If not given it is assumed that the base model has a stashed (=older) version against which comparison is done.
	type	string
minDiffBetaAbsolute=0.03	The minimum difference in beta required to consider two variables a different.
	type	double
minDiffBetaRelative=0.3	The minimum relative difference in beta required to consider two variables a different.
	type	double
minDiffImpact=5.0	The minimum difference in impact required to consider two variables a different.
	type	double
adjustForDifferentTargetProbability=FALSE	The two models might target to be explained events in time frames of different length. As a result betas will also be different. If the parameter adjustForDifferentTargetProbability is set to TRUE, the ratio of the overall target probability of the two models will be used to scale betas accordingly when comparing.
	type	boolean

getPathForStates

Get the path for the specified states in a certain attribute. WARNING: While state names are case-sensitive in general, they are treated as case-insensitive by this method!

Request

POST /xplainsession

Returns

{String[]} return.statesNotFound An array holding the names that are not contained as states in the specified attribute.

JSON Schema

getPathForStates
type	object
properties
method	type	string
	default	getPathForStates
object	The target object.
	type	string
dimension	The target dimension.
	type	string
attribute	The target attribute to be checked for the states.
	type	string
states	The states to be found within the attributes state hierarchy.
	type	string[]

getProgress

Get progress information about running jobs.

Request

POST /xplainsession

Returns

{Number} return.totalLoad An integer characterizing the total load (total number of entities to be processed). The special

value -1 indicates an empty task list.

JSON Schema

getProgress
type	object
properties
method	type	string
	default	getProgress

getSelectedInstances

getSelectedInstances retrieves the currently selected instances in a JSON format.

Example:

{
     "method": "getSelectedInstances",
     "elements": [
         {"object": "Person"},
         {"object": "Diagnosis", "dimension": "Physician"},
         {"object": "Prescription", "dimension": "Rx Code", "attribute": "ATC Hierarchy", "level": 2},
         {"object": "Prescription", "dimension": "Rx Code", "attribute": "Substance"}
     ],
     "maxNumberInstances": 5
     // "keys": [ "376", "5801", "11601" ]
}

The elements array defines which parts of an object are retrieved. It is an array of x-element paths, each one referring to an Xplain artifact, an object, a dimension or an attribute. In the above example all dimensions and attributes from the “Person” object are retrieved. as only the object is given in the x-element path. From the object “Diagnosis” only the dimension “Physician” is pulled with all its attributes. From the object “Prescriptions” only two specific attributes at the dimension “Rx Code” are written into the resulting JSON document. For the attribute “Substance” the values of the first level of the attribute are written, as no level is given (default is the first level values). For the attribute “ATC Hierarchy” values on the second level of the attribute are given.

Optionally an array of keys may be provided to pull data only for those keys, e.g. only for the patients with those keys.

To avoid that large amounts of data are pulled via the web-interface, the method is limited less then 100 instances. See also the method saveSelectedInstances for a method which allows to save a large amount of instances to file or a number of files.

Request

POST /xplainsession

Returns

{Array of JSON Objects} The object instances in a JSON format.

JSON Schema

getSelectedInstances
type	object
properties
method	type	string
	default	getSelectedInstances
elements	The elements (objects, dimensions and attributes) which should be written into the resulting JSON documents.
	type	json array
selectionSet	With this parameter you may specify the selection set for which to retrieve the detailed data. If not given the default is globalSelections (the standard yellow selection set in the Object Explorer).
	type	string
keys	An array of root object keys.
	type	array of string
maxNumberInstances	The maximum number of instances with are retrieved.
	type	integer

getSelectedRootObjectKeys

getSelectedRootObjectKeys retrieves the keys for the root object according to the current global selections.

See also related methods, e.g. saveSelectedRootObjectKeys or getSelectedInstances and getRootObjectDimensionsAsCSV.

Request

POST /xplainsession

Returns

{Array of String} An array with the keys.

JSON Schema

getSelectedRootObjectKeys
type	object
properties
method	type	string
	default	getSelectedRootObjectKeys

getSelectedStatesForLevel

Get the selected states for a specified level.

See also #getStatesListForLevel

Request

POST /xplainsession

Returns

The JSON array of selected states on the specified level.

JSON Schema

getSelectedStatesForLevel
type	object
properties
method	type	string
	default	getSelectedStatesForLevel
selection	The selection.
	type	string
levelName	The name of the level within the attributes state hierarchy.
	type	string

getSession

Get the session as JSON document.

Request

POST /xplainsession

Returns

The current state of the session in JSON format.

Example:

{ “method”: “getSession” // as an alternative method name “getSessionModel” will also work }

The session is a “model” of current status of a client’s interaction with the system. Most method calls anyhow return this session (or the recent changes to the session). In case the client has lost the session status (e.g. because the browser has crashed), you may just “restart” and with getSession get all relevant session status information.

JSON Schema

getSession
type	object
properties
method	type	string
	default	getSession

getStateHierarchy

Get the states of a given attribute. The results are returned in a hierarchical structure of states and children states.

Example:

{
    "method": "getStateHierarchy",
    "object": "Prescription",
    "dimension": "Drug Code",
    "attribute": "Anatomic Classification Hierarchy",
    "state": "Nervous System",
    "levels": 3
}

This example would return a sub-tree of the hierarchical attribute “Anatomic Classification Hierarchy”, containing all descendants up to three levels of the state “Nervous System”.

Request

POST /xplainsession

Returns

{Object} return.stateHierarchy The requested (partial) state hierarchy.

JSON Schema

getStateHierarchy
type	object
properties
method	type	string
	default	getStateHierarchy
object	The name of the object.
	type	string
dimension	The name of the dimension.
	type	string
attribute	The name of the attribute.
	type	string
state	The name of a state in the attributes hierarchy. If state is not specified, the root state of the attribute will be taken as default.
	type	string
levels	The levels of hierarchy to be returned. If levels is not specified, the maximum levels of the hierarchy will be considered.
	type	number

getStatesListForLevel

Get the list of states for a specified level of an attribute’s state hierarchy.

See also #getSelectedStatesForLevel

Request

POST /xplainsession

Returns

A JSON array of the states on the specified level.

JSON Schema

getStatesListForLevel
type	object
properties
method	type	string
	default	getStatesListForLevel
object	The object name.
	type	string
dimension	The dimension name.
	type	string
attribute	The attribute name.
	type	string
levelName	The level name in the attributes state hierarchy.
	type	string
levelNumber	The level number in the attributes state hierarchy.
	type	number
sort	A flag signaling whether the states should be sorted.
	type	boolean

getTreeContainingString

Get the subtree of an attribute’s state hierarchy that contains a certain substring.

Example:

{
    "method": "getTreeContainingString",
    "object": "Patient",
    "dimension": "Health insurance",
    "attribute": "Health insurance",
    "string": "BKK",
    "caseSensitive": true
}

Request

POST /xplainsession

Returns

{Object} return.treeContainingString A JSON for the subtree that contains all states containing the search string.

JSON Schema

getTreeContainingString
type	object
properties
method	type	string
	default	getTreeContainingString
object	The object of the dimension/attribute to be searched in.
	type	string
dimension	The dimension of the attribute to be searched in.
	type	string
attribute	The attribute to be searched in.
	type	string
string	The search string.
	type	string
caseSensitive=false	Signals whether matching should be done case-sensitive or not.
	type	boolean
subtreeLeafFlags=true	Signals whether the leaf flags should be with regard to the search-induced subtree (true) or with regard to the whole state tree of the complete attribute (false).
	type	boolean

goBackInSelections

Goes back to the selection status one or a number of steps in selections history.

Request

POST /xplainsession

Returns

Current status of the session as JSON with the previous selection.

JSON Schema

goBackInSelections
type	object
properties
method	type	string
	default	goBackInSelections
steps=1	Number of steps to go back in selections history.
	type	integer

goForwardInSelections

Goes forward the specified number of steps in selections history.

Request

POST /xplainsession

Returns

Current status of the session as JSON with the forwarded selections.

JSON Schema

goForwardInSelections
type	object
properties
method	type	string
	default	goForwardInSelections
steps=1	Number of steps to go forward in selections history.
	type	integer

importQuery

Load a query/request from a file (on the server). A synonym is #importRequest. See also #saveQuery / #saveRequest

Example:

{
    "method": "importQuery",
    "fileName": "my_query.json"
}

Request

POST /xplainsession

Returns

The current status of the session with the loaded query as JSON.

JSON Schema

importQuery
type	object
properties
method	type	string
	default	importQuery
file	The file descriptor of the query file to be loaded.
	type	object

importRequest

Load a query/request from a file (on the server). A synonym is #importQuery. See also #saveQuery / #saveRequest

Example:

{
    "method": "importRequest",
    "fileName": "my_query.json"
}

Request

POST /xplainsession

Returns

The current status of the session with the loaded query as JSON.

JSON Schema

importRequest
type	object
properties
method	type	string
	default	importRequest
file	The file descriptor of the query file to be loaded.
	type	object

importSelections

Load selections from a file (on the server). See also #exportSelections and #downloadSelections

Example:

{
    "method": "importSelections",
    // "fileName": "my_selections.xselection" // deprecated
    "file": {
        "ownership": "PUBLIC", // or "TEAM" / "USER"
        "fileType": "XSELECTION", // Could be left out
        "filePath": ["my_selections.xselection"]
        // , "team": "my_team"
        // , "user": "my_user"
    }
}

Request

POST /xplainsession

Returns

The current status of the session with the loaded selections as JSON.

JSON Schema

importSelections
type	object
properties
method	type	string
	default	importSelections
file	The file descriptor of the selection file to be loaded.
	type	object
selectionSet=globalSelections	The optional name of the selection set into which to import the selections (if not given the default / global selections are assumed).
	type	string

killTasks

Kill all submitted tasks.

Request

POST /xplainsession

Returns

The current status of the session as JSON.

Example:

{ “method”: “killTasks” }

JSON Schema

killTasks
type	object
properties
method	type	string
	default	killTasks

loadAnalysis

Loads an analysis from disk previously saved with the method saveAnalysis. After loading, all existing queries are immediately re-computed based on the current data. In case underlying data (XTables) have changed since last saving the numbers will reflect the new data. Artifacts (e.g. relative time dimensions, aggregation dimensions …) which this analysis requires are automatically re-generated. If a conflicting artifact already exists (same place, same name but logically different) an exception is thrown.

See also the method resumeAnalysis.

Request

POST /xplainsession

Returns

Current status of the session as JSON with the updated requests.

JSON Schema

loadAnalysis
type	object
properties
method	type	string
	default	loadAnalysis
fileName	The name of the file from which to load.
	type	string
retain	An optional list of dimensions which should not be re-generated but kept with the existing logic.
	type	array of xelementpath

loadObject

Load the XTable for an object from a file.

Request

POST /xplainsession

Returns

The current status of the session as JSON with the loaded object.

JSON Schema

loadObject
type	object
properties
method	type	string
	default	loadObject
file	The file descriptor of the file where the object has been persisted. Example: { method: loadObject, file: { fileType: XTABLE, // If this entry is missing, it is set automatically. ownership: PUBLIC, // or TEAM, or USER + the corresponding entry below // team: example_team, // user: example_user, filePath: [Patient.xtable] } }
	type	object

modifyAggregation

Replace an aggregation in an existing request.

Example:

{
    "method": "modifyAggregation",
    "requestName": "My Request",
    "position": 1, // This means second position since indexing starts with 0.
    "aggregation": {
        // An aggregation as JSON object
        "aggregationType": "SUM",
        "object": "Customer",
        "dimension": "Income"
    }
}

Request

POST /xplainsession

Returns

Current status of the session as JSON.

JSON Schema

modifyAggregation
type	object
properties
method	type	string
	default	modifyAggregation
requestName	The name of the request to which an aggregation should be added.
	type	string
position=0	The index specifying the position (counting starts with 0).
	type	number
aggregation	A JSON object representing an aggregation. This argument may also encode a computed measure, i.e., a function of aggregations already existing in the query (see example).
	type	object

openAttribute

openAttribute is a convenience method which is identical to openQuery, whereby the group-by comprises the first level states and the root state of the given attribute.

Request

POST /xplainsession

Returns

Current status of the session as JSON with additional results for the opened attribute.

JSON Schema

openAttribute
type	object
properties
method	type	string
	default	openAttribute
requestName	The name / ID of the resulting open query.
	type	string
object	The object name.
	type	string
dimensions	The dimension name.
	type	string
attribute	The attribute name.
	type	string
selectionSet=globalSelections	The selection set the resulting query should refer to - if left void, the method openAttribute assumes the standard global selections
	type	string

openQuery

openQuery is identical to openRequest - just another, sometimes more intuitive method name. For more details on parameter see the documentation of openRequest.

Request

POST /xplainsession

Returns

Current status of the session as JSON with additional results for the initiated query.

JSON Schema

openQuery
type	object
properties
method	type	string
	default	openQuery
request	The statistics request in json object format.
	type	json object
deleteIfExists	optional parameter - if set to true a prior existing query with that names is deleted
	type	boolean

openRequest

openRequest is the dynamic counterpart to executeRequest. The format of this call is identical to executeRequest. The only difference is that selections specified in the request are dynamically amended by the current global selections. This means: Selections for attributes explicitly given in the request are kept constant. Selections for other attributes which are currently existing in the global selections are pulled from there - initially any any time the global selections have changed (e.g. with the command select or clearSelections). Any time the global selections change, all requests initiated with an “openRequest” command are re-computed to reflect the changes in selection. This feature is the basis to implement an interactive usability concept such as in the Xplain Object Explorer.

openRequest is identical to openQuery - just another, sometimes more intuitive method name.

Example:

{
   "method" : "openRequest",
   "request" : {
      "requestName": "Simple Request",
      "groupBys": [
         {"attribute": {"object": "Patient", "dimension": "Geschlecht", "attribute": "Geschlecht" }}
      ],
      "aggregations": [
         {"aggregationType": "SUM", "object": "RX", "dimension": "Amount"}
      ],
      "selections" : [
         {   "attribute": { "object": "Patient", "dimension": "Region", "attribute": "Region" },
             "selectedStates" : ["Berlin"]
         }
      ]
   }
}

In the above example, a query is opened where the selection / where clause Region = Berlin is kept fix, but selections for any other attributes currently existing in the global selections are dynamically filled in from there. If no selections are given explicitly in the above method call, all selections from the globals selections are filled in.

Request

POST /xplainsession

Returns

Current status of the session as JSON with additional results for the initiated query.

JSON Schema

openRequest
type	object
properties
method	type	string
	default	openRequest
request	The statistics request in json object format.
	type	json object
deleteIfExists	optional parameter - if set to true a prior existing query with that names is deleted
	type	boolean

openSequence

openSequence is equivalent to an initial buildSortedSequence and an addition openSequenceQueries, i.e. this method immediately opens all the queries which are typically required to visualize the sequence. openSequence accepts all the same parameters as buildSortedSequence in combination with openSequenceQueries.

Example::

{
   "method": "openSequence",
   "sortDimension" : {"object" : "Prescription", "dimension" : "Date"},
   "dimensionsToReplicate" : [
         {"object" : "Prescription", "dimension" : "Rx Code"}
   ],
   "ranks" : [-1, -2, -3],
   "namePostfixes": ["Rx before Death"],
   "zeroPointDimension": {"object" : "Person", "dimension" : "Date of Death"},
   "sequenceNames" : ["Drugs before Death"],
   "openMarginalQueries" : true,
   "openTransitionQueries" : true
}

This example will generate the sequences of prescriptions before death and will immediately open marginal queries for all the dimensions/attributes in the sequence and also queries describing the transitions between elements in the sequence.

Request

POST /xplainsession

Returns

{Object} Current status of the session as JSON with the defined sequences

JSON Schema

openSequence
type	object
properties
method	type	string
	default	openSequence
parameters	See the parameter of buildSortedSequence and openSequenceQueries.
	type	…

openSequenceQueries

openSequenceQueries opens the queries typically required for visualizing a sequence.

Request

POST /xplainsession

Returns

{Object} Current status of the session as JSON with the additional open queries

JSON Schema

openSequenceQueries
type	object
properties
method	type	string
	default	openSequenceQueries
sequenceNames	Names of the sequences previously generated for which to open the queries.
	type	array of string
openMarginalQueries=true	If true, queries for the marginal distributions for each sequence step will be opened (one-dimensional).
	type	boolean
openTransitionQueries=false	If true, queries which describe the transitions between each step will be opened (two-dimensional).
	type	boolean
selectionSet=globalSelections	If specified, the sequence queries pull floating selections from the specified set
	type	string

pauseQuery

An alternative name method pauseRequest - see this method.

Request

POST /xplainsession

JSON Schema

pauseQuery
type	object
properties
method	type	string
	default	pauseQuery

pauseRequest

With the method pauseRequest you may stop a query from being re-computed with each change in selections. Results are no longer transmitted. You may unpause the query with the corresponding command unpauseQuery. An alternative method name is pauseQuery.

Request

POST /xplainsession

Returns

Current status of the session as JSON without results for the given request/query.

JSON Schema

pauseRequest
type	object
properties
method	type	string
	default	pauseRequest
requestName	The name / ID of the query which should be paused.
	type	string
keepLastResults=false	If set to true the most recent results before pausing are kept.
	type	boolean

pin

Once you have selected a number of objects (e.g. “customers” or “patients”) or a set of keys of a categorial dimension, you might want to “pin” the selected segment in terms of a new dimension. You can to that with the pin or pinObjects command. As a result a new binary dimension with a binary attribute is created. The currently selected objects are assigned to one of the two states. This may serve to implement set operations, for example you may select objects not in a segment or in the intersection of a two segments etc.

The generated pin refers to the current global selection on the object where you put the pin. Those selections may refer to dimension (e.g. aggregation dimensions) which have a floating semantics. Per default all floating semantics is “fixed” before generating the pin such that the pin finally has a fixed semantics (internally a copy of the corresponding aggregation dimensions is generated with fixed semantics). In case you want to keep the semantics of the generated pin floating as well, set the parameter fixAllFloatingSemantics to false.

A pin will ignore selections on the dimension “.RandomSamplingSegments” which is used for sampling, such that the the logic of the pin will apply also outside of the random segment which is currently used for sampling.

Instead of pinning the current logical selection, you may also generate pins in terms of an explicitly given list of keys. The keys to pin may also be read from an Excel file.

Example:

{
     "method" : "pin",
     "object" : "Patient",
     "pinName" : "Pinned Patients",
}

Pins the currently selected patients (current globals selections) by creating a new dimension with name “Pinned Patients”.

Example:

{
     "method" : "pin",
     "object" : "Sold Products",
     "dimension" : "Product Keys",
     "pinName" : "My Product Segment",
     "excelFileName" : "My Product Segment.xlsx"
}

Pins the product keys given in the excel file.

Example:

{
     "method" : "pin",
     "object" : "Machine",
     "pinName" : "Problem Machines",
     "keys" : [ "42", "2020" ]
}

Sets a pin on the two problem machines “42” and “2020”.

Request

POST /xplainsession

Returns

Current status of the session as JSON with updated results if the pin is immediately selected.

JSON Schema

pin
type	object
properties
method	type	string
	default	pin
object	The name of the object for which you would like to pin the selected instances.
	type	string
pinName	The name of the pin, i.e. the name of the new dimension and attribute.
	type	string
dimension	The dimension name in case you want to pin the values of a categorial dimension (instead of keys for object instances).
	type	string
excelFileName	Excel file name which provides a list of keys.
	type	string
keys	Explicitly given keys.
	type	array of string
selections	If given instead of other arguments, those selections are used as a logical definition of the pin.
	type	array of selections
attributes	If given instead of other arguments, selections in the listed attributes are used as a logical definition of the pin.
	type	string of string
logic=AND	One of the three values AND, OR or XOR. Different components of the given selections (selections on different attributes) are combined with the give boolean logic.
	type	string
selectPinnedObjects	If given and set to true, there is immediately a selection set to the pin, i.e. only then the pin is active.
	type	boolean
fixAllFloatingSemantics	If true all floating semantics is fixed, otherwise the pin itself becomes floating. This parameter is deprecated. Use the parameter fixExplicitSelections instead.
	type	boolean
fixExplicitSelections=none	This parameter may have one of the three values none (the default), all or only_propagate_upward. In case of none the selections for the pin are kept as they are, which means that the resulting pin hasnt necessarily a fixed semantics (may change in case the selections refer to a dimension which itself has floating semantics - this includes propagate upward dimensions). The name pin may be miss-leading in that case. If the parameter is set to all, all semantics will be fixed (indeed recursively, i.e., if the floating semantics emerges from a chain of references). In case of only_propagate_upward only propagate upward dimensions are fixed and are replaced by their non-floating counterpart (in this case non-recursively). This parameter offers an heuristics how to deal with the given selections before they are used as a part of the definition of the new dimension (it is not a part of the final definition of the resulting dimension). See also the equivalent parameter in #addAggregationDimension, # addRelativeTimeDimensions and #buildSortedSequence.
	type	enum

pinObjects

Just an alias name for the method pin. See the method pin for details.

Request

POST /xplainsession

JSON Schema

pinObjects
type	object
properties
method	type	string
	default	pinObjects

putSelection

Put a selection into an existing request. “Put” means that in case there is already a selection on the given attribute, then this selection is overridden.

Example:

{
    "method": "putSelection",
    "requestName": "My Request",
    "selection": {
        // A selection as JSON object
    }
}

Request

POST /xplainsession

Returns

Current status of the session as JSON.

JSON Schema

putSelection
type	object
properties
method	type	string
	default	putSelection
requestName	The name of the request to which the selection is associated.
	type	string
selection	A JSON object representing a selection - see the description of the generic artifacts.
	type	object

putUserData

Add some data in terms of a JSON document to the current session or specifically to a request. Data is put based on a key and later retrieved using that key. The purpose of this method is to allow users / developer to store / persist data in a session (server side). Once the session JSON document is returned to the client it will hold those data (see the property “userData”) and can be read from there by the client. Typically this is used when developing clients which need to store e.g. additional formatting information. When saving a session (an analysis) those data are persisted with the session and will be there once loading the session again.

Request

POST /xplainsession

Returns

Current status of the session as JSON with the additional JSON data.

JSON Schema

putUserData
type	object
properties
method	type	string
	default	putUserData
key	The key under which data are stored (userKey is also allowed as a parameter name).
	type	string
data	The data to be stored as a JSON object (jsonObject is also allowed as a parameter name).
	type	josonobject
request	Optional a requestID can be give in which case the data are specifically attached to the request - otherwise to the session.
	type	string

refitModel

‘refitModel’ Re-computes the parameters of a noisy-or model, whereby a different significance or new target time frame can be given.

Request

POST /xplainsession

Returns

The session document as JSON.

JSON Schema

refitModel
type	object
properties
method	type	string
	default	refitModel
modelName	The name of the model which will be re-fitted.
	type	string
significance	A new significance - if not given the previous significance will be used.
	type	double
fixExistingVariables=TRUE	If TRUE, the existing variables will not be pruned.
	type	boolean
targetTimeRange	If this selection is given, it is used as a new target time frame. It needs to be a selection on the target time dimension of the original model.
	type	selections
newModelName	The name of the new, re-fitted model which will be re-fitted. In case you provide a new targetTimeFrame the parameter newModelName is mandatory.
	type	string

removeAggregation

Remove an aggregation from a request.

Example:

{
    "method": "removeAggregation",
    "requestName": "My Request",
    "position": 2 // Refers to the third aggregation, since counting starts with 0.
}

The example request removes the third aggregation from the request with name “My Request”.

Request

POST /xplainsession

Returns

Current status of the session as JSON.

JSON Schema

removeAggregation
type	object
properties
method	type	string
	default	removeAggregation
requestName	The name (ID) of the request from which the aggregation should be removed.
	type	string
position	The index of the aggregation (counting starts with 0). As each request may have several aggregations, each aggregation is addressed by its position. This parameter specifies which aggregation should be removed.
	type	number

removeAttribute

Remove an attribute from the current analysis within the current session. In case of “global” dimensions, does not permanently remove or delete this attribute but instead hides it within the current session.

Example:

{
    "method": "removeAttribute",
    "object": "Customer",
    "dimension": "Age",
    "attribute": "Age Group"
}

Request

POST /xplainsession

Returns

Current status of the session as JSON with the attribute removed.

JSON Schema

removeAttribute
type	object
properties
method	type	string
	default	removeAttribute
object	The object which holds the dimension.
	type	string
dimension	The dimension which holds the attribute.
	type	string
attribute	The attribute to be removed.
	type	string

removeAttributeIfExists

Remove an attribute from a dimension - see the method removeAttribute: the only difference is that this method will not report an error if the referenced attribute does not exist.

Example:

{
    "method": "removeAttributeIfExists",
    "object": "Customer",
    "dimension": "Age",
    "attribute": "Age Group"
}

Request

POST /xplainsession

Returns

Current status of the session as JSON with the attribute removed.

JSON Schema

removeAttributeIfExists
type	object
properties
method	type	string
	default	removeAttributeIfExists
object	The object which holds the dimension.
	type	string
dimension	The dimension which holds the attribute.
	type	string
attribute	The attribute to be removed.
	type	string

removeDimension

Remove a dimension (and all of its attributes) from the current analysis within the current session. In case of “global” dimensions, does not permanently remove or delete this dimension but instead hides it within the current session.

Example:

{
    "method": "removeDimension",
    "object": "Customer",
    "dimension": "Age"
}

Request

POST /xplainsession

Returns

Current status of the session as JSON with the dimension removed.

JSON Schema

removeDimension
type	object
properties
method	type	string
	default	removeDimension
object	The object which holds the dimension.
	type	string
dimension	The dimension to be removed.
	type	string

removeDimensionIfExists

Remove a dimension from the object tree - see the #removeDimension : the only difference is that this method will not report an error if the referenced dimension is not existing.

Example:

{
    "method": "removeDimensionIfExists",
    "object": "Customer",
    "dimension": "Age"
}

Request

POST /xplainsession

Returns

Current status of the session as JSON with the dimension removed.

JSON Schema

removeDimensionIfExists
type	object
properties
method	type	string
	default	removeDimensionIfExists
object	The object which holds the dimension.
	type	string
dimension	The dimension to be removed.
	type	string

removeGroupBy

Removes an existing group-by for the given attribute in the given request/query.

Example:

{
    "method": "removeGroupBy",
    "requestName": "My Request",
    "attribute": {
            "object": "Customer",
            "dimension": "Gender",
            "attribute": "Gender"
    }
}

Request

POST /xplainsession

Returns

Current status of the session as JSON with new results for the corresponding request

JSON Schema

removeGroupBy
type	object
properties
method	type	string
	default	removeGroupBy
requestName	The name/ID of the request to which a group-by should be added.
	type	string
attribute	The path to an attribute.
	type	attribute

removeObject

Removes the specified object from its parent object.

Example:

{
    "method": "removeObject",
    "object": "Prescription"
}

Request

POST /xplainsession

Returns

The current status of the session as JSON (without the removed sub-object).

JSON Schema

removeObject
type	object
properties
method	type	string
	default	removeObject
object	The name of the object to be deleted.
	type	string

removeObjectIfExists

Removes the specified object (if it exits) from its parent object. No error message is issued if no such object exists.

Example:

{
    "method": "removeObjectIfExists",
    "object": "Prescription"
}

Request

POST /xplainsession

Returns

The current status of the session as JSON (without the removed sub-object).

JSON Schema

removeObjectIfExists
type	object
properties
method	type	string
	default	removeObjectIfExists
object	The name of the object to be deleted.
	type	string

removeSelectionSet

Removes the set with given name from the defined selection sets.

Request

POST /xplainsession

Returns

Current status of the session as JSON with the selection set removed.

JSON Schema

removeSelectionSet
type	object
properties
method	type	string
	default	removeSelectionSet
name	The name (ID) of the set which is to be removed.
	type	string

renameDimension

Rename a dimension. The method will report an error if the dimension is used somewhere (e.g. in the current global selections or in a query) or if it is a dimension not generated within the current session (i.e. a dimension which existed a priori in one of the XTables of the startup configuration).

Request

POST /xplainsession

Returns

Current status of the session as JSON with the dimension renamed.

JSON Schema

renameDimension
type	object
properties
method	type	string
	default	renameDimension
dimension	The dimension to be renamed specified as an XElementPath ({object: …, dimension: …}).
	type	xelementpath
newName	The new name of the dimension.
	type	string

replicateDimension

Replicates a dimension into a sub-object.

Example:

{
  "method": "replicateDimension",
  "dimension": {"object":"Hospital cases","dimension":"HC Admission date"},
  "toObject": "Hospital diagnoses",
  "name": "Replicated Admission Date"
}

With the above command the dimension “HC Admission date” of object “Hospital cases” will also show in the sub-object “Hospital diagnoses”. All attributes of the original dimension will also be copied.

Note: Replicating dimensions into lower level objects (i.e., flattening an object model) is a workaround if no other options are available. In general this is not necessary. In some cases, e.g., the XOE does not allow access to super level objects and dimension. In those cases you may use this method to replicate a dimension down the object hierarchy.

Request

POST /xplainsession

Returns

The session document including the replicated dimension.

JSON Schema

replicateDimension
type	object
properties
method	type	string
	default	replicateDimension
dimension	The dimension which will be replicated. It needs to be a numeric dimension.
	type	dimension path
toObject	The object into which the dimension should be replicated. It needs to be a sub-object of the object where the replicated dimension comes from.
	type	string
name	Name of the new dimension. If not given the name will be identical to that of the replicated dimension.
	type	string

resumeAnalysis

See the method “loadSession” - the only difference to that is that the session JSON document is not loaded from a file, but is given in terms of the parameter “session”.

Request

POST /xplainsession

Returns

Current status of the session as JSON with the updated requests.

JSON Schema

resumeAnalysis
type	object
properties
method	type	string
	default	resumeAnalysis
session	A session as a JSON object.
	type	jsonobject
retain	An optional list of dimensions which should not be re-generated but kept with the existing logic.
	type	array of xelementpath

saveAnalysis

Saves the current status of the session (= an “analysis”) in terms of a JSON replica of the session to disk (in the sub-folder “sessions”). The given file name will be amended with the extension “.xanalysis” if not existing. See also the method getAnalysis.

Request

POST /xplainsession

Returns

void.

JSON Schema

saveAnalysis
type	object
properties
method	type	string
	default	saveAnalysis
file	The file descriptor of the file where to save the analysis.
	type	object
rebuildAllDimensionsWhenLoading=false	If set to true all dimensions in the object tree will be rebuilt, even if not required for the current analysis (in any queries or selections).
	type	boolean
dropResults=false	Optional parameter which may be used to drop results before saving the analysis so to only persist the query structure without results.
	type	boolean
keepOnlyArtefactDefinitions=false	Optional parameter which may be used to drop all data except artefact definitions (e.g. drop data the user has added to the session, formatting data of the frontend, …) before saving the analysis.
	type	boolean

saveAsCSV

saveAsCSV writes for all object instances currently selected (current global selections) data into a flat csv file. Data for which objects, dimensions and attributes to write are configured in the elements parameter. The objects configured there need to be from one object branch (no sibling objects). Only then data can be “flattened” into one csv table. See the method getSelectedInstances for more details how to configure which objects dimensions and attributes to write.

See also related methods, e.g. saveSelectedRootDimensionsAsCSV, saveSelectedRootObjectKeys or saveSelectedInstances.

Request

POST /xplainsession

JSON Schema

saveAsCSV
type	object
properties
method	type	string
	default	saveAsCSV
elements	The elements (objects, dimensions and attributes) which should be written into the resulting JSON documents.
	type	json array
keys	An array of root object keys which can be used to constrain written data to only those keys.
	type	string[]
fileName	The name of the csv file. If left void the keys will be written to the file with name Flat Table Export.csv.
	type	string
charset	The name of the character set for encoding the csv file (e.g., UTF-8, ISO-8859-1, US-ASCII).
	type	string
outerJoin=false	If set to true, the export will implement an outer join logic, i.e., if an object instance does not have data for one its sub-objects specified in the export, then nevertheless one line is written for such an object where data for missing sub-objects are coded as null.
	type	boolean

saveQuery

Save a query/request to a file (on the server). A synonym is #saveRequest. See also #importQuery / #importRequest

Example:

{
    "method": "saveQuery",
    "requestId": "my_query_id",
    "fileName": "my_query.json"
}

Request

POST /xplainsession

JSON Schema

saveQuery
type	object
properties
method	type	string
	default	saveQuery
fileName	The name of the destination file.
	type	string
requestId	The name/id of the query/request.
	type	string

saveRequest

Save a query/request to a file (on the server). A synonym is #saveQuery. See also #importQuery / #importRequest

Example:

{
    "method": "saveRequest",
    "requestId": "my_query_id",
    "fileName": "my_query.json"
}

Request

POST /xplainsession

JSON Schema

saveRequest
type	object
properties
method	type	string
	default	saveRequest
fileName	The name of the destination file.
	type	string
requestId	The name/id of the query/request.
	type	string

saveRootDimensionsAsCSV

saveRootDimensionsAsCSV writes for all object instances currently selected (current global selections) the dimension at the root object to a csv file. Which dimensions to write can be configured. See the method getSelectedInstances for more details how to configure which dimensions and attributes to write.

See also related methods, e.g. getSelectedRootObjectKeys or saveSelectedInstances.

Request

POST /xplainsession

JSON Schema

saveRootDimensionsAsCSV
type	object
properties
method	type	string
	default	saveRootDimensionsAsCSV
elements	The elements (objects, dimensions and attributes) which should be written into the resulting JSON documents.
	type	json array
keys	An array of root object keys which can be used to constrain written data to only those keys.
	type	array of string
fileName	The name of the csv file. If left void the keys will be written to the file with name Selected Root Dimensions.csv.
	type	string

saveSelectedInstances

saveSelectedInstances saves the currently selected instances to file in a JSON format.

See also the method getSelectedInstances for more details on how to define which parts of an object (which sub-objects, dimensions and attributes) are to be exported.

Request

POST /xplainsession

JSON Schema

saveSelectedInstances
type	object
properties
method	type	string
	default	saveSelectedInstances
fileName	Name of the file.
	type	string
split	If a number 1 is given, data will be split into multiple files.
	type	integer

saveSelectedRootObjectKeys

saveSelectedRootObjectKeys retrieves the keys for the root object according to the current global selections and writes them to a csv file.

See also related methods, e.g. getSelectedRootObjectKeys or saveSelectedInstances and saveRootObjectDimensionsAsCSV.

Request

POST /xplainsession

JSON Schema

saveSelectedRootObjectKeys
type	object
properties
method	type	string
	default	saveSelectedRootObjectKeys
fileName	The name of the csv file. If left void the keys will be written to the file with name Selected Root Object Keys.csv.
	type	string

saveToFile

Save a string to a file on the server.

Request

POST /xplainsession

JSON Schema

saveToFile
type	object
properties
method	type	string
	default	saveToFile
fileType	The type of file (CONFIG, DATA, RESULT, SESSION, TEMP, USER_CONFIG, SCRIPT, SELECTION, APPLICATION). (This type determines the directory, where the file resides.)
	type	string
fileName	The name of the destination file.
	type	string
content	The content/string to be stored.
	type	string

select

select puts one or multiple selections to the “global selections” (see the description of the dynamic user interaction). “Put” thereby means, the selections will be put for the attribute given in the selection, i.e. it will override existing selections for the given attribute. After calling the select method all open requests which are affected by this selection are re-computed. The returned session document is updated with the new open request results.

Example:

{
     "method": "select",
     "selection": {
         "attribute" : { "object" : "Patient", "dimension" : "Gender", "attribute" : "Gender" },
         "selectedStates" : ["male"]
    }
}

It is also possible to use wildcards to select several states matching a certain pattern.

Example:

{
     "method": "select",
     "selection": {
         "attribute" : { "object" : "Prescription", "dimension" : "PZN", "attribute" : "ATC Class" },
         "wildcardPattern" : "D03%",
         "wildcardSymbold" : "%"
    }
}

Specifying a wildcard symbol is optional, the default is “*”.

Example:

{
     "method": "select",
     "selection": {
         "attribute" : { "object" : "Prescription", "dimension" : "PZN", "attribute" : "ATC Class" },
         "wildcardPattern" : "D03*"
    }
}

For matching more complicated patterns, regular expressions can be used. The corresponding syntax can be found here: https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/regex/Pattern.html

Example:

{
     "method": "select",
     "selection": {
         "attribute" : { "object" : "Machine", "dimension" : "Serial Number", "attribute" : "Serial Number" },
         "regexPattern" : "[a-z,A-Z]*[0-9]+.*"
    }
}

Instead of a single selection an array of selections may be given:

Example:

{
     "method": "select",
     "selections": [
         { <a selection in JSON format> },
         { <a selection in JSON format> }
    ]
}

Request

POST /xplainsession

Returns

Current status of the session as JSON with new results according to the updated selections.

JSON Schema

select
type	object
properties
method	type	string
	default	select
selection	A selection JSON object (see description of the generic artifacts).
	type	jsonobject
selections	An array of JSON objects, each one representing a selection.
	type	jsonarray
selectionSet	The optional name of the selection set where to put the selection - if not give, the global / default set is assumed.
	type	string

selectBetween

selectBetween selects all states between the given from and to value for the given attribute (See also the method select). The attribute needs to be an attribute of a numeric dimension. As of the current implementation, one of the two bounds is included and the other one is excluded. Which one is included depends on the setting for the attribute. One of the two bounds may be omitted, in which case all states below or above are selected. If the from or to value falls within the boundaries of a state, this state will be included into the selection.

This method might be soon replaced by something more convenient.

The following request for example selects all states of the attribute “Date” which are greater than 1.1.2014 (note that this mapping to a date depends on the time zone):

Example:

{
     "method": "selectBetween",
     "object" : "Customer",
     "dimension" : "Date",
     "attribute" : "Date",
     "lowValue" : 1388530800000
}

Request

POST /xplainsession

Returns

Current status of the session as JSON with new results according to the updated selections.

JSON Schema

selectBetween
type	object
properties
method	type	string
	default	selectBetween
object	The Object where the dimension and attribute is to be found.
	type	string
dimension	The dimension of the attribute.
	type	string
attribute	The attribute, either as string in combination with the dimension and object parameter or an XElementPath pointing to the attribute.
	type	string or xelementpath
from	Lower value
	type	number
to	Upper value
	type	number
lowValue	Lower value - just an alias for the from parameter
	type	number
highValue	Upper value - just an alias for the to parameter
	type	number

setDescription

A session may hold a description which can be set with this method. Typically this is use to describe the purpose of a session / an analysis which has been performed. The Object Explorer for example shows this description when clicking the corresponding info icon and allows to edit this description as an html document.

Request

POST /xplainsession

Returns

Current status of the session as JSON including the description.

JSON Schema

setDescription
type	object
properties
method	type	string
	default	setDescription
description	The description text.
	type	string

setFormat

Sets the format string for the given dimension. All dimensions which inherit format information will also immediately have this updated format in the session JSON.

Request

POST /xplainsession

Returns

Current status of the session as JSON including updated format information.

JSON Schema

setFormat
type	object
properties
method	type	string
	default	setFormat
dimension	A JSONObject representing the path to a dimension (i.e. with properties object and dimension).
	type	jsonobject
format	The format string.
	type	string

setMaxNrInstancesForRanking

Set the maximum number of instances allowed for ranking. Increasing this number might drastically increase the runtime when using ranking resources.

Request

POST /xplainsession

JSON Schema

setMaxNrInstancesForRanking
type	object
properties
method	type	string
	default	setMaxNrInstancesForRanking
maxNrInstancesForRanking	The maximum number to be set (or null if no limit should be applied).
	type	integer

setMaxOneDimGroupBySize

Sets the maximum size of of a one-dimensional group-by for the current session. The size of a group-by is the number of distinct states, e.g., if you define a “group by Product”, and there are 500 different states existing in the attribute “Product”, the size of the group-by is 500. The parameter setMaxOneDimGroupBySize defines a limit on each “one-dimensional” group-by, i.e. each component of a potentially multi-dimensional group-by. You can use this parameter to avoid that too large result sets are transmitted to web-based frontends.

Request

POST /xplainsession

Returns

void

JSON Schema

setMaxOneDimGroupBySize
type	object
properties
method	type	string
	default	setMaxOneDimGroupBySize
size	The maximum size
	type	integer

setPropagateSelectionsUpward

Set the upward propagation schema, i.e. from which objects selection propagate upward the object tree. For an explanation how selections propagate in a complex object model, see the description of the Object Analytics propagation schema.

Request

POST /xplainsession

Returns

Current status of the session as JSON with updated results according to propagated selections.

JSON Schema

setPropagateSelectionsUpward
type	object
properties
method	type	string
	default	setPropagateSelectionsUpward
propagateSelectionsUpward	Boolean flag setting upward propagation to on or off.
	type	boolean
objects	List of objects where to set the upward propagation flag - if omitted the flag will be set at all objects.
	type	array of string
selectionSet=globalSelections	The name of the selection set for which the upward propagation is to be set. If omitted the flag is set for the globalSelections.
	type	string

setReference

Set the given selections as a reference. Reference selections is an EXPERIMENTAL feature (beta feature), which might not be supported long term. As of the current status it will likely not be fully functional in combination with all other features.

Example:

{
    "method": "setReference",
    "referenceName": "Target Customers",
    "referenceSelections": [
        {
            // Selection 1 in JSON format
        },
        {
            // Selection 2 in JSON format
        }
    ]
}

Request

POST /xplainsession

Returns

Current status of the session as JSON together with the new reference.

JSON Schema

setReference
type	object
properties
method	type	string
	default	setReference
referenceName	An arbitrary but unique name for this reference.
	type	string
referenceSelections	An array of JSON objects representing selections. (See the section on the generic artifacts)
	type	object[]

setResidualAnalysisDefinition

Once you have started a residual analysis, you may change the parameters, e.g. set a different selection set for the residual analysis. See also the documentation of startResidualAnalysis.

Example:

{
     "method" : "startResidualAnalysis",
     "modelName": "My Discovery Model",
     "aggregation" : {"object" : "Prescriptions", "dimension" : "DDD", "aggregationType" : "SUM"},
     "selectionSet" : "selectionSet1"
}

Request

POST /xplainsession

Returns

Current status of the session as JSON with the adjusted queries describing the residual for the changed variable.

JSON Schema

setResidualAnalysisDefinition
type	object
properties
method	type	string
	default	setResidualAnalysisDefinition
modelName	The name of the model for with the analysis is to be started. The model needs to be already loaded/existing in the session, and the residual analysis already started.
	type	string
aggregation	The aggregation which defined the constructed independent variable.
	type	object
selectionSet=globalSelections	The selection set which defines the where-clause of the constructed independent variable.
	type	string

setSelectionSetForQuery

setSelectionsForQuery with the argument externalSelections (alias selectionSet) binds a open query to the given selection set. Per default an open query pulls its selections from the “globalSelections” - it is called an “open” query because it is open for any further selections added or removed to the global selections (dynamically pulls selections from that set). A query may be bound to a different selection set by providing the argument externalSelections - the query henceforth pulls its selections from the given set. You may also define a set of selections which are kept fix by means of the argument selections. Selections for the corresponding attributes are not dynamically pulled form an external selection set. For the general mechanism on fixed and floating selections see the general description of how a query is specified.

Request

POST /xplainsession

Returns

Current status of the session as JSON with updated results

JSON Schema

setSelectionSetForQuery
type	object
properties
method	type	string
	default	setSelectionSetForQuery
requestName	The name (=ID) of the query
	type	string
selectionSet	The name (=ID) of the selection set (alias externalSelections)
	type	string
externalSelections	The name (=ID) of the selection set (alias selectionSet)
	type	string
selections	A set for selections which will be applied as fixed selections to the query
	type	array of selection

setXcdDefaultConfigFile

Set the file, which is used as a the default configuration for the causal discovery algorithms.

Example:

{
     "method":"setXcdDefaultConfigFile",
     "configFile" : {"ownership" : "PUBLIC", "filePath" : ["Causal Discovery - deep.xmodel"]}
}

Request

POST /xplainsession

Returns

Current status of the session as JSON with the updated setting.

JSON Schema

setXcdDefaultConfigFile
type	object
properties
method	type	string
	default	setXcdDefaultConfigFile
configFile	The location configuration file, e.g. with ownership and file path. The file needs to be of type XMODEL.
	type	xfile

startResidualAnalysis

Once you have built or loaded a model you may start the residual analysis for that model. I.e., you may define your own factor (independent variable) and see the difference of the predicted target probability vs. the observed target probability (the residual of the model) in dependence of that factor. There are two queries automatically generated which serve that purpose: The average of the predicted probability of the model by the chosen independent variable, and the number of target and non-target cases by the chosen independent variable. In percentage values, the latter give you the observed target probability.

Usually the gap between the two should be small, meaning that the model provided a good prediction in dependence of the chosen variable (the residual / error of the model is small). If so, that means that there is no need to explicitly add this variable into the set of independent variables. Some of the independent variables already “do the job” - viewing those helps you to understand, why the chosen independent variable is not in the model. The approach is therefore also termed as “Xplain Why Not”: Understand why certain factors are not in the list of direct, potentially causal factors.

It may also happen that the observed residual is significant (i.e. the automated search algorithm has not spotted the residual and has not closed the gap by automatically constructing a corresponding variable). In that case, you may force that variable into the model - see the method “addVariable”. The model parameters will be re-computed and you will see the contribution of the new factor and whether it is indeed significant.

Example:

{
     "method" : "startResidualAnalysis",
     "modelName": "My Discovery Model",
     "object" : "Prescriptions",
     "selectionSet" : "globalSelections"
}

Starts the residual analysis for the given model. The variable is defined by the current selections in the globalSelections on the object “Prescriptions”. I.e., if you have currently selected the “pain killer” prescriptions, the defined variable is: number of pain killer prescriptions in the admitted time range prior to the target (or surrogate target) event. Usually it is helpful to choose a different selection set which has specifically been added for defining the semantics of the constructed variable. By simply choosing a different selection in that set, you may quickly evaluate variables with different semantics.

Example:

{
     "method" : "startResidualAnalysis",
     "modelName": "My Discovery Model",
     "aggregation" : {"object" : "Prescriptions", "dimension" : "DDD", "aggregationType" : "SUM"},
     "selectionSet" : "selectionSet1"
}

Starts the residual analysis whereby the defined variable is: sum of DDDs of the prescriptions of a patient according to current selections in selectionSet1.

Request

POST /xplainsession

Returns

Current status of the session as JSON with the additional queries describing the residual.

JSON Schema

startResidualAnalysis
type	object
properties
method	type	string
	default	startResidualAnalysis
modelName	The name of the model for with the analysis is to be started. The model needs to be already loaded/existing in the session.
	type	string
object	The name of the object which is used for build the independent variable. Either the object needs to be given or explicitly the argument aggregation.
	type	string
aggregation	The aggregation which defined the constructed independent variable.
	type	object
selectionSet=globalSelections	The selection set which defines the where-clause of the constructed independent variable.
	type	string

startSampling

startSampling starts the sampling mode whereby all queries are computed using a quasi-random sample. With method stopSampling you may terminate the sampling mode again.

@paramInteger} [sampleSize=10] The sample size in 1 of 1000, i.e. sampleSize=10 means a 1% sample. This parameter needs to be >0 and <1000.

Request

POST /xplainsession

Returns

Current status of the session as JSON with updated (sampled) results.

JSON Schema

startSampling
type	object
properties
method	type	string
	default	startSampling

stopResidualAnalysis

Request

POST /xplainsession

Returns

Current status of the session as JSON with without the residual analysis artifacts/queries.

JSON Schema

stopResidualAnalysis
type	object
properties
method	type	string
	default	stopResidualAnalysis
modelName	The name of the model for with the analysis is to be stoped.
	type	string

stopSampling

stopSampling terminates the sampling mode which has been started with the call startSampling

Request

POST /xplainsession

Returns

Current status of the session as JSON with updated (non-sampled) results.

JSON Schema

stopSampling
type	object
properties
method	type	string
	default	stopSampling

swapData

swapData swaps data in a session.

Example: swapping a single object, whereby the file comes from the public folder)

{

“method” : “swapData”, “swapObject” : “Operation”, “tableFileName” : “Operation_08.xtable”

}

Example: swapping multiple objects simultaneously, whereby using fully qualified file descriptors

{

“method” : “swapData”, “swapObjectList”: [

{

“swapObject” : “Part”, “file” : {“ownership”: “PUBLIC”, “fileType”: “XTABLE”, “filePath” : [“Part_08.xtable”] }

}, {

“swapObject” : “Operation”, “file” : {“ownership”: “PUBLIC”, “fileType”: “XTABLE”, “filePath” : [“Operation_08.xtable”] }

}

]

}

Request

POST /xplainsession

Returns

Current status of the session as JSON whereby queries are not yet recomputed with the new data

JSON Schema

swapData
type	object
properties
method	type	string
	default	swapData
swapObject	The object where data should be swapped.
	type	string
tableFileName	Name of the xtable file with the new data. If you use this parameter it is assumed that the file is in the public area. To specify the ownership explicitly use the file parameter.
	type	string
file	Fully qualified file descriptor instead of the parameter tableFileName (see example).
	type	file descriptor
swapObjectList	An array of objects to be swapped, each with the parameters swapObject and tableFileName/file (see example).
	type	array

unpauseRequest

The counterpart to the method unpauseQuery.

Request

POST /xplainsession

Returns

Current status of the session as JSON with results for the given request/query.

JSON Schema

unpauseRequest
type	object
properties
method	type	string
	default	unpauseRequest
requestName	The name / ID of the query which should be unpaused.
	type	string