XplainClient — Session API

The XplainClient class is auto-generated from the OpenAPI spec and exposes every POST /api/session/{method} endpoint as a typed Python method.

All HTTP credentials (session cookies, CSRF token, connection pool) are inherited from the Xsession instance passed to the constructor.

Quick start:

from xplain import Xsession
from xplain.session_client import XplainClient

s = Xsession(url="http://myhost:8080", user="me", password="secret")
client = XplainClient(s)

# Session
state = client.get_session()

# Load data
client.load_object(file={"fileType": "XTABLE", "ownership": "PUBLIC",
                          "filePath": ["Patient.xtable"]})

# Query
client.execute_request(request={
    "requestId": "gender-count",
    "groupBys": [{"attribute": {"object": "Patient",
                                 "dimension": "Gender",
                                 "attribute": "Gender"}}],
    "aggregations": [{"aggregationType": "COUNT", "object": "Patient"}],
})

# Filter
client.select(selection={"attribute": {"object": "Patient",
                                        "dimension": "Region",
                                        "attribute": "Region"},
                          "selectedStates": ["Berlin"]})

Note

This file is auto-generated. Do not edit it directly. Regenerate with:

python xplain-openapi/generate_client.py

class xplain.session_client.XplainClient(xsession)

Bases: object

Typed client for the Xplain Session API.

Wraps a Xsession and exposes every POST /api/session/{method} endpoint as a named Python method.

Under the hood every method calls run() which posts to the legacy /xplainsession dispatch endpoint with the method name encoded in the JSON body:

POST /api/session/getSession   {}
      ↕  equivalent  ↕
POST /xplainsession            {"method": "getSession"}

This means all HTTP state — session cookies, CSRF token, connection pool — is managed exclusively by the Xsession.

Parameters: xsession (Xsession) – An authenticated Xsession instance.
Return type: None

Example:

from xplain import Xsession
from xplain.session_client import XplainClient

s = Xsession(url="http://myhost:8080", user="me", password="secret")
client = XplainClient(s)
state = client.get_session()

Session

XplainClient.get_session()

Get the current session state as JSON

Get the full session as a JSON document. Most method calls return the session anyway, but this method can be used to retrieve the current session state without making any changes. Useful when a client has lost its session state (e.g. after a browser crash) and needs to re-sync.

An alternative method name getSessionModel is also accepted.

Returns: The session state after the operation.
Return type: dict

Note

Also accepted by the server as: getSessionModel.

XplainClient.save_analysis(file=None, rebuild_all_dimensions_when_loading=False, drop_results=False, keep_only_artefact_definitions=False)

Save the current analysis session to a file

Persist the current analysis session (including all loaded objects, dimensions, requests, selections, and results) to a file for later retrieval.

Parameters

file (dict, optional) – File descriptor where the analysis should be saved. If not given, the session is returned as JSON and can be persisted client-side. FileDescriptor
rebuild_all_dimensions_when_loading (bool, optional, default=False) – If set to true, all dimensions in the object tree will be rebuilt even if not required for the current analysis.
drop_results (bool, optional, default=False) – If set to true, results are dropped before saving so only the query structure is persisted.
keep_only_artefact_definitions (bool, optional, default=False) – If set to true, all data except artefact definitions is dropped before saving.

Returns

The session state after the operation.

Return type

dict

XplainClient.get_analysis(file=None, rebuild_all_dimensions_when_loading=False, drop_results=True, keep_only_artefact_definitions=True, get_as_script=False)

Get the analysis as a JSON document (without loading it)

Read a previously saved analysis file and return its contents as a JSON document, without actually loading it into the current session.

Parameters

file (dict, optional) – The file descriptor of the file from where to pull the JSON content. FileDescriptor
rebuild_all_dimensions_when_loading (bool, optional, default=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).
drop_results (bool, optional, default=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.
keep_only_artefact_definitions (bool, optional, default=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.
get_as_script (bool, optional, default=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.

Returns

The session state after the operation.

Return type

dict

XplainClient.load_analysis(file, retain=None)

Load a previously saved analysis into the current session

Load a previously saved analysis file into the current session. This replaces the current session state (objects, dimensions, requests, selections) with the saved state.

Parameters

file (dict) – The name of the file from which to load. FileDescriptor
retain (list, optional) – An optional list of dimensions which should not be re-generated but kept with the existing logic.

Returns

The session state after the operation.

Return type

dict

XplainClient.resume_analysis(session=None, file=None, retain=None)

Resume a previously saved analysis (load without recomputing)

Load a previously saved analysis, restoring the session state including results as they were when saved, without recomputing requests. Faster than loadAnalysis when results do not need to be recomputed.

Parameters

session (dict, optional) – A session as a JSON object.
file (dict, optional) – The file descriptor of the analysis file to resume from. Either session or file must be provided. FileDescriptor
retain (list, optional) – An optional list of dimensions which should not be re-generated but kept with the existing logic.

Returns

The session state after the operation.

Return type

dict

Object Management

XplainClient.load_object(file, data_load_method='LOAD_VIA_MAPPED_BYTE_BUFFERS', remove_mapped_byte_buffers_after_loading=False)

Load an XTable for an object from a file

Load the XTable for an object from a file into the current session. The loaded object becomes the root object of the session.

Parameters

file (dict) – The file descriptor of the file where the object has been persisted. FileDescriptor
data_load_method (str, optional, default='LOAD_VIA_MAPPED_BYTE_BUFFERS') – Data load method to use. One of: LOAD_VIA_MAPPED_BYTE_BUFFERS, LOAD_VIA_READ_METHOD.
remove_mapped_byte_buffers_after_loading (bool, optional, default=False) – Whether to remove mapped byte buffers after loading.

Returns

The session state after the operation.

Return type

dict

XplainClient.add_object(file, parent_object, data_load_method='LOAD_VIA_MAPPED_BYTE_BUFFERS', remove_mapped_byte_buffers_after_loading=False)

Load an XTable for a sub-object and add it to an existing object

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

Parameters

file (dict) – The file descriptor of the XTable file where the object has been persisted. FileDescriptor
parent_object (str) – The name of the parent object.
data_load_method (str, optional, default='LOAD_VIA_MAPPED_BYTE_BUFFERS') – The data load method, either “LOAD_VIA_MAPPED_BYTE_BUFFERS” or “LOAD_VIA_READ_METHOD”. One of: LOAD_VIA_MAPPED_BYTE_BUFFERS, LOAD_VIA_READ_METHOD.
remove_mapped_byte_buffers_after_loading (bool, optional, default=False) – Decides whether the mapped byte buffers should be removed after loading the data.

Returns

The session state after the operation.

Return type

dict

XplainClient.swap_data(swap_object=None, table_file_name=None, file=None, swap_object_list=None)

Swap the underlying data of an existing object with data from a file

Replace the data of an already-loaded object with data from a different XTable file. The object structure (dimensions, attributes) is preserved; only the raw data changes.

Parameters

swap_object (str, optional) – The object where data should be swapped.
table_file_name (str, optional) – 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.
file (dict, optional) – Fully qualified file descriptor instead of the parameter tableFileName (see example). FileDescriptor
swap_object_list (list, optional) – An array of objects to be swapped, each with the parameters swapObject and tableFileName/file (see example).

Returns

The session state after the operation.

Return type

dict

XplainClient.remove_object(object)

Remove a sub-object from the session

Remove a sub-object (and all its associated dimensions and attributes) from the current session. Throws an error if the object does not exist.

Parameters: object (str) – The name of the object to be deleted.
Returns: The session state after the operation.
Return type: dict

XplainClient.remove_object_if_exists(object)

Remove a sub-object if it exists (no error if missing)

Like removeObject but does not throw an error if the object does not exist. Safe to call in scripts where object existence is not guaranteed.

Parameters: object (str) – The name of the object to be deleted.
Returns: The session state after the operation.
Return type: dict

Query Execution

XplainClient.execute_request(request, delete_if_exists=False)

Execute a statistics request and return results immediately

Execute the specified statistics request and immediately return the results in the session JSON document. The results of this request are “static” — the request will not be automatically recomputed when global selections change. To get dynamic results that respond to global selection changes, use openRequest instead.

The alias executeQuery is also accepted (deprecated name).

Parameters

request (dict) – The statistics request to execute. StatisticsRequestUIModel
delete_if_exists (bool, optional, default=False) – If true, a prior existing request with the same ID is deleted first.

Returns

The session state after the operation.

Return type

dict

Note

Also accepted by the server as: executeQuery.

XplainClient.execute_query(request, delete_if_exists=False)

[Deprecated] Alias for executeRequest

Deprecated alias for executeRequest. Use executeRequest instead.

Parameters

request (dict) – StatisticsRequestUIModel
delete_if_exists (bool, optional, default=False) – See API documentation.

Returns

The session state after the operation.

Return type

dict

Deprecated since version Use: the non-deprecated equivalent instead.

XplainClient.execute_and_export_request(result_xls, request=None, requests=None, template_xls=None, sheet_name=None, column_headers=None, use_display_names=None)

Execute a request and immediately export the results to a file

Execute a statistics request and write the results directly to an export file, without storing them in the session. This is a combined compute+export operation useful for large result sets that need not be held in memory.

The alias executeAndExportQuery is also accepted.

Parameters

result_xls (str) – The name of the result (Excel) file.
request (dict, optional) – The statistics request in JSON object format. One of request or requests must be provided. StatisticsRequestUIModel
requests (list, optional) – An array of statistics requests in JSON object format. One of request or requests must be provided. StatisticsRequestUIModel
template_xls (str, optional) – The filename of an Excel template.
sheet_name (str, optional) – Optional sheet name for the result when a single request is given.
column_headers (dict, optional) – The array of column names overwrites the default column headers in the result Excel file.
use_display_names (bool, optional) – Signals whether the display names of the states shall be used in the Excel file instead of the technical state names.

Returns

The session state after the operation.

Return type

dict

Note

Also accepted by the server as: executeAndExportQuery.

XplainClient.create_request(request=None, request_name=None, delete_if_exists=False)

Create a request without computing it yet

Create a request without immediately computing the results. Once created, additional aggregations, selections, or group-bys can be added via addAggregation, addGroupBy, etc. Then call computeRequest to compute.

Two forms are accepted: - With request object: creates from a full StatisticsRequestUIModel. - With requestName only: creates an empty named request.

Parameters

request (dict, optional) – Full request definition (optional; use requestName for empty request). StatisticsRequestUIModel
request_name (str, optional) – Name/ID for a new empty request (if request object is not given).
delete_if_exists (bool, optional, default=False) – Delete a prior existing request with the same ID if present.

Returns

The session state after the operation.

Return type

dict

XplainClient.compute_request(request_name)

(Re-)compute a request

(Re-)compute the results for a given request. Use this after modifying a request (e.g. adding aggregations, group-bys, or selections) to recalculate the results.

Parameters: request_name (str) – The name/ID of the request to compute.
Returns: The session state after the operation.
Return type: dict

XplainClient.compute_all_open_requests()

Recompute all open (dynamic) requests

Trigger recomputation of all requests that were opened with openRequest. Useful after bulk changes to force immediate refresh.

Returns: The session state after the operation.
Return type: dict

XplainClient.delete_request(request_name)

Delete a named request from the session

Permanently remove a request from the session. The request will no longer appear in the session state and its results are discarded.

Group-By & Aggregation

XplainClient.add_aggregation(request_name, aggregation)

Add an aggregation to an existing request

Add an aggregation (measure) to an already existing request. Supports all aggregation types: COUNT, SUM, AVG, MIN, MAX, VAR, VARP, STDEV, STDEVP, COUNTENTITY, COUNTDISTINCT, FIRSTKEY, QUANTILE, and COMPUTED_MEASURE.

After adding aggregations, call computeRequest to recompute the results.

Parameters

request_name (str) – The name/ID of the request to which the aggregation should be added.
aggregation (dict) – The aggregation to add. AggregationUIModel

Returns

The session state after the operation.

Return type

dict

XplainClient.modify_aggregation(request_name, aggregation, position=0)

Replace an aggregation in an existing request at a given position

Replace the aggregation at the given position in an existing request. The position is 0-based (0 = first aggregation).

Parameters

request_name (str) – The name/ID of the request.
aggregation (dict) – The new aggregation to put at the given position. AggregationUIModel
position (int, optional, default=0) – The 0-based index of the aggregation to replace.

Returns

The session state after the operation.

Return type

dict

XplainClient.remove_aggregation(request_name, position)

Remove an aggregation from a request by position

Remove the aggregation at the given position from a request. Positions are 0-based (0 = first aggregation, 1 = second aggregation, etc.).

Parameters

request_name (str) – The name/ID of the request.
position (int) – The 0-based index of the aggregation to remove.

Returns

The session state after the operation.

Return type

dict

XplainClient.add_group_by(request_name, group_by)

Add a group-by to a request

Add a group-by (grouping dimension) to an existing request. The group-by defines how data is sliced/segmented in the results.

After adding a group-by, call computeRequest to recompute the results.

Parameters

request_name (str) – The name/ID of the request.
group_by (dict) – The group-by definition to add. GroupByUIModel

Returns

The session state after the operation.

Return type

dict

XplainClient.remove_group_by(request_name, attribute)

Remove a group-by from a request

Remove the group-by associated with the given attribute from a request.

Parameters

request_name (str) – The name/ID of the request.
attribute (dict) – The attribute path identifying which group-by to remove. XElementPath

Returns

The session state after the operation.

Return type

dict

Navigation

XplainClient.open_attribute(request_name, object, dimension, attribute, selection_set='globalSelections')

Open an attribute as a dynamic group-by (convenience wrapper for openRequest)

Convenience method equivalent to openRequest where the group-by comprises the first-level states and the root state of the specified attribute. Any changes to the global selections will automatically trigger recomputation.

Parameters

request_name (str) – The name/ID of the resulting open query.
object (str) – The object name.
dimension (str) – The dimension name.
attribute (str) – The attribute name.
selection_set (str, optional, default='globalSelections') – The selection set the resulting query should refer to. If omitted, the standard global selections are used.

Returns

The session state after the operation.

Return type

dict

XplainClient.expand(request_name, state_name)

Expand a state in an open query (drill down)

Add the children states of the specified state into the first group-by of the given open request. All states in the group-by must form a hierarchy. This operation drills into one of the hierarchy nodes, adding sub-states and computing additional results.

Example: For an age hierarchy (0-9, 10-19, 20-40, >40), calling expand with stateName=”10-19” will add states 10-13, 14-17, and 18-19 to the group-by.

Parameters

request_name (str) – The name/ID of the open request containing the state to expand.
state_name (str) – The name of the state to expand (its children will be added).

Returns

The session state after the operation.

Return type

dict

XplainClient.collapse(request_name, state_name)

Collapse a state in an open query (drill up)

Recursively remove all children states of the specified state from the first group-by of the open request. The reverse of expand. Collapsing a state removes sub-state results, saving resources (they are no longer computed or transmitted).

Parameters

request_name (str) – The name/ID of the open request.
state_name (str) – The name of the state to collapse (its children will be removed).

Returns

The session state after the operation.

Return type

dict

XplainClient.expand_to_level(request_name, level_name, max_states=None)

Expand an open query to a specific hierarchy level

Add all states up to the specified hierarchy level into the group-by of the given open request. Useful for expanding a calendar hierarchy to e.g. the month level to show results for all years, quarters, and months at once.

Parameters

request_name (str) – The name/ID of the open request.
level_name (str) – The name of the hierarchy level to expand to.
max_states (int, optional) – Optional limit: only expand if the level has fewer than this many states. Prevents accidentally expanding huge hierarchies.

Returns

The session state after the operation.

Return type

dict

XplainClient.omit_null_value_results(omit=True, request_name=None)

Toggle omission of null/zero-value results for open requests

Control whether result rows where all aggregation values are null or zero are omitted from the response. When enabled, rows with no meaningful data are excluded, reducing the size of the result set.

If requestName is not given, the setting is applied to all currently open requests. Whenever a new query is initiated, the default is omit = false.

Parameters

omit (bool, optional, default=True) – Whether to omit null/zero results. Defaults to true if not given.
request_name (str, optional) – The specific request to configure. If not given, applies to all open requests.

Returns

The session state after the operation.

Return type

dict

XplainClient.get_children(object=None, dimension=None, attribute=None, state=None, list=None)

Get children states of a given state

Returns the direct children states of the specified state. Can be called for a single state or a list of states.

Parameters

object (str, optional) – Object name (when querying a single state).
dimension (str, optional) – Dimension name (when querying a single state).
attribute (str, optional) – Attribute name (when querying a single state).
state (str, optional) – State name whose children to retrieve. If omitted, the root state’s children are returned.
list (list, optional) – List of {object, dimension, attribute, state} combinations for batch child retrieval. XElementPath

Returns

The session state after the operation.

Return type

dict

XplainClient.get_state_hierarchy(object, dimension, attribute, state=None, levels=None)

Get a (partial) state hierarchy for an attribute

Returns the hierarchical structure of states for an attribute, starting from the given state (or root if not specified) and going down the specified number of levels.

Parameters

object (str) – The name of the object.
dimension (str) – The name of the dimension.
attribute (str) – The name of the attribute.
state (str, optional) – The name of a state in the attribute’s hierarchy. If state is not specified, the root state of the attribute will be taken as default.
levels (int, optional) – The levels of hierarchy to be returned. If levels is not specified, the maximum levels of the hierarchy will be considered.

Returns

The session state after the operation.

Return type

dict

XplainClient.get_states_list_for_level(object, dimension, attribute, level_name=None, level_number=None, sort=None)

Get all states at a specific hierarchy level

Returns a flat list of all states at the specified level of the hierarchy for the given attribute.

Parameters

object (str) – The object name.
dimension (str) – The dimension name.
attribute (str) – The attribute name.
level_name (str, optional) – The level name in the attribute’s state hierarchy. Exactly one of levelName or levelNumber must be provided.
level_number (int, optional) – The level number in the attribute’s state hierarchy. Exactly one of levelName or levelNumber must be provided.
sort (bool, optional) – A flag signaling whether the states should be sorted.

Returns

The session state after the operation.

Return type

dict

XplainClient.get_path_for_states(object, dimension, attribute, states)

Get the hierarchy path for specified states in an attribute

Retrieves the path (ancestor chain) for each of the specified states in the attribute hierarchy.

Note: State names are treated case-insensitively by this method.

Parameters

object (str) – See API documentation.
dimension (str) – See API documentation.
attribute (str) – See API documentation.
states (list) – The state names to find paths for.

Returns

The session state after the operation.

Return type

dict

XplainClient.get_tree_containing_string(object, dimension, attribute, string, case_sensitive=False, subtree_leaf_flags=True, search_display_names=False)

Get the subtree of states containing a search string

Searches the state hierarchy of an attribute for states whose names contain the given string, and returns the minimal subtree containing all matching states.

Parameters

object (str) – See API documentation.
dimension (str) – See API documentation.
attribute (str) – See API documentation.
string (str) – The search string to match in state names.
case_sensitive (bool, optional, default=False) – Whether to perform a case-sensitive search.
subtree_leaf_flags (bool, optional, default=True) – If true, leaf flags reflect whether a state is a leaf in the search-induced subtree. If false, leaf flags reflect the complete state tree.
search_display_names (bool, optional, default=False) – If true, the search is also applied to display names of states in addition to their regular names.

Returns

The session state after the operation.

Return type

dict

Selections

XplainClient.select(selection=None, selections=None, selection_set=None)

Apply selections (filters) to the session

Apply one or more selections to the current global selection set (or a specified selection set). All open requests that reference the given selection set are automatically recomputed.

Selections define which states (values) of an attribute are included in analysis. For example, selecting Region = “Berlin” filters the data to Berlin only.

Parameters

selection (dict, optional) – A single selection to apply. SelectionUIModel
selections (list, optional) – Multiple selections to apply at once. SelectionUIModel
selection_set (str, optional) – The name of the selection set to apply to. Defaults to “globalSelections” if omitted.

Returns

The session state after the operation.

Return type

dict

XplainClient.multiselect(selections, selection_set=None)

[Deprecated] Apply multiple selections — use select with selections array instead

Deprecated. Use select with the selections array parameter instead.

Apply multiple selections simultaneously.

Parameters

selections (list) – SelectionUIModel
selection_set (str, optional) – Target selection set name.

Returns

The session state after the operation.

Return type

dict

Deprecated since version Use: the non-deprecated equivalent instead.

XplainClient.select_between(object=None, dimension=None, attribute=None, from_=None, to=None, low_value=None, high_value=None)

Select states in a range (between two values)

Select all states of an attribute that fall between two specified boundary states. Useful for range-based filtering on ordered attributes (e.g. dates, numeric ranges).

Parameters

object (str, optional) – The Object where the dimension and attribute is to be found.
dimension (str, optional) – The dimension of the attribute.
attribute (str, optional) – The attribute, either as string in combination with the dimension and object parameter or an XElementPath pointing to the attribute.
from (float, optional) – Lower value
to (float, optional) – Upper value
low_value (float, optional) – Lower value - just an alias for the from parameter
high_value (float, optional) – Upper value - just an alias for the to parameter
from_ (float) –

Returns

The session state after the operation.

Return type

dict

XplainClient.select_entities(object, selection)

Select entities (root objects) matching a selection

Select all root-object entities (e.g. patients) that match the given selection criteria. The resulting selection propagates upward in the object hierarchy.

Parameters

object (str) – The object whose entities to select.
selection (dict) – The selection criteria to match. SelectionUIModel

Returns

The session state after the operation.

Return type

dict

XplainClient.select_entities_in_field(request_name, field, selection)

Select entities corresponding to a result field in an open query

Select entities corresponding to a specific result row (field) in an open query. Used for cross-filtering when a user clicks on a result cell.

Parameters

request_name (str) – The name/ID of the open request.
field (str) – The field name in the result set.
selection (dict) – The selection corresponding to the clicked result line. SelectionUIModel

Returns

The session state after the operation.

Return type

dict

XplainClient.clear_selections(object=None, dimension=None, attribute=None, attributes=None, retain_attributes=None, selection_set=None)

Clear selections for specific attributes

Remove selections for one or more specific attributes from the selection set. Open requests that reference the selection set are automatically recomputed.

Parameters

object (str, optional) – The object for which selections are to be cleared.
dimension (str, optional) – The dimension for which selections are to be cleared.
attribute (str, optional) – The attribute for which selections are to be cleared.
attributes (list, optional) – An explicit list of attributes in terms of their path. AttributePath
retain_attributes (list, optional) – An explicit list of attribute paths whose selections should be retained (all others cleared). AttributePath
selection_set (str, optional) – The selection set for which to clear selections - if not given “globalSelections” is cleared.

Returns

The session state after the operation.

Return type

dict

XplainClient.clear_all_selections(selection_set=None)

Clear all selections from a selection set

Clear all selections from the specified selection set (or globalSelections if not specified). All open requests referencing the selection set are recomputed with no filters applied.

To clear all selection sets, use clearAllSelectionSets.

Parameters: selection_set (str, optional) – The name of the selection set to clear. Defaults to “globalSelections” if not given.
Returns: The session state after the operation.
Return type: dict

XplainClient.clear_all_selection_sets()

Clear all selections for all selection sets

Clear all selections in all selection sets. All open requests are recomputed with no filters applied across all selection contexts.

Returns: The session state after the operation.
Return type: dict

XplainClient.put_selection(request_name, selection)

Put (overwrite) a selection into a request

Put a selection directly into an existing request. If a selection on the same attribute already exists in the request, it is replaced (overwritten).

Parameters

request_name (str) – The name/ID of the request.
selection (dict) – The selection to put into the request. SelectionUIModel

Returns

The session state after the operation.

Return type

dict

XplainClient.add_selection_set(name)

Add a new named selection set to the session

Create a new named selection set that can be used as an independent selection context for open requests.

Parameters: name (str) – The name (ID) of the set which is to be added.
Returns: The session state after the operation.
Return type: dict

XplainClient.remove_selection_set(name)

Remove a named selection set from the session

Delete a previously added named selection set and all its selections.

Parameters: name (str) – The name (ID) of the set which is to be removed.
Returns: The session state after the operation.
Return type: dict

XplainClient.set_selection_set_for_query(request_name, selection_set=None, external_selections=None, selections=None)

Associate a selection set with an open query

Change the selection set that an open query uses for its dynamic selections. The alias setSelectionsForQuery is also accepted.

Parameters

request_name (str) – The name (=ID) of the query
selection_set (str, optional) – The name (=ID) of the selection set (alias externalSelections)
external_selections (str, optional) – The name (=ID) of the selection set (alias selectionSet)
selections (list, optional) – A set for selections which will be applied as fixed selections to the query SelectionUIModel

Returns

The session state after the operation.

Return type

dict

Note

Also accepted by the server as: setSelectionsForQuery.

XplainClient.go_back_in_selections(steps=1)

Navigate backward in the selection history

Undo the last selection change, navigating to the previous selection state.

Parameters: steps (int, optional, default=1) – Number of steps to go back in selections history.
Returns: The session state after the operation.
Return type: dict

XplainClient.go_forward_in_selections(steps=1)

Navigate forward in the selection history

Redo a previously undone selection change.

Parameters: steps (int, optional, default=1) – Number of steps to go forward in selections history.
Returns: The session state after the operation.
Return type: dict

XplainClient.import_selections(file, selection_set='globalSelections')

Load selections from a file

Load selections from a file on the server and apply them to the specified selection set (defaults to globalSelections).

See also exportSelections and getSelections.

Parameters

file (dict) – The selection file to load. FileDescriptor
selection_set (str, optional, default='globalSelections') – The selection set to import into.

Returns

The session state after the operation.

Return type

dict

XplainClient.export_selections(file, objects=None, selection_set='globalSelections')

Export selections to a file

Export selections (save to a file) for the global selections or a specified selection set. Floating semantics are fixed before export.

See also importSelections and getSelections.

Parameters

file (dict) – The destination file for the exported selections. FileDescriptor
objects (list, optional) – Optional list of object names to export selections for. If omitted, selections for all objects are exported.
selection_set (str, optional, default='globalSelections') – The selection set to export.

Returns

The session state after the operation.

Return type

dict

XplainClient.get_selections(objects=None, selection_set='globalSelections')

Get current selections as JSON (without saving to file)

Return current selections as a JSON document. Unlike exportSelections, this does not write to a file.

See also exportSelections and importSelections.

Parameters

objects (list, optional) – Optional list of object names to retrieve selections for. If omitted, selections for all objects are returned.
selection_set (str, optional, default='globalSelections') – The selection set to retrieve.

Returns

The session state after the operation.

Return type

dict

XplainClient.get_selected_leafs(attribute, selection_set='globalSelections')

Get selected leaf states for an attribute

For the current selections (or a given selection set), retrieve the leaf states of the specified attribute that are currently selected.

The selections must be “simple” (no complex logic or negations).

Parameters

attribute (dict) – The attribute path to retrieve selected leaf states for. AttributePath
selection_set (str, optional, default='globalSelections') – The selection set to use.

Returns

The session state after the operation.

Return type

dict

XplainClient.set_propagate_selections_upward(propagate_selections_upward, objects=None, selection_set='globalSelections')

Enable or disable upward selection propagation for objects

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

When upward propagation is enabled for an object, selections made on that object’s attributes are automatically propagated to its parent objects in the hierarchy.

Parameters

propagate_selections_upward (bool) – Boolean flag setting upward propagation to on or off.
objects (list, optional) – List of object names for which to set the upward propagation flag. If omitted, the flag is set for all objects in the session.
selection_set (str, optional, default='globalSelections') – The name of the selection set for which upward propagation is to be set. If omitted, defaults to “globalSelections”.

Returns

The session state after the operation.

Return type

dict

References

XplainClient.set_global_selections_as_reference(reference_name)

Set the current global selections as a named reference

Save the current global selections as a reference selection set under the given name. Reference selections can be used for comparison in queries.

Parameters: reference_name (str) – A unique name for the reference.
Returns: The session state after the operation.
Return type: dict

XplainClient.set_reference(reference_name, reference_selections)

Set explicit selections as a named reference

Set the given selections as a named reference selection set. Reference selections is an experimental (beta) feature that may not be fully supported with all other features.

Parameters

reference_name (str) – A unique name for this reference.
reference_selections (list) – The selections to store as a reference. SelectionUIModel

Returns

The session state after the operation.

Return type

dict

XplainClient.remove_reference(reference_name)

Remove a named reference

Delete a reference selection set by name. All open queries that used this reference for comparison are recomputed.

Parameters: reference_name (str) – The name of the reference to remove.
Returns: The session state after the operation.
Return type: dict

Dimensions

XplainClient.add_attribute(object, dimension=None, dimension_pattern=None, dimension_exclusion_pattern=None, attribute=None, new_attribute_name_prefix=None, new_attribute_name_suffix=None, file_name=None, xls_file=None, sheet_name=None, hierarchy_level_column_names=None, csv_file=None, properties=None, bin_boundaries=None, upper_bin_boundary_included=True)

Add a categorial attribute to an existing dimension

Add a new categorial (discrete-valued) attribute to an existing dimension of an object. The attribute defines the state hierarchy (values) for that dimension.

Parameters

object (str) – The target object.
dimension (str, optional) – The target dimension. (Might be replaced by dimensionPattern and/or dimensionExclusionPattern.)
dimension_pattern (str, optional) – Might be used instead of dimension.
dimension_exclusion_pattern (str, optional) – Might be used instead of dimension.
attribute (str, optional) – The name of the new attribute to be created. Defaults to the dimension name.
new_attribute_name_prefix (str, optional) – Prefix for new attribute name(s).
new_attribute_name_suffix (str, optional) – Suffix for new attribute name(s).
file_name (str, optional) – The filename of an attribute file to be loaded (usually .xattribute).
xls_file (str, optional) – The file descriptor of a Microsoft Excel file to be loaded as an attribute.
sheet_name (str, optional) – The name of the sheet in the Excel file where the attribute shall be loaded from.
hierarchy_level_column_names (list, optional) – The names of the columns in the Excel sheet that make up the attribute hierarchy.
csv_file (str, optional) – The file descriptor of a CSV file to be loaded as an attribute.
properties (dict, optional) – A map of properties for the JDBC driver (currently only for CSV files).
bin_boundaries (list, optional) – The bin boundaries / interval endpoints / split keys (deprecated single-level variant).
upper_bin_boundary_included (bool, optional, default=True) – Signals whether the intervals are left-open and right-closed (true), or left-closed and right-open (false).

Returns

The session state after the operation.

Return type

dict

XplainClient.add_number_ranges_attribute(object, dimension=None, dimension_pattern=None, dimension_exclusion_pattern=None, attribute=None, new_attribute_name_prefix=None, new_attribute_name_suffix=None, upper_bin_boundary_included=True, endpoint_class=None, creation_mode='IRREGULAR', endpoint_representation='BINARY', level_names=None, interval_name_scheme='HALFOPEN_INTERVALS', bin_boundaries=None, state_names=None, state_display_names=None, lower_limit=None, upper_limit=None, equidistant_creation_bin_size_per_level=None, exponential_creation_base_value=None, exponential_creation_factor=None)

Add a numeric ranges attribute (binning) to a dimension

Add a numeric ranges attribute that bins continuous numeric values into discrete ranges (e.g. 0-10, 10-20, 20-50, >50).

Parameters

object (str) – The target object.
dimension (str, optional) – The target dimension. (Might be replaced by dimensionPattern and/or dimensionExclusionPattern.)
dimension_pattern (str, optional) – Might be used instead of dimension.
dimension_exclusion_pattern (str, optional) – Might be used instead of dimension.
attribute (str, optional) – The name of the new attribute to be created. Defaults to the dimension name.
new_attribute_name_prefix (str, optional) – Prefix for new attribute name(s).
new_attribute_name_suffix (str, optional) – Suffix for new attribute name(s).
upper_bin_boundary_included (bool, optional, default=True) – Signals whether the intervals are left-open and right-closed (true), or left-closed and right-open (false).
endpoint_class (str, optional) – The fully qualified name of the class for the interval endpoints.
creation_mode (str, optional, default='IRREGULAR') – The creation mode. One of: IRREGULAR, EQUIDISTANT, EXPONENTIAL.
endpoint_representation (str, optional, default='BINARY') – The endpoints representation mode. One of: BINARY, DECIMAL.
level_names (list, optional) – The level names.
interval_name_scheme (str, optional, default='HALFOPEN_INTERVALS') – The naming scheme for the attribute states. One of: HALFOPEN_INTERVALS, FROM_TO, FROM_TO_PLUS, ONLY_FROM.
bin_boundaries (list, optional) – The bin boundaries / interval endpoints / split keys, one array per level.
state_names (list, optional) – The interval names, one array per level.
state_display_names (list, optional) – The interval display names, one array per level.
lower_limit (float, optional) – The lower limit for the intervals.
upper_limit (float, optional) – The upper limit for the intervals.
equidistant_creation_bin_size_per_level (list, optional) – The interval sizes (one per level) for equidistant creation.
exponential_creation_base_value (float, optional) – The base value for the exponential creation.
exponential_creation_factor (float, optional) – The factor for the exponential creation.

Returns

The session state after the operation.

Return type

dict

XplainClient.add_point_in_time_attribute(object, start_date_time, stop_date_time, date_time_levels, dimension=None, dimension_pattern=None, dimension_exclusion_pattern=None, attribute=None, new_attribute_name_prefix=None, new_attribute_name_suffix=None, upper_bin_boundary_included=True, format_locale=None, format_year='yyyy', format_quarter='yyyy QQQ', format_month='yyyy-MM', format_week=None, format_day='yyyy-MM-dd', format_hour='yyyy-MM-dd HH', zone_id=None, dimension_time_unit='MILLISECOND', endpoint_class=None, level_names=None, interval_name_scheme='HALFOPEN_INTERVALS')

Add a point-in-time attribute (time granularity binning) to a time dimension

Add an attribute that bins timestamps into discrete time intervals (e.g. day, week, month, quarter, year) for a point-in-time dimension.

Parameters

object (str) – The target object.
start_date_time (str) – A string representing the start of the first local date/time interval.
stop_date_time (str) – A string representing the end of the last local date/time interval.
date_time_levels (list) – An array of time units (e.g., “DECADE”, “YEAR”, “HALFYEAR”, “QUARTER”, “MONTH”, “WEEK”, “DAY”, “HOUR”).
dimension (str, optional) – The target dimension. (Might be replaced by dimensionPattern and/or dimensionExclusionPattern.)
dimension_pattern (str, optional) – Might be used instead of dimension.
dimension_exclusion_pattern (str, optional) – Might be used instead of dimension.
attribute (str, optional) – The name of the new attribute to be created. Defaults to the dimension name.
new_attribute_name_prefix (str, optional) – Prefix for new attribute name(s).
new_attribute_name_suffix (str, optional) – Suffix for new attribute name(s).
upper_bin_boundary_included (bool, optional, default=True) – Signals whether the intervals are left-open and right-closed (true), or left-closed and right-open (false).
format_locale (str, optional) – A string defining the locale to be used for formatting the date/time instances.
format_year (str, optional, default='yyyy') – A string defining the format for the state names of years.
format_quarter (str, optional, default='yyyy QQQ') – A string defining the format for the state names of quarters.
format_month (str, optional, default='yyyy-MM') – A string defining the format for the state names of months.
format_week (str, optional) – A string defining the format for the state names of weeks.
format_day (str, optional, default='yyyy-MM-dd') – A string defining the format for the state names of days.
format_hour (str, optional, default='yyyy-MM-dd HH') – A string defining the format for the state names of hours.
zone_id (str, optional) – A string representing the time zone.
dimension_time_unit (str, optional, default='MILLISECOND') – The time unit (“MILLISECOND”, “SECOND”, “DAY”, or “MONTH”) characterizing the units of the underlying dimension.
endpoint_class (str, optional) – The fully qualified name of the class for the interval endpoints.
level_names (list, optional) – The level names.
interval_name_scheme (str, optional, default='HALFOPEN_INTERVALS') – The naming scheme for the attribute states. One of: HALFOPEN_INTERVALS, FROM_TO, FROM_TO_PLUS, ONLY_FROM.

Returns

The session state after the operation.

Return type

dict

XplainClient.add_elapsed_time_attribute(object, ref_date_time, bin_boundaries, dimension=None, dimension_pattern=None, dimension_exclusion_pattern=None, attribute=None, new_attribute_name_prefix=None, new_attribute_name_suffix=None, upper_bin_boundary_included=True, level_names=None, interval_name_scheme='HALFOPEN_INTERVALS', base_time_unit='MILLISECOND', output_time_unit='YEAR')

Add an elapsed-time attribute to a duration dimension

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. Either dimension, dimensionPattern, or dimensionExclusionPattern must be provided to identify the target dimension(s).

Parameters

object (str) – The target object.
ref_date_time (str) – The reference date/time.
bin_boundaries (list) – The bin boundaries / interval endpoints / split keys, one array per level.
dimension (str, optional) – The target dimension. (Might be replaced by dimensionPattern and/or dimensionExclusionPattern.)
dimension_pattern (str, optional) – Might be used instead of dimension.
dimension_exclusion_pattern (str, optional) – Might be used instead of dimension.
attribute (str, optional) – The name of the new attribute to be created. Defaults to the dimension name.
new_attribute_name_prefix (str, optional) – Prefix for new attribute name(s).
new_attribute_name_suffix (str, optional) – Suffix for new attribute name(s).
upper_bin_boundary_included (bool, optional, default=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.)
level_names (list, optional) – The level names. (The default is “Level 1”, “Level 2”, and so on.)
interval_name_scheme (str, optional, default='HALFOPEN_INTERVALS') – The naming scheme for the attribute states: “HALFOPEN_INTERVALS”, “FROM_TO”, “FROM_TO_PLUS”, or “ONLY_FROM”. One of: HALFOPEN_INTERVALS, FROM_TO, FROM_TO_PLUS, ONLY_FROM.
base_time_unit (str, optional, default='MILLISECOND') – The base time unit.
output_time_unit (str, optional, default='YEAR') – The output time unit.

Returns

The session state after the operation.

Return type

dict

XplainClient.add_time_duration_attribute(object, dimension=None, dimension_time_unit=None, dimension_pattern=None, dimension_exclusion_pattern=None, attribute=None, new_attribute_name_prefix=None, new_attribute_name_suffix=None, upper_bin_boundary_included=True, creation_mode='IRREGULAR', bin_boundaries_in_base_units=None, bin_boundaries=None, state_names=None, state_display_names=None, level_names=None, interval_name_scheme='HALFOPEN_INTERVALS', base_unit=None, min_base_units=None, max_base_units=None, equidistant_creation_time_unit_bin_sizes=None, exponential_creation_time_unit_base_value=None, exponential_creation_factor=None, reduce_units=True)

Add a time duration attribute to a dimension

Add an attribute representing time durations in a specified unit.

Parameters

object (str) – The target object.
dimension (str, optional) – The target dimension. (Might be replaced by dimensionPattern and/or dimensionExclusionPattern.)
dimension_time_unit (str, optional) – The time unit that the values of this dimension are measured in.
dimension_pattern (str, optional) – Might be used instead of dimension.
dimension_exclusion_pattern (str, optional) – Might be used instead of dimension.
attribute (str, optional) – The name of the new attribute to be created. Defaults to the dimension name.
new_attribute_name_prefix (str, optional) – Prefix for new attribute name(s).
new_attribute_name_suffix (str, optional) – Suffix for new attribute name(s).
upper_bin_boundary_included (bool, optional, default=True) – Signals whether intervals are left-open and right-closed.
creation_mode (str, optional, default='IRREGULAR') – The creation mode. One of: IRREGULAR, EQUIDISTANT, EXPONENTIAL.
bin_boundaries_in_base_units (list, optional) – The bin boundaries measured in the time units specified in baseUnit, one array per level. (Applies only to IRREGULAR mode.)
bin_boundaries (list, optional) – The bin boundaries measured in the time units of the underlying dimension, one array per level. (Applies only to IRREGULAR mode.)
state_names (list, optional) – The interval names, one array per level. (Applies only to IRREGULAR mode.)
state_display_names (list, optional) – The interval display names, one array per level.
level_names (list, optional) – The level names.
interval_name_scheme (str, optional, default='HALFOPEN_INTERVALS') – The naming scheme for the attribute states. One of: HALFOPEN_INTERVALS, FROM_TO, FROM_TO_PLUS, ONLY_FROM.
base_unit (str, optional) – Specifies in which units the bin sizes are given. (Applies only to EQUIDISTANT and EXPONENTIAL modes.)
min_base_units (int, optional) – The minimum value (measured in baseUnits). (Applies only to EQUIDISTANT and EXPONENTIAL modes.)
max_base_units (int, optional) – The maximum value (measured in baseUnits). (Applies only to EQUIDISTANT and EXPONENTIAL modes.)
equidistant_creation_time_unit_bin_sizes (list, optional) – The interval sizes (one per level) for equidistant creation. (Mandatory if creationMode is “EQUIDISTANT”.)
exponential_creation_time_unit_base_value (float, optional) – The base value for the exponential creation. (Mandatory if creationMode is “EXPONENTIAL”.)
exponential_creation_factor (float, optional) – The factor for the exponential creation. (Mandatory if creationMode is “EXPONENTIAL”.)
reduce_units (bool, optional, default=True) – Signals whether larger numbers of smaller units should be reduced to smaller numbers of larger units.

Returns

The session state after the operation.

Return type

dict

XplainClient.remove_dimension(object, dimension)

Remove a dimension from an object

Remove a dimension (and all its attributes) from an object. Throws an error if the dimension does not exist.

Parameters

object (str) – See API documentation.
dimension (str) – See API documentation.

Returns

The session state after the operation.

Return type

dict

XplainClient.remove_dimension_if_exists(object, dimension)

Remove a dimension if it exists (no error if missing)

Like removeDimension but does not throw an error if the dimension does not exist.

Parameters

object (str) – See API documentation.
dimension (str) – See API documentation.

Returns

The session state after the operation.

Return type

dict

XplainClient.add_boolean_logic_dimension(object, dimension1, dimension2, type='AND', name=None)

Add a boolean-logic dimension combining two boolean dimensions

Add a new computed dimension that is the boolean logic combination (AND, OR, 1NOT2, 2NOT1) of two existing boolean dimensions. All involved dimensions must belong to the same object.

Parameters

object (str) – The object holding all involved dimensions.
dimension1 (str) – First boolean operand dimension name.
dimension2 (str) – Second boolean operand dimension name.
type (str, optional, default='AND') – The boolean logic operation. One of: AND, OR, 1NOT2, 2NOT1.
name (str, optional) – Name for the new dimension (optional).

Returns

The session state after the operation.

Return type

dict

XplainClient.add_date_time_element_dimension(object, source_dimension, target_dimension, date_time_element, zone_id=None, data_type=None)

Add a computed dimension extracting a date/time element

Add a computed dimension extracting a specific date/time element (such as day-of-week, hour-of-day, month-of-year) from a timestamp dimension.

Deprecated aliases: addDayOfWeekDimension (use dateTimeElement: DAY_OF_WEEK), addHourOfDayDimension (use dateTimeElement: HOUR_OF_DAY).

Parameters

object (str) – The object containing the source dimension.
source_dimension (str) – The source timestamp dimension (storing ms since epoch).
target_dimension (str) – Name for the new computed dimension.
date_time_element (str) – The date/time element to extract. One of: 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.
zone_id (str, optional) – Time zone identifier (e.g. “Europe/Berlin”). Defaults to server time zone.
data_type (str, optional) – Data type for the values. Usually omitted (auto-selected). One of: BYTE, SHORT, INT, LONG.

Returns

The session state after the operation.

Return type

dict

XplainClient.add_day_of_week_dimension(object, source_dimension, target_dimension, zone_id=None)

[Deprecated] Add day-of-week dimension — use addDateTimeElementDimension instead

Deprecated. Use addDateTimeElementDimension with dateTimeElement: DAY_OF_WEEK instead.

Parameters

object (str) – See API documentation.
source_dimension (str) – See API documentation.
target_dimension (str) – See API documentation.
zone_id (str, optional) – See API documentation.

Returns

The session state after the operation.

Return type

dict

Deprecated since version Use: the non-deprecated equivalent instead.

XplainClient.add_hour_of_day_dimension(object, source_dimension, target_dimension, zone_id=None)

[Deprecated] Add hour-of-day dimension — use addDateTimeElementDimension instead

Deprecated. Use addDateTimeElementDimension with dateTimeElement: HOUR_OF_DAY instead.

Parameters

object (str) – See API documentation.
source_dimension (str) – See API documentation.
target_dimension (str) – See API documentation.
zone_id (str, optional) – See API documentation.

Returns

The session state after the operation.

Return type

dict

Deprecated since version Use: the non-deprecated equivalent instead.

XplainClient.add_shift_number_dimension(object, source_dimension, target_dimension, shift_ends, shift_names=None, zone_id=None, data_type=None)

Add a shift-number dimension (classifies timestamps into work shifts)

Add a computed dimension that classifies timestamp values into numbered work shifts based on shift-end times.

Parameters

object (str) – See API documentation.
source_dimension (str) – Source timestamp dimension (ms since epoch).
target_dimension (str) – Name for the new shift-number dimension.
shift_ends (list) – End times for each shift (in order).
shift_names (list, optional) – Names for each shift (must match length of shiftEnds if given).
zone_id (str, optional) – Time zone identifier.
data_type (str, optional) – One of: BYTE, SHORT, INT, LONG.

Returns

The session state after the operation.

Return type

dict

XplainClient.add_time_in_shift_dimension(object, source_dimension, target_dimension, shift_ends, zone_id=None, data_type=None, attribute_configuration=None)

Add a time-in-shift dimension (elapsed time within a shift)

Add a computed dimension that calculates the elapsed time within the current work shift for each timestamp value.

Parameters

object (str) – See API documentation.
source_dimension (str) – See API documentation.
target_dimension (str) – See API documentation.
shift_ends (list) – Shift end times in HH:MM:SS format.
zone_id (str, optional) – See API documentation.
data_type (str, optional) – One of: BYTE, SHORT, INT, LONG.
attribute_configuration (dict, optional) – Optional attribute configuration JSON.

Returns

The session state after the operation.

Return type

dict

XplainClient.add_ratio_dimension(target_object, dimensions, dimension_name, min_denominator=1.0, add_first_to_denominator=True, target_share=None)

Add a ratio dimension (quotient of counts)

Add a computed dimension that computes the ratio (share) of the first input dimension relative to the sum of all input dimensions.

Parameters

target_object (str) – The object to add the ratio dimension to.
dimensions (list) – Input numeric dimensions for the ratio computation. XElementPath
dimension_name (str) – Name for the new ratio dimension.
min_denominator (float, optional, default=1.0) – Minimum denominator value (ratios with smaller denominators get null).
add_first_to_denominator (bool, optional, default=True) – Whether to include the first dimension in the denominator.
target_share (float, optional) – Optional target share value for the ratio attribute.

Returns

The session state after the operation.

Return type

dict

XplainClient.add_linear_sum_dimension(dimensions, data_type='DOUBLE', betas=None, constant=None, dimension_name=None)

Add a linear sum computed dimension

Add a computed dimension that is a weighted linear sum of existing numeric dimensions.

Parameters

dimensions (list) – The dimensions to be summed, given as an array of XElementPath. XElementPath
data_type (str, optional, default='DOUBLE') – The data type.
betas (list, optional) – An array of weights of the same length as dimensions (if omitted, a simple sum is computed).
constant (float, optional) – An additive constant to the linear sum.
dimension_name (str, optional) – The name of the new dimension. If null, the name will be generated.

Returns

The session state after the operation.

Return type

dict

XplainClient.add_min_number_dimension(input_dimensions, constant=None, output_dimension=None)

Add a minimum computed dimension

Add a computed dimension returning the minimum of specified numeric dimensions.

Parameters

input_dimensions (list) – The dimensions to be used for calculating the minimum, given as array of XElementPath. XElementPath
constant (float, optional) – A constant to be used in calculating the minimum value (i.e. an upper bound).
output_dimension (str, optional) – The name of the new dimension. If null, the name will be generated.

Returns

The session state after the operation.

Return type

dict

XplainClient.add_max_number_dimension(input_dimensions, constant=None, output_dimension=None)

Add a maximum computed dimension

Add a computed dimension returning the maximum of specified numeric dimensions.

Parameters

input_dimensions (list) – The dimensions to be used for calculating the maximum, given as array of XElementPath. XElementPath
constant (float, optional) – A constant to be used in calculating the maximum value (i.e. a lower bound).
output_dimension (str, optional) – The name of the new dimension. If null, the name will be generated.

Returns

The session state after the operation.

Return type

dict

XplainClient.add_product_dimension(dimensions, constant_factor=1, output_dimension=None, data_type='DOUBLE')

Add a product computed dimension

Add a computed dimension that is the product of specified numeric dimensions.

Parameters

dimensions (list) – The factor dimensions, given as an array of XElementPath. XElementPath
constant_factor (float, optional, default=1) – The constant factor.
output_dimension (str, optional) – The name of the new dimension. If null, the name will be generated.
data_type (str, optional, default='DOUBLE') – The data type.

Returns

The session state after the operation.

Return type

dict

XplainClient.add_quotient_dimension(numerator_dimension, denominator_dimension, output_dimension=None, data_type='DOUBLE')

Add a quotient computed dimension

Add a computed dimension that is the quotient of two numeric dimensions.

Parameters

numerator_dimension (dict) – The dimension to be used as the numerator for calculating the quotient. XElementPath
denominator_dimension (dict) – The dimension to be used as the denominator for calculating the quotient. XElementPath
output_dimension (str, optional) – The name of the new dimension. If null, the name will be generated.
data_type (str, optional, default='DOUBLE') – The output data type of the quotient dimension.

Returns

The session state after the operation.

Return type

dict

XplainClient.add_time_difference_dimension(minuend_dimension, subtrahend_dimension, time_unit, calendar_based, age_based=False, zone_id=None, output_dimension=None, data_type=None)

Add a time-difference computed dimension

Add a computed dimension representing the difference between two timestamp dimensions in a specified time unit.

Parameters

minuend_dimension (dict) – The dimension to be used as the minuend for calculating the time difference. XElementPath
subtrahend_dimension (dict) – The dimension to be used as the subtrahend for calculating the time difference. XElementPath
time_unit (str) – The output time unit of the new dimension. (If ageBased is true, only “YEAR” and “MONTH” are allowed.)
calendar_based (bool) – Signals whether the time difference should be based on a calendar (and a certain time zone).
age_based (bool, optional, default=False) – Signals whether a calendar-based time difference should follow the style of the usual age computation.
zone_id (str, optional) – The time zone (e.g., “Europe/Berlin”). If null, the default of the JVM is used.
output_dimension (str, optional) – The name of the new dimension. If null, the name will be generated.
data_type (str, optional) – The output data type of the time difference dimension. (null means to infer it automatically from timeUnit.)

Returns

The session state after the operation.

Return type

dict

XplainClient.add_threshold_dimension(object, dimension, threshold, strict=False, negate=False, boolean_value_for_null=False, output_dimension=None)

Add a threshold dimension (boolean flag based on threshold comparison)

Add a boolean dimension that flags entities where a numeric dimension’s value exceeds (or falls below) a specified threshold.

Parameters

object (str) – The name of the object where the new dimension is to be added.
dimension (str) – The dimension of the given object that holds the values to be compared with the threshold.
threshold (float) – The threshold to be compared with the dimension values.
strict (bool, optional, default=False) – Signals whether the dimension values have to be strictly greater (instead of greater or equal) than the threshold.
negate (bool, optional, default=False) – Signals whether the boolean result should be negated.
boolean_value_for_null (bool, optional, default=False) – Defines the Boolean value for the case of null in the input dimension.
output_dimension (str, optional) – The name of the dimension to be created.

Returns

The session state after the operation.

Return type

dict

XplainClient.add_interval_flag_dimension(object, dimension, lower_limit=None, lower_limit_strict=False, lower_limit_active=None, upper_limit=None, upper_limit_strict=False, upper_limit_active=None, negate=False, boolean_value_for_null=False, output_dimension=None)

Add an interval flag dimension

Add a boolean dimension that flags entities within a specified time interval relative to an event.

Parameters

object (str) – The name of the object where the new dimension is to be added.
dimension (str) – The dimension of the given object that holds the values to be compared with the limits.
lower_limit (float, optional) – The lower limit of the interval to be compared with the dimension values.
lower_limit_strict (bool, optional, default=False) – Signals whether the dimension values have to be strictly greater than the lower limit.
lower_limit_active (bool, optional) – Explicitly activates/deactivates the lower limit check.
upper_limit (float, optional) – The upper limit of the interval to be compared with the dimension values.
upper_limit_strict (bool, optional, default=False) – Signals whether the dimension values have to be strictly less than the upper limit.
upper_limit_active (bool, optional) – Explicitly activates/deactivates the upper limit check.
negate (bool, optional, default=False) – Signals whether the boolean result should be negated.
boolean_value_for_null (bool, optional, default=False) – Defines the Boolean value for the case of null in the input dimension.
output_dimension (str, optional) – The name of the dimension to be created.

Returns

The session state after the operation.

Return type

dict

XplainClient.add_flag_extraction_dimension(object, dimension, bit_index, boolean_value_for_null=False, output_dimension=None)

Add a flag-extraction dimension

Add a dimension that extracts a flag value from a boolean dimension hierarchy.

Parameters

object (str) – The name of the object where the new dimension is to be added.
dimension (str) – The dimension of the given object that holds the numeric values where the boolean flag is to be extracted from.
bit_index (int) – The index of the bit to be extracted (index i stands for value 2^i, lowest possible index is 0).
boolean_value_for_null (bool, optional, default=False) – Defines the Boolean value for the case of null in the input dimension.
output_dimension (str, optional) – The name of the dimension to be created.

Returns

The session state after the operation.

Return type

dict

XplainClient.add_sample_dimension(dimension=None, number_of_segments=10, sample_object=None)

Add a sample dimension (stratified random sample flag)

Add a boolean dimension that flags a random sample of entities, respecting stratification groups.

Parameters

dimension (str, optional) – Name of the new dimension. Defaults to “Random Segment”.
number_of_segments (int, optional, default=10) – The number of random segments.
sample_object (str, optional) – The object whose instances are assigned to random segments (root object if not given).

Returns

The session state after the operation.

Return type

dict

XplainClient.add_numeric_dimensions(object, key_dimension_name, xls_file, sheet, key_field_name, value_field_names, attribute=None, attribute_level=None, dimension_names=None, value_data_types=None)

Add multiple standard numeric attributes to a numeric dimension

Convenience method to add a standard set of numeric range attributes to a numeric dimension (e.g. fine, medium, and coarse range bins).

Parameters

object (str) – Name of object where the new dimensions are to be added.
key_dimension_name (str) – A dimension of the given object — its values are used as a key mapping to values in the Excel file.
xls_file (str) – Excel file name which defines the numeric dimension / the mapping from keys to values.
sheet (str) – Sheet name in Excel file where the dimension is defined.
key_field_name (str) – The name of the column in the Excel sheet which holds the key values.
value_field_names (list) – The names of the columns in the Excel sheet which hold the values of the new dimensions.
attribute (str, optional) – If given, states on the first level of this attribute are used as keys instead of dimension values.
attribute_level (int, optional) – If given in combination with attribute, states on the specified level are used as keys.
dimension_names (list, optional) – Names of the new dimensions to be added. Defaults to valueFieldNames.
value_data_types (list, optional) – Data types of the new dimensions.

Returns

The session state after the operation.

Return type

dict

XplainClient.add_normalized_response_dimension(input_dimension, categories, dimension=None)

Add a normalized-response dimension

Add a dimension computing normalized response rates relative to a baseline.

The deprecated alias addNormalisedResponseDimension is also accepted.

Parameters

input_dimension (dict) – The input dimension (as XElementPath). XElementPath
categories (dict) – The grouping categories (as GroupByUIModel).
dimension (str, optional) – The name of the new dimension. If null, the name will be generated.

Returns

The session state after the operation.

Return type

dict

Note

Also accepted by the server as: addNormalisedResponseDimension.

XplainClient.add_constant_categorial_dimension(object, dimension, root_state)

Add a constant-value categorial dimension

Add a dimension that assigns a constant categorial value to all entities (useful for labeling or tagging groups).

Parameters

object (str) – The target object.
dimension (str) – The name of the new constant dimension to be created.
root_state (str) – The constant state value to assign to all instances.

Returns

The session state after the operation.

Return type

dict

XplainClient.add_aggregation_dimension(target_object, aggregation, dimension=None, display_name=None, selections=None, selection_set=None, fix_explicit_selections=None, add_default_attribute=True, threshold=None, negate=None, zero_point_dimension=None, sort_dimension=None, base_object=None, from_=None, to=None)

Add a dimension derived from an aggregation on a sub-object

Add a computed dimension on the root object that aggregates values from a sub-object (e.g. sum of prescription costs per patient).

Parameters

target_object (str) – Name of the target object.
aggregation (dict) – An aggregation in JSON object format. AggregationUIModel
dimension (str, optional) – The name of the new dimension. If omitted, the name will be generated.
display_name (str, optional) – An optional display name. XOE shows this instead of the dimension name.
selections (dict, optional) – The set of selections applied as the “where” clause during aggregation.
selection_set (str, optional) – If specified, the aggregation dimension will use the selections from the given set.
fix_explicit_selections (str, optional) – Controls fixing semantics for explicit selections. One of: none, all, only_propagate_upward.
add_default_attribute (bool, optional, default=True) – If set to false, no attribute will be attached to the new dimension.
threshold (float, optional) – An optional threshold for the aggregation.
negate (bool, optional) – Negates the threshold condition (used together with threshold).
zero_point_dimension (dict, optional) – If set, activates relative-to-aggregation mode. XElementPath
sort_dimension (dict, optional) – Required when zeroPointDimension is set. XElementPath
base_object (str, optional) – The base object for relative-to-aggregation (used with zeroPointDimension).
from (int, optional) – Lower bound for relative-to-aggregation range (used with zeroPointDimension).
to (int, optional) – Upper bound for relative-to-aggregation range (used with zeroPointDimension).
from_ (int) –

Returns

The session state after the operation.

Return type

dict

XplainClient.add_disaggregation_dimension(dimension_name, disaggregate_onto_object, to_be_disaggregated_dimension=None, to_be_disaggregated_value=None)

Add a disaggregation dimension

Add a computed dimension that disaggregates a total value proportionally down to sub-object level based on a weighting dimension.

Parameters

dimension_name (str) – See API documentation.
disaggregate_onto_object (str) – The sub-object onto which to disaggregate.
to_be_disaggregated_dimension (str, optional) – The dimension holding the total value to disaggregate.
to_be_disaggregated_value (float, optional) – A fixed value to disaggregate (alternative to dimension).

Returns

The session state after the operation.

Return type

dict

XplainClient.add_conditional_factor_dimension(dimension_name, object, condition_dimension, condition_attribute, input_dimension, conditional_values, default_value=None)

Add a conditional factor dimension

Add a dimension whose value depends on conditions from a boolean attribute. Different numeric scaling factors are applied based on the active states of the condition attribute.

Parameters

dimension_name (str) – Name for the new dimension.
object (str) – The object containing the condition.
condition_dimension (str) – The dimension containing the condition attribute.
condition_attribute (str) – The boolean condition attribute name.
input_dimension (str) – The numeric dimension to scale.
conditional_values (dict) – Map of state name → scaling factor.
default_value (float, optional) – Factor to apply when no condition matches.

Returns

The session state after the operation.

Return type

dict

XplainClient.rename_dimension(dimension, new_name)

Rename a session-generated dimension

Rename a dimension that was generated within the current session. Will report an error if the dimension is in use (e.g. referenced by selections or queries) or if it is a pre-existing dimension from an XTable.

Parameters

dimension (dict) – The dimension to rename, specified as an XElementPath with object and dimension fields. XElementPath
new_name (str) – The new name for the dimension.

Returns

The session state after the operation.

Return type

dict

XplainClient.replicate_dimension(dimension, to_object, name=None)

Replicate a dimension with a new name

Create a copy of an existing dimension under a new name, preserving all attributes and configuration.

Parameters

dimension (dict) – The dimension which will be replicated. It needs to be a numeric dimension. Specified as an XElementPath with object and dimension fields. XElementPath
to_object (str) – 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.
name (str, optional) – Name of the new dimension. If not given, the name will be identical to that of the replicated dimension.

Returns

The session state after the operation.

Return type

dict

Attributes

XplainClient.remove_attribute(object, dimension, attribute)

Remove an attribute from the current session

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.

Note: Default attributes generated with an aggregation dimension and attributes which existed a priori in XTables (global attributes) are not allowed to be removed. Use removeAttributeIfExists if you want to suppress the error when the attribute is not found.

Parameters

object (str) – The object which holds the dimension.
dimension (str) – The dimension which holds the attribute.
attribute (str) – The attribute to be removed.

Returns

The session state after the operation.

Return type

dict

XplainClient.remove_attribute_if_exists(object, dimension, attribute)

Remove an attribute if it exists (no error if missing)

Remove an attribute from the current session if it exists. Unlike removeAttribute, this method does not throw an error if the attribute is not found.

Parameters

object (str) – The object which holds the dimension.
dimension (str) – The dimension which holds the attribute.
attribute (str) – The attribute to be removed (silently ignored if not found).

Returns

The session state after the operation.

Return type

dict

XplainClient.reorganize_attribute(new_attribute_name, object=None, dimension=None, attribute=None, hierarchy=None, level=None, level_name=None, hierarchy_level_names=None, others_state_name='others')

Reorganize (reindex) an attribute

Reorganize (reindex) the internal data of an attribute. This can improve performance after many selective operations have been applied. Typically used after building complex hierarchies or after many selection-based modifications.

Parameters

new_attribute_name (str) – The name for the resulting reorganized attribute.
object (str, optional) – The object which holds the attribute to reorganize. Required together with dimension and attribute when identifying the attribute by full path; omit when passing attribute as a shorthand path object.
dimension (str, optional) – The dimension which holds the attribute to reorganize.
attribute (str, optional) – The attribute to reorganize. Can be a plain name string (when combined with object and dimension) or a shorthand path object when object is not given.
hierarchy (list, optional) – The explicit list of first-level state names defining the new hierarchy. Exactly one of hierarchy, level, or levelName must be provided.
level (int, optional) – Pull states from this hierarchy level number up to the first level. Exactly one of hierarchy, level, or levelName must be provided.
level_name (str, optional) – Pull states from this named hierarchy level up to the first level. Exactly one of hierarchy, level, or levelName must be provided.
hierarchy_level_names (list, optional) – Optional names for the resulting hierarchy levels.
others_state_name (str, optional, default='others') – Name for the catch-all state that collects first-level states not present at the pulled-up level (used with level / levelName). Defaults to “others”.

Returns

The session state after the operation.

Return type

dict

XplainClient.remove_attributes_with_tag(tag, ignore_exception=False)

Remove all attributes with a given tag

Remove all attributes across all objects and dimensions that have the specified tag. Optionally ignores errors if a particular attribute cannot be removed.

Parameters

tag (str) – The tag name; all attributes with this tag will be removed.
ignore_exception (bool, optional, default=False) – If true, errors during removal of individual attributes are suppressed.

Returns

The session state after the operation.

Return type

dict

XplainClient.add_tag(element, tag)

Add a tag to an element (object, dimension, or attribute)

Add the specified tag to a dimension or attribute identified by its XElementPath. Tags can later be used to select or remove groups of attributes with removeAttributesWithTag.

Parameters

element (dict) – The path to the element to tag. XElementPath
tag (str) – The tag to add.

Returns

The session state after the operation.

Return type

dict

XplainClient.remove_tag(element, tag)

Remove a tag from an element

Remove the specified tag from a dimension or attribute identified by its XElementPath.

Parameters

element (dict) – The path to the element to untag. XElementPath
tag (str) – The tag to remove.

Returns

The session state after the operation.

Return type

dict

XplainClient.add_all_tags(element)

Remove all tags from an element

Remove all tags from the specified element (dimension or attribute). Despite the name “addAllTags”, this operation clears all existing tags from the element.

Parameters: element (dict) – The path to the element whose tags should be cleared. XElementPath
Returns: The session state after the operation.
Return type: dict

XplainClient.build_attribute_from_selection(attribute, new_attribute_name=None, object=None, dimension=None, selection_set='globalSelections')

Build a new attribute from the current selection

Create a new attribute whose states are derived from the current global selections. This allows saving a selection pattern as a reusable attribute hierarchy.

Parameters

attribute (str) – The name for the new attribute (plain name string when combined with object and dimension, or a shorthand path when object is omitted).
new_attribute_name (str, optional) – The name for the new attribute to be created.
object (str, optional) – The object for which to build the attribute. When provided, dimension and attribute must also be given as plain name strings.
dimension (str, optional) – The dimension in which to add the new attribute. Required when object is provided.
selection_set (str, optional, default='globalSelections') – The selection set to derive states from. Defaults to “globalSelections” if not given.

Returns

The session state after the operation.

Return type

dict

Predictive Models

XplainClient.build_predictive_model(model_name, xmodel_configuration_file_name=None, configuration=None, target_event_object=None, target_dimension=None, significance=None, max_independent_variables=None, min_support=None, number_of_validation_partitions=None, estimate_causal_graph=None, build_recommendations=None, segment_measures=None, explanation_generation_file_name=None, goal=None, training_scope=None, primary_target_selection_attributes=None, target_selections=None, target_and_surrogate_target_event_space=None, start_of_episode_selections=None)

Build a predictive (causal discovery) model

Build a predictive model using the Noisy-Or causal discovery algorithm. The model is trained on the currently loaded data using the specified configuration.

Aliases: buildModel, createModel, crossValidateModel (all work identically).

A model configuration file (.xmodel) can be provided via xmodelConfigurationFileName or configuration, or the configuration can be proposed using proposeModelConfiguration first.

Parameters

model_name (str) – The name for the model (must be unique within the session).
xmodel_configuration_file_name (str, optional) – Name of an .xmodel configuration file. Aliases: xmodelConfigurationName, fileName.
configuration (dict, optional) – Inline model configuration as a JSON object.
target_event_object (str, optional) – Name of the target event object (for Noisy-Or models).
target_dimension (str, optional) – Name of the target dimension.
significance (float, optional) – Statistical significance threshold.
max_independent_variables (int, optional) – Maximum number of independent variables to include.
min_support (int, optional) – Minimum support count for a factor to be considered.
number_of_validation_partitions (int, optional) – Number of cross-validation partitions.
estimate_causal_graph (bool, optional) – Whether to estimate the causal graph after building.
build_recommendations (bool, optional) – Whether to build recommendations.
segment_measures (list, optional) – Optional list of segment measure names.
explanation_generation_file_name (str, optional) – Optional file containing explanation generation configuration.
goal (str, optional) – Optional goal description for explanation generation (used with explanationGenerationFileName).
training_scope (list, optional) – Optional array of selections on root object level to restrict model training. The validation set is implicitly the model scope minus the training scope. SelectionUIModel
primary_target_selection_attributes (list, optional) – Optional list of attributes that primarily define the target selections. Also accepted as the deprecated alias targetSelectionAttributes. XElementPath
target_selections (list, optional) – Optional explicit target selections. SelectionUIModel
target_and_surrogate_target_event_space (list, optional) – Optional target and surrogate target event space selections. SelectionUIModel
start_of_episode_selections (list, optional) – Optional start-of-episode selections. SelectionUIModel

Returns

The session state after the operation.

Return type

dict

XplainClient.propose_model_configuration(model_name, model_object, target_object=None, search_objects=None, process_time_scale='DAY', file=None, exclude=None)

Generate a model configuration proposal from minimal parameters

Generate a basic causal discovery model configuration from as few parameters as possible. All further parameters are proposed or set to default values. This serves as a starting point for further refining the configuration.

The returned configuration can be saved to a .xmodel file and passed to buildPredictiveModel for the actual model building.

Parameters

model_name (str) – Mandatory name of the model.
model_object (str) – Mandatory name of the model object (the entity for which the statistical model is built).
target_object (str, optional) – Name of the target object. If not given, defaults to modelObject.
search_objects (list, optional) – Optional list of object names to search for causal factors. If not given, all objects are searched.
process_time_scale (str, optional, default='DAY') – Time scale of the process when explaining an event where the target object is a sub-object of the model object. Possible values: NANOSECOND, MILLISECOND, SECOND, MINUTE, HOUR, DAY (default), WEEK, MONTH, QUARTER, HALFYEAR, YEAR, DECADE, CENTURY.
file (dict, optional) – If given, the proposed configuration is persisted to this file. FileDescriptor
exclude (list, optional) – Elements to exclude from the model (list of XElementPath).

Returns

The session state after the operation.

Return type

dict

XplainClient.set_model_configuration(model_name, event_space=None)

Set configuration parameters for an existing model

Update configuration parameters for an existing model in the current session. Currently supports setting the eventSpace for Noisy-Or models.

Parameters

model_name (str) – The name of the model to configure.
event_space (list, optional) – The event space definition for Noisy-Or models. SelectionUIModel

Returns

The session state after the operation.

Return type

dict

XplainClient.save_model_configuration(model_name, file)

Save a model’s current configuration to a file

After computing a Causal Discovery model, the final result holds information about causal factors found and the causal graph. The result file also holds the original configuration to which changes may have been made during the model building process.

Using saveModelConfiguration, you can save the final configuration to use it as a starting point in a new Causal Discovery run. All result fields are cleared in the saved output.

Parameters

model_name (str) – The name of the model for which to save the configuration. The model must be loaded in the current session. Can also be specified as predictiveModel.
file (dict) – The file descriptor where the configuration should be written. FileDescriptor

Returns

The session state after the operation.

Return type

dict

XplainClient.get_model_configuration(file=None, file_name=None, model_name=None)

Get or load a model configuration

Retrieve a model configuration, either from a file or from an existing model in the session. Returns the configuration JSON. The alias getModelProposal also works.

Parameters

file (dict, optional) – A .xmodel or .xmodelresult file to load. FileDescriptor
file_name (str, optional) – [Deprecated] Deprecated. Use file instead.
model_name (str, optional) – Name of an existing model in the session.

Returns

The session state after the operation.

Return type

dict

XplainClient.evaluate_model(model_name)

Evaluate a predictive model and return evaluation metrics

Evaluate the predictive performance of an existing model and return model evaluation results (e.g., AUC, accuracy, confusion matrix).

Parameters: model_name (str) – The name of the model to evaluate.
Returns: The session state after the operation.
Return type: dict

XplainClient.delete_model(model_name)

Delete a model from the current session

Delete the model from the current session. Results will be lost if the model has not been saved. Use exportModel to save before deleting.

Parameters: model_name (str) – The name of the model to delete.
Returns: The session state after the operation.
Return type: dict

XplainClient.refit_model(model_name, significance=None, fix_existing_variables=True, target_time_range=None, new_model_name=None)

Refit an existing model with current data

Re-run the model fitting procedure on the current data. Useful after selections have changed or after adding/removing variables.

Parameters

model_name (str) – The name of the model which will be re-fitted.
significance (float, optional) – A new significance threshold. If not given, the previous significance will be used.
fix_existing_variables (bool, optional, default=True) – If true, the existing variables will not be pruned.
target_time_range (dict, optional) – If given, used as a new target time frame. Must be a selection on the target time dimension of the original model. If provided, newModelName is mandatory. SelectionUIModel
new_model_name (str, optional) – The name of the new re-fitted model. Mandatory if targetTimeRange is given.

Returns

The session state after the operation.

Return type

dict

XplainClient.clone_model(model_name, new_model_name)

Clone an existing model under a new name

Create an identical copy of an existing Noisy-Or model under a different name. Both the original and the clone remain in the session.

Parameters

model_name (str) – The name of the model to clone.
new_model_name (str) – The name for the cloned model (must be different from modelName).

Returns

The session state after the operation.

Return type

dict

XplainClient.open_model(model_name)

Open a model for interactive exploration

Open an existing model in the session for interactive exploration and visualization.

Parameters: model_name (str) – The name of the model to open.
Returns: The session state after the operation.
Return type: dict

XplainClient.close_model(model_name)

Close an open model

Close a model that was previously opened with openModel. Frees the resources associated with the open model view.

Parameters: model_name (str) – The name of the model to close.
Returns: The session state after the operation.
Return type: dict

XplainClient.import_model(file, file_name=None, explanation_generation_file_name=None, goal=None)

Import a model from a file into the current session

Load a previously saved model (.xmodelresult) from a file into the current session. The alias loadModel also works.

Parameters

file (dict) – The .xmodelresult file to import. FileDescriptor
file_name (str, optional) – [Deprecated] Deprecated. Use file instead.
explanation_generation_file_name (str, optional) – Optional file containing explanation generation configuration.
goal (str, optional) – Optional goal description for explanation generation.

Returns

The session state after the operation.

Return type

dict

XplainClient.export_model(model_name, file, file_name=None)

Export a model to a file

Save a model from the current session to a file. Aliases: saveModel, exportVariableSet.

Parameters

model_name (str) – The name of the model to export. Also accepted as predictiveModel.
file (dict) – The destination file. FileDescriptor
file_name (str, optional) – [Deprecated] Deprecated. Use file instead.

Returns

The session state after the operation.

Return type

dict

XplainClient.select_factor(model_name, factor)

Select a factor in a predictive model

Mark a factor as selected in the specified model. Selected factors are highlighted in the model visualization and can be used for targeted analysis.

Parameters

model_name (str) – The name of the model.
factor (str) – The name of the factor to select.

Returns

The session state after the operation.

Return type

dict

XplainClient.clear_factor_selection(model_name)

Clear the factor selection in a predictive model

Remove all factor selections from the specified model, returning it to a neutral state.

Parameters: model_name (str) – The name of the model.
Returns: The session state after the operation.
Return type: dict

Causal Discovery

XplainClient.estimate_causal_graph(model_name)

Estimate the causal graph for a Noisy-Or model

Estimate the causal graph for the specified Noisy-Or model. The causal graph shows directional relationships between variables in the model. Requires that the model has been built first with buildPredictiveModel.

Parameters: model_name (str) – The name of the Noisy-Or model.
Returns: The session state after the operation.
Return type: dict

XplainClient.reject_factors(model_name, ignore_events=None, ignore_all_factors=None, find_alternatives_for=None, keep_history_point=False)

Reject specified factors from a Noisy-Or model

Reject (remove) specific factors from a Noisy-Or model and optionally search for alternatives. Factors can be specified by name or all can be rejected at once.

Parameters

model_name (str) – The name of the Noisy-Or model.
ignore_events (list, optional) – List of factor/event names to reject. Also accepted as ignoreFactors.
ignore_all_factors (bool, optional) – If true, all current factors are rejected.
find_alternatives_for (list, optional) – List of factor names for which to search alternatives after rejection.
keep_history_point (bool, optional, default=False) – Whether to keep a history point before rejection.

Returns

The session state after the operation.

Return type

dict

XplainClient.reject_factors_recursively(model_name, indirect_factorslikelihood_ratio_limit=1.0, max_indirect_factors_search_cycles=None, observations_file=None, prune_and_refit_final_variable_set=False)

Recursively reject factors and search for alternatives

Iteratively rejects indirect factors in a Noisy-Or model based on a likelihood ratio threshold, cycling until no more factors qualify for rejection. Optionally writes observations to a file and prunes/refits the final variable set.

Parameters

model_name (str) – The name of the Noisy-Or model.
indirect_factorslikelihood_ratio_limit (float, optional, default=1.0) – Likelihood ratio threshold for rejecting indirect factors. Factors with a ratio below this value are rejected.
max_indirect_factors_search_cycles (int, optional) – Maximum number of rejection cycles. No limit if not given.
observations_file (str, optional) – Optional file to write observations data to.
prune_and_refit_final_variable_set (bool, optional, default=False) – Whether to prune and refit the final variable set.

Returns

The session state after the operation.

Return type

dict

XplainClient.find_related_factors(model_name, factors=None, min_correlation=0.5, max=10)

Find factors correlated with specified factors

Search for factors that are correlated with the specified list of factors in a Noisy-Or model. Returns the top correlated factors above the minimum correlation threshold.

Parameters

model_name (str) – The name of the Noisy-Or model.
factors (list, optional) – List of factor names to find correlations for.
min_correlation (float, optional, default=0.5) – Minimum correlation coefficient to include in results.
max (int, optional, default=10) – Maximum number of related factors to return.

Returns

The session state after the operation.

Return type

dict

XplainClient.search_for_new_factors(model_name, new_model_name)

Search for new causal factors in a model

Perform a search for new causal factors not yet in the model. This expands the variable set by looking for additional predictors.

Parameters

model_name (str) – The name of the existing model to refit and compare against.
new_model_name (str) – The name of the new model used as the comparison target.

Returns

The session state after the operation.

Return type

dict

XplainClient.run_discovery_bot(config_file, assumed_current_time=None, charset=None)

Run the automated discovery bot

Run the automated causal discovery bot, which performs a systematic analysis comparing different model configurations and suggesting improvements.

Parameters

config_file (dict) – The bot configuration file (of type XCD_BOT_CONFIG). FileDescriptor
assumed_current_time (str, optional) – Optional assumed current time for the bot run (ISO-8601 or similar parseable time string). If not given, the actual current time is used.
charset (str, optional) – Optional character set for the CSV result log file. Defaults to the session’s default CSV export charset.

Returns

The session state after the operation.

Return type

dict

XplainClient.set_causal_relation(model_name, causal_relation, variables=None)

Set the causal relation type for variables in a model

Set the causal relation type (e.g., CAUSAL, ANTICAUSAL, SPURIOUS) for specific variables or all variables in a Noisy-Or model.

Parameters

model_name (str) – The name of the model.
causal_relation (str) – The causal relation type to assign. Possible values depend on the CausalRelationType enum (e.g., CAUSAL, ANTICAUSAL, SPURIOUS).
variables (list, optional) – List of variable names to set the relation for. If not given, all variables are updated.

Returns

The session state after the operation.

Return type

dict

XplainClient.add_variable(model_name, selections, threshold, aggregation=None)

Add a variable to a causal model

Add a new variable (independent factor) to an existing causal model. The variable is specified as a dimension/attribute path.

Parameters

model_name (str) – The name of the model.
selections (list) – A set of selections which define the semantics of the variable. Must not be empty. SelectionUIModel
threshold (int) – The threshold of the binary aggregation variable.
aggregation (dict, optional) – An optional aggregation which defines the aggregation variable. Default is a simple COUNT of the corresponding object. AggregationUIModel

Returns

The session state after the operation.

Return type

dict

XplainClient.evaluate_all_alternatives(model_name)

Evaluate all alternative variables for each factor in a model

Search for and evaluate alternative variables for all factors currently in the Noisy-Or model. Results are stored in the model and shown in the visualization.

Parameters: model_name (str) – The name of the model.
Returns: The session state after the operation.
Return type: dict

Configuration

XplainClient.enable_caching()

Enable caching for aggregation dimensions

Sets the flag cachingEnabled = true. As a result, aggregation dimensions built henceforth will be cached, improving performance for repeated queries.

Returns: The session state after the operation.
Return type: dict

XplainClient.disable_caching()

Disable caching for aggregation dimensions

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

Returns: The session state after the operation.
Return type: dict

XplainClient.get_caching_enabled()

Get whether caching is currently enabled

Returns the current value of the cachingEnabled flag.

Returns: The session state after the operation.
Return type: dict

XplainClient.set_enable_hot_swap(hot_swap_enabled)

Set whether hot-swap (data swapping) is allowed

Sets whether the user / the current session allows data swaps (hot-swap). When enabled, waiting data on the stage will be immediately swapped in.

Parameters: hot_swap_enabled (bool) – Whether data swaps are allowed (true or false).
Returns: The session state after the operation.
Return type: dict

XplainClient.cache_aggregation_dimensions(dimensions=None)

Cache aggregation dimensions

Caches all aggregation dimensions which are currently not cached (and which do not have floating semantics). An optional list of specific dimensions can be provided; if not given, all eligible aggregation dimensions will be considered.

Parameters: dimensions (list, optional) – Optional list of specific dimensions to cache. If not given, all eligible aggregation dimensions are cached. XElementPath
Returns: The session state after the operation.
Return type: dict

XplainClient.drop_aggregation_dimension_caches()

Drop all aggregation dimension caches

Drops all existing caches of aggregation dimensions, freeing memory. After this call, aggregation dimensions will need to be recomputed on next use.

Returns: The session state after the operation.
Return type: dict

XplainClient.set_max_threads(max_threads)

Set the global maximum number of parallel threads

Sets the global MAX_PARALLEL_THREADS value. This affects all sessions on the server. Use setMaxThreadsForSession to limit threads for a specific session only.

Parameters: max_threads (int) – The maximum number of parallel threads.
Returns: The session state after the operation.
Return type: dict

XplainClient.set_tasks_per_thread(tasks_per_thread)

Set the number of tasks per thread

Sets the global TASKS_PER_THREAD value, controlling how many computation tasks are assigned to each thread during parallel computation.

Parameters: tasks_per_thread (int) – The number of tasks per thread.
Returns: The session state after the operation.
Return type: dict

XplainClient.set_max_threads_for_session(max_threads)

Set the maximum number of threads for this session

Sets the maximum number of parallel threads for this specific session only (does not affect global settings). A value of 0 or negative resets to the global default.

Parameters: max_threads (int) – The maximum number of threads for this session. A value ≤ 0 resets to the global default.
Returns: The session state after the operation.
Return type: dict

XplainClient.set_max_one_dim_group_by_size(size)

Set the maximum size of a one-dimensional group-by

Sets the maximum size 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 there are 500 different states in the “Product” attribute, the size is 500). This parameter limits each component of a potentially multi-dimensional group-by, to avoid transmitting too-large result sets to web-based frontends.

Parameters: size (int) – The maximum number of states allowed in a one-dimensional group-by.
Returns: The session state after the operation.
Return type: dict

XplainClient.set_max_nr_instances_for_ranking(max_nr_instances_for_ranking)

Set the maximum number of instances for ranking

Set the maximum number of instances allowed for ranking computations. Increasing this number might drastically increase runtime when using ranking resources. Pass null to remove the limit.

Parameters: max_nr_instances_for_ranking (int) – The maximum number of instances (or null for no limit).
Returns: The session state after the operation.
Return type: dict

XplainClient.set_memory_parameters(stock_increment_size=None, stock_size_limit=None)

Set memory management parameters

Configure memory parameters for the Xplain engine. All parameters are optional; only those provided are updated.

Parameters

stock_increment_size (int, optional) – The size increment for stock allocations (STOCK_INCREMENT_SIZE).
stock_size_limit (int, optional) – The upper limit for stock size (STOCK_SIZE_LIMIT).

Returns

The session state after the operation.

Return type

dict

XplainClient.set_results_format(format)

Set the results format for this session

Sets the format in which results are returned for the current session. The alias setResultFormat (without the ‘s’) also works.

Parameters: format (str) – The results format name (e.g., a ResultsFormat enum value).
Returns: The session state after the operation.
Return type: dict

XplainClient.set_description(description)

Set the session description

Set a description for the current session. The description is typically used to describe the purpose of a session or analysis. The ObjectExplorer shows this description when clicking the corresponding info icon and allows editing it as an HTML document.

Parameters: description (str) – The description text (may contain HTML).
Returns: The session state after the operation.
Return type: dict

XplainClient.set_format(dimension, format)

Set the format string for a dimension

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.

Parameters

dimension (dict) – A JSON object specifying the dimension path (with object and dimension properties).
format (str) – The format string.

Returns

The session state after the operation.

Return type

dict

XplainClient.configure_garbage_collections(gc_before_import=None, gc_during_import_before_mapping_packages=None, gc_after_import=None, gc_before_startup=None, gc_after_startup=None, gc_after_startup_script=None)

Configure when explicit garbage collections are performed

Configure when to perform additional/explicit garbage collections during various lifecycle phases of data import and startup.

Parameters

gc_before_import (bool, optional) – Whether to GC before data import.
gc_during_import_before_mapping_packages (bool, optional) – Whether to GC during import before mapping package start positions.
gc_after_import (bool, optional) – Whether to GC after data import.
gc_before_startup (bool, optional) – Whether to GC before running a startup configuration.
gc_after_startup (bool, optional) – Whether to GC after running a startup configuration. If enabled, the GC is run before the startup script.
gc_after_startup_script (bool, optional) – Whether to GC after running a startup script.

Returns

The session state after the operation.

Return type

dict

Batch & Scripting

XplainClient.execute_batch(file=None, file_name=None, method_calls=None, script=None, recompute_requests_after_batch=True, execute_in_batch_mode=True, terminate_on_exception=True)

Execute multiple method calls in one batch

Execute multiple requests in one batch. Provide either an inline array of method calls or a reference to a script file. The synonym executeScript also works.

Example with inline calls:

{

“methodCalls”: [
{ “method”: “deleteAllRequests” }, {

“method”: “executeRequest”, “request”: { … }

}

]

}

Task Management

XplainClient.kill_tasks()

Kill all currently running computation tasks

Immediately terminates all running computation tasks for this session. Use terminateComputation to request a graceful stop instead.

Returns: The session state after the operation.
Return type: dict

XplainClient.get_progress()

Get progress information about running jobs

Get progress information about running computation jobs. Returns a fraction of processed load and absolute counts.

Special values for progress: - -1.0: No tasks are currently registered in the task list. - -2.0: A task exists but total load is 0.

Special value -1 for processedLoad and totalLoad indicates an empty task list.

Returns: The session state after the operation.
Return type: dict

XplainClient.get_messages(clear=False)

Get current session messages

Get current messages, for example information on the progress of the predictive models or on missing states when loading a session. Those messages are also transmitted as a property of the session document.

Parameters: clear (bool, optional, default=False) – If true, messages are cleared after being returned.
Returns: The session state after the operation.
Return type: dict

XplainClient.terminate_computation()

Request graceful termination of the current computation

Sets a flag requesting that the current computation be gracefully terminated. The computation will stop at the next safe checkpoint. For immediate termination, use killTasks instead.

Returns: The session state after the operation.
Return type: dict

Diagnostics

XplainClient.resource_usage()

Get memory and resource usage information

Returns detailed memory and resource usage statistics for the current JVM, including heap memory, non-heap memory, system CPU load, and session instance counts.

Returns: The session state after the operation.
Return type: dict

XplainClient.gc()

Invoke garbage collection

Invokes System.gc() to request a JVM garbage collection. The JVM is not guaranteed to immediately perform a full GC, but this signals the intent.

Returns: The session state after the operation.
Return type: dict

XplainClient.validate_x_table(object=None, print=None)

Validate an XTable

Validates the integrity of an XTable. Checks consistency of data structures and reports any errors found.

Parameters

object (str, optional) – The object whose XTable should be validated.
print (bool, optional) – Whether to print validation output to the log.

Returns

The session state after the operation.

Return type

dict

XplainClient.evaluate_performance(threads, method_call, file_name='performance.xlsx', repeats=1)

Measure server performance across different thread counts

Measures the server performance by executing a given method call with different maxThreads values and comparing the results. The output is stored in an Excel file which can be downloaded via: <host>:<port>/downloadfile?type=RESULT&filename=performance.xlsx

Parameters

threads (list) – The list of maxThreads values to test.
method_call (dict) – The method call to benchmark.
file_name (str, optional, default='performance.xlsx') – Output Excel filename.
repeats (int, optional, default=1) – Number of repeats per thread count to average measurements.

Returns

The session state after the operation.

Return type

dict

XplainClient.output_x_table_statistics(indentation_string=' ')

Get XTable memory and structure statistics

Returns detailed statistics about the internal structure and memory consumption of the loaded XTable(s).

Parameters: indentation_string (str, optional, default=' ') – Indentation string used for formatting the output.
Returns: The session state after the operation.
Return type: dict

XplainClient.get_recent_execution_statistics()

Get statistics from the most recent computation

Returns timing and performance statistics from the most recently completed computation. Returns empty if no computation has been performed yet.

Returns: The session state after the operation.
Return type: dict

XplainClient.run_x_object_diagnostics()

Run diagnostics on the XObject tree

Runs a comprehensive diagnostic on the XObject hierarchy and returns a JSON document with the diagnostic results.

Returns: The session state after the operation.
Return type: dict

Export & File

XplainClient.export_results(request_names, result_xls, template_xls=None, sheet_names=None, column_headers=None, use_display_names=True, ignore_zero_result_lines=True, fix_invalid_sheet_name=False, excel_fonts=None, excel_cell_styles=None, map_request_to_excel_header_cell_styles=None, map_request_to_excel_data_cell_styles=None)

Export query results to a file

Export the results of the current requests/queries to a file (e.g., Excel or CSV). The exact parameters depend on the configuration of the export.

Parameters

request_names (list) – The names of the requests to be exported.
result_xls (str) – The name of the result (Excel) file.
template_xls (str, optional) – The filename of an Excel template.
sheet_names (list, optional) – An optional array of names, one for each request. If given, those names are used as sheetNames instead of the request names.
column_headers (dict, optional) – The array of column names overwrites the default column headers in the result Excel file.
use_display_names (bool, optional, default=True) – Signals whether the display names of the states shall be used in the Excel file instead of the technical state names.
ignore_zero_result_lines (bool, optional, default=True) – Result lines (aggregation cells) where all exported measures are 0 are omitted.
fix_invalid_sheet_name (bool, optional, default=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.
excel_fonts (dict, optional) – 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).
excel_cell_styles (dict, optional) – 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”, “verticalAlignment”, “rotation” (short), “fillPattern”, “fillBackgroundColor”, “fillForegroundColor” (short), border style and color entries, “hidden”, “locked”, “quotePrefixed”, “shrinkToFit”, “wrapText” (boolean).
map_request_to_excel_header_cell_styles (dict, optional) – A mapping from request names to arrays of cell style names for the header cells.
map_request_to_excel_data_cell_styles (dict, optional) – A mapping from request names to arrays of cell style names for the data cells.

Returns

The session state after the operation.

Return type

dict

XplainClient.run_export_requests(result_directory_name, export_requests=None, export_requests_file=None, replacements=None)

Run a set of export requests and write results to a directory

Execute a batch of export requests and write their results to a result directory. Each export request specifies what to export and in what format.

Parameters

result_directory_name (str) – The name of the directory where result files are written.
export_requests (list, optional) – Array of export request definitions (alternative to exportRequestsFile).
export_requests_file (str, optional) – File name of a config file containing export request definitions (alternative to exportRequests).
replacements (dict, optional) – Key-value pairs for placeholder substitution in export templates.

Returns

The session state after the operation.

Return type

dict

XplainClient.save_as_csv(elements, keys=None, file=None, file_name=None, charset=None, outer_join=False)

Save data as a CSV file

Save the specified data (based on current selections and/or requests) as a CSV file. The deprecated alias exportAsCSV also works.

Parameters

elements (list) – The elements (objects, dimensions and attributes) which should be written into the resulting JSON documents.
keys (list, optional) – An array of root object keys which can be used to constrain written data to only those keys.
file (dict, optional) – The file descriptor of the destination (csv) file. If left void the keys will be written to a public file with name “Flat Table Export.csv”. FileDescriptor
file_name (str, optional) – [Deprecated] (Deprecated) The filename parameter for the csv file.
charset (str, optional) – The name of the character set for encoding the csv file (e.g., “UTF-8”, “ISO-8859-1”, “US-ASCII”).
outer_join (bool, optional, default=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.

Returns

The session state after the operation.

Return type

dict

XplainClient.export_feature_table(root_dimensions=None, aggregation_variable_set=None, constrain_aggregations_to_current_selections=False, encode_names=None, file_name=None)

Export a feature table for machine learning

Export a feature table (flat table of features) derived from the current object model, suitable for use in external machine learning workflows.

Parameters

root_dimensions (list, optional) – List of root dimension names to include. If not given, all root dimensions are exported. To export no root dimensions, pass an empty array.
aggregation_variable_set (dict, optional) – A variable set JSON object specifying aggregation dimensions to include as features.
constrain_aggregations_to_current_selections (bool, optional, default=False) – If true, aggregations are constrained to the current global selections.
encode_names (bool, optional) – If true, dimension names are encoded (anonymized) in the output.
file_name (str, optional) – Output file name. Defaults to “Feature Table.csv” if not given.

Returns

The session state after the operation.

Return type

dict

XplainClient.save_selected_instances(file_name, split=None)

Save currently selected instances to a file

Save all instances (rows) that are currently selected by the global selections to a file. The output can be used to extract a subset of the data for further analysis.

Parameters

file_name (str) – Name of the file.
split (int, optional) – If a number > 1 is given, data will be split into multiple files.

Returns

The session state after the operation.

Return type

dict

XplainClient.save_selected_root_object_keys(file_name=None)

Save the keys of selected root object instances to a file

Save the primary keys of all currently selected root object instances to a file. Useful for identifying and exporting a specific cohort.

Parameters: file_name (str, optional) – The name of the csv file. If left void the keys will be written to the file with name “Selected Root Object Keys.csv”.
Returns: The session state after the operation.
Return type: dict

XplainClient.copy_table(source_object, new_table_name=None, new_table_file_name=None, add_as_sub_object=False, dimensions_to_copy=None, sampling_factor=None, dimensions_to_randomize=None, randomize_all=False, package_size=None, conversions=None, sort_dimension=None, segments_group_by=None, others_segment_name=None)

Copy a table or subset to a new XTable

Copy a table (or a subset according to current selections) and save it as a new XTable and/or add the subset into the current object model. Use cases include: - Cutting a subset from a large table for faster analysis - Pulling a randomized sample for debugging (without exposing raw customer data)

Note: Only physical dimensions of the underlying XTable can be copied (aggregation dimensions cannot be copied). If the subset is used in an analysis, it must be regenerated before the analysis can be reloaded.

Parameters

source_object (str) – The object from which to generate a copy.
new_table_name (str, optional) – The name of the new XTable / XObject. Defaults to <sourceObject> - Copy if not given.
new_table_file_name (str, optional) – File name where the new XTable will be written. If not given, the table is not persisted. Must include the .xtable extension.
add_as_sub_object (bool, optional, default=False) – If true, the new table is immediately added into the object tree.
dimensions_to_copy (list, optional) – If given, only these dimensions are copied.
sampling_factor (int, optional) – If given, only every N-th root object is written (sampling at root level).
dimensions_to_randomize (list, optional) – Values in these dimensions are randomly scrambled.
randomize_all (bool, optional, default=False) – If true, all values are randomly scrambled.
package_size (int, optional) – The package size for the new table.
conversions (dict, optional) – Optional mapping of dimension names to target data types for type conversion.
sort_dimension (str, optional) – Optional dimension name to sort by.
segments_group_by (dict, optional) – Required when sortDimension is given. A one-dimensional group-by JSON object that defines the segments used for sorting.
others_segment_name (str, optional) – Optional name for the “others” segment when sortDimension is used.

Returns

The session state after the operation.

Return type

dict

User Data

XplainClient.put_user_data(key, data=None, request=None)

Store custom JSON data in the session or a request

Add custom data in terms of a JSON document to the current session or specifically to a named request. Data is stored under a key and later retrieved from the userData property in the session JSON. Typically used by clients to persist additional formatting or UI state information alongside the session.

When saving an analysis, user data is persisted with it and restored on reload.

The synonyms storeUserData and setUserData also work (deprecated, prefer putUserData).

The parameter key can alternatively be named userKey, and data can alternatively be named jsonObject.

Parameters

key (str) – The key under which data are stored. Can also be named userKey.
data (dict, optional) – The data to be stored as a JSON object. Can also be named jsonObject.
request (str, optional) – Optional request ID. If given, the data is attached to that specific request rather than the session. Can also be named xElement or xArtifact.

Returns

The session state after the operation.

Return type

dict

XplainClient.store_user_data(key, data=None, request=None)

Store custom JSON data (deprecated, use putUserData)

Deprecated synonym for putUserData. Use putUserData instead.

Parameters

key (str) – See API documentation.
data (dict, optional) – See API documentation.
request (str, optional) – See API documentation.

Returns

The session state after the operation.

Return type

dict

Deprecated since version Use: the non-deprecated equivalent instead.

XplainClient.set_user_data(key, data=None, request=None)

Store custom JSON data (deprecated, use putUserData)

Deprecated synonym for putUserData. Use putUserData instead.

Parameters

key (str) – See API documentation.
data (dict, optional) – See API documentation.
request (str, optional) – See API documentation.

Returns

The session state after the operation.

Return type

dict

Deprecated since version Use: the non-deprecated equivalent instead.

XplainClient.clear_user_data()

Clear all user data from the session

Removes all custom user data that was previously stored in the session via putUserData. This clears the entire userData map.

Returns: The session state after the operation.
Return type: dict

XplainClient.set_definition(dimension)

Set a definition for a session element

Set a JSON definition associated with a specific element in the session. Definitions are used for storing structured metadata about dimensions or attributes. Currently only supported for dimensions (aggregation dimensions, relative time axis, rank dimensions, selection dimensions, and linear sum dimensions).

Parameters: dimension (dict) – The dimension for which to get definitions specified as an XElementPath ({object: <…>, dimension: <…>}). XElementPath
Returns: The session state after the operation.
Return type: dict

XplainClient.get_definition(dimension=None, attribute=None, request=None)

Get the definition for a session element

Retrieve the JSON definition associated with a specific element in the session. One of the arguments dimension, attribute or request (alternatively query) needs to be given.

Parameters

dimension (dict, optional) – The dimension for which to get definitions specified as an XElementPath ({object: <…>, dimension: <…>}). XElementPath
attribute (dict, optional) – The attribute for which to get definitions specified as an XElementPath ({object: <…>, dimension: <…>, attribute: <…>}). XElementPath
request (str, optional) – The name/ID of the request for which to get definitions.

Returns

The session state after the operation.

Return type

dict

Sampling

XplainClient.start_sampling(sample_size=10)

Start sampling mode for the session

Activates sampling mode on the session. In sampling mode, computations are performed on a sample of the data rather than the full dataset, allowing for faster interactive exploration. Use stopSampling to deactivate.

Parameters: sample_size (int, optional, default=10) – The sample size in 1 of 1000, i.e. sampleSize=10 means a 1% sample. This parameter needs to be >0 and <1000.
Returns: The session state after the operation.
Return type: dict

XplainClient.stop_sampling()

Stop sampling mode and return to full data

Deactivates sampling mode. Subsequent computations will use the full dataset again.

Returns: The session state after the operation.
Return type: dict

Longitudinal Analysis

XplainClient.run_longitudinal_analysis(configuration_file=None, configuration=None)

Run a longitudinal (event-based) analysis

Run a longitudinal analysis on the currently loaded data. The analysis is driven by a configuration that specifies event definitions, time windows, and output structure.

The configuration can be provided either as a file reference (configurationFile) or as an inline JSON object/string (configuration). Exactly one of the two must be specified.

After the analysis completes, the results are added to the session as new sub-objects.

Parameters

configuration_file (str, optional) – Name of the configuration file (in the config directory). Mutually exclusive with configuration.
configuration (dict, optional) – Inline configuration as a JSON object or JSON string. Mutually exclusive with configurationFile.

Returns

The session state after the operation.

Return type

dict

XplainClient.run_mix_market_analysis(configuration_file=None, configuration=None)

Run a Mix & Market analysis

Run a Mix & Market analysis on the currently loaded data. Similar to runLongitudinalAnalysis but uses a MixMarketConfiguration. Provide either configurationFile or configuration, but not both.

Parameters

configuration_file (str, optional) – Name of the configuration file (in the config directory). Mutually exclusive with configuration.
configuration (dict, optional) – Inline configuration as a JSON object or JSON string. Mutually exclusive with configurationFile.

Returns

The session state after the operation.

Return type

dict

XplainClient.add_relative_time_dimensions(reference_time_dimension, time_dimensions=None, interval_end_time_dimension=None, base_object=None, relative_time_type=None, names=None, reference_event_selections=None, fix_explicit_selections=None, time_unit=None, calendar_based=False, cache_reference_time=False, selection_set=None, floating_semantics=None)

Construct relative time dimension(s) based on reference events

Construct one or more relative time dimensions, measuring time relative to a reference event. The reference event is defined by the referenceEventSelections (e.g., “first diagnosis of a specific disease”).

If referenceEventSelections are given, they define the fixed part of the relative time axis. If in addition an external selection set is specified via selectionSet, any selections on attributes not part of referenceEventSelections are pulled dynamically from that set (giving the time axis floating semantics).

If no referenceEventSelections are given, the current global selections are used.

The deprecated method addRelativeTimes falls through to this method.

Parameters

reference_time_dimension (dict) – An element path (object and dimension name). XElementPath
time_dimensions (list, optional) – An array of element paths (each consisting of object and dimension name). XElementPath
interval_end_time_dimension (dict, optional) – An element path (object and dimension name), optional coding an interval in combination with referenceTimeDimension. XElementPath
base_object (str, optional) – The name of the base object. If the baseObject is not given, the root object used as baseObject.
relative_time_type (str, optional) – The reference type (“TO_FIRST”, “TO_LAST”, “TO_NEAREST”, “TO_NEXT”, “TO_PREVIOUS”). One of: TO_FIRST, TO_LAST, TO_NEAREST, TO_NEXT, TO_PREVIOUS.
names (list, optional) – The names of the new relative time dimensions (must be of same cardinality as timeDimensions).
reference_event_selections (list, optional) – The reference event selections. SelectionUIModel
fix_explicit_selections (str, optional) – 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 hasn’t 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. One of: none, all, only_propagate_upward.
time_unit (str, optional) – The time unit (“NANOSECOND”, “MILLISECOND”, “SECOND”, “MINUTE”, “HOUR”, “DAY”, “WEEK”, “MONTH”, “QUARTER”, “HALFYEAR”, “YEAR”, “DECADE”, “CENTURY”). One of: NANOSECOND, MILLISECOND, SECOND, MINUTE, HOUR, DAY, WEEK, MONTH, QUARTER, HALFYEAR, YEAR, DECADE, CENTURY.
calendar_based (bool, optional, default=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.)
cache_reference_time (bool, optional, default=False) – Decides whether caching should be applied.
selection_set (str, optional) – 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.
floating_semantics (bool, optional) – 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 - don’t use it any more.

Returns

The session state after the operation.

Return type

dict

XplainClient.build_sorted_sequence(target_object=None, ranks=None, reverse=False, names=None, name_postfixes=None, dimensions_to_replicate=None, sort_dimension=None, base_object=None, zero_point_dimension=None, selections=None, fix_explicit_selections=None, selection_set=None, selection_set_defining_rank=None, floating_semantics=None, attributes_to_copy=None, sequence_names=None, rank_dimension_name=None, rank_zero_is_first_instance_equal_or_greater_zero_point=False, transition_attribute=None, only_segment_starts=False, transition_level=1)

Build a sorted sequence from time-ordered events

Build a sorted sequence structure from time-ordered events, enabling sequence analysis (e.g., patient event journeys sorted by time).

Parameters

target_object (str, optional) – 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.)
ranks (list, optional) – The ranks of the new dimension (position when sorted according to sortDimension).
reverse (bool, optional, default=False) – For the case of reverse sorting / counting.
names (list, optional) – Names of the new dimensions - if not given a name 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).
name_postfixes (list, optional) – When given instead of names, the names will be generated based on those post-fixes.
dimensions_to_replicate (list, optional) – The dimensions which should be replicated (“unfolded” in time). Those need to be from the same source object. XElementPath
sort_dimension (dict, optional) – The dimension which defines the sorting (typically a time dimension, but could by any numeric dimension). XElementPath
base_object (str, optional) – 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.
zero_point_dimension (dict, optional) – An optional dimension relative to which the sorting / ranking is done. XElementPath
selections (list, optional) – The set of selections that will be applied as the “where” clause to the to be sorted/ranked events. SelectionUIModel
fix_explicit_selections (str, optional) – 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 hasn’t 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). One of: none, all, only_propagate_upward.
selection_set (str, optional) – 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.
selection_set_defining_rank (str, optional) – An old deprecated parameter which may be used instead of selectionSet.
floating_semantics (bool, optional) – 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 - don’t use it any more.
attributes_to_copy (list, optional) – 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.
sequence_names (list, optional) – If given the dimensions will be grouped into a sequence (see the corresponding methods for more details, e.g. openSequence).
rank_dimension_name (str, optional) – 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.
rank_zero_is_first_instance_equal_or_greater_zero_point (bool, optional, default=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, …
transition_attribute (dict, optional) – 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. XElementPath
only_segment_starts (bool, optional, default=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.
transition_level (int, optional, default=1) – See the parameter transitionAttribute: the hierarchy level of the attribute which is used to detect transitions.

Returns

The session state after the operation.

Return type

dict

XplainClient.open_sequence(sequence_names, dimensions_to_replicate=None, sort_dimension=None, ranks=None, target_object=None, base_object=None, zero_point_dimension=None, reverse=False, names=None, name_postfixes=None, selections=None, fix_explicit_selections=None, selection_set=None, selection_set_defining_rank=None, floating_semantics=None, rank_dimension_name=None, rank_zero_is_first_instance_equal_or_greater_zero_point=False, attributes_to_copy=None, transition_attribute=None, only_segment_starts=False, transition_level=1, open_marginal_queries=True, open_transition_queries=False)

Open a sequence for interactive exploration

Open a previously built sequence in the session for interactive analysis. The opened sequence computes and returns aggregated sequence results. Accepts all parameters of buildSortedSequence combined with those of openSequenceQueries.

Parameters

sequence_names (list) – Names of the sequences to build and immediately open.
dimensions_to_replicate (list, optional) – The dimensions which should be replicated (“unfolded” in time). Those need to be from the same source object. XElementPath
sort_dimension (dict, optional) – The dimension which defines the sorting (typically a time dimension, but could be any numeric dimension). XElementPath
ranks (list, optional) – The ranks of the new dimension (position when sorted according to sortDimension).
target_object (str, optional) – 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.)
base_object (str, optional) – 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).
zero_point_dimension (dict, optional) – An optional dimension relative to which the sorting / ranking is done. XElementPath
reverse (bool, optional, default=False) – For the case of reverse sorting / counting.
names (list, optional) – Names of the new dimensions - if not given a name 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).
name_postfixes (list, optional) – When given instead of names, the names will be generated based on those post-fixes.
selections (list, optional) – The set of selections that will be applied as the “where” clause to the to be sorted/ranked events. SelectionUIModel
fix_explicit_selections (str, optional) – This parameter may have one of the three values “none” (the default), “all” or “only_propagate_upward”. See buildSortedSequence for full description. One of: none, all, only_propagate_upward.
selection_set (str, optional) – If specified, the selections from the given set will be used as the selections, thereby implementing a “floating semantics” concept.
selection_set_defining_rank (str, optional) – An old deprecated parameter which may be used instead of selectionSet.
floating_semantics (bool, optional) – Deprecated. If false when a selectionSet is specified, the current selections are copied and kept fixed.
rank_dimension_name (str, optional) – 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.
rank_zero_is_first_instance_equal_or_greater_zero_point (bool, optional, default=False) – If true this means that the first instance in the array of sorted instances which is >= zero point receives the rank 0.
attributes_to_copy (list, optional) – 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.
transition_attribute (dict, optional) – 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. XElementPath
only_segment_starts (bool, optional, default=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.
transition_level (int, optional, default=1) – See the parameter transitionAttribute: the hierarchy level of the attribute which is used to detect transitions.
open_marginal_queries (bool, optional, default=True) – If true, queries for the marginal distributions for each sequence step will be opened (one-dimensional).
open_transition_queries (bool, optional, default=False) – If true, queries which describe the transitions between each step will be opened (two-dimensional).

Returns

The session state after the operation.

Return type

dict

XplainClient.join(from_, to, as_, on_time_diff, base_object=None, selections=None, sort_dimension=None, transition_attribute=None, only_segment_starts=False, transition_level=1, selection_set=None, floating_semantics=None, fix_explicit_selections=None, reverse=False, zero_point_dimension=None, rank_zero_is_first_instance_equal_or_greater_zero_point=False)

Join records from one sub-object into another via temporal constraints

Add records (object instances) from one sub-object of the root object into another sub-object, a sibling-object, or any object in a sibling branch. This is equivalent to a database join performed within the root object or any common ancestor (i.e. on matching keys).

In addition to the relative time axis and sequence analysis, join enables analyzing sub-objects in different branches in relation to each other — a powerful feature of ObjectAnalytics for analyzing an object hierarchy as a whole.

Example use cases: - Add prescriptions of a certain type to all diagnoses (e.g. each diagnosis holds all

prescriptions in the same quarter of a specific therapy as a sub-object).

For all visits of a customer in a local store, see what the customer ordered online on days after the visit.

Important: Because a join can replicate data (the same source record may be assigned to multiple target records), results can be huge. The selections and onTimeDiff clause must be restrictive — empty selections or an empty on-clause are not admitted.

The join operation is comparable to buildSortedSequence — many parameters are shared. The onTimeDiff parameters are identical to those of addTimeDifferenceDimension (for computing the time difference) combined with addIntervalFlagDimension (for the interval constraint).

Parameters

from (str) – Name of the source object from which records are to be added into the target object.
to (str) – Name of the target object to which instances of the source object are joined. The new object will appear as a sub-object of this object.
as (str) – Name of the new sub-object created by the join.
on_time_diff (dict) – Defines the temporal constraint that joined elements must fulfill. Combines parameters from addTimeDifferenceDimension (to compute the time difference) and addIntervalFlagDimension (to define the accepted interval).
base_object (str, optional) – The common ancestor object within which the join is performed (i.e. on matching keys of this object). Must be a common ancestor of both the from and to objects. Defaults to the root object if not specified.
selections (list, optional) – The set of selections applied as the “where” clause to filter the source records before joining. Must be restrictive to prevent huge join results. SelectionUIModel
sort_dimension (dict, optional) – The dimension that defines the sorting of joined records (typically a time dimension, but could be any numeric dimension). Optional. XElementPath
transition_attribute (dict, optional) – If specified, only transitions are coded — a new entry is made only when the value of this attribute on the given transitionLevel changes. XElementPath
only_segment_starts (bool, optional, default=False) – If true, only the first occurrence of a segment is assigned a rank (i.e. only when a new value of the transitionAttribute appears, as defined by transitionLevel).
transition_level (int, optional, default=1) – The hierarchy level of the transitionAttribute used to detect transitions.
selection_set (str, optional) – If specified, selections are pulled dynamically from this named selection set, implementing floating semantics.
floating_semantics (bool, optional) – Deprecated. If false when a selectionSet is specified, the current selections are copied and kept fixed rather than floating.
fix_explicit_selections (str, optional) – Controls how explicit selections are handled before being used in the join definition. “none” (default) keeps them as-is, “all” fixes all floating semantics recursively, “only_propagate_upward” fixes only propagate-upward dimensions non-recursively. One of: none, all, only_propagate_upward.
reverse (bool, optional, default=False) – For reverse sorting / counting of joined records.
zero_point_dimension (dict, optional) – An optional dimension relative to which the sorting / ranking is done. XElementPath
rank_zero_is_first_instance_equal_or_greater_zero_point (bool, optional, default=False) – If true, the first instance >= zero point receives rank 0, and numbering goes upward from there (0, 1, 2, …).
from_ (str) –
as_ (str) –

Returns

The session state after the operation.

Return type

dict

XplainClient.open_sequence_queries(sequence_names, open_marginal_queries=True, open_transition_queries=False, selection_set=None)

Open queries for a sequence

Open multiple queries associated with a sequence for parallel computation.

Parameters

sequence_names (list) – Names of the sequences previously generated for which to open the queries.
open_marginal_queries (bool, optional, default=True) – If true, queries for the marginal distributions for each sequence step will be opened (one-dimensional).
open_transition_queries (bool, optional, default=False) – If true, queries which describe the transitions between each step will be opened (two-dimensional).
selection_set (str, optional) – If specified, the sequence queries pull floating selections from the specified set.

Returns

The session state after the operation.

Return type

dict

XplainClient.clear_selections_for_sequence(sequence_name)

Clear selections associated with a sequence

Remove all selections that have been applied to the specified sequence, returning it to an unfiltered state.

Parameters: sequence_name (str) – Name of the sequence.
Returns: The session state after the operation.
Return type: dict

XplainClient.delete_sequence(sequence_name)

Delete a sequence from the session

Delete a sequence and all its associated resources from the current session.

Parameters: sequence_name (str) – Name of the sequence.
Returns: The session state after the operation.
Return type: dict

XplainClient.delete_sequence_queries(sequence_name, delete_marginal_queries=True, delete_transition_queries=True)

Delete queries associated with a sequence

Delete all open queries (requests) associated with the specified sequence, freeing their resources without deleting the sequence itself.

Parameters

sequence_name (str) – Name of the sequence.
delete_marginal_queries (bool, optional, default=True) – If true, queries for the marginal distributions for each sequence step will be deleted (one-dimensional).
delete_transition_queries (bool, optional, default=True) – If true, queries which describe the transitions between each step will be deleted (two-dimensional).

Returns

The session state after the operation.

Return type

dict