mpml_lib 1.0.0__py3-none-any.whl

combination/bagging.py

@@ -0,0 +1,102 @@
+
+import pandas as pd
+from sklearn.ensemble import BaggingClassifier
+from .voting import majority_vote
+
+def train_bagging(
+    perspectives,
+    X_train,
+    y_train,
+    n_estimators=5,
+    random_state=42
+):
+    """
+    Train a bagging ensemble for each MPML perspective.
+
+    Each perspective uses its assigned feature subset.
+    BaggingClassifier automatically performs bootstrap
+    sampling and trains multiple copies of the model.
+
+    Returns:
+        trained_models: Dictionary of trained bagging ensembles.
+    """
+
+    # Dictionary to store the trained bagging models.
+    trained_models = {}
+
+    # Loop through each perspective.
+    for model_name in perspectives.get_dict():
+
+        # Get the model assigned to this perspective.
+        model = perspectives.get_model(model_name)
+
+        # Get the features assigned to this perspective.
+        feature_list = perspectives.get_features(model_name)
+
+        # Select only the features for this perspective.
+        X_perspective = X_train[feature_list]
+
+        # Create a bagging ensemble for this model.
+        bagging_model = BaggingClassifier(
+            estimator=model,
+            n_estimators=n_estimators,
+            max_samples=1.0,
+            bootstrap=True,
+            n_jobs=-1,
+            random_state=random_state
+        )
+
+        # Train the ensemble.
+        bagging_model.fit(X_perspective, y_train)
+
+        # Store the trained ensemble.
+        trained_models[model_name] = bagging_model
+
+    return trained_models
+
+def bagging_predict(perspectives, trained_models, X_instance):
+    """
+    Predict one instance using the trained bagging ensembles.
+
+    Each perspective contains a trained BaggingClassifier.
+    Each BaggingClassifier produces one final prediction.
+
+    These perspective predictions are then combined
+    using the existing majority_vote() function.
+
+    Parameters:
+        perspectives: Perspectives object containing feature lists.
+        trained_models: Dictionary of trained BaggingClassifier objects.
+        X_instance: DataFrame containing exactly one row.
+
+    Returns:
+        Final predicted class.
+    """
+
+    # Check that an instance was provided correctly.
+    if not isinstance(X_instance, pd.DataFrame):
+        raise TypeError("X_instance must be a DataFrame.")
+
+    if len(X_instance) != 1:
+        raise ValueError(
+            "X_instance must contain exactly one row."
+        )
+
+    # Make sure the bagging models have been trained.
+    if not trained_models:
+        raise ValueError(
+            "No trained bagging models were supplied."
+        )
+
+    # Reuse the existing majority voting function.
+    #
+    # Each BaggingClassifier supports predict()
+    # and predict_proba(), which are used by
+    # majority_vote() to combine model decisions.
+    prediction = majority_vote(
+        perspectives,
+        trained_models,
+        X_instance
+    )
+
+    return prediction

combination/blending.py

@@ -0,0 +1,239 @@
+
+import pandas as pd
+
+from sklearn.base import clone
+from sklearn.model_selection import train_test_split
+from sklearn.linear_model import LogisticRegression
+
+def train_blending(
+    perspectives,
+    X_train,
+    y_train,
+    meta_model=None,
+    meta_train_size=0.20,
+    random_state=42
+):
+    """
+    Train a blending ensemble independently of the MPML class.
+
+    Parameters:
+        perspectives: Perspectives object containing the models
+                      and their assigned feature lists.
+        X_train: Original training DataFrame.
+        y_train: Original target labels.
+        meta_model: Optional scikit-learn classifier.
+        meta_train_size: Fraction used for meta-model training.
+        random_state: Random seed for reproducibility.
+
+    Returns:
+        trained_models:
+            Dictionary containing the trained base models.
+
+        trained_meta_model:
+            Trained blending meta-model.
+
+        meta_feature_names:
+            Ordered column names used by the meta-model.
+
+        X_base_train:
+            Features used to train the base models.
+
+        y_base_train:
+            Target labels used to train the base models.
+    """
+
+    # 1. Validate the supplied training dataset.
+    if not isinstance(X_train, pd.DataFrame):
+        raise TypeError("X_train must be a pandas DataFrame.")
+
+    if len(X_train) != len(y_train):
+        raise ValueError("X_train and y_train must have equal lengths.")
+
+    if len(perspectives.get_dict()) == 0:
+        raise ValueError("No perspectives have been added.")
+
+    # 2. Split the original training dataset.
+    # The base models will not see the meta-training samples
+    # during their own training.
+    X_base_train, X_meta_train, y_base_train, y_meta_train = (
+        train_test_split(
+            X_train,
+            y_train,
+            test_size=meta_train_size,
+            random_state=random_state,
+            stratify=y_train
+        )
+    )
+
+    # 3. Train each base model on its assigned features.
+    trained_models = {}
+
+    for model_name in perspectives.get_dict():
+
+        model = perspectives.get_model(model_name)
+        feature_list = perspectives.get_features(model_name)
+
+        # Extract the features used by this perspective.
+        X_perspective = X_base_train[feature_list]
+
+        # Train a separate copy of the model.
+        trained_model = clone(model)
+        trained_model.fit(X_perspective, y_base_train)
+
+        # Store the trained model.
+        trained_models[model_name] = trained_model
+
+    # 4. Get the classes learned by the first model.
+    # All base models must recognize the same classes.
+    first_model = list(trained_models.values())[0]
+    classes = list(first_model.classes_)
+
+    # 5. Prepare a DataFrame for meta-model training.
+    X_meta_features = pd.DataFrame(index=X_meta_train.index)
+
+    # 6. Generate probability predictions from each base model.
+    for model_name, trained_model in trained_models.items():
+
+        feature_list = perspectives.get_features(model_name)
+
+        # Select features from the held-out meta-training data.
+        X_perspective = X_meta_train[feature_list]
+
+        # Check that the model can predict probabilities.
+        if not callable(getattr(trained_model, "predict_proba", None)):
+            raise TypeError(
+                f"{model_name} does not support predict_proba()."
+            )
+
+        # Ensure all models were trained on the same classes.
+        if set(trained_model.classes_) != set(classes):
+            raise ValueError(
+                f"{model_name} has different class labels."
+            )
+
+        # Obtain probabilities for all meta-training instances.
+        probabilities = trained_model.predict_proba(X_perspective)
+
+        # Create one meta-feature column per class.
+        for i in range(len(classes)):
+
+            class_label = classes[i]
+
+            # Find the position of this class in this model.
+            class_index = list(trained_model.classes_).index(
+                class_label
+            )
+
+            # Create a unique column name.
+            column_name = f"{model_name}_class_{i}"
+
+            # Store the probabilities for all instances.
+            # [:, class_index] means all rows, one column.
+            X_meta_features[column_name] = probabilities[
+                :, class_index
+            ]
+
+    # 7. Select the meta-model.
+    if meta_model is None:
+        meta_model = LogisticRegression(max_iter=1000)
+
+    # Clone the meta-model to avoid modifying the original.
+    trained_meta_model = clone(meta_model)
+
+    # 8. Train the meta-model on the base-model probabilities.
+    trained_meta_model.fit(X_meta_features, y_meta_train)
+
+    # 9. Save the meta-feature column order.
+    meta_feature_names = X_meta_features.columns.tolist()
+
+    # 10. Return the trained models and the original
+    # base-training subset used to train them.
+    return (
+        trained_models,
+        trained_meta_model,
+        meta_feature_names,
+        X_base_train.copy(),
+        y_base_train.copy()
+    )
+
+def blending_predict(
+    perspectives,
+    trained_models,
+    trained_meta_model,
+    meta_feature_names,
+    X_instance
+):
+    """
+    Predict one instance using the trained blending ensemble.
+
+    X_instance must be a DataFrame containing exactly one row.
+    """
+
+    # Check the input.
+    if not isinstance(X_instance, pd.DataFrame):
+        raise TypeError("X_instance must be a DataFrame.")
+
+    if len(X_instance) != 1:
+        raise ValueError("X_instance must contain exactly one row.")
+
+    if not trained_models:
+        raise ValueError("No trained base models were supplied.")
+
+    # Create a DataFrame containing the meta-model inputs.
+    X_meta_features = pd.DataFrame(index=X_instance.index)
+
+    # Get the expected class labels.
+    first_model = list(trained_models.values())[0]
+    classes = list(first_model.classes_)
+
+    # Generate class probabilities from every base model.
+    for model_name, trained_model in trained_models.items():
+
+        # Get the feature subset assigned to this perspective.
+        feature_list = perspectives.get_features(model_name)
+
+        # Select the appropriate input features.
+        X_perspective = X_instance[feature_list]
+
+        # Generate the class probabilities.
+        probabilities = trained_model.predict_proba(
+            X_perspective
+        )
+
+        # Get this model's class ordering.
+        model_classes = list(trained_model.classes_)
+
+        # Ensure class labels match.
+        if set(model_classes) != set(classes):
+            raise ValueError(
+                f"{model_name} has different class labels."
+            )
+
+        # Create the probability columns used by the meta-model.
+        for i in range(len(classes)):
+
+            class_label = classes[i]
+
+            # Find the corresponding probability column.
+            class_index = model_classes.index(class_label)
+
+            # Use the same column naming convention as training.
+            column_name = f"{model_name}_class_{i}"
+
+            # [:, class_index] selects every row and the
+            # probability column for the current class.
+            X_meta_features[column_name] = probabilities[
+                :, class_index
+            ]
+
+    # Arrange the columns in their original training order.
+    X_meta_features = X_meta_features[meta_feature_names]
+
+    # Generate the final prediction using the meta-model.
+    prediction = trained_meta_model.predict(X_meta_features)[0]
+
+    # Convert a NumPy scalar into a regular Python value.
+    if hasattr(prediction, "item"):
+        prediction = prediction.item()
+
+    return prediction

combination/boosting.py

@@ -0,0 +1,151 @@
+
+import inspect
+from collections import Counter
+
+import pandas as pd
+from sklearn.base import clone
+from sklearn.ensemble import AdaBoostClassifier
+
+from .voting import majority_vote
+
+def train_boosting(
+    perspectives,
+    X_train,
+    y_train,
+    n_estimators=50,
+    learning_rate=1.0,
+    random_state=42
+):
+    """
+    Train an AdaBoost ensemble for each MPML perspective.
+
+    Each perspective keeps its assigned feature subset.
+    AdaBoost trains multiple copies of the perspective's
+    estimator sequentially, focusing on difficult samples.
+
+    Returns:
+        trained_models: Dictionary containing fitted
+                        AdaBoost ensembles.
+    """
+
+    # 1. Validate the training data.
+    if not isinstance(X_train, pd.DataFrame):
+        raise TypeError("X_train must be a DataFrame.")
+
+    if len(X_train) == 0 or len(X_train) != len(y_train):
+        raise ValueError(
+            "X_train must be nonempty and match y_train in length."
+        )
+
+    if type(n_estimators) is not int or n_estimators < 1:
+        raise ValueError("n_estimators must be a positive integer.")
+
+    if not isinstance(learning_rate, (int, float)) or not (
+        0 < learning_rate < float("inf")
+    ):
+        raise ValueError("learning_rate must be positive and finite.")
+
+    # 2. Get the registered perspectives.
+    perspective_dict = perspectives.get_dict()
+
+    if not perspective_dict:
+        raise ValueError("No perspectives have been added.")
+
+    # Dictionary for trained boosting ensembles.
+    trained_models = {}
+
+    # 3. Train an independent boosting ensemble
+    # for each perspective.
+    for model_name in perspective_dict:
+
+        # Get the configured estimator and feature list.
+        model = perspectives.get_model(model_name)
+        feature_list = perspectives.get_features(model_name)
+
+        # Check that the required features exist.
+        for feature in feature_list:
+            if feature not in X_train.columns:
+                raise ValueError(
+                    f"{model_name}: Feature '{feature}' is missing."
+                )
+
+        # AdaBoost requires a base estimator that accepts
+        # sample_weight in its fit() method.
+        #
+        # inspect.signature() lets us inspect the parameters
+        # accepted by another function or method.
+        try:
+            parameters = inspect.signature(model.fit).parameters
+            supports_weights = "sample_weight" in parameters
+        except (AttributeError, TypeError, ValueError):
+            supports_weights = False
+
+        if not supports_weights:
+            raise TypeError(
+                f"{model_name}: The selected estimator must "
+                "support sample_weight in fit()."
+            )
+
+        # Select only this perspective's features.
+        X_perspective = X_train[feature_list]
+
+        # 4. Create an AdaBoost classifier.
+        #
+        # estimator: The base model to boost.
+        # n_estimators: Maximum number of sequential models.
+        # learning_rate: Controls the contribution of each stage.
+        # random_state: Makes training reproducible.
+        boosting_model = AdaBoostClassifier(
+            estimator=clone(model),
+            n_estimators=n_estimators,
+            learning_rate=learning_rate,
+            random_state=random_state
+        )
+
+        # 5. Train the boosting ensemble.
+        # AdaBoost manages the sequential training internally.
+        boosting_model.fit(X_perspective, y_train)
+
+        # Save the trained ensemble under its perspective name.
+        trained_models[model_name] = boosting_model
+
+    return trained_models
+
+def boosting_predict(perspectives, trained_models, X_instance):
+    """
+    Predict a single instance using trained boosting ensembles.
+
+    Each perspective has its own trained AdaBoostClassifier.
+
+    The AdaBoostClassifier combines its internal models,
+    producing one prediction for that perspective.
+
+    The final prediction across perspectives is determined
+    using the existing majority_vote() function.
+
+    Parameters:
+        perspectives: Perspectives object.
+        trained_models: Dictionary of trained AdaBoost models.
+        X_instance: DataFrame containing exactly one row.
+
+    Returns:
+        Final predicted class.
+    """
+
+    # Ensure that trained boosting models were supplied.
+    if not trained_models:
+        raise ValueError(
+            "No trained boosting models were supplied."
+        )
+
+    # Reuse the majority_vote() function.
+    # It selects each perspective's assigned features,
+    # generates predictions and resolves voting ties.
+    prediction = majority_vote(
+        perspectives,
+        trained_models,
+        X_instance
+    )
+
+    return prediction
+

combination/stacking.py

@@ -0,0 +1,212 @@
+import numpy as np
+import pandas as pd
+from sklearn.base import clone
+from sklearn.linear_model import LogisticRegression
+from sklearn.model_selection import StratifiedKFold, cross_val_predict
+
+def train_stacking(
+    perspectives,
+    X_train,
+    y_train,
+    meta_model=None,
+    cv=5,
+    random_state=42
+):
+    """
+    Train an MPML stacking ensemble using out-of-fold probabilities.
+
+    Returns:
+        trained_models: Dictionary containing base models fitted on all training data.
+        trained_meta_model: Meta-model fitted on out-of-fold probability features.
+        meta_feature_names: Ordered column names for meta-model prediction inputs.
+
+    Each perspective is independently fitted on its own feature columns.
+    The original estimators inside `perspectives` are not modified.
+    """
+
+    # 1. Validate input data and the requested number of folds.
+    if not isinstance(X_train, pd.DataFrame):
+        raise TypeError("X_train must be a pandas DataFrame.")
+
+    if X_train.empty:
+        raise ValueError("X_train must contain training samples and features.")
+
+    if len(X_train) != len(y_train):
+        raise ValueError("X_train and y_train must have equal lengths.")
+
+    if isinstance(cv, bool) or not isinstance(cv, int) or cv < 2:
+        raise ValueError("cv must be an integer of at least 2.")
+
+    definitions = perspectives.get_dict()
+    if not definitions:
+        raise ValueError("No perspectives have been added.")
+
+    # Reset the target index to make it positional, like X_train's rows.
+    # A Series from a previous train_test_split may have a different index.
+    y = pd.Series(y_train).reset_index(drop=True)
+    if y.isna().any():
+        raise ValueError("y_train must not contain missing labels.")
+
+    # np.unique() returns the class labels in sorted order,
+    # matching scikit-learn's standard classifier class order.
+    classes = list(np.unique(y))
+    if len(classes) < 2:
+        raise ValueError("Classification requires at least two classes.")
+
+    # Stratified CV needs enough examples of every class in every fold.
+    counts = y.value_counts()
+    if counts.min() < cv:
+        raise ValueError("Every class must have at least cv training samples.")
+
+    # One fold arrangement is shared by all perspectives.
+    splitter = StratifiedKFold(
+        n_splits=cv,
+        shuffle=True,
+        random_state=random_state
+    )
+
+    # 2. Assemble meta-model features from out-of-fold probabilities.
+    X_meta_features = pd.DataFrame(index=range(len(X_train)))
+    trained_models = {}
+
+    for model_name in definitions:
+        model = perspectives.get_model(model_name)
+        feature_list = perspectives.get_features(model_name)
+
+        # Selecting with a list keeps this as a DataFrame.
+        X_perspective = X_train[feature_list]
+
+        # A new clone is trained separately on each fold, then predicts
+        # only the fold that clone was NOT trained on.
+        # cross_val_predict returns predictions in the original row order.
+        try:
+            probabilities = cross_val_predict(
+                clone(model),
+                X_perspective,
+                y,
+                cv=splitter,
+                method="predict_proba"
+            )
+        except AttributeError as error:
+            raise TypeError(
+                f"{model_name} must support predict_proba() for stacking."
+            ) from error
+
+        # Fit the final model on all training rows for later inference.
+        trained_model = clone(model)
+        trained_model.fit(X_perspective, y)
+        trained_models[model_name] = trained_model
+
+        # cross_val_predict aligns probability columns with the class
+        # order of the full y passed to it; sklearn uses sorted classes.
+        # Align explicitly with classes used by the final fitted model.
+        probability_classes = list(trained_model.classes_)
+        if set(probability_classes) != set(classes):
+            raise ValueError(f"{model_name} learned different classes.")
+
+        for i in range(len(classes)):
+            class_label = classes[i]
+            class_index = probability_classes.index(class_label)
+            column_name = f"{model_name}_class_{i}"
+
+            # [:, class_index] means every row, one probability column.
+            X_meta_features[column_name] = probabilities[:, class_index]
+
+    # 3. Train a separate meta-model on the out-of-fold features.
+    if meta_model is None:
+        meta_model = LogisticRegression(max_iter=1000)
+
+    trained_meta_model = clone(meta_model)
+    trained_meta_model.fit(X_meta_features, y)
+
+    # Preserve the exact meta-feature order for predictions on new data.
+    meta_feature_names = X_meta_features.columns.tolist()
+    return trained_models, trained_meta_model, meta_feature_names
+
+def stacking_predict(
+    perspectives,
+    trained_models,
+    trained_meta_model,
+    meta_feature_names,
+    X_instance
+):
+    """
+    Predict one instance using a trained stacking ensemble.
+
+    Parameters:
+        perspectives: Perspectives object.
+        trained_models: Dictionary of trained base models.
+        trained_meta_model: Trained stacking meta-model.
+        meta_feature_names: Columns used to train the meta-model.
+        X_instance: DataFrame containing exactly one row.
+
+    Returns:
+        Final predicted class.
+    """
+
+    # 1. Validate the input instance.
+    if not isinstance(X_instance, pd.DataFrame):
+        raise TypeError("X_instance must be a DataFrame.")
+
+    if len(X_instance) != 1:
+        raise ValueError("X_instance must contain exactly one row.")
+
+    # 2. Create a DataFrame for meta-model input.
+    X_meta_features = pd.DataFrame(index=X_instance.index)
+
+    # 3. Get the expected class order.
+    # All base models must recognize the same classes.
+    first_model = list(trained_models.values())[0]
+    classes = list(first_model.classes_)
+
+    # 4. Generate probabilities from each base model.
+    for model_name, trained_model in trained_models.items():
+
+        # Get the assigned features.
+        feature_list = perspectives.get_features(model_name)
+
+        # Select only the required features.
+        X_perspective = X_instance[feature_list]
+
+        # Generate class probabilities.
+        probabilities = trained_model.predict_proba(
+            X_perspective
+        )
+
+        # Get this model's class ordering.
+        model_classes = list(trained_model.classes_)
+
+        # Ensure every model has the same class labels.
+        if set(model_classes) != set(classes):
+            raise ValueError(
+                f"{model_name} has different class labels."
+            )
+
+        # Create the same probability columns
+        # used during meta-model training.
+        for i in range(len(classes)):
+
+            class_label = classes[i]
+
+            # Find the correct probability column.
+            class_index = model_classes.index(class_label)
+
+            column_name = f"{model_name}_class_{i}"
+
+            # Store the class probability.
+            X_meta_features[column_name] = probabilities[
+                :, class_index
+            ]
+
+    # 5. Arrange the columns in the same order
+    # used when the meta-model was trained.
+    X_meta_features = X_meta_features[meta_feature_names]
+
+    # 6. Predict using the trained meta-model.
+    prediction = trained_meta_model.predict(X_meta_features)[0]
+
+    # Convert NumPy values into regular Python values.
+    if hasattr(prediction, "item"):
+        prediction = prediction.item()
+
+    return prediction

combination/voting.py

@@ -0,0 +1,289 @@
+import pandas as pd
+from collections import Counter
+
+def get_final_prediction(predictions, classes=None):
+    """
+    Determine the final prediction using majority voting.
+
+    If there is a tie, select the class with the highest
+    combined probability across all models.
+
+    Parameters:
+        predictions: List of (prediction, probabilities) tuples.
+        classes: Class labels in the same order as probabilities.
+
+    Returns:
+        The final predicted class.
+    """
+
+    if not predictions:
+        raise ValueError("Predictions list cannot be empty.")
+
+    if classes is None:
+        classes = list(range(len(predictions[0][1])))
+
+    # Count how many models predicted each class.
+    counts = Counter(pred for pred, _ in predictions)
+
+    # Find the highest number of votes.
+    max_count = max(counts.values())
+
+    # Find classes tied for the most votes.
+    tied_classes = [
+        cls for cls, count in counts.items()
+        if count == max_count
+    ]
+
+    # If there is no tie, return the winning class.
+    if len(tied_classes) == 1:
+        return tied_classes[0]
+
+    # If there is a tie, sum the probabilities
+    # assigned to each tied class by all models.
+    confidence_sums = {
+        cls: sum(
+            probs[classes.index(cls)]
+            for _, probs in predictions
+        )
+        for cls in tied_classes
+    }
+
+    # Return the tied class with the highest confidence.
+    return max(
+        tied_classes,
+        key=lambda cls: confidence_sums[cls]
+    )
+
+def majority_vote(perspectives, trained_models, X_instance):
+    """
+    Predict a single instance using majority voting.
+
+    Each trained perspective contributes one vote.
+    The final decision is made by get_final_prediction().
+
+    Parameters:
+        perspectives: Perspectives object.
+        trained_models: Dictionary containing fitted models.
+        X_instance: DataFrame containing exactly one row.
+
+    Returns:
+        The final predicted class.
+    """
+
+    # Check that the input is a DataFrame with one row.
+    if not isinstance(X_instance, pd.DataFrame):
+        raise TypeError("X_instance must be a DataFrame.")
+
+    if len(X_instance) != 1:
+        raise ValueError("X_instance must contain exactly one row.")
+
+    if not trained_models:
+        raise ValueError("No trained models were supplied.")
+
+    # Store each model's prediction and probabilities.
+    mv_predictions = []
+
+    # Use a consistent class order for all models.
+    classes = None
+
+    # Loop through each trained perspective.
+    for model_name, trained_model in trained_models.items():
+
+        # Get the features assigned to this perspective.
+        feature_list = perspectives.get_features(model_name)
+
+        # Select the appropriate columns.
+        X_perspective = X_instance[feature_list]
+
+        # Predict the class of the instance.
+        prediction = trained_model.predict(X_perspective)[0]
+
+        # Convert NumPy values into regular Python values.
+        if hasattr(prediction, "item"):
+            prediction = prediction.item()
+
+        # Get the class probabilities.
+        probabilities = trained_model.predict_proba(
+            X_perspective
+        )[0]
+
+        # Get the classes recognized by this model.
+        model_classes = list(trained_model.classes_)
+
+        # Establish the class order from the first model.
+        if classes is None:
+            classes = model_classes
+
+        # Ensure every model recognizes the same classes.
+        if set(model_classes) != set(classes):
+            raise ValueError(
+                f"{model_name} has different class labels."
+            )
+
+        # Arrange probabilities in the same class order.
+        ordered_probabilities = []
+
+        for class_label in classes:
+
+            # Find the position of this class.
+            class_index = model_classes.index(class_label)
+
+            # Get the probability associated with the class.
+            probability = float(probabilities[class_index])
+
+            ordered_probabilities.append(probability)
+
+        # Store the prediction and probabilities as a tuple.
+        results = (prediction, ordered_probabilities)
+
+        mv_predictions.append(results)
+
+    # Call the separate function in the same file.
+    return get_final_prediction(mv_predictions, classes)
+
+def weighted_sum(
+    perspectives,
+    trained_models,
+    X_instance,
+    voting_type="soft"
+):
+    """
+    Predict a single instance using weighted voting.
+
+    Parameters:
+        perspectives: Perspectives object containing model weights
+                      and feature lists.
+
+        trained_models: Dictionary of trained base models.
+
+        X_instance: DataFrame containing exactly one row.
+
+        voting_type:
+            "soft" (default) - Multiply each model's weight by
+                               its probability for each class.
+
+            "hard" - Assign the model's entire weight to
+                     its predicted class.
+
+    Returns:
+        The final predicted class.
+    """
+
+    # 1. Validate the voting type.
+    if voting_type not in ("soft", "hard"):
+        raise ValueError(
+            "voting_type must be either 'soft' or 'hard'."
+        )
+
+    # 2. Validate the input instance.
+    if not isinstance(X_instance, pd.DataFrame):
+        raise TypeError("X_instance must be a DataFrame.")
+
+    if len(X_instance) != 1:
+        raise ValueError(
+            "X_instance must contain exactly one row."
+        )
+
+    if not trained_models:
+        raise ValueError("No trained models were supplied.")
+
+    # Dictionary to store accumulated class scores.
+    class_weights = {}
+
+    # Keep track of the total assigned weight.
+    total_weight = 0
+
+    # 3. Process each trained perspective.
+    for model_name, trained_model in trained_models.items():
+
+        # Get the features assigned to the perspective.
+        feature_list = perspectives.get_features(model_name)
+
+        # Get the weight assigned to this perspective.
+        weight = perspectives.get_weight(model_name)
+
+        # Ensure the assigned weight is valid.
+        if (
+            not isinstance(weight, (int, float))
+            or isinstance(weight, bool)
+            or not 0 <= weight < float("inf")
+        ):
+            raise ValueError(
+                f"{model_name} must have a finite, "
+                "nonnegative numerical weight."
+            )
+
+        total_weight += weight
+
+        # Select the appropriate features.
+        X_perspective = X_instance[feature_list]
+
+        # ------------------------------------------
+        # HARD WEIGHTED VOTING
+        # ------------------------------------------
+        if voting_type == "hard":
+
+            # Predict the class for this instance.
+            prediction = trained_model.predict(X_perspective)[0]
+
+            # Convert NumPy values to Python values.
+            if hasattr(prediction, "item"):
+                prediction = prediction.item()
+
+            # Initialize the score for this class.
+            if prediction not in class_weights:
+                class_weights[prediction] = 0.0
+
+            # Assign the model's full weight to
+            # the class it predicted.
+            class_weights[prediction] += weight
+
+        # ------------------------------------------
+        # SOFT WEIGHTED VOTING
+        # ------------------------------------------
+        else:
+
+            # Get the predicted probability of each class.
+            probabilities = trained_model.predict_proba(
+                X_perspective
+            )[0]
+
+            # Get the class labels corresponding to
+            # the probability values.
+            classes = trained_model.classes_
+
+            # Calculate the weighted contribution
+            # for each class.
+            for i in range(len(classes)):
+
+                class_label = classes[i]
+
+                if hasattr(class_label, "item"):
+                    class_label = class_label.item()
+
+                probability = float(probabilities[i])
+
+                # Multiply the probability by the weight.
+                weighted_probability = weight * probability
+
+                # Initialize this class's score.
+                if class_label not in class_weights:
+                    class_weights[class_label] = 0.0
+
+                # Add the weighted probability.
+                class_weights[class_label] += weighted_probability
+
+    # 4. Ensure there is at least one positive weight.
+    if total_weight == 0:
+        raise ValueError(
+            "At least one perspective must have a positive weight."
+        )
+
+    # 5. Select the class with the highest total score.
+    final_prediction = max(
+        class_weights,
+        key=class_weights.get
+    )
+
+    return final_prediction
+

mpml_lib-1.0.0.dist-info/METADATA

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: mpml_lib
+Version: 1.0.0
+Requires-Python: >=3.14
+Requires-Dist: numpy>=2.5.4
+Requires-Dist: pandas>=3.1.1
+Requires-Dist: scikit-learn>=1.9.1

mpml_lib-1.0.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+combination/bagging.py,sha256=OIPWmPnO9H8-sDv0mOQvVGBvfROAf-eYWU7NcAxVt_Q,2914
+combination/blending.py,sha256=ZHZfxQFSc8H4SLaKrAMsNl2xwIZTamXc-GUuXi_wLeo,7653
+combination/boosting.py,sha256=7ZrGd__l5TW5TlUJ4AK2J44mX4BcV6WXdwCze2V96Vw,4724
+combination/stacking.py,sha256=FFIZ-ZEqkYI0bAYCBzSYdW5TTDVJGaZ268dEX82o4vA,7502
+combination/voting.py,sha256=-Rvj0sWPddVeccL0NJccDXAxOjomqGXPhr97aNW7HbU,8731
+mpml_lib-1.0.0.dist-info/METADATA,sha256=6IYWOU_3KzuU8SdOdmUasjuh1BtrJxuYm_LDr6GOYnU,168
+mpml_lib-1.0.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+mpml_lib-1.0.0.dist-info/top_level.txt,sha256=giyna2YQfB5l932_M983n0Yf_M0Z_up1_9wb91FLFsE,12
+mpml_lib-1.0.0.dist-info/RECORD,,

mpml_lib-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mpml_lib-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+combination