howso.client#

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.

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

Add a feature to a trainee’s model.

abstract analyze(trainee_id, context_features=None, action_features=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, analysis_sub_model_size=None, p_values=None, targeted_model=None, use_case_weights=None, use_deviations=None, weight_feature=None, **kwargs)#

Analyzes a trainee.

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

Append the specified contexts to a series store.

abstract auto_analyze(trainee_id)#

Auto-analyze the trainee model.

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

Begin a new session.

abstract copy_subtrainee(trainee_id, new_trainee_name, *, target_name_path=None, target_id=None, source_name_path=None, source_id=None)#

Copy a subtrainee in trainee’s hierarchy.

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

Copy a trainee in the Howso service.

abstract create_trainee(trainee, *, library_type=None, max_wait_time=None, overwrite_trainee=False, resources=None)#

Create a trainee on the Howso service.

abstract delete_trainee(trainee_id, file_path=None)#

Delete a trainee in the Howso service.

abstract delete_trainee_session(trainee_id, session)#

Delete a session from a trainee.

abstract 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.

Return type:

int

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

Evaluate custom code on case values within the trainee.

Return type:

Dict

abstract get_auto_ablation_params(trainee_id)#

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

abstract 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 trainee.

Return type:

Cases | DataFrame

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

Compute distances matrix for specified cases.

Return type:

Dict

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

Get the extreme cases of a trainee for the given feature(s).

Parameters:

features (Iterable[str] | None, default: None)

Return type:

Cases | DataFrame

abstract get_feature_attributes(trainee_id)#

Get a dict of feature attributes.

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

Get familiarity conviction for features in the model.

Parameters:

  • familiarity_conviction_addition (bool | str, default: True)

  • familiarity_conviction_removal (bool | str, default: False)

  • use_case_weights (bool, default: False)

Return type:

Dict | DataFrame

abstract get_hierarchy(trainee_id)#

Output the hierarchy for a trainee.

Return type:

Dict

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

Get marginal stats for all features.

Return type:

DataFrame | Dict

abstract get_num_training_cases(trainee_id)#

Return the number of trained cases in the model.

Return type:

int

abstract 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=False, weight_feature=None)#

Compute pairwise distances between specified cases.

Return type:

List[float]

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

Get parameters used by the system.

Return type:

Dict[str, Any]

abstract get_session(session_id)#

Get session details.

abstract get_sessions(search_terms=None)#

Get list of all accessible sessions.

abstract get_substitute_feature_values(trainee_id, clear_on_get=True)#

Get a substitution map for use in extended nominal generation.

Return type:

Dict

abstract get_trainee(trainee_id)#

Get an existing trainee from the Howso service.

abstract get_trainee_information(trainee_id)#

Get information about the trainee.

Return type:

TraineeInformation

abstract get_trainee_metrics(trainee_id)#

Get metric information for a trainee.

Return type:

Metrics

abstract get_trainee_session_indices(trainee_id, session)#

Get list of all session indices for a specified session.

Return type:

Index | List[int]

abstract get_trainee_session_training_indices(trainee_id, session)#

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

Return type:

Index | List[int]

abstract get_trainee_sessions(trainee_id)#

Get the session ids of a trainee.

Return type:

List[Dict[str, str]]

abstract get_trainees(search_terms=None)#

Return a list of all accessible trainees.

Return type:

List

abstract get_version()#

Get Howso version.

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

Impute the missing values for the specified features_to_impute.

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

Move training cases from one trainee to another in the hierarchy.

Return type:

int

abstract persist_trainee(trainee_id)#

Persist a trainee in the Howso service.

abstract 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=None, 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=False, use_regional_model_residuals=True, weight_feature=None)#

Send a react to the Howso engine.

Return type:

Reaction

abstract react_aggregate(trainee_id, *, action_feature=None, confusion_matrix_min_count=None, context_features=None, details=None, feature_influences_action_feature=None, hyperparameter_param_path=None, num_samples=None, num_robust_influence_samples=None, num_robust_residual_samples=None, num_robust_influence_samples_per_case=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)#

Computes, caches, and/or returns specified feature interpretations.

Return type:

DataFrame | dict

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

Compute specified data for a set of cases.

Return type:

DataFrame | Dict

abstract 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=False, weight_feature=None)#

Calculate conviction and other data for the specified feature(s).

Parameters:

  • distance_contribution (bool | str, default: False)

  • familiarity_conviction_addition (bool | str, default: False)

  • familiarity_conviction_removal (bool | str, default: False)

  • influence_weight_entropy (bool | str, default: False)

  • p_value_of_addition (bool | str, default: False)

  • p_value_of_removal (bool | str, default: False)

  • similarity_conviction (bool | str, default: False)

  • use_case_weights (bool | str, default: False)

abstract 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=None, 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_stop_maps=None, series_index=None, substitute_output=True, suppress_warning=False, use_case_weights=False, use_regional_model_residuals=True, weight_feature=None)#

React in a series until a stop condition is met.

Return type:

Reaction

abstract 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.

abstract release_trainee_resources(trainee_id)#

Release a trainee’s resources from the Howso service.

abstract remove_cases(trainee_id, num_cases, *, case_indices=None, condition=None, condition_session=None, distribute_weight_feature=None, precision=None)#

Remove training cases from a trainee.

Return type:

int

abstract remove_feature(trainee_id, feature, *, condition=None, condition_session=None)#

Remove a feature from a trainee.

abstract remove_series_store(trainee_id, series=None)#

Clear stored series from trainee.

abstract rename_subtrainee(trainee_id, new_name, *, child_name_path=None, child_id=None)#

Renames a contained child trainee in the hierarchy.

Return type:

None

abstract set_auto_ablation_params(trainee_id, auto_ablation_enabled=False, *, auto_ablation_weight_feature='.case_weight', conviction_lower_threshold=None, conviction_upper_threshold=None, exact_prediction_features=None, influence_weight_entropy_threshold=0.6, minimum_model_size=1000, relative_prediction_threshold_map=None, residual_prediction_features=None, tolerance_prediction_threshold_map=None, **kwargs)#

Set trainee parameters for auto-ablation.

abstract set_auto_analyze_params(trainee_id, auto_analyze_enabled=False, analyze_threshold=None, *, auto_analyze_limit_size=None, analyze_growth_factor=None, **kwargs)#

Set trainee parameters for auto analysis.

abstract set_feature_attributes(trainee_id, feature_attributes)#

Set feature attributes for a trainee.

abstract set_params(trainee_id, params)#

Set specific hyperparameters in the trainee.

abstract set_random_seed(trainee_id, seed)#

Set the random seed for the trainee.

abstract set_substitute_feature_values(trainee_id, substitution_value_map)#

Set a substitution map for use in extended nominal generation.

abstract train(trainee_id, cases, features=None, *, accumulate_weight_feature=None, batch_size=None, derived_features=None, initial_batch_size=None, input_is_substituted=False, progress_callback=None, series=None, train_weights_only=False, validate=True)#

Train a trainee with sessions containing training cases.

abstract update_session(session_id, *, metadata=None)#

Update a session.

abstract update_trainee(trainee)#

Update an existing trainee in the Howso service.

abstract property active_session#

Return the active session.

abstract property react_initial_batch_size: int#

The default number of cases in the first react batch.

abstract property train_initial_batch_size: int#

The default number of cases in the first train batch.

abstract property trainee_cache#

Return the trainee cache.

howso.client.HowsoClient(**kwargs)#

Return the appropriate AbstractHowsoClient subclass based on config.

This is a “factory function” that, based on the given parameters, will decide which AbstractHowsoClient derivative to instantiate and return.

Parameters:

  • config_path – The path to a valid configuration file, or None

  • verbose – If True provides more verbose messaging. Default is false.

  • kwargs – Additional client arguments. These will be passed to the client constructor along with config_path and verbose.

Returns:

An instantiated subclass of AbstractHowsoClient.

howso.client.HowsoPandasClient(**kwargs)#

Return the appropriate AbstractHowsoClient subclass based on config.

This is a “factory function” that, based on the given parameters, will decide which AbstractHowsoClient derivative to instantiate and return using the Pandas client mixin.

Parameters:

  • config_path – The path to a valid configuration file, or None

  • verbose – If True provides more verbose messaging. Default is false.

  • kwargs – Additional client arguments. These will be passed to the client constructor along with config_path and verbose.

Returns:

An instantiated subclass of AbstractHowsoClient constructed with the HowsoPandasClientMixin.

howso.client.get_configuration_path(config_path=None, verbose=False)#

Determine where the configuration is stored, if anywhere.

If config_path is None, None will be returned.

If a config_path is that is non-None, it will be processed as a YAML file, if the file does not exist at the provided path or there are parse errors, an exception will be raised.

Parameters:

  • config_path (Path | str | None, default: None) – The given config_path.

  • verbose (bool, default: False) – If True provides more verbose messaging. Default is false.

Returns:

The found config_path or None

Raises:

HowsoConfigurationError – Raised if a config_path is provided but points to a non-existent file or the file is un-parsable as a YAML file.

Return type:

Path | None

howso.client.get_howso_client(**kwargs)#

Return the appropriate AbstractHowsoClient subclass based on config.

This is a “factory function” that, based on the given parameters, will decide which AbstractHowsoClient derivative to instantiate and return.

Parameters:

  • config_path – The path to a valid configuration file, or None

  • verbose – If True provides more verbose messaging. Default is false.

  • kwargs – Additional client arguments. These will be passed to the client constructor along with config_path and verbose.

Returns:

An instantiated subclass of AbstractHowsoClient.