xplain.Xsession

class xplain.Xsession(url='http://localhost:8080', user='user', password='xplainData', httpsession=None, jwt_dispatch_url=None, jwt_cookie_name=None, jwt_token=None)

Bases: object

build_predictive_model(model_name, model_config, model_object_name, significance, target_event_object_name, target_selection_object_name, target_selection_dimension_name, target_selection_attribute, output_prefix='')

build predictive model [BETA!!]

Parameters

  • model_name (string) – model name

  • xmodel_config (string) – xmodel configuration file

  • model_object_name (string) – model object name

  • significance (float) – significance 0.0 - 1.0

  • target_event_object_name (string) – target even object name

  • target_selection_object_name (string) – target selection object name

  • target_selection_dimension_name (string) – target selection dimension name

  • target_selection_attribute (string) – target selection attribute name

  • output_prefix – prefix of output csv files on file system,

default is empty :type output_prefix: string :return: results of predictive model as dictionary of padas dataframes which includs independent varialbes, observations, learning log, predicted probabilities, ROC :rtype: dictionary

Example:
>>> xsession.build_predictive_model(model_name='Depression',
                    xmodel_config='DEPRESSION - demo.xmodel',
                    model_object_name='Person',
                    significance=0.9,
                    target_event_object_name='Diagnosen',
                    target_selection_object_name='Diagnosen',
                    target_selection_dimension_name='Type',
                    target_selection_attribute='Type')
build_tree_data(json_object)

Convert complex JSON structure into a format suitable for D3.js tree visualization. This recursively parses the JSON, building a nested dictionary format compatible with D3.js.

collapsible_tree(output_file='tree_visualization.html')
convert_to_dataframe(data)

Convert result JSON to DataFrame format.

Parameters

data – data in JSON format

Returns

data in pandas DataFrame format

download_result(filename, save_as)

download a file from result directory of server and save it to current local path

Parameters

  • file_name (string) – file name in result directory

  • save_as (string) – downloaded file save as local file

execute_query(query, data_frame=True)

execute the xplain request

Parameters

  • query (Query_config or json) – specification of the query

  • data_frame (boolean) – if True, the result will be returned as dataFrame

Returns

result of given query

Return type

JSON or DataFrame, depending on parameter dataFrame

Example:
>>> import xplain

>>> session = xplain.Xsession()
>>> session.startup('Patients')

>>> # option 1, query config object
>>>  query_config = xplain.Query_config()
>>>  query_config.add_aggregation(
                        object_name="Hospital Diagnose",
                        dimension_name="Diagnose", type="COUNT")
>>>  query_config.add_groupby(object_name="Hospital Diagnose",
                              dimension_name="Diagnose",
                              attribute_name="Type")
>>> query_config.add_selection(object_name="Hospital Diagnose",
                              dimension_name="Date_from",
                              attribute_name="Date_from",
                           selected_states=["2020-12"])
>>> session.execute_query(query_config)

>>> # option 2,  query in json
>>> query = {
        "aggregations" :[
            {
               "object": "AU-Diagnosen",
               "dimension": "Diagnose",
               "type": "SUM"
           }
        ],
        "groupBys":[{
           "attribute": {
               "object": "Hospital Diagnose",
               "dimension": "Diagnose",
               "attribute": "Type"
           }]
    }
}
>>> session.execute_query(query)
gen_xtable(data, xtable_config, file_name)

Generates an XTable with the given data and configuration.

Parameters

  • data – Data for the XTable.

  • xtable_config – Configuration for the XTable.

  • file_name – Name of the output file.

get(params=None)

Send a GET request to the /xplainsession endpoint.

Parameters

params – Optional URL parameters.

Returns

API response.

get_attribute_info(object_name, dimension_name, attribute_name)

find and retrieves the details of an attribute

Parameters

  • object_name – the name of xobject

  • dimension_name – the name of dimension

  • attribute_name – the name of attribute

Returns

details of this attribute in json format

get_dimension_info(object_name, dimension_name)

find and retrieves the details of a dimension

Parameters

  • object_name – the name of the xobject

  • dimension_name – the name of dimension

Returns

details of this dimension in json format

get_instance_as_dataframe(elements)

get a pandas dataframe representation of the xplain artifacts references by elements, equivalent to the standard csv download functionality in XOE

Parameters

elements – array of x-element paths, each one referring a

Xplain artifact, an object, a dimension or an attribute :type elements: list :return: Dataframe representation of requested instance :rtype: pd.Dataframe

Example:
elements: [

{“object”: “Person”}, {“object”: “Diagnosis”, “dimension”: “Physician”}, {“object”: “Prescription”, “dimension”: “Rx Code”, “attribute”: “ATC Hierarchy”}, {“object”: “Prescription”, “dimension”: “Rx Code”, “attribute”: “Substance”}

],

get_model_names()

list all loaded predictive models

Returns

list of model names

Return type

array of string

get_object_info(object_name, root=None)

find and display the details of a xobject in json

Parameters

  • object_name –

  • root – the object name from where the search starts. if none

root is provided, the root node of the entire object tree :return: details of the 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

Returns

list of query ids

Return type

array of string

get_result(query_name, data_frame=True)

get the result of the query :param query_name: the name /id of the query :type query_name: string :return: Dataframe result of the query :rtype: pd.Dataframe or json

get_root_object()

[Beta] retrieve the root object

Returns

the root object

Return type

XObject

get_selections()

display all global selections in the current xplain session

Returns

selections as json

Return type

list of json

get_sequence_transition_matrix(sequence_name)

Retrieves the transition matrix for the specified sequence.

Parameters

sequence_name – Name of the sequence.

Returns

Transition matrix as a dictionary with labels, sources, targets, and values.

get_session()
get_session_id()

get the current xplain session id

Returns

session id

Return type

string

get_tree_details(object_name=None, dimension_name=None, attribute_name=None)

get the metadata details of certain xplain object, dimension or attribute as json

Parameters

object_name – the name of object optional , if empty, show the

whole object tree from root, if only objectName is specified, this funtion will return the metadata of

this object

Parameters

dimension_name – the name of dimension, optional,

it object_name and dimension_name are specified, it will return the dimesion metadata :type dimension_name: string, optional :param attribute_name: the name of attribute, optional, it object_name, dimension_name and attribute_name is specified, it will return the attribute metadata :type attribute_name: string, optional :return: object tree details :rtype: json

get_variable_details(model_name, data_frame=True)

get the predictive model independent variables details

Parameters

  • model_name (string) – the name of predictive model

  • data_frame (boolean) – if result shall be returned as pandas

Returns

the model result

Return type

data frame or json

get_variable_list(model_name)

get the list of independent variables of given predictive model

Parameters

model_name (string) – name of predictive model

Returns

list of independent variables

Return type

array of string

get_xobject(object_name)

[Beta] retrieve the object with given name

Returns

the object with given name

Return type

XObject

http_get(entrypoint, params=None)

Performs an HTTP GET request to the specified endpoint.

Parameters

  • entrypoint – API endpoint relative to the base URL.

  • params – Query parameters for the GET request.

Returns

Parsed JSON response or raw content.

Raises

RuntimeError – If the GET request fails.

http_post(entrypoint, payload_json=None)

Performs an HTTP POST request to the specified endpoint.

Parameters

  • entrypoint – API endpoint relative to the base URL.

  • payload_json – Dictionary payload for the POST request.

Returns

Parsed JSON response or raw content.

Raises

RuntimeError – If the POST request fails.

list_files(ownership, file_type, file_extension=None)

Lists files with the specified ownership and type.

Parameters

  • ownership – Ownership type.

  • file_type – File type.

  • file_extension – Optional file extension.

Returns

List of files or raises exception on failure.

load_file_as_df(filename)

Load a file from the session as a pandas DataFrame.

Parameters

filename – Name of the file to load.

Returns

DataFrame containing file content.

load_from_session_id(session_id)

load xplain session by given exisiting session id

Parameters

session_id (string) – the 32 digit xplain session id

open_attribute(object_name, dimension_name, attribute_name, request_name=None, data_frame=True)

convinient method to open an attribute

Parameters

  • object_name (string) – name of object

  • dimension_name (string) – name of dimension

  • attribute_name (string) – name of attribute

  • request_name (string) – id or name of request

  • data_frame (boolean) – if result shall be returned as pandas

Returns

attribute groupped by on first level and aggregated by count.

Return type

attribute: data frame or json

Example:
>>> session = xplain.Xsession(url="myhost:8080", user="myUser",
password="myPwd")
>>> session.startup("mystartup")
>>> session.open_attribute("Patient", "Age", "Agegroup")
open_query(query, data_frame=True)

perform the query and keep it open, the result of this query will be impacted by further modification of current session, like selection changes

Parameters

  • query – either xplain.Query instance or JSON

  • data_frame – if True, the result will be returned as

dataFrame :return: result of given query :rtype: JSON or DataFrame, depending on parameter dataFrame

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)
perform(payload)

Send POST request against entry point /xplainsession with payload as json

Parameters

method_call (json) – content of xplain web api

Returns

request response

Return type

json

Example
>>> session.perform({"method": "deleteRequest",
                      "requestName":"abcd"})
post(payload)

Send POST request against entry point /xplainsession with payload as json

Parameters

payload – xplain web api in json

Returns

request response as JSON

post_and_broadcast(payload)

Send a POST request and notify the backend of session updates.

Parameters

payload – JSON payload for the API request.

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.

Parameters

  • file_name – Name of the file to be downloaded.

  • file_type – Type of the file.

  • ownership – Ownership type, defaults to “PUBLIC”.

  • team – Team identifier, optional.

  • user – User identifier, optional.

  • delete_after_download – Whether to delete the file after download, defaults to True.

Returns

HTTP response object or raises exception on failure.

print_error()

Print the last error message.

print_last_stack_trace()

Print the stack trace of the last error.

read_file(ownership, file_type, file_path)

Reads the specified file.

Parameters

  • ownership – Ownership type.

  • file_type – File type.

  • file_path – Path of the file.

Returns

File content or raises exception on failure.

refresh()

synchronize the session content with the backend

resume_analysis(file_name)

resume the stored session

Parameters

file_name (string) – name of stored session file

Returns

False (fail) or True (success)

Return type

Boolean

run(method)

perform xplain web api method and broadcast the change to other client sharing with same session id

Parameters

method (json) – xplain web api method in json format

run_py(file_name, options, ownership)

Executes a Python script file on the server.

Parameters

  • file_name – Name of the Python file.

  • options – Execution options.

  • ownership – File ownership type.

Returns

Parsed JSON result or raw content.

Raises

RuntimeError – If the request fails.

set_default_broadcast(broadcast)

set default broadcast behaviour so that other xplain client sharing the same xplain session could get informed about the update of current xplain session.

Parameters

broadcast – after successful session update via python call,

if a default refresh signal should be broadcasted to all xplain clients those are sharing the same xplain session, in order to force them to perform the refresh to get the most current session. :type broadcast: boolean

show_tree()

show object tree

Returns

render the object hierarchy as a tree

Return type

string

Raises

  • RuntimeError – if the session is not properly initialized.

  • Exception – if an unexpected error occurs.

show_tree_details()

Display the details of the object tree.

startup(startup_file)

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

Parameters

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

store_xsession(response_json)

Store session details from the response.

Parameters

response_json – Response parsed as JSON.

terminate()

terminate the xplain session

upload_data(file_name)

upload the file from current local directory to data directory on server :param file_name: file :type file_name: string

validate_db(db_connection_config)

Validates a database connection configuration.

Parameters

db_connection_config – Dictionary containing DB connection settings.

Raises

RuntimeError – If validation fails or an error occurs.