howso.client#

Submodules

typing

Classes

AbstractHowsoClient

The base definition of the Howso client interface.

Functions

`get_configuration_path`	Determine where the configuration is stored, if anywhere.
`get_howso_client`	Return the appropriate AbstractHowsoClient subclass based on config.
`HowsoClient`	Return the appropriate AbstractHowsoClient subclass based on config.
`HowsoPandasClient`	Return the appropriate AbstractHowsoClient subclass based on config.

The Python API for the Howso Client.

The Howso Python Client API has two major components,

client module:
A basic client that implements the Howso REST API.
scikit module:
Implements a scikit-learn Estimator which uses the Howso cloud service to make predictions off of fit data.

Additional submodules are included in the package but are for internal client/scikit operations and thus are omitted from the documentation.

Examples implementations are included in the howso/examples directory.

class howso.client.AbstractHowsoClient#

Bases: ABC

The base definition of the Howso client interface.

abstract acquire_trainee_resources(trainee_id, *, max_wait_time=None)#

Acquire resources for a Trainee in the Howso service.

Parameters:

trainee_id (str)
max_wait_time (int | float | None, default: None)

add_feature(trainee_id, feature, feature_value=None, *, condition=None, condition_session=None, feature_attributes=None, overwrite=False)#

Adds a feature to a trainee.

Updates the accumulated data mass for the model proportional to the number of cases modified.

Parameters:

trainee_id (str) – The ID of the Trainee add the feature to.
feature (str) – The name of the feature.
feature_attributes (Mapping | None, default: None) – The dict of feature specific attributes for this feature. If unspecified and conditions are not specified, will assume feature type as ‘continuous’.
feature_value (int | float | str | None, default: None) – The value to populate the feature with. By default, populates the new feature with None.
condition (Mapping | None, default: None) –
A condition map where feature values will only be added when certain criteria is met.

If None, the feature will be added to all cases in the model and feature metadata will be updated to include it. If specified as an empty dict, the feature will still be added to all cases in the model but the feature metadata will not be updated.
Note

The dictionary keys are the feature name and values are one of:
- None
- A value, must match exactly.
- An array of two numeric values, specifying an inclusive range. Only applicable to continuous and numeric ordinal features.
- An array of string values, must match any of these values exactly. Only applicable to nominal and string ordinal features.
Tip

For instance to add the feature_value only when the length and width features are equal to 10:
```
condition = {"length": 10, "width": 10}
```
condition_session (str | None, default: None) – If specified, ignores the condition and operates on cases for the specified session id.
overwrite (bool, default: False) – If True, the feature will be over-written if it exists.

analyze(trainee_id, context_features=None, action_features=None, *, analysis_sub_model_size=None, bypass_calculate_feature_residuals=None, bypass_calculate_feature_weights=None, bypass_hyperparameter_analysis=None, dt_values=None, inverse_residuals_as_weights=None, k_folds=None, k_values=None, num_analysis_samples=None, num_samples=None, p_values=None, targeted_model=None, use_case_weights=None, use_deviations=None, weight_feature=None, **kwargs)#

Analyzes a Trainee.

Parameters:

trainee_id (str) – The ID of the Trainee.
context_features (Collection[str] | None, default: None) – The context features to analyze for.
action_features (Collection[str] | None, default: None) – The action features to analyze for.
analysis_sub_model_size (int | None, default: None) – Number of samples to use for analysis. The rest will be randomly held-out and not included in calculations.
bypass_calculate_feature_residuals (bool | None, default: None) – When True, bypasses calculation of feature residuals.
bypass_calculate_feature_weights (bool | None, default: None) – When True, bypasses calculation of feature weights.
bypass_hyperparameter_analysis (bool | None, default: None) – When True, bypasses hyperparameter analysis.
dt_values (Collection[float] | None, default: None) – The dt value hyperparameters to analyze with.
inverse_residuals_as_weights (bool | None, default: None) – When True, will compute and use inverse of residuals as feature weights.
k_folds (int | None, default: None) – The number of cross validation folds to do.
k_values (Collection[int] | None, default: None) – The number of cross validation folds to do. A value of 1 does hold-one-out instead of k-fold.
num_analysis_samples (int | None, default: None) – If the dataset size to too large, analyze on (randomly sampled) subset of data. The num_analysis_samples specifies the number of observations to be considered for analysis.
num_samples (int | None, default: None) – The number of samples used in calculating feature residuals.
p_values (Collection[float] | None, default: None) – The p value hyperparameters to analyze with.
targeted_model (Literal['single_targeted', 'omni_targeted', 'targetless'] | None, default: None) –
Type of hyperparameter targeting. Valid options include:
- single_targeted: Analyze hyperparameters for the specified action_features.
- omni_targeted: Analyze hyperparameters for each context feature as an action feature, ignores action_features parameter.
- targetless: Analyze hyperparameters for all context features as possible action features, ignores action_features parameter.
use_case_weights (bool | None, default: None) – If set to True, will scale influence weights by each case’s weight_feature weight. If unspecified, case weights will be used if the Trainee has them.
use_deviations (bool | None, default: None) – When True, uses deviations for LK metric in queries.
weight_feature (str | None, default: None) – Name of feature whose values to use as case weights. When left unspecified uses the internally managed case weight.
kwargs – Additional experimental analyze parameters.

append_to_series_store(trainee_id, series, contexts, *, context_features=None)#

Append the specified contexts to a series store.

For use with train series.

Parameters:

trainee_id (str) – The ID of the Trainee to append to.
series (str) – The name of the series store to append to.
contexts (DataFrame | list[list[Any]]) – The list of list of context values to append to the series. When the value is a DataFrame, the value will be used to populate both context_values and context_features parameters of the Engine. When the value is a list, context_features must also be specified.
context_features (Collection[str] | None, default: None) – The feature names corresponding to context values. If contexts is a DataFrame, overrides what columns will be used in context_values supplied to the Engine.

auto_analyze(trainee_id)#

Auto-analyze the Trainee model.

Re-uses all parameters from the previous analyze or set_auto_analyze_params call. If analyze or set_auto_analyze_params has not been previously called, auto_analyze will default to a robust and versatile analysis.

Parameters:: trainee_id (str) – The ID of the Trainee to auto-analyze.

abstract begin_session(name='default', metadata=None)#

Begin a new session.

Parameters:

name (str | None, default: 'default')
metadata (Mapping | None, default: None)

Return type:

Session

clear_imputed_data(trainee_id, impute_session=None)#

Clears values that were imputed during a specified session.

Won’t clear values that were manually set by the user after the impute.

Parameters:

trainee_id (str) – The id of the trainee.
impute_session (str | Session | None, default: None) – Session or session identifier of the impute for which to clear the data. If none is provided, will clear all imputed.

abstract copy_trainee(trainee_id, new_trainee_name=None, *, library_type=None, resources=None)#

Copy a trainee in the Howso service.

Return type:: Trainee

abstract create_trainee(name=None, features=None, *, id=None, library_type=None, max_wait_time=None, metadata=None, overwrite_trainee=False, persistence='allow', project=None, resources=None)#

Create a Trainee in the Howso service.

Parameters:

name (str | None, default: None)
features (Mapping[str, Mapping] | None, default: None)
id (str | UUID | None, default: None)
library_type (Literal['st', 'mt'] | None, default: None)
max_wait_time (int | float | None, default: None)
metadata (MutableMapping[str, Any] | None, default: None)
overwrite_trainee (bool, default: False)
persistence (Literal['allow', 'always', 'never'], default: 'allow')
project (str | Project | None, default: None)
resources (Mapping[str, Any] | None, default: None)

Return type:

Trainee

delete_session(trainee_id, session)#

Delete a session from a Trainee.

Parameters:

trainee_id (str) – The ID of the Trainee to delete the session from.
session (str | Session) – The session or session identifier to delete.

abstract delete_trainee(trainee_id, *, file_path=None)#

Delete a Trainee from the Howso service.

Parameters:

trainee_id (str)
file_path (Path | str | None, default: None)

edit_cases(trainee_id, feature_values, *, case_indices=None, condition=None, condition_session=None, features=None, num_cases=None, precision=None)#

Edit feature values for the specified cases.

Updates the accumulated data mass for the model proportional to the number of cases and features modified.

Parameters:

trainee_id (str) – The ID of the Trainee to edit the cases of.
feature_values (Collection[Any] | DataFrame) – The feature values to edit the case(s) with. If specified as a list, the order corresponds with the order of the features parameter. If specified as a DataFrame, only the first row will be used.
case_indices (Sequence[tuple[str, int]] | None, default: None) – Sequence of tuples containing the session id and index, where index is the original 0-based index of the case as it was trained into the session. This explicitly specifies the cases to edit. When specified, condition and condition_session are ignored.
condition (Mapping | None, default: None) –
A condition map to select which cases to edit. Ignored when case_indices are specified.
Note

The dictionary keys are the feature name and values are one of:
- None
- A value, must match exactly.
- An array of two numeric values, specifying an inclusive range. Only applicable to continuous and numeric ordinal features.
- An array of string values, must match any of these values exactly. Only applicable to nominal and string ordinal features.
condition_session (str | None, default: None) – If specified, ignores the condition and operates on all cases for the specified session.
features (Collection[str] | None, default: None) – The names of the features to edit. Required when feature_values is not specified as a DataFrame.
num_cases (int | None, default: None) – The maximum amount of cases to edit. If not specified, the limit will be k cases if precision is “similar”, or no limit if precision is “exact”.
precision (Literal['exact', 'similar'] | None, default: None) – The precision to use when moving the cases, defaults to “exact”.

Returns:

The number of cases modified.

Return type:

int

evaluate(trainee_id, features_to_code_map, *, aggregation_code=None)#

Evaluate custom code on feature values of all cases in the trainee.

Parameters:

trainee_id (str) – The ID of the Trainee.
features_to_code_map (Mapping[str, str]) –
A dictionary with feature name keys and custom Amalgam code string values.

The custom code can use “#feature_name 0” to reference the value of that feature for each case.
aggregation_code (str | None, default: None) – A string of custom Amalgam code that can access the list of values derived form the custom code in features_to_code_map. The custom code can use “#feature_name 0” to reference the list of values derived from using the custom code in features_to_code_map.

Returns:

A dictionary with keys: ‘evaluated’ and ‘aggregated’

’evaluated’ is a dictionary with feature name keys and lists of values derived from the features_to_code_map custom code.

’aggregated’ is None if no aggregation_code is given, it otherwise holds the output of the custom ‘aggregation_code’

Return type:

Evaluation

abstract execute(trainee_id, label, payload, **kwargs)#

Execute a label in Howso engine.

Parameters:

trainee_id (str) – The identifier of the Trainee.
label (str) – The label to execute.
payload (Any) – The payload to send to label.

Returns:

The label’s response.

Return type:

Any

abstract execute_sized(trainee_id, label, payload, **kwargs)#

Execute a label in Howso engine and return the request and response sizes.

Parameters:

trainee_id (str) – The identifier of the Trainee.
label (str) – The label to execute.
payload (Any) – The payload to send to label.

Return type:

tuple[Any, int, int]

Returns:

Any – The label’s response.
int – The request payload size.
int – The response payload size.

get_auto_ablation_params(trainee_id)#

Get Trainee parameters for auto-ablation set by set_auto_ablation_params().

Parameters:: trainee_id (str) – The ID of the Trainee to get auto ablation parameters for.
Returns:: The auto-ablation parameters.
Return type:: dict[str, Any]

get_cases(trainee_id, session=None, case_indices=None, indicate_imputed=False, features=None, condition=None, num_cases=None, precision=None)#

Retrieve cases from a model given a Trainee id.

Parameters:

trainee_id (str) – The ID of the Trainee retrieve cases from.
session (str | None, default: None) –
The session ID to retrieve cases for, in their trained order.

Note

If a session is not provided, retrieves all feature values for cases for all (unordered) sessions in the order they were trained within each session.
case_indices (Sequence[tuple[str, int]] | None, default: None) – Sequence of tuples, of session id and index, where index is the original 0-based index of the case as it was trained into the session. If specified, returns only these cases and ignores the session parameter.
indicate_imputed (bool, default: False) – If set, an additional value will be appended to the cases indicating if the case was imputed.
features (Collection[str] | None, default: None) –
A list of feature names to return values for in leu of all default features.

Built-in features that are available for retrieval:

.session - The session id the case was trained under.

.session_training_index - 0-based original index of the case, ordered by training during the session; is never changed.
condition (Mapping | None, default: None) –
The condition map to select the cases to retrieve that meet all the provided conditions.
Note

The dictionary keys are the feature name and values are one of:
- None
- A value, must match exactly.
- An array of two numeric values, specifying an inclusive range. Only applicable to continuous and numeric ordinal features.
- An array of string values, must match any of these values exactly. Only applicable to nominal and string ordinal features.
Tip

Example 1 - Retrieve all values belonging to feature_name:
```
criteria = {"feature_name": None}
```
Example 2 - Retrieve cases that have the value 10:
```
criteria = {"feature_name": 10}
```
Example 3 - Retrieve cases that have a value in range [10, 20]:
```
criteria = {"feature_name": [10, 20]}
```
Example 4 - Retrieve cases that match one of [‘a’, ‘c’, ‘e’]:
```
condition = {"feature_name": ['a', 'c', 'e']}
```
Example 5 - Retrieve cases using session name and index:
```
criteria = {'.session':'your_session_name',
            '.session_training_index': 1}
```
num_cases (int | None, default: None) – The maximum amount of cases to retrieve. If not specified, the limit will be k cases if precision is “similar”, or no limit if precision is “exact”.
precision (Literal['exact', 'similar'] | None, default: None) – The precision to use when retrieving the cases via condition. Options are “exact” or “similar”. If not provided, “exact” will be used.

Returns:

A cases object containing the feature names and cases.

Return type:

Cases

get_distances(trainee_id, features=None, *, action_feature=None, case_indices=None, feature_values=None, use_case_weights=None, weight_feature=None)#

Compute distances matrix for specified cases.

Returns a dict with computed distances between all cases specified in case_indices or from all cases in local model as defined by feature_values. If neither case_indices nor feature_values is specified, returns computed distances for the entire dataset.

Parameters:

trainee_id (str) – The trainee ID.
features (Collection[str] | None, default: None) – List of feature names to use when computing distances. If unspecified uses all features.
action_feature (str | None, default: None) – The action feature. If specified, uses targeted hyperparameters used to predict this action_feature, otherwise uses targetless hyperparameters.
case_indices (Sequence[tuple[str, int]] | None, default: None) – A sequence of tuples, of session id and index, where index is the original 0-based index of the case as it was trained into the session. If specified, returns distances for all of these cases. Ignored if feature_values is provided. If neither feature_values nor case_indices is specified, uses full dataset.
feature_values (Collection[Any] | DataFrame | None, default: None) – If specified, returns distances of the local model relative to these values, ignores case_indices parameter. If provided a DataFrame, only the first row will be used.
use_case_weights (bool | None, default: None) – If set to True, will scale influence weights by each case’s weight_feature weight. If unspecified, case weights will be used if the Trainee has them.
weight_feature (str | None, default: None) – Name of feature whose values to use as case weights. When left unspecified uses the internally managed case weight.

Returns:

A dict containing a matrix of computed distances and the list of corresponding case indices in the following format:

{
    'case_indices': [ session-indices ],
    'distances': DataFrame[ distances ]
}

Return type:

Distances

get_extreme_cases(trainee_id, num, sort_feature, features=None)#

Gets the extreme cases of a Trainee for the given feature(s).

Parameters:

trainee_id (str) – The ID of the Trainee to retrieve extreme cases from.
num (int) – The number of cases to get.
sort_feature (str) – The feature name by which extreme cases are sorted by.
features (Collection[str] | None, default: None) – The feature names to use when getting extreme cases.

Returns:

A cases object containing the feature names and extreme cases.

Return type:

Cases

get_feature_attributes(trainee_id)#

Get stored feature attributes.

Parameters:: trainee_id (str) – The ID of the Trainee.
Returns:: A dictionary of feature name to dictionary of feature attributes.
Return type:: dict[str, dict]

get_feature_conviction(trainee_id, *, action_features=None, features=None, familiarity_conviction_addition=True, familiarity_conviction_removal=False, use_case_weights=None, weight_feature=None)#

Get familiarity conviction for features in the model.

Parameters:

trainee_id (str) – The id of the trainee.
features (Collection[str] | None, default: None) – A collection of feature names to calculate convictions. At least 2 features are required to get familiarity conviction. If not specified all features will be used.
action_features (Collection[str] | None, default: None) – A collection of feature names to be treated as action features during conviction calculation in order to determine the conviction of each feature against the set of action_features. If not specified, conviction is computed for each feature against the rest of the features as a whole.
familiarity_conviction_addition (bool, default: True) – Calculate and output familiarity conviction of adding the specified features in the output.
familiarity_conviction_removal (bool, default: False) – Calculate and output familiarity conviction of removing the specified features in the output.
weight_feature (str | None, default: None) – Name of feature whose values to use as case weights. When left unspecified uses the internally managed case weight.
use_case_weights (bool | None, default: None) – If set to True, will scale influence weights by each case’s weight_feature weight. If unspecified, case weights will be used if the Trainee has them.

Returns:

A dict with familiarity_conviction_addition or familiarity_conviction_removal

Return type:

dict

get_marginal_stats(trainee_id, *, condition=None, num_cases=None, precision=None, weight_feature=None)#

Get marginal stats for all features.

Parameters:

trainee_id (str) – The ID of the Trainee to retrieve marginal stats for.
condition (Mapping | None, default: None) –
A condition map to select which cases to compute marginal stats for.
Note

The dictionary keys are the feature name and values are one of:
- None
- A value, must match exactly.
- An array of two numeric values, specifying an inclusive range. Only applicable to continuous and numeric ordinal features.
- An array of string values, must match any of these values exactly. Only applicable to nominal and string ordinal features.
num_cases (int | None, default: None) – The maximum amount of cases to use to calculate marginal stats. If not specified, the limit will be k cases if precision is “similar”. Only used if condition is not None.
precision (Literal['exact', 'similar'] | None, default: None) – The precision to use when selecting cases with the condition. Options are ‘exact’ or ‘similar’. If not specified “exact” will be used. Only used if condition is not None.
weight_feature (str | None, default: None) – When specified, will attempt to return stats that were computed using this weight_feature.

Returns:

A map of feature names to map of stat type to stat values.

Return type:

dict[str, dict[str, float]]

get_num_training_cases(trainee_id)#

Return the number of trained cases in the Trainee.

Parameters:: trainee_id (str) – The Id of the Trainee to retrieve the number of training cases from.
Returns:: The number of cases in the model
Return type:: int

get_pairwise_distances(trainee_id, features=None, *, action_feature=None, from_case_indices=None, from_values=None, to_case_indices=None, to_values=None, use_case_weights=None, weight_feature=None)#

Compute pairwise distances between specified cases.

Returns a list of computed distances between each respective pair of cases specified in either from_values or from_case_indices to to_values or to_case_indices. If only one case is specified in any of the lists, all respective distances are computed to/from that one case.

Note

One of from_values or from_case_indices must be specified, not both.
One of to_values or to_case_indices must be specified, not both.

Parameters:

trainee_id (str) – The trainee ID.
features (Collection[str] | None, default: None) – List of feature names to use when computing pairwise distances. If unspecified uses all features.
action_feature (str | None, default: None) – The action feature. If specified, uses targeted hyperparameters used to predict this action_feature, otherwise uses targetless hyperparameters.
from_case_indices (Sequence[tuple[str, int]] | None, default: None) – A sequence of tuples, of session id and index, where index is the original 0-based index of the case as it was trained into the session. If specified must be either length of 1 or match length of to_values or to_case_indices.
from_values (DataFrame | list[list[Any]] | None, default: None) – A 2d-list of case values. If specified must be either length of 1 or match length of to_values or to_case_indices.
to_case_indices (Sequence[tuple[str, int]] | None, default: None) – A sequence of tuples, of session id and index, where index is the original 0-based index of the case as it was trained into the session. If specified must be either length of 1 or match length of from_values or from_case_indices.
to_values (DataFrame | list[list[Any]] | None, default: None) – A 2d-list of case values. If specified must be either length of 1 or match length of from_values or from_case_indices.
use_case_weights (bool | None, default: None) – If set to True, will scale influence weights by each case’s weight_feature weight. If unspecified, case weights will be used if the Trainee has them.
weight_feature (str | None, default: None) – Name of feature whose values to use as case weights. When left unspecified uses the internally managed case weight.

Returns:

A list of computed pairwise distances between each corresponding pair of cases in from_case_indices and to_case_indices.

Return type:

list[float]

get_params(trainee_id, *, action_feature=None, context_features=None, mode=None, weight_feature=None)#

Get the parameters used by the Trainee.

If ‘action_feature’, ‘context_features’, ‘mode’, or ‘weight_feature’ are specified, then the best hyperparameters analyzed in the Trainee are the value of the ‘hyperparameter_map’ key, otherwise this value will be the dictionary containing all the hyperparameter sets in the Trainee.

Parameters:

trainee_id (str) – The ID of the Trainee.
action_feature (str | None, default: None) – If specified will return the best analyzed hyperparameters to target this feature.
context_features (Collection[str] | None, default: None) – If specified, will find and return the best analyzed hyperparameters to use with these context features.
mode (Literal['robust', 'full'] | None, default: None) – If specified, will find and return the best analyzed hyperparameters that were computed in this mode.
weight_feature (str | None, default: None) – If specified, will find and return the best analyzed hyperparameters that were analyzed using this weight feature.

Returns:

A dict including the either all of the Trainee’s internal parameters or only the best hyperparameters selected using the passed parameters.

Return type:

dict[str, Any]

abstract get_session(session_id)#

Get session details.

Parameters:: session_id (str)
Return type:: Session

get_session_indices(trainee_id, session)#

Get list of all session indices for a specified session.

Parameters:

trainee_id (str) – The ID of the Trainee get parameters from.
session (str | Session) – The session or session identifier to retrieve indices of.

Returns:

A list of the session indices for the session.

Return type:

list[int]

get_session_training_indices(trainee_id, session)#

Get list of all session training indices for a specified session.

Parameters:

trainee_id (str) – The ID of the Trainee get parameters from.
session (str | Session) – The session or session identifier to retrieve indices of.

Returns:

A list of the session training indices for the session.

Return type:

list[int]

get_sessions(trainee_id)#

Get all sessions in a Trainee.

Parameters:: trainee_id (str) – The ID of the Trainee to get the list of sessions from.
Returns:: A list of dicts with keys “id” and “name” for each session in the Trainee.
Return type:: list[dict[str, str]]

Examples

>>> print(cl.get_sessions(trainee.id))
[{'id': '6c35e481-fb49-4178-a96f-fe4b5afe7af4', 'name': 'default'}]

get_substitute_feature_values(trainee_id, clear_on_get=True)#

Gets a substitution map for use in extended nominal generation.

Parameters:

trainee_id (str) – The ID of the Trainee to get the substitution feature values from.
clear_on_get (bool, default: True) – Clears the substitution values map in the Trainee upon retrieving them. This is done if it is desired to prevent the substitution map from being persisted. If set to False the model will not be cleared which preserves substitution mappings if the model is saved; representing a potential privacy leak should the substitution map be made public.

Returns:

A dictionary of feature name to a dictionary of feature value to substitute feature value.

Return type:

dict

abstract get_trainee(trainee_id)#

Get an existing trainee from the Howso service.

Parameters:: trainee_id (str)
Return type:: Trainee

abstract get_trainee_runtime(trainee_id)#

Get runtime details of a Trainee.

Parameters:: trainee_id (str) – The identifier of the Trainee.
Returns:: The Trainee runtime details. Including Trainee version and configuration parameters.
Return type:: TraineeRuntime

abstract get_version()#

Get Howso version.

Return type:: HowsoVersion

impute(trainee_id, features=None, features_to_impute=None, batch_size=1)#

Impute, or fill in the missing values, for the specified features.

If no ‘features’ are specified, will use all features in the trainee for imputation. If no ‘features_to_impute’ are specified, will impute all features specified by ‘features’.

Parameters:

trainee_id (str) – The ID of the Trainee to impute.
features (Collection[str] | None, default: None) – A list of feature names to use for imputation. If not specified, all features will be used imputed.
features_to_impute (Collection[str] | None, default: None) – A list of feature names to impute. If not specified, features will be used (see above)
batch_size (int, default: 1) –
Larger batch size will increase accuracy and decrease speed. Batch size indicates how many rows to fill before recomputing conviction.

The default value (which is 1) should return the best accuracy but might be slower. Higher values should improve performance but may decrease accuracy of results.

abstract is_tracing_enabled(trainee_id)#

Get if tracing is enabled for Trainee.

Parameters:: trainee_id (str) – The identifier of the Trainee.
Returns:: True, if tracing is enabled for provided Trainee.
Return type:: bool

move_cases(trainee_id, num_cases, *, case_indices=None, condition=None, condition_session=None, precision=None, preserve_session_data=False, source_id=None, source_name_path=None, target_name_path=None, target_id=None)#

Moves training cases from one Trainee to another in the hierarchy.

Parameters:

trainee_id (str) – The identifier of the Trainee doing the moving.
num_cases (int) – The number of cases to move; minimum 1 case must be moved. Ignored if case_indices is specified.
case_indices (Sequence[tuple[str, int]] | None, default: None) – A list of tuples containing session ID and session training index for each case to be removed.
condition (Mapping | None, default: None) –
The condition map to select the cases to move that meet all the provided conditions. Ignored if case_indices is specified.
Note

The dictionary keys are the feature name and values are one of:
- None
- A value, must match exactly.
- An array of two numeric values, specifying an inclusive range. Only applicable to continuous and numeric ordinal features.
- An array of string values, must match any of these values exactly. Only applicable to nominal and string ordinal features.
Tip

Example 1 - Move all values belonging to feature_name:
```
criteria = {"feature_name": None}
```
Example 2 - Move cases that have the value 10:
```
criteria = {"feature_name": 10}
```
Example 3 - Move cases that have a value in range [10, 20]:
```
criteria = {"feature_name": [10, 20]}
```
Example 4 - Remove cases that match one of [‘a’, ‘c’, ‘e’]:
```
condition = {"feature_name": ['a', 'c', 'e']}
```
Example 5 - Move cases using session name and index:
```
criteria = {'.session':'your_session_name',
            '.session_index': 1}
```
condition_session (str | None, default: None) – If specified, ignores the condition and operates on cases for the specified session id. Ignored if case_indices is specified.
precision (Literal['exact', 'similar'] | None, default: None) – The precision to use when moving the cases. Options are ‘exact’ or ‘similar’. If not specified, “exact” will be used. Ignored if case_indices is specified.
preserve_session_data (bool, default: False) – When True, will move cases without cleaning up session data.
source_id (str | None, default: None) – The source trainee unique id from which to move cases. Ignored if source_name_path is specified. If neither source_name_path nor source_id are specified, moves cases from the trainee itself.
source_name_path (Collection[str] | None, default: None) – List of strings specifying the user-friendly path of the child subtrainee from which to move cases.
target_name_path (Collection[str] | None, default: None) – List of strings specifying the user-friendly path of the child subtrainee to move cases to.
target_id (str | None, default: None) – The target trainee id to move the cases to. Ignored if target_name_path is specified. If neither target_name_path nor target_id are specified, moves cases to the trainee itself.

Returns:

The number of cases moved.

Return type:

int

abstract persist_trainee(trainee_id)#

Persist a trainee in the Howso service.

Parameters:: trainee_id (str)

abstract query_sessions(search_terms=None, *, trainee=None, **kwargs)#

Query all accessible sessions.

Parameters:

search_terms (str | None, default: None)
trainee (str | Trainee | None, default: None)

Return type:

list[Session]

abstract query_trainees(search_terms=None)#

Query accessible Trainees.

Parameters:: search_terms (str | None, default: None)
Return type:: list[dict]

react(trainee_id, *, action_features=None, actions=None, allow_nulls=False, batch_size=None, case_indices=None, contexts=None, context_features=None, derived_action_features=None, derived_context_features=None, desired_conviction=None, details=None, exclude_novel_nominals_from_uniqueness_check=False, feature_bounds_map=None, generate_new_cases='no', initial_batch_size=None, input_is_substituted=False, into_series_store=None, leave_case_out=False, new_case_threshold='min', num_cases_to_generate=1, ordered_by_specified_features=False, post_process_features=None, post_process_values=None, preserve_feature_values=None, progress_callback=None, substitute_output=True, suppress_warning=False, use_case_weights=None, use_regional_model_residuals=True, weight_feature=None)#

React to supplied values and cases contained within the Trainee.

If desired_conviction is not specified, executes a discriminative react: provided a list of context values, the trainee reacts to the model and produces predictions for the specified actions. If desired_conviction is specified, executes a generative react, produces action_values for the specified action_features conditioned on the optionally provided contexts.

Parameters:

trainee_id (str) – The ID of the Trainee to react to.
contexts (DataFrame | list[list[Any]] | None, default: None) –
The context values to react to. When the value is a DataFrame, the value will be used to populate both context_values and context_features parameters of the Engine. When the value is a list, context_features must also be specified.
```
>>> contexts = [[1, 2, 3], [4, 5, 6]]
```
action_features (Collection[str] | None, default: None) –
Feature names to treat as action features during react. If actions is a DataFrame, overrides what columns will be used in action_values supplied to the Engine.
```
>>> action_features = ['rain_chance', 'is_sunny']
```
actions (DataFrame | list[list[Any]] | None, default: None) –
One or more action values to use for action features. If specified, will only return the specified explanation details for the given actions (Discriminative reacts only). When the value is a DataFrame, the value will be used to populate both action_values and action_features parameters of the Engine. When the value is a list, action_features must also be specified.
```
>>> actions = [[1, 2, 3], [4, 5, 6]]
```
allow_nulls (bool, default: False) – When true will allow return of null values if there are nulls in the local model for the action features, applicable only to discriminative reacts.
batch_size (int | None, default: None) – Define the number of cases to react to at once. If left unspecified, the batch size will be determined automatically.
context_features (Collection[str] | None, default: None) –
Feature names to treat as context features during react. If contexts is a DataFrame, overrides what columns will be used in context_values supplied to the Engine.
```
>>> context_features = ['temperature', 'humidity', 'dew_point',
...                     'barometric_pressure']
```
derived_context_features (Collection[str] | None, default: None) – An iterable of feature names whose values should be computed from the provided context in the specified order. Must be different than context_features.
derived_action_features (Collection[str] | None, default: None) –
An iterable of feature names whose values should be computed after generation from the generated case prior to output, in the specified order. Must be a subset of action_features.

Note

Both of these derived feature lists rely on the features’ “derived_feature_code” attribute to compute the values. If ‘derived_feature_code’ attribute is undefined or references non-0 feature indices, the derived value will be null.
input_is_substituted (bool, default: False) – if True assumes provided categorical (nominal or ordinal) feature values have already been substituted.
substitute_output (bool, default: True) – If False, will not substitute categorical feature values. Only applicable if a substitution value map has been set.
details (Mapping | None, default: None) –
If details are specified, the response will contain the requested explanation data along with the reaction. Below are the valid keys and data types for the different audit details. Omitted keys, values set to None, or False values for Booleans will not be included in the audit data returned.
- boundary_casesbool, optional
  If True, outputs an automatically determined (when ‘num_boundary_cases’ is not specified) relevant number of boundary cases. Uses both context and action features of the reacted case to determine the counterfactual boundary based on action features, which maximize the dissimilarity of action features while maximizing the similarity of context features. If action features aren’t specified, uses familiarity conviction to determine the boundary instead.
- boundary_cases_familiarity_convictionsbool, optional
  If True, outputs familiarity conviction of addition for each of the boundary cases.
- case_contributions_fullbool, optional
  If true outputs each influential case’s differences between the predicted action feature value and the predicted action feature value if each individual case were not included. Uses only the context features of the reacted case to determine that area. Uses full calculations, which uses leave-one-out for cases for computations.
- case_contributions_robustbool, optional
  If true outputs each influential case’s differences between the predicted action feature value and the predicted action feature value if each individual case were not included. Uses only the context features of the reacted case to determine that area. Uses robust calculations, which uses uniform sampling from the power set of all combinations of cases.
- case_feature_residuals_fullbool, optional
  If True, outputs feature residuals for all (context and action) features for just the specified case. Uses leave-one-out for each feature, while using the others to predict the left out feature with their corresponding values from this case. Uses full calculations, which uses leave-one-out for cases for computations.
- case_feature_residuals_robustbool, optional
  If True, outputs feature residuals for all (context and action) features for just the specified case. Uses leave-one-out for each feature, while using the others to predict the left out feature with their corresponding values from this case. Uses robust calculations, which uses uniform sampling from the power set of features as the contexts for predictions.
- case_mda_robustbool, optional
  If True, outputs each influential case’s mean decrease in accuracy of predicting the action feature in the local model area, as if each individual case were included versus not included. Uses only the context features of the reacted case to determine that area. Uses robust calculations, which uses uniform sampling from the power set of all combinations of cases.
- case_mda_fullbool, optional
  If True, outputs each influential case’s mean decrease in accuracy of predicting the action feature in the local model area, as if each individual case were included versus not included. Uses only the context features of the reacted case to determine that area. Uses full calculations, which uses leave-one-out for cases for computations.
- categorical_action_probabilitiesbool, optional
  If True, outputs probabilities for each class for the action. Applicable only to categorical action features.
- derivation_parametersbool, optional
  If True, outputs a dictionary of the parameters used in the react call. These include k, p, distance_transform, feature_weights, feature_deviations, nominal_class_counts, and use_irw.
  - k: the number of cases used for the local model.
  - p: the parameter for the Lebesgue space.
  - distance_transform: the distance transform used as an exponent to convert distances to raw influence weights.
  - feature_weights: the weight for each feature used in the distance metric.
  - feature_deviations: the deviation for each feature used in the distance metric.
  - nominal_class_counts: the number of unique values for each nominal feature. This is used in the distance metric.
  - use_irw: a flag indicating if feature weights were derived using inverse residual weighting.
- distance_contributionbool, optional
  If True, outputs the distance contribution (expected total surprisal contribution) for the reacted case. Uses both context and action feature values.
- distance_ratiobool, optional
  If True, outputs the ratio of distance (relative surprisal) between this reacted case and its nearest case to the minimum distance (relative surprisal) in between the closest two cases in the local area. All distances are computed using only the specified context features.
- feature_contributions_robustbool, optional
  If True outputs each context feature’s absolute and directional differences between the predicted action feature value and the predicted action feature value if each context were not in the model for all context features in the local model area Uses robust calculations, which uses uniform sampling from the power set of features as the contexts for predictions. Directional feature contributions are returned under the key ‘directional_feature_contributions_robust’.
- feature_contributions_fullbool, optional
  If True outputs each context feature’s absolute and directional differences between the predicted action feature value and the predicted action feature value if each context were not in the model for all context features in the local model area. Uses full calculations, which uses leave-one-out for cases for computations. Directional feature contributions are returned under the key ‘directional_feature_contributions_full’.
- case_feature_contributions_robust: bool, optional
  If True outputs each context feature’s absolute and directional differences between the predicted action feature value and the predicted action feature value if each context feature were not in the model for all context features in this case, using only the values from this specific case. Uses robust calculations, which uses uniform sampling from the power set of features as the contexts for predictions. Directional case feature contributions are returned under the ‘case_directional_feature_contributions_robust’ key.
- case_feature_contributions_full: bool, optional
  If True outputs each context feature’s absolute and directional differences between the predicted action feature value and the predicted action feature value if each context feature were not in the model for all context features in this case, using only the values from this specific case. Uses full calculations, which uses leave-one-out for cases for computations. Directional case feature contributions are returned under the ‘case_directional_feature_contributions_full’ key.
- feature_mda_robustbool, optional
  If True, outputs each context feature’s mean decrease in accuracy of predicting the action feature given the context. Uses only the context features of the reacted case to determine that area. Uses robust calculations, which uses uniform sampling from the power set of features as the contexts for predictions.
- feature_mda_fullbool, optional
  If True, outputs each context feature’s mean decrease in accuracy of predicting the action feature given the context. Uses only the context features of the reacted case to determine that area. Uses full calculations, which uses leave-one-out for cases for computations.
- feature_mda_ex_post_robustbool, optional
  If True, outputs each context feature’s mean decrease in accuracy of predicting the action feature as an explanation detail given that the specified prediction was already made as specified by the action value. Uses both context and action features of the reacted case to determine that area. Uses robust calculations, which uses uniform sampling from the power set of features as the contexts for predictions.
- feature_mda_ex_post_fullbool, optional
  If True, outputs each context feature’s mean decrease in accuracy of predicting the action feature as an explanation detail given that the specified prediction was already made as specified by the action value. Uses both context and action features of the reacted case to determine that area. Uses full calculations, which uses leave-one-out for cases for computations.
- featureslist of str, optional
  A list of feature names that specifies for what features will per-feature details be computed (residuals, contributions, mda, etc.). This should generally preserve compute, but will not when computing details robustly. Details will be computed for all context and action features if this value is not specified.
- feature_residual_robustbool, optional
  If True, outputs feature residuals for all (context and action) features locally around the prediction. Uses only the context features of the reacted case to determine that area. Uses robust calculations, which uses uniform sampling from the power set of features as the contexts for predictions.
- feature_residuals_fullbool, optional
  If True, outputs feature residuals for all (context and action) features locally around the prediction. Uses only the context features of the reacted case to determine that area. Uses full calculations, which uses leave-one-out for cases for computations.
- hypothetical_valuesdict, optional
  A dictionary of feature name to feature value. If specified, shows how a prediction could change in a what-if scenario where the influential cases’ context feature values are replaced with the specified values. Iterates over all influential cases, predicting the action features each one using the updated hypothetical values. Outputs the predicted arithmetic over the influential cases for each action feature.
- influential_casesbool, optional
  If True, outputs the most influential cases and their influence weights based on the surprisal of each case relative to the context being predicted among the cases. Uses only the context features of the reacted case.
- influential_cases_familiarity_convictionsbool, optional
  If True, outputs familiarity conviction of addition for each of the influential cases.
- influential_cases_raw_weightsbool, optional
  If True, outputs the surprisal for each of the influential cases.
- case_feature_residual_convictions_robustbool, optional
  If True, outputs this case’s feature residual convictions for the region around the prediction. Uses only the context features of the reacted case to determine that region. Computed as: region feature residual divided by case feature residual. Uses robust calculations, which uses uniform sampling from the power set of features as the contexts for predictions.
- case_feature_residual_convictions_fullbool, optional
  If True, outputs this case’s feature residual convictions for the region around the prediction. Uses only the context features of the reacted case to determine that region. Computed as: region feature residual divided by case feature residual. Uses full calculations, which uses leave-one-out for cases for computations.
- most_similar_casesbool, optional
  If True, outputs an automatically determined (when ‘num_most_similar_cases’ is not specified) relevant number of similar cases, which will first include the influential cases. Uses only the context features of the reacted case.
- num_boundary_casesint, optional
  Outputs this manually specified number of boundary cases.
- num_most_similar_casesint, optional
  Outputs this manually specified number of most similar cases, which will first include the influential cases.
- num_most_similar_case_indicesint, optional
  Outputs this specified number of most similar case indices when ‘distance_ratio’ is also set to True.
- num_robust_influence_samples_per_caseint, optional
  Specifies the number of robust samples to use for each case. Applicable only for computing robust feature contributions or robust case feature contributions. Defaults to 2000. Higher values will take longer but provide more stable results.
- observational_errorsbool, optional
  If True, outputs observational errors for all features as defined in feature attributes.
- outlying_feature_valuesbool, optional
  If True, outputs the reacted case’s context feature values that are outside the min or max of the corresponding feature values of all the cases in the local model area. Uses only the context features of the reacted case to determine that area.
- prediction_statsbool, optional
  When true outputs feature prediction stats for all (context and action) features locally around the prediction. The stats returned are (“r2”, “rmse”, “spearman_coeff”, “precision”, “recall”, “accuracy”, “mcc”, “confusion_matrix”, “missing_value_accuracy”). Uses only the context features of the reacted case to determine that area. Uses full calculations, which uses leave-one-out context features for computations.
- selected_prediction_statslist, optional. List of stats to output. When unspecified,
  returns all except the confusion matrix. Allowed values:
  - all : Returns all the the available prediction stats, including the confusion matrix.
  - accuracy : The number of correct predictions divided by the total number of predictions.
  - confusion_matrix : A sparse map of actual feature value to a map of predicted feature value to counts.
  - mae : Mean absolute error. For continuous features, this is calculated as the mean of absolute values of the difference between the actual and predicted values. For nominal features, this is 1 - the average categorical action probability of each case’s correct classes. Categorical action probabilities are the probabilities for each class for the action feature.
  - mda : Mean decrease in accuracy when each feature is dropped from the model, applies to all features.
  - feature_mda_permutation_full : Mean decrease in accuracy that used scrambling of feature values instead of dropping each feature, applies to all features.
  - precision : Precision (positive predictive) value for nominal features only.
  - r2 : The r-squared coefficient of determination, for continuous features only.
  - recall : Recall (sensitivity) value for nominal features only.
  - rmse : Root mean squared error, for continuous features only.
  - spearman_coeff : Spearman’s rank correlation coefficient, for continuous features only.
  - mcc : Matthews correlation coefficient, for nominal features only.
- similarity_convictionbool, optional
  If True, outputs similarity conviction for the reacted case. Uses both context and action feature values as the case values for all computations. This is defined as expected (local) distance contribution divided by reacted case distance contribution.
- generate_attemptsbool, optional
  If True outputs the number of attempts taken to generate each case. Only applicable when ‘generate_new_cases’ is “always” or “attempt”.
```
>>> details = {'num_most_similar_cases': 5,
...            'feature_residuals_full': True}
```
desired_conviction (float | None, default: None) – If specified will execute a generative react. If not specified will executed a discriminative react. Conviction is the ratio of expected surprisal to generated surprisal for each feature generated, valid values are in the range of \((0, \\infty)\).
weight_feature (str | None, default: None) – Name of feature whose values to use as case weights. When left unspecified uses the internally managed case weight.
use_case_weights (bool | None, default: None) – If set to True, will scale influence weights by each case’s weight_feature weight. If unspecified, case weights will be used if the Trainee has them.
case_indices (Sequence[tuple[str, int]] | None, default: None) – An Iterable of Sequences, of session id and index, where index is the original 0-based index of the case as it was trained into the session. If this case does not exist, discriminative react outputs null, generative react ignores it.
preserve_feature_values (Collection[str] | None, default: None) – List of features that will preserve their values from the case specified by case_indices, appending and overwriting the specified contexts as necessary. For generative reacts, if case_indices isn’t specified will preserve feature values of a random case.
leave_case_out (bool, default: False) – If set to True and specified along with case_indices, each individual react will respectively ignore the corresponding case specified by case_indices by leaving it out.
initial_batch_size (int | None, default: None) – Define the number of cases to react to in the first batch. If unspecified, the value of the react_initial_batch_size property is used. The number of cases in following batches will be automatically adjusted. This value is ignored if batch_size is specified.
into_series_store (str | None, default: None) – The name of a series store. If specified, will store an internal record of all react contexts for this session and series to be used later with train series.
use_regional_model_residuals (bool, default: True) – If false uses model feature residuals, if True recalculates regional model residuals.
feature_bounds_map (Mapping | None, default: None) –
A mapping of feature names to the bounds for the feature values to be generated in. For continuous features this should be a numeric value, for datetimes this should be a datetime string. Min bounds should be equal to or smaller than max bounds, except when setting the bounds around the cycle length of a cyclic feature.(e.g., to allow 0 +/- 60 degrees, set min=300 and max=60).
Example feature bounds map:#
```
{
    "feature_a": {"min": 0},
    "feature_b" : {"min": 1, "max": 5},
    "feature_c": {"max": 1}
}
```
generate_new_cases (Literal['always', 'attempt', 'no'], default: 'no') –
(Optional) Whether to generate new cases.

This parameter takes in a string equal to one of the following:
1. ”attempt”
  
  Synthesizer attempts to generate new cases and if its not possible to generate a new case, it might generate cases in “no” mode (see point c.)
2. ”always”
  
  Synthesizer always generates new cases and if its not possible to generate a new case, it returns None.
3. ”no”
  
  Synthesizer generates data based on the desired_conviction specified and the generated data is not guaranteed to be a new case (that is, a case not found in original dataset.)
ordered_by_specified_features (bool, default: False) – If True order of generated feature values will match the order of specified features.
num_cases_to_generate (int, default: 1) – The number of cases to generate.
suppress_warning (bool, default: False) – If True, warnings will not be displayed.
post_process_features (Collection[str] | None, default: None) – List of feature names that will be made available during the execution of post_process feature attributes.
post_process_values (DataFrame | list[list[Any]] | None, default: None) – A 2d list of values corresponding to post_process_features that will be made available during the execution of post_process feature attributes.
progress_callback (Callable | None, default: None) – A callback method that will be called before each batched call to react and at the end of reacting. The method is given a ProgressTimer containing metrics on the progress and timing of the react operation, and the batch result.
new_case_threshold (Literal['max', 'min', 'most_similar'], default: 'min') –
Distance to determine the privacy cutoff. If None, will default to “min”.

Possible values:
- min: minimum distance in the original local space.
- max: maximum distance in the original local space.
- most_similar: distance between the nearest neighbor to the nearest neighbor in the original space.
exclude_novel_nominals_from_uniqueness_check (bool, default: False) – If True, will exclude features which have a subtype defined in their feature attributes from the uniqueness check that happens when generate_new_cases is True. Only applies to generative reacts.

Returns:

A MutableMapping (dict-like) with these keys -> values:

action -> pandas.DataFrame: A data frame of action values.
details -> Dict or List: An aggregated list of any requested details.

Raises:

ValueError – If derived_action_features is not a subset of action_features. If new_case_threshold is not one of {“max”, “min”, “most_similar”}. If the number of context values does not match the number of context features.
HowsoError – If num_cases_to_generate is not an integer greater than 0.

Return type:

Reaction

react_aggregate(trainee_id, *, action_feature=None, action_features=None, confusion_matrix_min_count=None, context_features=None, details=None, feature_influences_action_feature=None, hyperparameter_param_path=None, num_robust_influence_samples=None, num_robust_residual_samples=None, num_robust_influence_samples_per_case=None, num_samples=None, prediction_stats_action_feature=None, residuals_hyperparameter_feature=None, robust_hyperparameters=None, sample_model_fraction=None, sub_model_size=None, use_case_weights=None, weight_feature=None)#

Reacts into the aggregate trained cases in the Trainee.

Calculates, caches, and/or returns the requested influences and prediction stats.

Parameters:

action_feature (str | None, default: None) – Name of target feature for which to do computations. If prediction_stats_action_feature and feature_influences_action_feature are not provided, they will default to this value. If feature_influences_action_feature is not provided and feature influences details are selected, this feature must be provided.
action_features (Collection[str] | None, default: None) – List of feature names to compute any requested residuals or prediction statistics for. If unspecified, the value used for context features will be used.
confusion_matrix_min_count (int | None, default: None) – The number of predictions a class should have (value of a cell in the matrix) for it to remain in the confusion matrix. If the count is less than this value, it will be accumulated into a single value of all insignificant predictions for the class and removed from the confusion matrix. Defaults to 10, applicable only to confusion matrices when computing residuals.
context_features (Collection[str] | None, default: None) – List of features names to use as contexts for computations. Default is all trained non-unique features if unspecified.
details (dict | None, default: None) –
If details are specified, the response will contain the requested explanation data.. Below are the valid keys and data types for the different audit details. Omitted keys, values set to None, or False values for Booleans will not be included in the data returned.
- prediction_statsbool, optional
  If True outputs full feature prediction stats for all (context and action) features. The prediction stats returned are set by the “selected_prediction_stats” parameter in the details parameter. Uses full calculations, which uses leave-one-out for features for computations.
- feature_residuals_fullbool, optional
  For each context_feature, use the full set of all other context_features to predict the feature. When prediction_stats in the details parameter is true, the Trainee will also calculate the full feature residuals.
- feature_residuals_robustbool, optional
  For each context_feature, use the robust (power set/permutations) set of all other context_features to predict the feature.
- feature_contributions_fullbool, optional
  For each context_feature, use the full set of all other context_features to compute the mean absolute delta between prediction of action feature with and without the context features in the model. Returns the mean absolute delta under the key ‘feature_contributions_full’ and returns the mean delta under the key ‘directional_feature_contributions_full’.
- feature_contributions_robustbool, optional
  For each context_feature, use the robust (power set/permutation) set of all other context_features to compute the mean absolute delta between prediction of the action feature with and without the context features in the model. Returns the mean absolute delta under the key ‘feature_contributions_robust’ and returns the mean delta under the key ‘directional_feature_contributions_robust’.
- feature_mda_fullbool, optional
  When True will compute Mean Decrease in Accuracy (MDA) for each context feature at predicting the action feature. Drop each feature and use the full set of remaining context features for each prediction.
- feature_mda_robustbool, optional
  Compute Mean Decrease in Accuracy MDA by dropping each feature and using the robust (power set/permutations) set of remaining context features for each prediction.
- feature_feature_mda_permutation_fullbool, optional
  Compute MDA by scrambling each feature and using the full set of remaining context features for each prediction.
- feature_feature_mda_permutation_robustbool, optional
  Compute MDA by scrambling each feature and using the robust (power set/permutations) set of remaining context features for each prediction.
- action_conditionmap of str -> any, optional
  A condition map to select the action set, which is the dataset for which the prediction stats are for. If both action_condition and context_condition are provided, then all of the action cases selected by the action_condition will be excluded from the context set, which is the set being queried to make to make predictions on the action set, effectively holding them out. If only action_condition is specified, then only the single predicted case will be left out.
  Note
  
  The dictionary keys are the feature name and values are one of:
  
  None
  
  A value, must match exactly.
  
  An array of two numeric values, specifying an inclusive
  
  range. Only applicable to continuous and numeric ordinal features. - An array of string values, must match any of these values exactly. Only applicable to nominal and string ordinal features.
- action_num_casesint, optional
  The maximum amount of cases to use to calculate prediction stats. If not specified, the limit will be k cases if precision is “similar”, or 1000 cases if precision is “exact”. Works with or without action_condition. -If action_condition is set:
  
  If None, will be set to k if precision is “similar” or no limit if precision is “exact”.
  - If action_condition is not set:
    If None, will be set to the Howso default limit of 2000.
- action_condition_precision{“exact”, “similar”}, optional
  The precision to use when selecting cases with the action_condition. If not specified “exact” will be used. Only used if action_condition is not None.
- context_conditionmap of str -> any, optional
  A condition map to select the context set, which is the set being queried to make to make predictions on the action set. If both action_condition and context_condition are provided, then all of the cases from the action set, which is the dataset for which the prediction stats are for, will be excluded from the context set, effectively holding them out. If only action_condition is specified, then only the single predicted case will be left out.
  Note
  
  The dictionary keys are the feature name and values are one of:
  
  None
  
  A value, must match exactly.
  
  An array of two numeric values, specifying an inclusive
  
  range. Only applicable to continuous and numeric ordinal features. - An array of string values, must match any of these values exactly. Only applicable to nominal and string ordinal features.
- context_precision_num_casesint, optional
  Limit on the number of context cases when context_condition_precision is set to “similar”. If None, will be set to k.
- context_condition_precision{“exact”, “similar”}, optional
  The precision to use when selecting cases with the context_condition. If not specified “exact” will be used. Only used if context_condition is not None.
- prediction_stats_featureslist, optional
  List of features to use when calculating conditional prediction stats. Should contain all action and context features desired. If action_feature is also provided, that feature will automatically be appended to this list if it is not already in the list.
  
  stats : list of str, optional
- selected_prediction_statslist, optional
  List of stats to output. When unspecified, returns all except the confusion matrix. Allowed values:
  - all : Returns all the the available prediction stats, including the confusion matrix.
  - accuracy : The number of correct predictions divided by the total number of predictions.
  - confusion_matrix : A sparse map of actual feature value to a map of predicted feature value to counts.
  - mae : Mean absolute error. For continuous features, this is calculated as the mean of absolute values of the difference between the actual and predicted values. For nominal features, this is 1 - the average categorical action probability of each case’s correct classes. Categorical action probabilities are the probabilities for each class for the action feature.
  - mda : Mean decrease in accuracy when each feature is dropped from the model, applies to all features.
  - feature_mda_permutation_full : Mean decrease in accuracy that used scrambling of feature values instead of dropping each feature, applies to all features.
  - precision : Precision (positive predictive) value for nominal features only.
  - r2 : The r-squared coefficient of determination, for continuous features only.
  - recall : Recall (sensitivity) value for nominal features only.
  - rmse : Root mean squared error, for continuous features only.
  - spearman_coeff : Spearman’s rank correlation coefficient, for continuous features only.
  - mcc : Matthews correlation coefficient, for nominal features only.
feature_influences_action_feature (str | None, default: None) – When feature influences such as contributions and mda, use this feature as the action feature. If not provided, will default to the action_feature if provided. If action_feature is not provided and feature influences details are selected, this feature must be provided.
hyperparameter_param_path (Collection[str] | None, default: None) – Full path for hyperparameters to use for computation. If specified for any residual computations, takes precedence over action_feature parameter. Can be set to a ‘paramPath’ value from the results of ‘get_params()’ for a specific set of hyperparameters.
num_robust_influence_samples (int | None, default: None) – Total sample size of model to use (using sampling with replacement) for robust contribution computation. Defaults to 300.
num_robust_residual_samples (int | None, default: None) – Total sample size of model to use (using sampling with replacement) for robust mda and residual computation. Defaults to 1000 * (1 + log(number of features)). Note: robust mda will be updated to use num_robust_influence_samples in a future release.
num_robust_influence_samples_per_case (int | None, default: None) – Specifies the number of robust samples to use for each case for robust contribution computations. Defaults to 300 + 2 * (number of features).
num_samples (int | None, default: None) – Total sample size of model to use (using sampling with replacement) for all non-robust computation. Defaults to 1000. If specified overrides sample_model_fraction.```
residuals_hyperparameter_feature (str | None, default: None) – When calculating residuals and prediction stats, uses this target features’s hyperparameters. The trainee must have been analyzed with this feature as the action feature first. If not provided, by default residuals and prediction stats uses “.targetless” hyperparameters.
robust_hyperparameters (bool | None, default: None) – When specified, will attempt to return residuals that were computed using hyperparameters with the specified robust or non-robust type.
prediction_stats_action_feature (str | None, default: None) – When calculating residuals and prediction stats, uses this target features’s hyperparameters. The trainee must have been analyzed with this feature as the action feature first. If both prediction_stats_action_feature and action_feature are not provided, by default residuals and prediction stats uses “.targetless” hyperparameters. If “action_feature” is provided, and this value is not provided, will default to action_feature.
sample_model_fraction (float | None, default: None) – A value between 0.0 - 1.0, percent of model to use in sampling (using sampling without replacement). Applicable only to non-robust computation. Ignored if num_samples is specified. Higher values provide better accuracy at the cost of compute time.
sub_model_size (int | None, default: None) – Subset of model to use for calculations. Applicable only to models > 1000 cases.
use_case_weights (bool | None, default: None) – If set to True, will scale influence weights by each case’s weight_feature weight. If unspecified, case weights will be used if the Trainee has them.
weight_feature (str | None, default: None) – The name of feature whose values to use as case weights. When left unspecified uses the internally managed case weight.
trainee_id (str)

Returns:

If specified, a map of feature to map of stat type to stat values is returned.

Return type:

dict[str, dict[str, float]]

react_group(trainee_id, new_cases, *, features=None, distance_contributions=False, familiarity_conviction_addition=True, familiarity_conviction_removal=False, kl_divergence_addition=False, kl_divergence_removal=False, p_value_of_addition=False, p_value_of_removal=False, weight_feature=None, use_case_weights=None)#

Computes specified data for a set of cases.

Return the list of familiarity convictions (and optionally, distance contributions or p values) for each set.

Parameters:

trainee_id (str) – The trainee id.
new_cases (list[DataFrame] | list[list[list[Any]]]) –
Specify a set using a list of cases to compute the conviction of groups of cases as shown in the following example.
```
>>> [ [[1, 2, 3], [4, 5, 6], [7, 8, 9]], # Group 1
>>>   [[1, 2, 3]] ] # Group 2
```
features (Collection[str] | None, default: None) – The feature names to consider while calculating convictions.
distance_contributions (bool, default: False) – Calculate and output distance contribution ratios in the output dict for each case.
familiarity_conviction_addition (bool, default: True) – Calculate and output familiarity conviction of adding the specified cases.
familiarity_conviction_removal (bool, default: False) – Calculate and output familiarity conviction of removing the specified cases.
kl_divergence_addition (bool, default: False) – Calculate and output KL divergence of adding the specified cases.
kl_divergence_removal (bool, default: False) – Calculate and output KL divergence of removing the specified cases.
p_value_of_addition (bool, default: False) – If true will output p value of addition.
p_value_of_removal (bool, default: False) – If true will output p value of removal.
weight_feature (str | None, default: None) – Name of feature whose values to use as case weights. When left unspecified uses the internally managed case weight.
use_case_weights (bool | None, default: None) – If set to True, will scale influence weights by each case’s weight_feature weight. If unspecified, case weights will be used if the Trainee has them.

Returns:

The react group response.

Return type:

dict

react_into_features(trainee_id, *, distance_contribution=False, familiarity_conviction_addition=False, familiarity_conviction_removal=False, features=None, influence_weight_entropy=False, p_value_of_addition=False, p_value_of_removal=False, similarity_conviction=False, use_case_weights=None, weight_feature=None)#

Calculate and cache conviction and other statistics.

Parameters:

trainee_id (str) – The ID of the Trainee to calculate and store conviction for.
features (Collection[str] | None, default: None) – An iterable of features to calculate convictions.
familiarity_conviction_addition (bool | str, default: False) – The name of the feature to store conviction of addition values. If set to True the values will be stored to the feature ‘familiarity_conviction_addition’.
familiarity_conviction_removal (bool | str, default: False) – The name of the feature to store conviction of removal values. If set to True the values will be stored to the feature ‘familiarity_conviction_removal’.
influence_weight_entropy (bool | str, default: False) – The name of the feature to store influence weight entropy values in. If set to True, the values will be stored in the feature ‘influence_weight_entropy’.
p_value_of_addition (bool | str, default: False) – The name of the feature to store p value of addition values. If set to True the values will be stored to the feature ‘p_value_of_addition’.
p_value_of_removal (bool | str, default: False) – The name of the feature to store p value of removal values. If set to True the values will be stored to the feature ‘p_value_of_removal’.
similarity_conviction (bool | str, default: False) – The name of the feature to store similarity conviction values. If set to True the values will be stored to the feature ‘similarity_conviction’.
distance_contribution (bool | str, default: False) – The name of the feature to store distance contribution. If set to True the values will be stored to the feature ‘distance_contribution’.
weight_feature (str | None, default: None) – Name of feature whose values to use as case weights. When left unspecified uses the internally managed case weight.
use_case_weights (bool | None, default: None) – If set to True, will scale influence weights by each case’s weight_feature weight. If unspecified, case weights will be used if the Trainee has them.

react_series(trainee_id, *, action_features=None, actions=None, batch_size=None, case_indices=None, contexts=None, context_features=None, continue_series=False, continue_series_features=None, continue_series_values=None, derived_action_features=None, derived_context_features=None, desired_conviction=None, details=None, exclude_novel_nominals_from_uniqueness_check=False, feature_bounds_map=None, final_time_steps=None, generate_new_cases='no', init_time_steps=None, initial_batch_size=None, initial_features=None, initial_values=None, input_is_substituted=False, leave_case_out=False, max_series_lengths=None, new_case_threshold='min', num_series_to_generate=1, ordered_by_specified_features=False, output_new_series_ids=True, preserve_feature_values=None, progress_callback=None, series_context_features=None, series_context_values=None, series_id_tracking='fixed', series_index=None, series_stop_maps=None, substitute_output=True, suppress_warning=False, use_case_weights=None, use_regional_model_residuals=True, weight_feature=None)#

React in a series until a series_stop_map condition is met.

Aggregates rows of data corresponding to the specified context, action, derived_context and derived_action features, utilizing previous rows to derive values as necessary. Outputs a dict of “action_features” and corresponding “action” where “action” is the completed ‘matrix’ for the corresponding action_features and derived_action_features.

Parameters:

trainee_id (str) – The ID of the Trainee to react to.
num_series_to_generate (int, default: 1) – The number of series to generate.
final_time_steps (list[Any] | None, default: None) – The time steps at which to end synthesis. Time-series only. Must provide either one for all series, or exactly one per series.
init_time_steps (list[Any] | None, default: None) – The time steps at which to begin synthesis. Time-series only. Must provide either one for all series, or exactly one per series.
initial_features (Collection[str] | None, default: None) – List of features to condition just the first case in a series, overwrites context_features and derived_context_features for that first case. All specified initial features must be in one of: context_features, action_features, derived_context_features or derived_action_features. If provided a value that isn’t in one of those lists, it will be ignored.
initial_values (DataFrame | list[list[Any]] | None, default: None) – 2d list of values corresponding to the initial_features, used to condition just the first case in each series. Must provide either one for all series, or exactly one per series.
series_stop_maps (list[Mapping[str, Mapping[str, Any]]] | None, default: None) –
A dictionary of feature name to stop conditions. Must provide either one for all series, or exactly one per series.
Tip

Stop series when value exceeds max or is smaller than min:
```
{"feature_name":  {"min" : 1, "max": 2}}
```
Stop series when feature value matches any of the values listed:
```
{"feature_name":  {"values": ["val1", "val2"]}}
```
max_series_lengths (list[int] | None, default: None) – maximum size a series is allowed to be. Default is 3 * model_size, a 0 or less is no limit. If forecasting with continue_series, this defines the maximum length of the forecast. Must provide either one for all series, or exactly one per series.
continue_series (bool, default: False) –
When True will attempt to continue existing series instead of starting new series. If initial_values provide series IDs, it will continue those explicitly specified IDs, otherwise it will randomly select series to continue. .. note:
```
Terminated series with terminators cannot be continued and
will result in null output.
```
continue_series_features (Collection[str] | None, default: None) – The list of feature names corresponding to the values in each row of continue_series_values. This value is ignored if continue_series_values is None.
continue_series_values (list[Any] | list[list[Any]] | None, default: None) – The set of series data to be forecasted with feature values in the same order defined by continue_series_values. The value of continue_series will be ignored and treated as true if this value is specified.
derived_context_features (Collection[str] | None, default: None) – List of context features whose values should be computed from the entire series in the specified order. Must be different than context_features.
derived_action_features (Collection[str] | None, default: None) –
List of action features whose values should be computed from the resulting last row in series, in the specified order. Must be a subset of action_features.

Note

Both of these derived feature lists rely on the features’ “derived_feature_code” attribute to compute the values. If “derived_feature_code” attribute references non-existing feature indices, the derived value will be null.
exclude_novel_nominals_from_uniqueness_check (bool, default: False) – If True, will exclude features which have a subtype defined in their feature attributes from the uniqueness check that happens when generate_new_cases is True. Only applies to generative reacts.
series_context_features (Collection[str] | None, default: None) – List of context features corresponding to series_context_values, if specified must not overlap with any initial_features or context_features.
series_context_values (list[DataFrame] | list[list[list[Any]]] | None, default: None) – 3d-list of context values, one for each feature for each row for each series. If specified, max_series_lengths are ignored.
output_new_series_ids (bool, default: True) – If True, series ids are replaced with unique values on output. If False, will maintain or replace ids with existing trained values, but also allows output of series with duplicate existing ids.
series_id_tracking (Literal['fixed', 'dynamic', 'no'], default: 'fixed') –
Controls how closely generated series should follow existing series (plural).

Choices are: “fixed” , “dynamic” or “no”:
- If “fixed”, tracks the particular relevant series ID.
- If “dynamic”, tracks the particular relevant series ID, but is allowed to change the series ID that it tracks based on its current context.
- If “no”, does not track any particular series ID.
series_index (str | None, default: None) – When set to a string, will include the series index as a column in the returned DataFrame using the column name given. If set to None, no column will be added.
progress_callback (Callable | None, default: None) – A callback method that will be called before each batched call to react series and at the end of reacting. The method is given a ProgressTimer containing metrics on the progress and timing of the react series operation, and the batch result.
batch_size (int | None, default: None) – Define the number of series to react to at once. If left unspecified, the batch size will be determined automatically.
initial_batch_size (int | None, default: None) – The number of series to react to in the first batch. If unspecified, the number will be determined automatically. The number of series in following batches will be automatically adjusted. This value is ignored if batch_size is specified.
contexts (DataFrame | list[list[Any]] | None, default: None) – See parameter contexts in AbstractHowsoClient.react().
action_features (Collection[str] | None, default: None) – See parameter action_features in AbstractHowsoClient.react().
actions (DataFrame | list[list[Any]] | None, default: None) – See parameter actions in AbstractHowsoClient.react().
context_features (Collection[str] | None, default: None) – See parameter context_features in AbstractHowsoClient.react().
input_is_substituted (bool, default: False) – See parameter input_is_substituted in AbstractHowsoClient.react().
substitute_output (bool, default: True) – See parameter substitute_output in AbstractHowsoClient.react().
details (Mapping | None, default: None) – See parameter details in AbstractHowsoClient.react().
desired_conviction (float | None, default: None) – See parameter desired_conviction in AbstractHowsoClient.react().
weight_feature (str | None, default: None) – See parameter weight_feature in AbstractHowsoClient.react().
use_case_weights (bool | None, default: None) – See parameter use_case_weights in AbstractHowsoClient.react().
case_indices (Sequence[tuple[str, int]] | None, default: None) – See parameter case_indices in AbstractHowsoClient.react().
preserve_feature_values (Collection[str] | None, default: None) – See parameter preserve_feature_values in AbstractHowsoClient.react().
new_case_threshold (Literal['max', 'min', 'most_similar'], default: 'min') – See parameter new_case_threshold in AbstractHowsoClient.react().
leave_case_out (bool, default: False) – See parameter leave_case_out in AbstractHowsoClient.react().
use_regional_model_residuals (bool, default: True) – See parameter use_regional_model_residuals in AbstractHowsoClient.react().
feature_bounds_map (Mapping[str, Mapping[str, Any]] | None, default: None) – See parameter feature_bounds_map in AbstractHowsoClient.react().
generate_new_cases (Literal['always', 'attempt', 'no'], default: 'no') – See parameter generate_new_cases in AbstractHowsoClient.react().
ordered_by_specified_features (bool, default: False) – See parameter ordered_by_specified_features in AbstractHowsoClient.react().
suppress_warning (bool, default: False) – See parameter suppress_warning in AbstractHowsoClient.react().

Returns:

A MutableMapping (dict-like) with these keys -> values:

action -> pandas.DataFrame: A data frame of action values.
details -> Dict or List: An aggregated list of any requested details.

Raises:

ValueError – If the number of provided context values does not match the length of context features. If series_context_values is not a 3d list of objects. If series_continue_values is not a 3d list of objects. If derived_action_features is not a subset of action_features. If new_case_threshold is not one of {“max”, “min”, “most_similar”}.
HowsoError – If num_series_to_generate is not an integer greater than 0.

Return type:

Reaction

reduce_data(trainee_id, features=None, distribute_weight_feature=None, influence_weight_entropy_threshold=None, skip_auto_analyze=False, **kwargs)#

Smartly reduce the amount of trained cases while accumulating case weights.

Determines which cases to remove by comparing the influence weight entropy of each trained case to the influence_weight_entropy_threshold quantile of existing influence weight entropies.

Note

All ablation endpoints, including reduce_data() are experimental and may have their API changed without deprecation.