path-boost 2.1.0__py3-none-any.whl

path_boost/utils/plots_functions.py

@@ -0,0 +1,153 @@
+import logging
+import os
+from datetime import datetime
+
+from matplotlib import pyplot as plt
+from matplotlib.ticker import MaxNLocator
+
+logger = logging.getLogger("path_boost")
+
+
+def plot_training_and_eval_errors(
+    learning_rate: float,
+    train_mse: list,
+    mse_eval_set: list | None = None,
+    skip_first_n_iterations: int | bool = False,
+    show=True,
+    save=False,
+    save_path: str | None = None,
+):
+    """
+    Plots the training Mean Squared Error (MSE) and, if given, the MSE for multiple
+    evaluation sets over the boosting iterations.
+
+    Parameters
+    ----------
+    learning_rate : float
+        The learning rate used during training, used to adjust the x-axis.
+    train_mse : list[float]
+        A list of training MSE values, where each element corresponds to an iteration.
+    mse_eval_set : list[list[float]] | None, default=None
+        A list of lists, where each inner list contains MSE values for an evaluation
+        set over iterations. If None, only training MSE is plotted.
+    skip_first_n_iterations : int | bool, default=True
+        If True, the first iteration's errors are skipped in the plot (often an outlier).
+        If an integer, that many initial iterations are skipped.
+        If False or 0, all iterations are plotted.
+    show : bool, default=True
+        If True, the plot is displayed.
+    save : bool, default=False
+        If True, the plot is saved to a file.
+    save_path : str | None, default=None
+        The directory where the plot will be saved. If None, the current
+        working directory is used.
+    """
+    # skip_the_first n iterations
+    if isinstance(skip_first_n_iterations, bool):
+        if skip_first_n_iterations:
+            n = int(2 / learning_rate)
+        else:
+            n = 0
+    else:
+        n = skip_first_n_iterations
+
+    if len(train_mse) > n:
+        train_mse = train_mse[n:]
+    else:
+        train_mse = train_mse
+
+    plt.figure(figsize=(12, 6))
+
+    # Plot training errors
+    plt.plot(range(n, len(train_mse) + n), train_mse, label="Training Error", marker="")
+
+    # Plot evaluation set errors if available
+    if mse_eval_set is not None:
+        if len(mse_eval_set[0]) > n:
+            eval_set_mse = [mse_eval_set[i][n:] for i in range(len(mse_eval_set))]
+        else:
+            eval_set_mse = mse_eval_set
+
+        num_iterations = len(eval_set_mse[0])
+        num_eval_sets = len(eval_set_mse)
+        for eval_set_index in range(num_eval_sets):
+            if eval_set_mse[eval_set_index][0] is not None:
+                plt.plot(
+                    range(n, num_iterations + n),
+                    eval_set_mse[eval_set_index],
+                    label=f"Evaluation Set {eval_set_index + 1}",
+                    marker="",
+                )
+
+    plt.xlabel("Iteration")
+    plt.ylabel("Mean Squared Error")
+    plt.title("Training and Evaluation Set Errors Over Iterations")
+    plt.legend()
+    plt.grid(True)
+
+    # Ensure x-axis only shows integers
+    plt.gca().xaxis.set_major_locator(MaxNLocator(integer=True))
+
+    if save:
+        now = datetime.now()
+        timestamp = now.strftime("%Y-%m-%d_%H-%M-%S")
+        filename = f"training_and_eval_errors_{timestamp}.png"
+        if save_path:
+            if not os.path.exists(save_path):
+                os.makedirs(save_path)
+            filename = os.path.join(save_path, filename)
+        plt.savefig(filename)
+        logger.info(f"Plot saved to {filename}")
+
+    if show:
+        plt.show()
+
+
+def plot_variable_importance_utils(
+    variable_importance: dict,
+    parameters_variable_importance: dict,
+    top_n: int | None = None,
+    show: bool = True,
+):
+    """
+    Plots the variable importance scores.
+
+    This function visualizes the importance of features
+    as computed by the PathBoost or SequentialPathBoost models. The appearance and
+    details of the plot can be influenced by the parameters used to compute
+    the variable importance.
+
+    Parameters
+    ----------
+    variable_importance : dict
+        A dictionary where keys are feature identifiers and values are their corresponding importance scores.
+    parameters_variable_importance : dict
+        A dictionary containing parameters that were used for computing
+        variable importance (e.g., 'criterion', 'normalize') and potentially
+        other parameters to guide the plotting.
+    show : bool, default=True
+        If True, the plot is displayed.
+    """
+
+    assert isinstance(
+        variable_importance, dict
+    ), "Variable importance should be a dictionary."
+    sorted_items = sorted(variable_importance.items(), key=lambda x: x[1], reverse=True)
+    if top_n is not None:
+        sorted_items = sorted_items[:top_n]
+    labels, values = zip(*sorted_items)
+
+    # Convert tuples in labels to strings
+    labels = [
+        ",".join(map(str, label)) if isinstance(label, tuple) else str(label)
+        for label in labels
+    ]
+
+    plt.figure(figsize=(10, 6))
+    plt.barh(labels, values, color="skyblue")
+    plt.xlabel("Importance Score")
+    plt.title(parameters_variable_importance["criterion"] + " Variable Importance")
+    plt.gca().invert_yaxis()
+    plt.gca().xaxis.set_major_locator(MaxNLocator(integer=True))
+    if show:
+        plt.show()

path_boost/utils/validate_data.py

@@ -0,0 +1,223 @@
+import inspect
+import logging
+import numbers
+import warnings
+from typing import Iterable
+
+import networkx as nx
+import numpy as np
+from sklearn.tree import DecisionTreeRegressor
+from sklearn.utils.validation import validate_data
+
+from .classes.interfaces.interface_base_learner import BaseLearnerClassInterface
+from .classes.interfaces.interface_selector import SelectorClassInterface
+
+logger = logging.getLogger("path_boost")
+
+
+def check_interface(class_to_be_checked, interface_class):
+    if not issubclass(class_to_be_checked, interface_class):
+        missing_methods = []
+        interface_methods = inspect.getmembers(
+            interface_class, predicate=inspect.isfunction
+        )
+        class_methods = inspect.getmembers(
+            class_to_be_checked, predicate=inspect.isfunction
+        )
+        interface_method_names = [name for name, _ in interface_methods]
+        class_method_names = [name for name, _ in class_methods]
+
+        for method in interface_method_names:
+            if method not in class_method_names:
+                missing_methods.append(method)
+
+        missing_attributes = []
+        interface_attributes = inspect.getmembers(
+            interface_class, predicate=lambda x: not (inspect.isroutine(x))
+        )
+        class_attributes = inspect.getmembers(
+            class_to_be_checked, predicate=lambda x: not (inspect.isroutine(x))
+        )
+        interface_attribute_names = [name for name, _ in interface_attributes]
+        class_attribute_names = [name for name, _ in class_attributes]
+
+        for attribute in interface_attribute_names:
+            if attribute not in class_attribute_names:
+                missing_attributes.append(attribute)
+
+        missing_items = missing_methods + missing_attributes
+        raise TypeError(
+            f"{class_to_be_checked.__name__} must implement {interface_class.__name__}."
+            f" Missing items: {missing_items}"
+        )
+
+
+def util_validate_data(
+    model,
+    X="no_validation",
+    y="no_validation",
+    reset=True,
+    validate_separately=False,
+    **check_params,
+):
+    # We use the `_validate_data` method to validate the input data.
+    # This method is defined in the `BaseEstimator` class.
+    # It allows to:
+    # - run different checks on the input data
+    if not np.array_equal(X, "no_validation"):
+        assert isinstance(X, list) and all(isinstance(item, nx.Graph) for item in X)
+    if not np.array_equal(y, "no_validation"):
+        assert isinstance(y, Iterable) and all(
+            isinstance(item, numbers.Number) for item in y
+        )
+
+    # check BaseLearnerClass and SelectorClass respects the respective interfaces
+    check_interface(model.BaseLearnerClass, BaseLearnerClassInterface)
+
+    check_interface(model.SelectorClass, SelectorClassInterface)
+
+    # ------------------------------------------------------------------------------------------------------
+    # the following is just to set the default parameters for the selector class ant the base learner class
+    if issubclass(model.BaseLearnerClass, DecisionTreeRegressor):
+        if model.kwargs_for_base_learner is None:
+            model.kwargs_for_base_learner = model._default_kwargs_for_base_learner
+        else:
+            for key in model._default_kwargs_for_base_learner:
+                if key not in model.kwargs_for_base_learner:
+                    model.kwargs_for_base_learner[key] = (
+                        model._default_kwargs_for_base_learner[key]
+                    )
+
+    if issubclass(model.SelectorClass, DecisionTreeRegressor):
+        if model.kwargs_for_selector is None:
+            model.kwargs_for_selector = model._default_kwargs_for_selector
+        else:
+            for key in model._default_kwargs_for_selector:
+                if key not in model.kwargs_for_selector:
+                    model.kwargs_for_selector[key] = model._default_kwargs_for_selector[
+                        key
+                    ]
+
+    # ------------------------------------------------------------------------------------------------------
+
+    if model.kwargs_for_selector is None:
+        model.kwargs_for_selector = {}
+    if model.kwargs_for_base_learner is None:
+        model.kwargs_for_base_learner = {}
+
+    # check parameters for variable importance
+    parameters_variable_importance = check_params.get(
+        "parameters_variable_importance", None
+    )
+    if parameters_variable_importance is not None:
+        assert isinstance(parameters_variable_importance, dict)
+        for key, value in parameters_variable_importance.items():
+            assert isinstance(key, str)
+            if key == "criterion":
+                assert value in ["absolute", "relative"]
+            elif key == "error_used":
+                assert value in ["mse", "mae"]
+            elif key == "use_correlation":
+                assert isinstance(value, bool)
+            elif key == "normalize":
+                assert isinstance(value, bool)
+            elif key == "normalization_value":
+                assert value is None or isinstance(value, float)
+
+            else:
+                raise ValueError(f"Unknown parameter {key} for variable importance")
+
+    # check list_anchor_nodes_labels
+    list_anchor_nodes_labels = check_params.get("list_anchor_nodes_labels", None)
+    if list_anchor_nodes_labels is not None:
+        # Ensure each element in list_anchor_nodes_labels is a tuple
+        len_list_anchor_nodes_labels = len(list_anchor_nodes_labels)
+        for i in range(len_list_anchor_nodes_labels):
+            if not isinstance(list_anchor_nodes_labels[i], tuple):
+                if hasattr(list_anchor_nodes_labels[i], "__iter__") and not isinstance(
+                    list_anchor_nodes_labels[i], str
+                ):
+                    list_anchor_nodes_labels[i] = tuple(list_anchor_nodes_labels[i])
+                else:
+                    list_anchor_nodes_labels[i] = tuple([list_anchor_nodes_labels[i]])
+
+    elif (
+        "list_anchor_nodes_labels" in check_params and list_anchor_nodes_labels is None
+    ):
+        # Warn if X is provided but name_of_label_attribute is missing
+        if not (
+            not np.array_equal(X, "no_validation")
+            and "name_of_label_attribute" in check_params
+        ):
+            warnings.warn(
+                "list_anchor_nodes_labels can not be validated because it is None."
+            )
+        else:
+            anchor_attribute_values = []
+            if (
+                not np.array_equal(X, "no_validation")
+                and "name_of_label_attribute" in check_params
+            ):
+                label_attr = check_params["name_of_label_attribute"]
+                for graph in X:
+                    for _, node_data in graph.nodes(data=True):
+                        if label_attr in node_data:
+                            anchor_attribute_values.append(node_data[label_attr])
+            model.list_anchor_nodes_labels = anchor_attribute_values
+
+    model.list_anchor_nodes_labels = list_anchor_nodes_labels
+
+    # check m_stops
+    # only for cyclic path boost
+    m_stops = check_params.get("m_stops", None)
+    if m_stops is not None:
+        assert isinstance(m_stops, list) and all(
+            isinstance(item, (int, type(None))) for item in m_stops
+        )
+        assert len(m_stops) == len(model.list_anchor_nodes_labels)
+
+    # check eval sets
+    eval_set = check_params.get("eval_set", None)
+    if eval_set is not None:
+        assert isinstance(eval_set, Iterable) and all(
+            isinstance(eval_tuple, tuple) and len(eval_tuple) == 2
+            for eval_tuple in eval_set
+        )
+        for eval_tuple in eval_set:
+            assert isinstance(eval_tuple[0], list) and all(
+                isinstance(item, nx.Graph) for item in eval_tuple[0]
+            )
+            assert isinstance(eval_tuple[1], Iterable) and all(
+                isinstance(item, numbers.Number) for item in eval_tuple[1]
+            )
+
+    # check patience
+    patience = check_params.get("patience", None)
+    if patience is not None:
+        assert (
+            isinstance(patience, int) and patience >= 0
+        ), "patience must be a non-negative integer"
+        if check_params.get("eval_set", None) is None:
+            warnings.warn(
+                "patience is set to None because there is no eval_set provided"
+            )
+            patience = None
+    model.patience = patience
+
+    if not np.array_equal(y, "no_validation"):
+        validate_data(
+            model,
+            X="no_validation",
+            y=y,
+            reset=reset,
+            validate_separately=validate_separately,
+        )
+
+    if not np.array_equal(X, "no_validation") and not np.array_equal(
+        y, "no_validation"
+    ):
+        return X, y
+    elif not np.array_equal(X, "no_validation"):
+        return X
+    elif not np.array_equal(y, "no_validation"):
+        return y