API reference

The tutorials explain how the objects fit together. This page documents every public class and function exposed by the package. Private methods beginning with an underscore are implementation details unless a tutorial explicitly identifies them as diagnostic tools.

Public package namespace

These objects are available directly from mistic.

mistic.IntegratedGradientsResult	Values and metadata produced by an integrated-gradients explanation.
mistic.BoundaryCounterfactualResult	Per-model decision-boundary counterfactuals for supplied samples.
mistic.combined_rank	Blend perturbation and frozen-objective feature rankings.
mistic.cvSet	Store a dataset and construct reusable validation splits.
mistic.kernelWrapper	Compute pairwise kernels and supported analytical derivatives.
mistic.paramSet	Pair estimator parameters with precomputed-kernel parameters.
mistic.perDiff	Return mean relative differences for every pair of columns.
mistic.score_ocsvm	Score a one-class SVM using sklearn's -1/+1 convention.
mistic.score_svc	Score binary SVC members by discrimination and calibration.
mistic.score_svr	Score SVR members with correlation, R-squared, and RMSE.
mistic.svmSet	Manage cross-validated SVM members and a unified prediction model.

API index

• Index

• Module Index

• Search Page

Cross-validation

Cross-validation and held-out validation split management.

class mistic.cvSet.cvSet(X, y, num_feature_medoids=20, ensemble_validation_size=0.0, ensemble_validation_random_seed=0, ensemble_validation_stratify=False)

Store a dataset and construct reusable validation splits.

The object can reserve an ensemble-level validation subset before making classification, regression, or novelty-detection splits. It also derives deterministic feature medoids used to seed forward selection.

Parameters:

• X (array-like of shape (n_samples, n_features)) – Feature matrix stored by the object.

• y (array-like of shape (n_samples,)) – Classification labels, regression targets, or one-class labels.

• num_feature_medoids (int, default=20) – Maximum number of representative features to identify.

• ensemble_validation_size (float, default=0.0) – Fraction of samples reserved from all model-development splits.

• ensemble_validation_random_seed (int, default=0) – Seed used to select the ensemble validation samples.

• ensemble_validation_stratify (bool, default=False) – Whether to preserve label proportions in the ensemble holdout.

X

Input feature matrix.

Type:

numpy.ndarray

y

Input target vector.

Type:

numpy.ndarray

train, test

Training and validation indices for each generated split.

Type:

list of numpy.ndarray

type

Kind of the currently configured splits.

Type:

{“classification”, “k-fold”, “one-class”, “independent”} or None

ensemble_validation_indices_

Indices reserved for final ensemble validation.

Type:

numpy.ndarray

development_indices_

Indices available for cross-validation and feature selection.

Type:

numpy.ndarray

feature_medoids_

Indices of representative feature columns.

Type:

numpy.ndarray

classification(num_sets=5, validation_size=0.2, random_seed=0)

Create repeated stratified holdout splits for classification.

Parameters:

• num_sets (int, default=5) – Number of train/validation pairs to generate.

• validation_size (float, default=0.2) – Fraction of each class assigned to validation in every pair.

• random_seed (int, default=0) – Seed for sampling validation indices.

Returns:

Populates train and test.

Return type:

None

independent(num_sets=5, validation_size=0.2, random_seed=0)

Partition samples into independent train/test subsets by class.

Parameters:

• num_sets (int, default=5) – Number of disjoint sample groups used to construct splits.

• validation_size (float, default=0.2) – Fraction of each group assigned to validation.

• random_seed (int, default=0) – Seed used when partitioning each class.

Returns:

Populates train and test.

Return type:

None

k_fold(num_folds=5)

Create deterministic interleaved K-fold splits.

Parameters:

num_folds (int, default=5) – Number of cross-validation folds.

Returns:

Populates train and test.

Return type:

None

one_class(num_sets=5, validation_size=0.2, random_seed=0, inlier_label=1)

Create repeated novelty-detection splits with inlier-only training.

Labels must use sklearn’s convention: +1 for inliers and -1 for known outliers. Each test split contains held-out inliers and all development-set outliers; outliers are never included in training.

Parameters:

• num_sets (int, default=5) – Number of repeated splits.

• validation_size (float, default=0.2) – Fraction of inliers held out in each split.

• random_seed (int, default=0) – Seed used to select held-out inliers.

• inlier_label (int, default=1) – Required inlier label; retained for explicit validation.

Returns:

Populates train and test.

Return type:

None

SVM ensembles

SVM ensemble training, feature selection, prediction, and explanation.

class mistic.svmSet.svmSet(SVM, cvSet, score_method, kernel=None, separate_feature_sets=False, separate_parameters=False, perturbation_sets=None, perturbation_normalization='per_feature')

Manage cross-validated SVM members and a unified prediction model.

Parameters:

• SVM (sklearn.svm.SVC, sklearn.svm.SVR, or sklearn.svm.OneClassSVM) – Prototype estimator copied once per cross-validation split.

• cvSet (mistic.cvSet.cvSet) – Dataset and reusable training/validation splits.

• score_method (callable) – Callable accepting (svm_set, model_index) and returning a metric mapping containing an aggregate score.

• kernel (mistic.utility.kernelWrapper or None, default=None) – Pairwise-kernel implementation. The default is an RBF wrapper.

• separate_feature_sets (bool, default=False) – Whether each cross-validation member maintains its own features.

• separate_parameters (bool, default=False) – Whether each member selects its own model and kernel parameters.

• perturbation_sets (sequence of sequences of int or None, default=None) – Feature groups added, removed, and perturbed as indivisible units.

• perturbation_normalization ({"per_feature", "sqrt", "none"}, default="per_feature") – Group-size normalization applied to importance and decision perturbations before ranking.

SVM

Estimator prototype supplied at construction.

Type:

sklearn estimator

cv

Dataset and split manager.

Type:

mistic.cvSet.cvSet

models

Fitted cross-validation member estimators.

Type:

list

features

Active feature indices, shared or stored per member.

Type:

numpy.ndarray or list of numpy.ndarray

unified_features

Union of active features across all members.

Type:

numpy.ndarray

parameters_

Selected estimator and kernel parameters after tuning.

Type:

mistic.utility.paramSet or list of paramSet

performance_

Aggregate or member-level validation metrics.

Type:

mistic.utility.dotdict or list of dotdict

feature_rank

Feature ranks produced during feature selection.

Type:

numpy.ndarray

unified_model_

Final estimator trained on the unified feature subset.

Type:

sklearn estimator or None

unified_prediction_features_

Features used by unified_model_.

Type:

numpy.ndarray or None

decision_value_cutoff_

Calibrated binary classification threshold.

Type:

float

perturbation_sets

Normalized feature groups used by selection and explanation methods.

Type:

list of list of int

perturbation_normalization

Divisor applied to grouped perturbation measures.

Type:

{“per_feature”, “sqrt”, “none”}

calibrate_decision_value_cutoff()

Calibrate the binary svmSet cutoff on CV development data.

The decision value for each sample is averaged across all fitted SVMs, exactly as it is during aggregate predict() inference. The resulting cutoff therefore corrects a shift introduced by averaging the fold models’ decision values. Any reserved ensemble-validation samples are excluded from this calibration.

Returns:

The F1-optimal cutoff, also stored in decision_value_cutoff_.

Return type:

float

decision_function(X, model_index=None, prediction_mode='unified')

Return unified decision values, or member-set values on request.

Parameters:

• X (numpy.ndarray of shape (n_samples, n_features)) – Observations to evaluate.

• model_index (int or None, default=None) – Specific member to use, or None for aggregate inference.

• prediction_mode ({"unified", "set"}, default="unified") – Select the final unified estimator or cross-validation members.

Returns:

Continuous decision values or regression outputs.

Return type:

numpy.ndarray

decision_gradient_(model_index, X)

Evaluate analytical decision gradients for input samples.

Parameters:

• model_index (int) – Index of the fitted ensemble member.

• X (numpy.ndarray of shape (n_samples, n_features)) – Observations at which gradients are evaluated.

Returns:

Gradient for each sample and active model feature.

Return type:

numpy.ndarray

decision_perturbation_(model_index, X)

Estimate grouped-feature changes in the decision function.

Parameters:

• model_index (int) – Index of the fitted ensemble member.

• X (numpy.ndarray of shape (n_samples, n_features)) – Observations at which perturbations are evaluated.

Returns:

Decision change for each sample and active perturbation group, or inactive group during forward selection.

Return type:

numpy.ndarray

enrichment_score(metric='score', type='auc')

Summarize a feature-selection curve by normalized area or maximum.

Parameters:

• metric (str, default="score") – Performance key read from each feature-selection result.

• type ({"auc", "max"}, default="auc") – Summary statistic: normalized curve area or maximum value.

Returns:

Requested feature-selection enrichment summary.

Return type:

float

ensemble_stochastic_feature_selection(parameter_grid, n_iterations=100, temperature=0.05, cooling_rate=0.97, add_probability=0.5, random_seed=None, convergence_patience=20, convergence_min_delta=0.0, preserve_feature_count=False, feature_diversity_weight=0.0, prediction_diversity_weight=0.0, performance_tolerance=None, max_feature_similarity=None)

Refine features using one global pool of ensemble perturbations.

Unlike stochastic_feature_selection(), this method does not rank candidates within each model. It constructs every feasible (model, operation, perturbation group) candidate and estimates its effect on one aggregate out-of-fold ensemble prediction. One candidate is sampled from this global ranking and fully tuned per iteration.

Candidate effects use the fitted model’s decision perturbation, so scoring the complete pool does not require refitting every candidate. Acceptance uses the actual out-of-fold ensemble score after tuning the selected proposal. The best accepted state is restored on return. When preserve_feature_count is true, the global pool instead contains matched remove/add swaps within each model. Only perturbation groups of equal size are paired, so every model retains its initial feature count throughout the search.

Diversity can be rewarded through mean pairwise feature-set Jaccard distance and mean pairwise out-of-fold decision-value decorrelation. performance_tolerance limits the score loss relative to the best score seen, while max_feature_similarity can reject candidates whose pairwise feature Jaccard similarity is too high.

Parameters:

• parameter_grid (iterable of mistic.utility.paramSet) – Parameter candidates used to retune each accepted proposal.

• n_iterations (int, default=100) – Maximum number of pooled proposals.

• temperature (float, default=0.05) – Initial simulated-annealing temperature.

• cooling_rate (float, default=0.97) – Multiplicative temperature decay per iteration.

• add_probability (float, default=0.5) – Probability of selecting additions when both directions exist.

• random_seed (int or None, default=None) – Seed controlling proposal sampling and acceptance.

• convergence_patience (int or None, default=20) – Non-improving proposals allowed before early stopping.

• convergence_min_delta (float, default=0.0) – Minimum objective gain counted as improvement.

• preserve_feature_count (bool, default=False) – Restrict proposals to equal-sized feature-group swaps.

• feature_diversity_weight (float, default=0.0) – Reward assigned to mean pairwise feature-set distance.

• prediction_diversity_weight (float, default=0.0) – Reward assigned to prediction decorrelation.

• performance_tolerance (float or None, default=None) – Maximum score loss allowed relative to the best observed score.

• max_feature_similarity (float or None, default=None) – Maximum permitted pairwise feature-set Jaccard similarity.

Returns:

The refined ensemble (self).

Return type:

svmSet

explain_counterfactuals(X, feature_names=None, target=None, model_index=None)

Find local decision-boundary counterfactuals for observations.

One boundary point is optimized for every requested ensemble member and sample. These are unconstrained local boundary references used by MISTIC’s default classification integrated gradients; they are not guaranteed feasible, causal, or actionable recourse.

Parameters:

• X (numpy.ndarray of shape (n_samples, n_features)) – Observations from which boundary searches begin.

• feature_names (sequence of str or None, default=None) – Names for all input columns.

• target (array-like or None, default=None) – Optional labels retained for plotting and exported metadata.

• model_index (int or None, default=None) – Member to explain, or None to find points for every member.

Returns:

Per-model boundary points, changes, distances, and diagnostics.

Return type:

mistic.explanations.BoundaryCounterfactualResult

explain_integrated_gradients(X, feature_names=None, target=None, model_index=None, num_steps=20, reference_point=None, ref_point=None, output='decision')

Return integrated gradients together with plotting metadata.

Parameters:

• X (numpy.ndarray of shape (n_samples, n_features)) – Observations to explain.

• feature_names (sequence of str or None, default=None) – Names for all input columns or only selected columns.

• target (array-like or None, default=None) – Optional sample labels or targets stored for visualization.

• model_index (int or None, default=None) – Member to explain, or None to average all members.

• num_steps (int, default=20) – Number of points sampled along each integration path.

• reference_point (array-like or None, default=None) – Shared baseline vector or one baseline per observation.

• ref_point (array-like or None, default=None) – Deprecated alias for reference_point.

• output ({"decision", "probability"}, default="decision") – Model output whose gradient is integrated.

Returns:

Immutable attributions and visualization metadata.

Return type:

mistic.explanations.IntegratedGradientsResult

feature_importance_(model_index)

Measure the effect of removing one or more feature groups.

Parameters:

model_index (int) – Index of the fitted cross-validation model to analyze.

Returns:

Frozen-objective criterion for each active group, or each inactive group during forward selection.

Return type:

numpy.ndarray

Notes

Perturbation groups are read from self.perturbation_sets. Groups are intersected with the model’s active features, and groups with no active members are ignored.

find_knee(metric='score')

Return the feature count at the knee of a performance curve.

The curve is sorted by feature count and normalized to the unit square. The knee is the interior point with the greatest vertical distance above the diagonal, corresponding to the point after which adding features produces diminishing gains in metric.

Parameters:

metric (str, default="score") – Higher-is-better performance value stored in each row of feature_performance_.

Returns:

Number of features at the knee. The value is also stored in knee_num_features_.

Return type:

int or float

fit_unified_model(parameter_grid)

Tune and fit one SVM on the knee-ranked unified feature subset.

Candidate parameters are evaluated with the existing cvSet splits. The winning model is then fitted once on all labeled samples supplied to the cvSet. Member models remain unchanged and are still available through prediction_mode='set' or model_index.

Parameters:

parameter_grid (iterable of mistic.utility.paramSet) – Candidate estimator and kernel parameter combinations.

Returns:

This fitted instance.

Return type:

svmSet

greedy_backward_selection(parameter_grid, reduction_factor=0.1, feature_ranker=None, set_for_rank='train', tune_models_each_step=True, post_find_knee=True)

Rank and remove feature sets using greedy backward selection.

When tune_models_each_step is false, tuning is performed only for the initial full-feature model. Its selected parameters are retained, while gamma, when present, is scaled at each later step as initial_gamma * initial_feature_count / current_feature_count. Kernels without a gamma parameter retain their tuned parameters. Once the best feature subset has been selected, that subset is retuned with the full parameter grid so the returned model is not left at the search-time scaled parameters. When post_find_knee is true, the completed performance curve is used to select the knee feature count before this final retuning pass. If the curve has no detectable knee, the best-scoring subset is retained.

Parameters:

• parameter_grid (iterable of mistic.utility.paramSet) – Parameter candidates used during tuning.

• reduction_factor (float, default=0.1) – Fraction of active groups removed per iteration; zero removes one.

• feature_ranker (callable) – Callable returning removal ranks for a fitted member.

• set_for_rank (str, default="train") – CV index collection used by feature_ranker.

• tune_models_each_step (bool, default=True) – Whether to run full parameter tuning after every removal.

• post_find_knee (bool, default=True) – Whether to retain and retune the performance-curve knee.

Returns:

Stores feature rankings, performance history, and fitted models.

Return type:

None

greedy_forward_selection(parameter_grid, addition_factor=0.1, feature_ranker=None, set_for_rank='train', tune_models_each_step=True, max_features=None, post_find_knee=True)

Rank and add feature sets using greedy forward selection.

Every perturbation set is fitted by itself in the first round and the best singleton is retained. Later rounds use the same perturbation ranker as backward selection, but perturb inactive sets by adding them; consequently forward decision perturbations have the opposite sign. When max_features is supplied, the greedy search stops at that many active feature columns. Unselected features tie for the final rank, and a full-feature model is still evaluated for comparison but is not eligible to replace the best capped model. When tune_models_each_step is false, search-time gamma scaling is used after the initial tuning pass and the selected best subset is retuned once with the full parameter grid before returning. When post_find_knee is true, the completed performance curve is used to select the knee feature count before that final retuning pass. If the curve has no detectable knee, the best-scoring subset is retained. addition_factor controls the fraction of currently inactive perturbation sets added per iteration. A value of zero adds exactly one set at a time.

Parameters:

• parameter_grid (iterable of mistic.utility.paramSet) – Parameter candidates used during tuning.

• addition_factor (float, default=0.1) – Fraction of inactive groups added per iteration; zero adds one.

• feature_ranker (callable) – Callable returning addition ranks for a fitted member.

• set_for_rank (str, default="train") – CV index collection used by feature_ranker.

• tune_models_each_step (bool, default=True) – Whether to run full parameter tuning after every addition.

• max_features (int or None, default=None) – Maximum active feature count eligible for the selected model.

• post_find_knee (bool, default=True) – Whether to retain and retune the performance-curve knee.

Returns:

Stores feature rankings, performance history, and fitted models.

Return type:

None

integrated_gradient(X, model_index=None, num_steps=20, reference_point=None, ref_point=None, output='decision')

Calculate integrated gradients from supplied or inferred references.

When model_index is omitted, the result is the mean attribution across all models. For separate feature sets, its columns correspond to the sorted union of the models’ feature indices; a model contributes zero for every feature it does not use.

Set output='probability' to explain the calibrated positive-class probability of a binary SVC(probability=True). The default output='decision' retains decision-function (or SVR prediction) attributions.

reference_point may be one feature vector shared by every sample, or an array with one reference vector per row of X. Supplying it bypasses decision-boundary optimization entirely. ref_point is retained as a backward-compatible alias.

Parameters:

• X (numpy.ndarray of shape (n_samples, n_features)) – Observations to explain.

• model_index (int or None, default=None) – Member to explain, or None to average all members.

• num_steps (int, default=20) – Number of points sampled along each integration path.

• reference_point (array-like or None, default=None) – Shared baseline vector or one baseline per observation.

• ref_point (array-like or None, default=None) – Deprecated alias for reference_point.

• output ({"decision", "probability"}, default="decision") – Model output whose gradient is integrated.

Returns:

Attribution matrix with one row per sample and one column per selected feature.

Return type:

numpy.ndarray

mean_performance()

Return performance averaged across cross-validation models.

When performance_ is a list of per-model mappings, numeric scalar values are averaged across all models. Non-numeric values are retained only when they are identical in every model. If performance_ is already an aggregate mapping, a copy is returned unchanged.

Returns:

Aggregate performance values with attribute-style access.

Return type:

mistic.utility.dotdict

Raises:

• RuntimeError – If models have not been scored yet.

• TypeError – If performance_ is neither a mapping nor a non-empty sequence of mappings.

plot_performance(metric='score')

Plot a selection metric against the retained feature count.

Parameters:

metric (str, default="score") – Key in each feature_performance_ row to plot.

Returns:

Adds a line to the current Matplotlib axes.

Return type:

None

predict(X, model_index=None, use_voting=False, prediction_mode='unified')

Predict with the unified model by default.

Pass prediction_mode='set' to average member outputs as in older releases. Supplying model_index continues to select one member; use_voting=True likewise implies set-based classification.

Parameters:

• X (numpy.ndarray of shape (n_samples, n_features)) – Observations to predict.

• model_index (int or None, default=None) – Specific member to use, or None for aggregate prediction.

• use_voting (bool, default=False) – Use majority voting rather than averaged decision values for classification member sets.

• prediction_mode ({"unified", "set"}, default="unified") – Select the final unified estimator or cross-validation members.

Returns:

Predicted classes or regression values.

Return type:

numpy.ndarray

predict_proba(X, model_index=None, prediction_mode='unified')

Return SVC class probabilities from the unified model or member set.

Set-based probabilities are the arithmetic mean of member-model probabilities, with columns ordered according to classes_.

Parameters:

• X (numpy.ndarray of shape (n_samples, n_features)) – Observations for which probabilities are requested.

• model_index (int or None, default=None) – Specific member to use, or None for aggregate prediction.

• prediction_mode ({"unified", "set"}, default="unified") – Select the final unified estimator or cross-validation members.

Returns:

Class-probability matrix ordered by the estimator’s classes_.

Return type:

numpy.ndarray

probability_gradient_(model_index, X)

Return gradients of binary SVC positive-class probability.

Parameters:

• model_index (int) – Index of a fitted probability-enabled binary SVC member.

• X (numpy.ndarray of shape (n_samples, n_features)) – Observations at which gradients are evaluated.

Returns:

Positive-class probability gradient for each sample and active feature.

Return type:

numpy.ndarray

probability_perturbation_(model_index, X)

Approximate feature effects on calibrated positive probability.

The SVC Platt curve is differentiated at each sample and multiplied by the exact frozen-model decision perturbation. Returned columns correspond to the same perturbation sets as decision_perturbation_().

Parameters:

• model_index (int) – Index of the fitted binary SVC member.

• X (numpy.ndarray of shape (n_samples, n_features)) – Observations at which effects are evaluated.

Returns:

Approximate probability change for each sample and perturbation group.

Return type:

numpy.ndarray

set_num_features(num_features, parameter_grid)

Use the top-ranked features and retune the ensemble.

This method is intended for use after a feature-selection method has populated sorted_features. For ensembles with separate feature sets, each model uses the top features from its own ranking.

Parameters:

• num_features (int) – Number of highest-ranked features to retain.

• parameter_grid (iterable) – Parameter candidates accepted by tune_models().

Returns:

Replaces the active feature set and retunes the ensemble.

Return type:

None

stochastic_feature_selection(parameter_grid, n_iterations=100, feature_ranker=None, set_for_rank='train', temperature=0.05, cooling_rate=0.97, add_probability=0.5, random_seed=None, update_all_models=False, use_ensemble_validation=False, expected_changes_per_model=1.0, preserve_feature_count=False, convergence_patience=20, convergence_min_delta=0.0)

Refine the current feature set with rank-guided stochastic moves.

Each iteration proposes adding or removing one complete perturbation set. Candidate probabilities are biased by feature_ranker in the same direction as the greedy searches: highly ranked inactive sets are preferred for addition and low-ranked active sets for removal. Improving moves are always accepted; other moves are accepted with a simulated-annealing probability.

The search starts from the current fitted feature set, so it is most useful after greedy_forward_selection() or greedy_backward_selection(). With separate feature sets, a move changes one model’s set; otherwise it changes the ensemble-wide set. Every proposal is tuned using parameter_grid. The best accepted state, rather than merely the last state, is restored on return. If update_all_models is true for an ensemble with separate feature sets, every model proposes one independently ranked add/remove move per iteration. Those moves form one joint proposal and are accepted or rejected together according to the average cross-validation score. expected_changes_per_model controls how many perturbation groups use the chosen add/remove operation for each selected model. The count is sampled as 1 + Poisson(expected_changes_per_model - 1) and capped by the number of feasible groups, so every eligible selected model changes at least once. The default of one preserves single-group proposals exactly. When preserve_feature_count is true, each model instead proposes one removal and one addition of equally sized perturbation groups. Separate-feature-set ensembles update every model in this mode, and the complete collection of swaps is accepted or rejected jointly. If use_ensemble_validation is true, acceptance and best-state tracking instead use the mean model score on the holdout reserved by cvSet; parameter tuning still uses the ordinary CV folds. The search converges early after convergence_patience consecutive proposals fail to improve the best accepted objective by more than convergence_min_delta. Set patience to None to always run the requested number of iterations.

Search diagnostics are stored in stochastic_performance_. Each row records the iteration, operation, model index, proposed group, score, acceptance, temperature, and resulting feature membership.

Parameters:

• parameter_grid (iterable of mistic.utility.paramSet) – Parameter candidates used to retune each proposal.

• n_iterations (int, default=100) – Maximum number of proposed feature moves.

• feature_ranker (callable) – Callable returning group ranks for a model and ranking subset.

• set_for_rank (str, default="train") – Name of the CV index collection used by feature_ranker.

• temperature (float, default=0.05) – Initial simulated-annealing temperature.

• cooling_rate (float, default=0.97) – Multiplicative temperature decay per iteration.

• add_probability (float, default=0.5) – Probability of proposing additions when both directions are valid.

• random_seed (int or None, default=None) – Seed controlling proposal selection and acceptance.

• update_all_models (bool, default=False) – Whether separate-feature members propose joint moves.

• use_ensemble_validation (bool, default=False) – Score moves on the reserved ensemble holdout.

• expected_changes_per_model (float, default=1.0) – Expected number of groups changed by an eligible model.

• preserve_feature_count (bool, default=False) – Replace groups through equal-sized swaps instead of adding/removing.

• convergence_patience (int or None, default=20) – Non-improving proposals allowed before stopping early.

• convergence_min_delta (float, default=0.0) – Minimum objective gain counted as an improvement.

Returns:

The refined ensemble (self).

Return type:

svmSet

tune_models(parameter_grid)

Select the best estimator and kernel parameters from a grid.

Parameters:

parameter_grid (iterable of mistic.utility.paramSet) – Candidate estimator and kernel parameter combinations.

Returns:

Stores the winning members, parameters, performance, and unified predictor on the instance.

Return type:

None

Explanation results

Integrated-gradient results and visualizations.

class mistic.explanations.BoundaryCounterfactualResult(values: ndarray, inputs: ndarray, feature_names: tuple, model_indices: tuple, decision_values: ndarray, optimization_success: ndarray, target: ndarray | None = None)

Per-model decision-boundary counterfactuals for supplied samples.

values has shape (n_models, n_samples, n_features). These points are local boundary references, not constrained or causal recourse.

property deltas

Return counterfactual minus observed feature values.

property distances

Return Euclidean input-to-boundary distance per model and sample.

sample_plot(sample_index, ax=None, model_index=None, max_features=10, original_kwargs=None, counterfactual_kwargs=None, line_kwargs=None)

Compare one observation with its boundary counterfactual.

summary_plot(ax=None, model_index=None, max_features=20, bar_kwargs=None)

Plot mean absolute movement needed to reach the boundary.

to_frame(model_index=None)

Return counterfactual values for one member or the member mean.

class mistic.explanations.IntegratedGradientsResult(values: ndarray, inputs: ndarray, feature_indices: ndarray, feature_names: tuple, reference_points: ndarray | None, model_indices: tuple, num_steps: int, target: ndarray | None = None, counterfactuals: BoundaryCounterfactualResult | None = None)

Values and metadata produced by an integrated-gradients explanation.

Plot methods accept an existing Matplotlib ax and return the primary axes. Any additional Matplotlib keyword arguments can be supplied through scatter_kwargs or imshow_kwargs and the returned artists remain fully editable.

values

Integrated-gradient attribution assigned to each input value.

Type:

numpy.ndarray of shape (n_samples, n_features)

inputs

Input values corresponding to the attribution matrix.

Type:

numpy.ndarray of shape (n_samples, n_features)

feature_indices

Column indices in the original model input.

Type:

numpy.ndarray of shape (n_features,)

feature_names

Display names corresponding to the attribution columns.

Type:

tuple of str

reference_points

Baseline points used by the integration paths. Inferred member-specific boundary references have shape (n_models, n_samples, n_features); explicitly supplied references have shape (n_samples, n_features).

Type:

numpy.ndarray or None

model_indices

Ensemble members included in the explanation.

Type:

tuple of int

num_steps

Number of numerical integration steps.

Type:

int

target

Optional class labels or regression targets for sample annotation.

Type:

numpy.ndarray or None

counterfactuals

Boundary explanation reused by classification IG when no explicit reference was supplied.

Type:

BoundaryCounterfactualResult or None

heatmap(ax=None, target=None, cmap='coolwarm', center=0.0, cluster=False, imshow_kwargs=None, target_cmap=None, attribution_colorbar_kwargs=None, target_colorbar_kwargs=None, target_strip_width=0.1, strip_pad=0.04, colorbar_width=0.16, colorbar_pad=0.08, colorbar_gap=0.06, dendrogram_width=0.75, dendrogram_pad=0.04, dendrogram_linewidth=0.8, dendrogram_kwargs=None)

Draw an attribution heatmap with a class/target annotation bar.

cluster=True hierarchically orders samples and displays their row dendrogram. With cluster=False, samples are sorted by the supplied or stored target (and retain input order when no target is available). In both modes, features are sorted from greatest to least mean absolute attribution. Discrete targets receive a categorical colorbar; continuous values receive a continuous one. The strip widths and gaps are measured in inches, so their spacing is independent of figure size. The two *_colorbar_kwargs mappings are passed to matplotlib.figure.Figure.colorbar().

Parameters:

• ax (matplotlib.axes.Axes or None, default=None) – Main heatmap axes, created automatically when omitted.

• target (array-like or None, default=None) – Sample annotation overriding target.

• cmap (str or matplotlib.colors.Colormap) – Attribution and target-strip colormaps, respectively.

• target_cmap (str or matplotlib.colors.Colormap) – Attribution and target-strip colormaps, respectively.

• center (float, default=0.0) – Center of the symmetric attribution color scale.

• cluster (bool, default=False) – Whether to cluster samples hierarchically.

• imshow_kwargs (dict or None, default=None) – Extra keyword arguments passed to Axes.imshow.

• attribution_colorbar_kwargs (dict or None) – Extra keyword arguments for the two colorbars.

• target_colorbar_kwargs (dict or None) – Extra keyword arguments for the two colorbars.

• target_strip_width (float) – Fixed layout dimensions in inches.

• strip_pad (float) – Fixed layout dimensions in inches.

• colorbar_width (float) – Fixed layout dimensions in inches.

• colorbar_pad (float) – Fixed layout dimensions in inches.

• colorbar_gap (float) – Fixed layout dimensions in inches.

• dendrogram_width (float) – Dendrogram layout dimensions and line width.

• dendrogram_pad (float) – Dendrogram layout dimensions and line width.

• dendrogram_linewidth (float) – Dendrogram layout dimensions and line width.

• dendrogram_kwargs (dict or None, default=None) – Extra keyword arguments passed to SciPy’s dendrogram.

Returns:

Main axes containing the attribution heatmap.

Return type:

matplotlib.axes.Axes

property importance

Mean absolute attribution for each feature.

Returns:

Mean absolute attribution for every feature column.

Return type:

numpy.ndarray

interaction_plot(feature=None, interaction_feature=None, ax=None, cmap='viridis', scatter_kwargs=None)

Plot attribution dependence for a specified or automatic pair.

Parameters:

• feature (str, int, or None, default=None) – Feature shown on the horizontal axis; selected automatically when omitted.

• interaction_feature (str, int, or None, default=None) – Feature mapped to point color; selected automatically when omitted.

• ax (matplotlib.axes.Axes or None, default=None) – Axes to draw on; a new axes is created when omitted.

• cmap (str or matplotlib.colors.Colormap, default="viridis") – Colormap used for the interaction feature.

• scatter_kwargs (dict or None, default=None) – Additional keyword arguments passed to Axes.scatter.

Returns:

Axes containing the dependence plot.

Return type:

matplotlib.axes.Axes

interaction_scores()

Return a symmetric matrix of heuristic pairwise interaction scores.

Each attribution is linearly residualized against its own feature value. Absolute residual/other-feature correlations are then averaged in both directions. This is intended to nominate plots, not to provide a statistical interaction test.

Returns:

Symmetric feature-by-feature interaction score matrix.

Return type:

pandas.DataFrame

summary_plot(ax=None, max_features=None, jitter=0.22, cmap='coolwarm', random_state=0, scatter_kwargs=None)

Draw an attribution summary (beeswarm-style) plot.

Parameters:

• ax (matplotlib.axes.Axes or None, default=None) – Axes to draw on; a new axes is created when omitted.

• max_features (int or None, default=None) – Maximum number of highest-importance features to show.

• jitter (float, default=0.22) – Maximum vertical jitter applied to each sample point.

• cmap (str or matplotlib.colors.Colormap, default="coolwarm") – Colormap used for feature values.

• random_state (int, default=0) – Seed controlling deterministic point jitter.

• scatter_kwargs (dict or None, default=None) – Additional keyword arguments passed to Axes.scatter.

Returns:

Axes containing the summary plot.

Return type:

matplotlib.axes.Axes

to_frame()

Return attributions as a labeled DataFrame.

Returns:

Attribution matrix with feature names as columns.

Return type:

pandas.DataFrame

Utilities

Ranking, scoring, kernel, and numerical utility classes for MISTIC.

class mistic.utility.combined_rank(weight=0.75, number_samples=100, random_seed=0)

Blend perturbation and frozen-objective feature rankings.

Parameters:

• weight (float, default=0.75) – Weight assigned to the perturbation ranking.

• number_samples (int, default=100) – Number of synthetic samples used when set_for_rank="sample".

• random_seed (int, default=0) – Seed used to generate synthetic samples.

weight

Perturbation-ranking weight; feature importance receives 1-weight.

Type:

float

number_samples

Number of samples generated for synthetic ranking.

Type:

int

random_seed

Random seed for synthetic ranking data.

Type:

int

compute(svmSet, model_index, set_for_rank)

Return consensus ranks for one fitted ensemble member.

Parameters:

• svmSet (mistic.svmSet.svmSet) – Fitted ensemble whose features are ranked.

• model_index (int) – Index of the ensemble member to inspect.

• set_for_rank (str) – "sample" for synthetic observations, otherwise the name of a cross-validation index collection such as "train".

Returns:

Zero-based consensus rank for each feature.

Return type:

numpy.ndarray

class mistic.utility.dotdict

Dictionary supporting attribute-style key access.

keys

Dictionary keys are exposed dynamically as attributes.

Type:

object

class mistic.utility.kernelWrapper(type='rbf')

Compute pairwise kernels and supported analytical derivatives.

Parameters:

type (str, default="rbf") – Pairwise-kernel metric name.

type

Kernel metric passed to scikit-learn.

Type:

str

compute(X, feature_index, parameters=None, Y=None)

Compute a kernel matrix over the selected feature columns.

Parameters:

• X (numpy.ndarray of shape (n_samples_x, n_features)) – Left-hand input matrix.

• feature_index (array-like of int) – Feature columns included in the kernel.

• parameters (dict or None, default=None) – Keyword parameters passed to pairwise_kernels.

• Y (numpy.ndarray or None, default=None) – Optional right-hand input matrix. An empty value computes the symmetric kernel of X.

Returns:

Pairwise kernel matrix.

Return type:

numpy.ndarray

compute_gradient(X, feature_index, wrt, parameters, Y=None)

Differentiate a supported kernel with respect to one feature.

Parameters:

• X (numpy.ndarray) – Left-hand input matrix.

• feature_index (array-like of int) – Feature columns included in the kernel.

• wrt (int) – Original feature column with respect to which to differentiate.

• parameters (dict) – Kernel parameters, including gamma or degree as required.

• Y (numpy.ndarray or None, default=None) – Right-hand input matrix.

Returns:

Kernel derivative matrix with one row per X sample and one column per Y sample.

Return type:

numpy.ndarray

class mistic.utility.paramSet(model, kernel)

Pair estimator parameters with precomputed-kernel parameters.

Parameters:

• model (mapping) – Parameters passed to the scikit-learn SVM estimator.

• kernel (mapping) – Parameters passed to the pairwise-kernel computation.

model

Estimator parameter mapping.

Type:

mapping

kernel

Kernel parameter mapping.

Type:

mapping

mistic.utility.perDiff(dat)

Return mean relative differences for every pair of columns.

Pairs are evaluated in SciPy condensed-matrix order and in bounded chunks, avoiding both pandas row-wise callbacks and an unbounded n_rows x n_columns x n_columns temporary.

Parameters:

dat (array-like or pandas.DataFrame of shape (n_rows, n_columns)) – Numeric observations whose column pairs are compared.

Returns:

Mean relative difference for each column pair in SciPy condensed- matrix order.

Return type:

numpy.ndarray

mistic.utility.rank_items(score, descending=False)

Convert numeric scores into zero-based ordinal ranks.

Parameters:

• score (array-like) – Numeric values to rank.

• descending (bool, default=False) – Rank the greatest value first when true.

Returns:

Zero-based rank at each original input position.

Return type:

numpy.ndarray

class mistic.utility.score_ocsvm(weight=0.5)

Score a one-class SVM using sklearn’s -1/+1 convention.

With labeled inliers and outliers, score combines ROC AUC and inlier F1 in the same way score_svc does. A validation set containing only inliers is scored by the fraction retained inside the boundary.

Parameters:

weight (float, default=0.5) – AUC weight in the aggregate score; F1 receives 1-weight.

weight

AUC contribution to aggregate validation performance.

Type:

float

score(svmSet, model_index)

Return inlier rate, F1, AUC, and aggregate score for one member.

Parameters:

• svmSet (mistic.svmSet.svmSet) – Fitted one-class ensemble containing validation data.

• model_index (int) – Index of the ensemble member to score.

Returns:

Inlier rate, F1, AUC, and aggregate score. AUC is NaN when the validation subset contains inliers only.

Return type:

dict

class mistic.utility.score_svc(weight=0.5, calibration_weight=0.2)

Score binary SVC members by discrimination and calibration.

Parameters:

• weight (float, default=0.5) – AUC weight within the discrimination score; F1 receives 1-weight.

• calibration_weight (float, default=0.2) – Weight assigned to calibrated probability performance.

weight

AUC contribution to discrimination performance.

Type:

float

calibration_weight

Calibration contribution to aggregate performance.

Type:

float

score(svmSet, model_index)

Return F1, AUC, Brier loss, and aggregate score for one member.

Parameters:

• svmSet (mistic.svmSet.svmSet) – Fitted ensemble containing the member and validation data.

• model_index (int) – Index of the member to score.

Returns:

f1, auc, brier, calibration, and aggregate score values. Calibration entries are NaN when probability estimates are unavailable.

Return type:

dict

class mistic.utility.score_svr(weight=0.5)

Score SVR members with correlation, R-squared, and RMSE.

Parameters:

weight (float, default=0.5) – Squared-Pearson-correlation weight; nonnegative R-squared receives the remaining weight.

weight

Correlation contribution to the aggregate score.

Type:

float

score(svmSet, model_index)

Return RMSE, squared Pearson correlation, R-squared, and score.

Parameters:

• svmSet (mistic.svmSet.svmSet) – Fitted regression ensemble containing validation data.

• model_index (int) – Index of the ensemble member to score.

Returns:

rmse, squared pearson correlation, r2, and aggregate score values.

Return type:

dict

mistic.utility.svc_dec2(x, svmSet, model_index, n_to_opt=None, xref=None)

Return a squared decision value for boundary-point optimization.

Parameters:

• x (array-like) – Complete candidate point, or values for the optimized columns.

• svmSet (mistic.svmSet.svmSet) – Fitted ensemble used to evaluate the decision function.

• model_index (int) – Index of the ensemble member to evaluate.

• n_to_opt (array-like of int or None, default=None) – Columns replaced in xref by x. If omitted, x is treated as the complete point.

• xref (numpy.ndarray or None, default=None) – Reference point modified when only selected columns are optimized.

Returns:

Squared decision-function value for the candidate point.

Return type:

numpy.ndarray