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

class for managing xplain session and calling Xplain Web API. Each Xsession instance could manage an individual xplain session.

Example:

>>> from xplain import Xsession
>>> s1 = Xsession(url="myhost:8080", user="me",
password="secret1")
>>> s2 = XplainSession(url="my_other_host:8080", user="me",
password="secret2")
>>> s1.terminate()
>>> s2.terminate()

build_predictive_model(model_name, xmodel_config, model_object_name, significance, target_event_object_name, target_selection_object_name, target_selection_dimension_name, target_selection_attribute, output_prefix=None)

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')

download_result(file_name, save_as)

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

param file_name

file name in result directory

Parameters: 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, config, file_name)

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)

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)

get_open_sequences(sequence_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)

get_session_id()

get the current xplain session id

Returns: session id
Return type: string

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)

http_post(entrypoint, payload)

list_files(ownership, file_type, file_extension=None)

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='', 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=None, base_object=None, ranks=None, reverse=False, names=None, name_postfixes=None, dimensions_2_replicate=None, sort_dimension=None, zero_point_dimension=None, selections=None, selection_set_definition_rank=None, floating_semantics=False, attribute_2_copy=None, sequence_name=None, rank_dimension_name=None, rank_zero_is_first_instance_equal_or_greater_zero_point=False, transition_attribute=None, transition_level=None, open_marginal_queries=False, open_transition_queries=True, selection_set=None)

perform(method_call)

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"})

print_error()

read_file(ownership, file_type, file_path)

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_call)

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='PUBLIC')

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 hierarchy as 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,

terminate(): terminate the xplain session

upload2data(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)