MAMUT API

The main public API is Mamut. Import it with from mamut import Mamut to fit candidate models, select the best pipeline, generate predictions, create reports, and save model artifacts.

The public prediction surface is best_model_, predict, and predict_proba. Internal fitted estimators are also exposed for inspection through attributes such as raw_fitted_models_ and validation_summary_, but these are primarily diagnostics for reports and model comparison.

Mamut

class mamut.wrapper.Mamut(preprocess=True, imb_threshold=0.1, exclude_models=None, include_models=None, score_metric='f1', search_profile='balanced', optimization_method='bayes', n_iterations=30, random_state=42, n_jobs=1, selection_strategy='single_split', selection_cv_splits=5, selection_cv_repeats=2, selection_practical_margin=0.005, preprocessing_profile='auto', validation_size=0.2, holdout_size=None, save_models=False, models_output_dir='fitted_models', refit_final_model=False, verbose=False, evidence_cv_splits=5, evidence_cv_repeats=3, evidence_confidence_level=0.95, evidence_practical_margin=0.01, **preprocessor_kwargs)[source]

Bases: object

A class used to manage the machine learning pipeline, including preprocessing, model selection, and evaluation.

preprocess

Whether to apply preprocessing to the data.

Type:: bool

imb_threshold

Threshold for detecting imbalanced data.

Type:: float

exclude_models

List of models to exclude from selection.

Type:: Optional[List[str]]

score_metric

Metric used to evaluate model performance.

Type:: callable

optimization_method

Method for hyperparameter optimization.

Type:: Literal[“random_search”, “bayes”]

n_iterations

Number of iterations for optimization.

Type:: Optional[int]

random_state

Random state for reproducibility.

Type:: Optional[int]

preprocessor

Preprocessor object for data preprocessing.

Type:: Preprocessor

le

Label encoder for target variable.

Type:: LabelEncoder

model_selector

Object for model selection.

Type:: ModelSelector

X

Input features.

Type:: pd.DataFrame

y

Target variable.

Type:: pd.Series

X_train

Training features.

Type:: pd.DataFrame

X_validation

Validation features used for model selection.

Type:: pd.DataFrame

y_train

Training target variable.

Type:: pd.Series

y_validation

Validation target variable used for model selection.

Type:: pd.Series

X_holdout

Optional final holdout features used only for final evaluation.

Type:: Optional[pd.DataFrame]

y_holdout

Optional final holdout target used only for final evaluation.

Type:: Optional[pd.Series]

raw_fitted_models_

List of raw fitted models.

Type:: Optional[List[Pipeline]]

fitted_models_

List of fitted models with preprocessing.

Type:: Optional[List[Pipeline]]

best_model_

Best model pipeline.

Type:: Optional[Pipeline]

best_score_

Best model score.

Type:: float

training_summary_

Summary of the training process.

Type:: dict

optuna_studies_

Optuna studies for hyperparameter optimization.

Type:: dict

ensemble_

Ensemble model pipeline.

Type:: Optional[Pipeline]

greedy_ensemble_

Greedy ensemble model pipeline.

Type:: Optional[Pipeline]

ensemble_models_

List of models in the ensemble.

Type:: Optional[List[Pipeline]]

imbalanced_

Whether the data is imbalanced.

Type:: bool

fit(X: pd.DataFrame, y: pd.Series) → Pipeline[source]: Fits the model to the data.

predict(X: pd.DataFrame) → np.ndarray[source]: Predicts the target variable for the given data.

predict_proba(X: pd.DataFrame) → np.ndarray[source]: Predicts the probabilities of the target variable for the given data.

evaluate() → None[source]: Evaluates the fitted models.

save_best_model(path: str) → None[source]: Saves the best model to the specified path.

create_ensemble(voting: Literal['soft', 'hard'] = 'soft') → Pipeline[source]: Creates an ensemble of the fitted models.

create_greedy_ensemble(n_models: int = 6, voting: Literal['soft', 'hard'] = 'soft') → Pipeline[source]: Creates a greedy ensemble of the fitted models.

Common Methods

Mamut.fit(X, y, X_holdout=None, y_holdout=None, groups=None, groups_holdout=None)[source]

Fits the model to the data.

Parameters:

X (DataFrame) – The input features.
y (Series) – The target variable.
X_holdout (Optional[DataFrame]) – Optional final holdout features. If provided, y_holdout must also be provided and holdout_size must be None.
y_holdout (Optional[Series]) – Optional final holdout target. Holdout rows are never used for model or ensemble selection.
groups (Optional[Series]) – Group labels for observations that must remain in the same fold.
groups_holdout (Optional[Series]) – Group labels for explicit holdout rows. Required with groups and explicit holdout data so overlap can be rejected.

Returns:

The best model pipeline.

Return type:

Pipeline

Mamut.predict(X)[source]

Predicts the target variable for the given data.

Parameters:: X (DataFrame) – The input features.
Returns:: Predicted target variable.
Return type:: np.ndarray

Mamut.predict_proba(X)[source]

Predicts the probabilities of the target variable for the given data.

Parameters:: X (DataFrame) – The input features.
Returns:: Predicted probabilities of the target variable.
Return type:: np.ndarray

Mamut.evaluate(n_top_models=3, dataset='auto', include_evidence=True, output_dir='mamut_report', include_shap=True, shap_max_samples=200, display_plots=False, write_html=True, save_plots=True)[source]

Evaluates the fitted models.

Return type:: dict

Mamut.generate_evidence(dataset='auto', include_candidate_comparison=True)[source]

Build diagnostic evidence without changing the fitted candidate.

Parameters:

dataset (Literal['auto', 'validation', 'holdout']) – Evaluation partition to summarize.
include_candidate_comparison (bool) – Whether to score non-selected MAMUT candidates alongside fixed baselines. Disable this for a locked final confirmation analysis.

Return type:

dict

Mamut.save_best_model(path)[source]

Saves the best model to the specified path.

Parameters:: path (str) – The path to save the best model.
Return type:: None

Mamut.create_ensemble(voting='soft')[source]

Creates an ensemble of the fitted models.

Parameters:: voting (Literal['soft', 'hard']) – Voting strategy for the ensemble.
Returns:: The ensemble model pipeline.
Return type:: Pipeline

Mamut.create_greedy_ensemble(max_models=6)[source]

Model Selection

ModelSelector is used internally by mamut.wrapper.Mamut to compare supported estimators and optimize hyperparameters. Most users should configure model search through Mamut instead of instantiating ModelSelector directly.

class mamut.model_selection.ModelSelector(X_train, y_train, X_validation, y_validation, score_metric, X_train_raw=None, y_train_raw=None, X_validation_raw=None, y_validation_raw=None, groups_train_raw=None, preprocessor_factory=None, exclude_models=None, include_models=None, search_profile='balanced', optimization_method='bayes', n_iterations=50, random_state=42, n_jobs=1, verbose=False)[source]: Bases: object

Evaluation

ModelEvaluator is used internally by Mamut.evaluate to produce the HTML report and plots.

class mamut.evaluation.ModelEvaluator(models, X_evaluation, y_evaluation, X_train, y_train, X, y, optimizer, n_trials, metric, studies, training_summary, pca_loadings, binary, preprocessing_steps, is_ensemble, greedy_ensemble, X_explanation=None, feature_names=None, excluded_models=None, n_top_models=3, evaluation_dataset='validation', selected_model_name=None, rank_by_metric=True, evidence_report=None, report_output_path='mamut_report', include_shap=True, shap_max_samples=200, write_html=True, save_plots=True)[source]: Bases: object

Evidence

Evidence helpers power the validation integrity, leakage, baseline, and score stability sections of Mamut.evaluate.