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

  • 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

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