XplainSession

Note

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

python xplain-openapi/generate_client.py

Single entry point for all Xplain operations. Every method is organised into one of 8 namespaces accessible as properties of XplainSession.

from xplain import XplainSession

xp = XplainSession.from_profile("myserver")
xp.startup("MyModel")

df   = xp.query.attribute("Patients", "Gender", "Gender")
xp.select.values("Patients", "Gender", ["Male"])
xp.temporal.time_since(event=("Rx", "Date"), reference=("Dx", "Date"), name="Days")
xp.dimensions.add_number_ranges_attribute("Patients", "Age", bin_boundaries=[0,18,65])
xp.models.build_predictive_model("Model1", xmodel_configuration_file_name="m.json")
xp.data.export_results(["q1"], "results.xlsx")
xp.explore.structure()
xp.config.set_max_threads(8)

XplainSession class

class xplain.unified_session.XplainSession(url=None, user=None, password=None, profile=None, _session=None)

Unified xplain session with namespaced API.

Single entry point for all xplain operations. Every method from both Xsession and XplainClient is accessible through one of 8 namespaces.

Namespaces:: query: Query execution, results, aggregation, navigation select: Selection/filtering, references, selection sets temporal: Relative time dimensions, sequences, longitudinal analysis dimensions: Dimension/attribute CRUD, 30+ calculated dimension types models: Predictive modeling, causal discovery data: Object management, files, import/export, sampling, user data explore: Object structure, hierarchy navigation config: Server settings, performance, diagnostics, batch execution

Examples

Create and query:

from xplain import XplainSession

xp = XplainSession.from_profile("mimic")
xp.startup("Mimic")
df = xp.query.attribute("Patients", "Gender", "Gender")

Selections:

xp.select.values("Patients", "Gender", ["Male"])
xp.select.clear_all()

Temporal analysis:

xp.temporal.time_since(
    event=("Prescriptions", "Date"),
    reference=("Admissions", "AdmitTime"),
    name="DaysSinceAdmit",
    since="first", unit="DAY",
)

Auto-delegated methods (no wrapper needed):

xp.dimensions.add_ratio_dimension(...)
xp.models.build_predictive_model(...)
xp.data.load_object(file={...})
xp.config.set_max_threads(4)

__init__(url=None, user=None, password=None, profile=None, _session=None)

Create a unified xplain session.

Parameters

url – Server URL (e.g., “http://localhost:8080”)
user – Username
password – Password
profile – Profile name from ~/.xplainpyrc
_session – Pre-created Xsession (internal use)

classmethod from_profile(profile, **kwargs)

Create session from a named profile in ~/.xplainpyrc.

Parameters

profile – Profile name
**kwargs – Additional Xsession parameters

Returns

XplainSession instance

classmethod from_session_id(url, session_id)

Attach to an existing server session.

Parameters

url – Server URL
session_id – Existing HTTP session ID

Returns

XplainSession instance

startup(model)

Load xplain session by given startup configuration file name without file extension

Parameters: startup_file (string) – the file name of startup configuration,

terminate(): End the session and release server resources.

property session_id: Get the current session ID.

save_analysis(file=None, **kwargs)

Save current analysis state.

Parameters

file – File specification dict
**kwargs – Additional save parameters (drop_results, etc.)

load_analysis(file)

Load a saved analysis.

Parameters: file – File specification dict

resume_analysis(**kwargs)

Resume a previously saved analysis.

Parameters: **kwargs – Resume parameters (session, file, retain, etc.)

get_analysis(**kwargs)

Get analysis as a serializable dict.

Parameters: **kwargs – Options (get_as_script, drop_results, etc.)

structure()

Get the full object structure of the current session.

Returns: Nested object/dimension/attribute structure
Return type: dict

get_session_state(): Get the current session state dict.

add_quantile_based_attributes(object_name=None, dimension=None, quantiles=None, quantiles_attribute_name=None, ranges_attribute_name=None, use_names_as_postfix=False, selections=None, sample_size=None, script_file=None, script_file_ownership='PUBLIC'): Generate quantile-based attributes for FLOAT/DOUBLE dimensions.

build_formula(response, predictors): Dynamically build an R-style formula for Patsy.

build_predictive_model(model_name, xmodel_configuration_file_name, target_event_object): build predictive model [BETA!!].

build_tree_data(json_object): Convert complex JSON structure into a format suitable for D3.js tree visualization.

collapsible_tree(): Generate and visualize a collapsible tree using hierarchical data.

convert_to_dataframe(data): Convert query result JSON to pandas DataFrame format.

count_attribute(attribute_name, object_name=None, dimension_name=None, request_name=None, data_frame=True): Convenient method to count an attribute. Automatically resolves object and dimension.

create_contingency_table(df, var1, var2): Create a contingency table (frequency table) for two variables.

download_result(filename, save_as): download a file from result directory of server and save it to.

download_selections(objects, selection_set=None): returns the selection as json for given objects and selection set.

execute_query(query, data_frame=True): Execute an analytical query and return results.

gen_xtable(data, xtable_config, file_name): gen_xtable.

get(params=None): Send a GET request to the /xplainsession endpoint.

get_attribute_info(object_name, dimension_name, attribute_name): find and retrieves the details of an attribute.

get_current_xplain_session(): Get the current xplain session instance.

get_dimension_info(object_name, dimension_name): find and retrieves the details of a dimension.

get_full_object_structure(): Returns a flat list of all objects with their parent, dimensions, and attributes.

get_importer(): Get the importer instance for managing database connections and imports.

get_independent_variables_of_model(model_name): get the list of independent variables of given predictive model.

get_instance_as_dataframe(elements): get a pandas dataframe representation of the xplain artifacts.

get_model_names(): list all loaded predictive models.

get_object_info(object_name, root=None): find and display the details of a xobject in json.

get_open_sequences(sequence_name): Retrieves details of open sequences by name.

get_queries(): get the list of the existing query ids.

get_result(query_name, data_frame=True): get the result of the query.

get_root_object(): [Beta] Retrieve the root object.

get_selections(): display all global selections in the current xplain session.

get_sequence_transition_matrix(sequence_name): Retrieves the transition matrix for the specified sequence.

get_session(): get_session.

get_session_id(): Get the current Xplain session identifier.

get_state_hierarchy(object_name, dimension_name, attribute_name, state=None, levels=None, request_name=None): Retrieve the hierarchical structure of states for a given attribute.

get_tree_details(object_name=None, dimension_name=None, attribute_name=None): get the metadata details of certain xplain object, dimension or.

get_variable_details(model_name, data_frame=True): Retrieve the details of the independent variables for a predictive model.

get_variable_list(model_name): get the list of independent variables of given predictive model.

get_xobject(object_name): [Beta] Retrieve the object with the given name.

http_get(entrypoint, params=None): Performs an HTTP GET request to the specified endpoint.

http_post(entrypoint, payload_json=None, data=None, files=None, params=None): Performs an HTTP POST request to the specified endpoint.

list_analyses(): List available xanalysis configurations.

list_existing_analyses(): List available xanalysis configurations.

list_files(ownership, file_type, file_extension=None): Lists files with the specified ownership and type.

load_from_session_id(session_id): load xplain session by given exisiting session id.

load_result_file_as_df(filename): Load a file from the session as a pandas DataFrame.

open_attribute(object_name, dimension_name, attribute_name, request_name=None, data_frame=True): Open an attribute and get counts grouped by its values.

open_query(query, data_frame=True): perform the query and keep it open, the result of this query will be.

open_sequence(target_object, base_object, ranks, reverse, names, name_postfixes, dimensions_2_replicate, sort_dimension, zero_point_dimension, selections, selection_set_definition_rank, floating_semantics, attribute_2_copy, sequence_name, rank_dimension_name, rank_zero_is_first_instance_equal_or_greater_zero_point, transition_attribute, transition_level, open_marginal_queries, open_transition_queries, selection_set): open_sequence.

perform(payload): Send POST request against entry point /xplainsession with payload as.

post(payload): Send POST request against entry point /xplainsession with payload as.

post_and_broadcast(payload): Send a POST request and notify the backend of session updates.

post_file_download(file_name, file_type, ownership='PUBLIC', team=None, user=None, delete_after_download=True): Triggers the flat table download functionality in XOE.

print_error(): Print the last error message.

print_last_stack_trace(): Print the stack trace of the last error.

query_builder(name=None): Start building a query using the fluent QueryBuilder API.

read_file(ownership, file_type, file_path): Reads the specified file.

refresh(): synchronize the session content with the backend.

run(method): perform xplain web api method and broadcast the change to other.

run_py(file_name, options, ownership): Executes a Python script file on the server.

run_statsmodels(df, formula, model_type='logit'): Fit a statistical model to the provided dataframe using the specified formula and model type.

set_default_broadcast(broadcast): set default broadcast behaviour so that other xplain client sharing.

show_tree(): show object tree.

show_tree_details(): Display the details of the object tree.

startup_from_xview_config(xview_config): load xplain session by given view configuration json.

store_xsession(response_json): Store session details from the response.

upload_data(file_name): upload the file from current local directory to data directory on.

upload_xmodel(model_or_path, filename=None, ownership='PUBLIC'): Upload an .xmodel configuration file to the server’s public model store.

validate_db(db_connection_config): Validates a database connection configuration.

xp.query — Query Execution

Execute requests (queries), manage aggregations and group-bys, retrieve results, and navigate query trees.

df = xp.query.attribute("Patients", "Gender", "Gender")
xp.query.open(request={"requestId": "q1", "groupBys": [...], "aggregations": [...]})
df = xp.query.result("q1")
xp.query.delete_all()

class xplain.unified_session.query(unified_session)

Query execution, results, aggregation, and navigation.

Convenience methods:: attribute, execute, open, result, delete, delete_all, list
Auto-delegated client methods:: create_request, compute_request, compute_all_open_requests, delete_all_open_requests, pause_request, unpause_request, execute_and_export_request, add_aggregation, modify_aggregation, remove_aggregation, add_group_by, remove_group_by, omit_null_value_results, open_attribute, expand, collapse, expand_to_level
Auto-delegated session methods:: execute_query, count_attribute, convert_to_dataframe, get_instance_as_dataframe

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

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

attribute(object_name, dimension_name, attribute_name, request_name=None, data_frame=True)

Open an attribute query with COUNT aggregation.

Parameters

object_name – Object containing the attribute
dimension_name – Dimension containing the attribute
attribute_name – Attribute to query
request_name – Optional request name (defaults to attribute_name)
data_frame – Return as DataFrame (default True)

Returns

DataFrame or dict with query results

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

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

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

convert_to_dataframe(data): Convert query result JSON to pandas DataFrame format.

count_attribute(attribute_name, object_name=None, dimension_name=None, request_name=None, data_frame=True): Convenient method to count an attribute. Automatically resolves object and dimension.

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

delete(request_name): Delete a query request.

delete_all(): Delete all query requests.

delete_all_open_requests()

Delete all open (dynamic) requests

Delete all requests that were opened with openRequest/openQuery. Static requests created via executeRequest are not affected.

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

delete_all_requests()

Delete all requests from the session

Remove all requests (both static and open/dynamic) from the current session. After this call, no requests or results will be present in the session.

xp.select — Selections

Filter data by selecting values, ranges, or entity sets. Supports undo/redo, multiple selection sets, and import/export.

xp.select.values("Patients", "Gender", ["Male"])
xp.select.range("Patients", "Age", from_=18, to=65)
xp.select.undo()
xp.select.clear_all()

class xplain.unified_session.select(unified_session)

Selection operations for filtering data.

Convenience methods:: values, raw, range, clear, clear_all, get, undo, redo, set_reference, remove_reference
Auto-delegated client methods:: select, multiselect, select_between, select_entities, select_entities_in_field, clear_selections, clear_all_selections, clear_all_selection_sets, put_selection, add_selection_set, remove_selection_set, set_selection_set_for_query, go_back_in_selections, go_forward_in_selections, import_selections, export_selections, get_selections, get_selected_leafs, set_propagate_selections_upward, set_global_selections_as_reference, build_attribute_from_selection
Auto-delegated session methods:: download_selections

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

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

clear(object=None, dimension=None, attribute=None, selection_set=None): Clear selections for specific attributes.

clear_all(selection_set=None): Clear all selections.

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

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

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

download_selections(objects, selection_set=None): returns the selection as json for given objects and selection set.

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

get(objects=None, selection_set='globalSelections'): Get current selections.

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

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

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

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

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

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

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

range(object, dimension, attribute=None, from_=None, to=None)

Select a range of values.

Parameters

object – Object name
dimension – Dimension name
attribute – Attribute name (defaults to dimension)
from – Lower bound
to – Upper bound

raw(selection=None, selections=None, selection_set=None)

Apply a raw selection dict (pass-through to client.select).

Parameters

selection – Single selection dict
selections – List of selection dicts
selection_set – Selection set name

Returns

Session state after selection

Return type

dict

redo(steps=1): Redo selection steps.

remove_reference(reference_name): Remove a named reference.

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

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

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

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

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

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

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

set_reference(reference_name, reference_selections=None)

Set selections as a named reference for comparison.

Parameters

reference_name – Name for the reference
reference_selections – Explicit selections (default: use current global)

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

undo(steps=1): Undo selection steps.

values(object, dimension, values, attribute=None, selection_set=None)

Select specific values in a dimension.

Builds the selection dict automatically from simple arguments.

Parameters

object – Object name (e.g., “Patients”)
dimension – Dimension name (e.g., “Gender”)
values – List of values to select (e.g., [“Male”, “Female”])
attribute – Attribute name (defaults to dimension name)
selection_set – Selection set name (default: globalSelections)

Returns

Session state after selection

Return type

dict

xp.temporal — Temporal & Longitudinal Analysis

Create relative time dimensions, event sequences, and run longitudinal analyses.

xp.temporal.time_since(
    event=("Rx", "Date"), reference=("Dx", "Date"),
    name="Days since Dx", since="first", unit="DAY"
)
xp.temporal.sequence(base_object="Patient", sort_by=(...), replicate=[...], ranks=[1, 2, 3])
xp.temporal.add_relative_dimensions(time_dimensions=[...], reference={...})

class xplain.unified_session.temporal(unified_session)

Temporal and longitudinal analysis.

Convenience methods:: time_since, sequence, add_relative_dimensions, open_sequence, delete_sequence, remove_relative_dimensions
Auto-delegated client methods:: add_relative_time_dimensions, build_sorted_sequence, open_sequence_queries, clear_selections_for_sequence, delete_sequence_queries, run_longitudinal_analysis, run_mix_market_analysis
Auto-delegated session methods:: get_open_sequences, get_sequence_transition_matrix

add_relative_dimensions(time_dimensions, reference, time_type=None, unit=None, names=None, base_object=None, **kwargs)

Add relative time dimensions (advanced).

Lower-level method for full control. For common cases, prefer time_since().

Parameters

time_dimensions – List of time dimension paths
reference – Reference time dimension path
time_type – “TO_FIRST”, “TO_LAST”, “TO_NEAREST”, “TO_NEXT”, “TO_PREVIOUS”
unit – “DAY”, “MONTH”, “YEAR”, etc.
names – Names for the new dimensions
base_object – Base object
**kwargs – Additional parameters

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

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

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

delete_sequence(sequence_name): Delete a sequence.

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

get_open_sequences(sequence_name): Retrieves details of open sequences by name.

get_sequence_transition_matrix(sequence_name): Retrieves the transition matrix for the specified sequence.

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

open_sequence(sequence_names, **kwargs): Open sequence queries for analysis.

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

remove_relative_dimensions(names, base_object=None): Remove relative time dimensions.

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

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

sequence(base_object, sort_by, replicate, ranks, names=None, target_object=None, **kwargs)

Build a sorted sequence (rank events by time).

Parameters

base_object – Base object for sequencing
sort_by – Dimension to sort by (tuple, dict, or string)
replicate – Dimensions to replicate (list of tuple/dict/string)
ranks – List of rank numbers (e.g., [1, 2, 3])
names – Names for ranked dimensions (list of lists)
target_object – Target object (defaults to base_object)
**kwargs – Additional parameters (reverse, zero_point_dimension, etc.)

time_since(event, reference, name, since='first', unit='DAY', base_object=None, **kwargs)

Calculate time of events relative to a reference event.

Parameters

event – Event dimension (tuple, dict, or “Object.Dimension” string)
reference – Reference dimension (tuple, dict, or string)
name – Name for the new time dimension
since – Reference type - “first”, “last”, “nearest”, “next”, “previous”
unit – Time unit - “DAY”, “HOUR”, “MONTH”, “YEAR”, etc.
base_object – Base object for the relative time axis
**kwargs – Additional parameters (calendar_based, reference_filter, etc.)

xp.dimensions — Dimensions & Attributes

Create, modify, and remove dimensions and attributes. Includes 30+ computed dimension types (boolean logic, date/time elements, aggregation, factor, ratio, binning, and more).

xp.dimensions.remove("Patients", "TempDim")
xp.dimensions.add_boolean_logic_dimension(
    object="Patients", dimension1="HasDiagnosis", dimension2="HasRx", type="AND"
)
xp.dimensions.add_number_ranges_attribute(
    object="Patients", dimension="Age",
    bin_boundaries=[0, 18, 40, 65, 120]
)

class xplain.unified_session.dimensions(unified_session)

Dimension and attribute management.

Convenience methods:: remove, remove_if_exists, rename, replicate, add_attribute, remove_attribute
Auto-delegated client methods (30+ dimension types):: remove_dimension, remove_dimension_if_exists, rename_dimension, replicate_dimension, add_number_ranges_attribute, add_point_in_time_attribute, add_elapsed_time_attribute, add_time_duration_attribute, remove_attribute_if_exists, reorganize_attribute, remove_attributes_with_tag, add_tag, remove_tag, add_all_tags, add_boolean_logic_dimension, add_date_time_element_dimension, add_day_of_week_dimension, add_hour_of_day_dimension, add_shift_number_dimension, add_time_in_shift_dimension, add_ratio_dimension, add_linear_sum_dimension, add_min_number_dimension, add_max_number_dimension, add_product_dimension, add_quotient_dimension, add_time_difference_dimension, add_threshold_dimension, add_interval_flag_dimension, add_flag_extraction_dimension, add_sample_dimension, add_numeric_dimensions, add_normalized_response_dimension, add_constant_categorial_dimension, add_aggregation_dimension, add_disaggregation_dimension, add_conditional_factor_dimension
Auto-delegated session methods:: add_quantile_based_attributes

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

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

add_attribute(object, dimension=None, attribute=None, **kwargs): Add an attribute to a dimension.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

add_quantile_based_attributes(object_name=None, dimension=None, quantiles=None, quantiles_attribute_name=None, ranges_attribute_name=None, use_names_as_postfix=False, selections=None, sample_size=None, script_file=None, script_file_ownership='PUBLIC'): Generate quantile-based attributes for FLOAT/DOUBLE dimensions.

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

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

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

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

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

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

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

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

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

remove(object, dimension): Remove a dimension.

remove_attribute(object, dimension, attribute): Remove an attribute.

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

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

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

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

remove_if_exists(object, dimension): Remove a dimension if it exists (no error if missing).

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

rename(dimension, new_name)

Rename a dimension.

Parameters

dimension – Dimension path dict ({“object”: …, “dimension”: …})
new_name – New dimension name

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

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

replicate(dimension, to_object, name=None): Replicate a dimension to another object.

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

xp.models — Predictive Models & Causal Discovery

Build, evaluate, and manage predictive models and causal graphs.

xp.models.build_predictive_model(
    model_name="ReadmissionModel",
    xmodel_configuration_file_name="config/model.json"
)
xp.models.evaluate_model("ReadmissionModel")
xp.models.estimate_causal_graph("ReadmissionModel")

class xplain.unified_session.models(unified_session)

Predictive modeling and causal discovery.

Auto-delegated client methods:: build_predictive_model, propose_model_configuration, set_model_configuration, save_model_configuration, get_model_configuration, evaluate_model, delete_model, refit_model, clone_model, open_model, close_model, import_model, export_model, select_factor, clear_factor_selection, estimate_causal_graph, reject_factors, reject_factors_recursively, find_related_factors, search_for_new_factors, run_discovery_bot, set_causal_relation, add_variable, evaluate_all_alternatives
Auto-delegated session methods:: get_model_names, get_variable_list, get_independent_variables_of_model, get_variable_details

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

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

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

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

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

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

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

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

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

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

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

get_independent_variables_of_model(model_name): get the list of independent variables of given predictive model.

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

get_model_names(): list all loaded predictive models.

get_variable_details(model_name, data_frame=True): Retrieve the details of the independent variables for a predictive model.

get_variable_list(model_name): get the list of independent variables of given predictive model.

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

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

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

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

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

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

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

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

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

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

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

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

xp.data — Data Management & Export

Load and remove objects, upload/download files, export results, manage user data, and control sampling.

xp.data.load_object(file={"fileType": "XTABLE", "ownership": "PUBLIC",
                           "filePath": ["Patient.xtable"]})
xp.data.export_results(request_names=["q1"], result_xls="output.xlsx")
xp.data.upload("local_file.csv")

class xplain.unified_session.data(unified_session)

Data management: objects, files, import/export, sampling, user data.

Convenience methods:: upload, download
Auto-delegated client methods:: load_object, add_object, swap_data, remove_object, remove_object_if_exists, export_results, run_export_requests, save_as_csv, export_feature_table, save_selected_instances, save_selected_root_object_keys, copy_table, start_sampling, stop_sampling, put_user_data, store_user_data, set_user_data, clear_user_data, set_definition, get_definition
Auto-delegated session methods:: upload_data, upload_xmodel, download_result, post_file_download, load_result_file_as_df, list_files, read_file, gen_xtable, validate_db, list_analyses, list_existing_analyses

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

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

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

download(filename, save_as)

Download a result file from the server.

Parameters

filename – Server-side file name
save_as – Local file path to save to

download_result(filename, save_as): download a file from result directory of server and save it to.

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

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

gen_xtable(data, xtable_config, file_name): gen_xtable.

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

list_analyses(): List available xanalysis configurations.

list_existing_analyses(): List available xanalysis configurations.

list_files(ownership, file_type, file_extension=None): Lists files with the specified ownership and type.

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

load_result_file_as_df(filename): Load a file from the session as a pandas DataFrame.

post_file_download(file_name, file_type, ownership='PUBLIC', team=None, user=None, delete_after_download=True): Triggers the flat table download functionality in XOE.

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

read_file(ownership, file_type, file_path): Reads the specified file.

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

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

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

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

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

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

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

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

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

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

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

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

upload(file_name)

Upload a data file to the server.

Parameters: file_name – Path to the file to upload
Returns: Upload result
Return type: dict

upload_data(file_name): upload the file from current local directory to data directory on.

upload_xmodel(model_or_path, filename=None, ownership='PUBLIC'): Upload an .xmodel configuration file to the server’s public model store.

validate_db(db_connection_config): Validates a database connection configuration.

xp.explore — Object Structure Exploration

Browse the object/dimension/attribute hierarchy, inspect state trees, and navigate dimension structures.

struct = xp.explore.structure()
children = xp.explore.get_children(object="Patients", dimension="Gender",
                                    attribute="Gender", state="All")
tree = xp.explore.get_state_hierarchy(object="Patients", dimension="Age",
                                       attribute="Age")

class xplain.unified_session.explore(unified_session)

Object structure exploration and hierarchy navigation.

Convenience methods:: structure
Auto-delegated client methods:: get_children, get_state_hierarchy, get_states_list_for_level, get_path_for_states, get_tree_containing_string
Auto-delegated session methods:: get_full_object_structure, get_object_info, get_dimension_info, get_attribute_info, get_tree_details, get_root_object, get_xobject, show_tree, show_tree_details, build_tree_data, collapsible_tree

build_tree_data(json_object): Convert complex JSON structure into a format suitable for D3.js tree visualization.

collapsible_tree(): Generate and visualize a collapsible tree using hierarchical data.

get_attribute_info(object_name, dimension_name, attribute_name): find and retrieves the details of an attribute.

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

get_dimension_info(object_name, dimension_name): find and retrieves the details of a dimension.

get_full_object_structure(): Returns a flat list of all objects with their parent, dimensions, and attributes.

get_object_info(object_name, root=None): find and display the details of a xobject in json.

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

get_root_object(): [Beta] Retrieve the root object.

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

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

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

get_tree_details(object_name=None, dimension_name=None, attribute_name=None): get the metadata details of certain xplain object, dimension or.

get_xobject(object_name): [Beta] Retrieve the object with the given name.

show_tree(): show object tree.

show_tree_details(): Display the details of the object tree.

structure()

Get the full object structure of the current session.

Returns: Nested object/dimension/attribute structure
Return type: dict

xp.config — Server Configuration & Diagnostics

Tune server performance (threads, caching, memory), run diagnostics, monitor task progress, and execute batch scripts.

xp.config.set_max_threads(8)
xp.config.enable_caching()
xp.config.gc()
xp.config.get_progress()
xp.config.execute_batch(file={"filePath": ["script.json"]})

class xplain.unified_session.config(unified_session)

Server configuration, performance tuning, diagnostics, and task management.

Auto-delegated client methods:: enable_caching, disable_caching, get_caching_enabled, set_enable_hot_swap, cache_aggregation_dimensions, drop_aggregation_dimension_caches, set_max_threads, set_tasks_per_thread, set_max_threads_for_session, set_max_one_dim_group_by_size, set_max_nr_instances_for_ranking, set_memory_parameters, set_results_format, set_description, set_format, configure_garbage_collections, resource_usage, gc, validate_x_table, evaluate_performance, output_x_table_statistics, get_recent_execution_statistics, run_x_object_diagnostics, kill_tasks, get_progress, get_messages, terminate_computation, execute_batch, execute_script, start_call_logging, stop_call_logging, save_call_log
Auto-delegated session methods:: set_default_broadcast, print_error, print_last_stack_trace, refresh

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

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

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

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

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

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

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”: { … }

}

]

}