path-boost 2.1.0__py3-none-any.whl

path_boost/utils/cross_validation.py

@@ -0,0 +1,49 @@
+import logging
+
+import networkx as nx
+import numpy as np
+from sklearn.model_selection import GridSearchCV, train_test_split
+
+from path_boost._path_boost import PathBoost
+
+logger = logging.getLogger("path_boost")
+
+
+def independent_cross_validation_on_each_anchor_node(
+    X: list[nx.Graph], y, param_grid: dict = None
+):
+    # Define the parameter grid
+    # TODO remove this hard coded param_grid
+    if param_grid is None:
+        param_grid = {
+            "learning_rate": [0.01, 0.02, 0.05],
+            "max_path_length": [3, 5, 7],
+            "kwargs_for_base_learner": [{"max_depth": 3}, {"max_depth": 4}],
+        }
+
+    # Initialize the PathBoost model
+    path_boost = PathBoost(n_iter=10, n_of_cores=10, verbose=False)
+
+    # Initialize GridSearchCV
+    grid_search = GridSearchCV(
+        estimator=path_boost,
+        param_grid=param_grid,
+        cv=3,
+        scoring="neg_mean_squared_error",
+    )
+
+    # Fit the model on the training data
+    grid_search.fit(
+        X_train,
+        y_train,
+        list_anchor_nodes_labels=[25, 47, 48, 80],
+        anchor_nodes_label_name="feature_atomic_number",
+    )
+
+    logger.info(f"Best parameters found: {grid_search.best_params_}")
+    logger.info(f"Best cross-validation score: {-grid_search.best_score_}")
+
+    # Evaluate the best model on the test set
+    best_model = grid_search.best_estimator_
+    test_score = best_model.score(X_test, y_test)
+    logger.info(f"Test set score: {test_score}")

path_boost/utils/cyclic_path_boost_utils.py

@@ -0,0 +1,76 @@
+import networkx as nx
+
+from .classes.extended_boosting_matrix import ExtendedBoostingMatrix
+from .classes.sequential_path_boost import SequentialPathBoost
+
+
+def split_dataset_by_metal_centers(
+    graphs_list: list[nx.Graph], anchor_nodes_label_name: str, anchor_nodes: list
+) -> list[list[int]]:
+    """
+    Splits a list of graphs into subgroups based on anchor node labels.
+
+    This static method takes a list of graphs, an anchor nodes label name,
+    and a list of anchor nodes. It iterates through each graph and identifies
+    nodes labeled with anchor node labels. It then organizes the indices of
+    graphs where such anchor nodes are found into corresponding subgroups.
+
+    Args:
+        graphs_list (list[nx.Graph]): A list of networkx Graph objects to be processed.
+        anchor_nodes_label_name (str): The name of the attribute used to identify anchor nodes in the graphs.
+        anchor_nodes (list): A list of anchor nodes to be used as a reference for grouping.
+
+    Returns:
+        list[list[int]]: A list containing sublists of indices corresponding to the grouping
+                         of graphs based on the presence of the anchor nodes.
+    """
+
+    indices_list = [[] for _ in range(len(anchor_nodes))]
+    for index_in_anchor_nodes, anchor_node_label in enumerate(anchor_nodes):
+        for i, graph in enumerate(graphs_list):
+            path_found = ExtendedBoostingMatrix.find_labelled_path_in_nx_graph(
+                graph=graph,
+                path_labels=anchor_node_label,
+                main_label_name=anchor_nodes_label_name,
+            )
+            if len(path_found) > 0:
+                indices_list[index_in_anchor_nodes].append(i)
+    return indices_list
+
+
+def train_pattern_boosting(
+    input_from_parallelization: tuple,
+) -> SequentialPathBoost | None:
+    model: SequentialPathBoost = input_from_parallelization[0]
+    if model is None:
+        return None
+    X = input_from_parallelization[1]
+    y = input_from_parallelization[2]
+    list_anchor_nodes_labels: tuple = input_from_parallelization[3]
+    name_of_label_attribute = input_from_parallelization[4]
+    model.fit(
+        X=X,
+        y=y,
+        eval_set=None,
+        list_anchor_nodes_labels=[list_anchor_nodes_labels],
+        anchor_nodes_label_name=name_of_label_attribute,
+    )
+    return model
+
+
+def parallel_predict(input_from_parallelization: tuple):
+    model: SequentialPathBoost = input_from_parallelization[0]
+    X = input_from_parallelization[1]
+    if model is None or len(X) == 0:
+        return None
+
+    return model.predict(X)
+
+
+def parallel_predict_step_by_step(input_from_parallelization: tuple):
+    model: SequentialPathBoost = input_from_parallelization[0]
+    X = input_from_parallelization[1]
+    if model is None or len(X) == 0:
+        return None
+
+    return model.predict_step_by_step(X)

path_boost/utils/datasets_for_examples/__init__.py

@@ -0,0 +1,2 @@
+# Authors: scikit-learn-contrib developers
+# License: BSD 3 clause

path_boost/utils/datasets_for_examples/generate_example_dataset.py

@@ -0,0 +1,304 @@
+import numpy as np
+import networkx as nx
+from sklearn.model_selection import train_test_split, GridSearchCV
+from path_boost._path_boost import PathBoost
+
+
+def _find_path_instances(graph, path_definition, type_attribute_name="feature_0"):
+    """
+    Finds all instances of a given path definition in a graph.
+    A path definition is a sequence of node types.
+    An instance is a sequence of connected node IDs whose types match the definition.
+    """
+    instances = []
+    k = len(path_definition)
+    if k == 0:
+        return []
+
+    for start_node in graph.nodes:
+        if graph.nodes[start_node].get(type_attribute_name) == path_definition[0]:
+            # Stack stores (current_node_sequence, current_definition_index)
+            dfs_stack = [([start_node], 0)]
+            while dfs_stack:
+                current_nodes_in_path, def_idx = dfs_stack.pop()
+
+                if def_idx == k - 1:  # Path complete
+                    instances.append(list(current_nodes_in_path))
+                    continue
+
+                last_node_in_current_path = current_nodes_in_path[-1]
+                next_def_idx = def_idx + 1
+                expected_next_type = path_definition[next_def_idx]
+
+                for neighbor in graph.neighbors(last_node_in_current_path):
+                    if (
+                        neighbor not in current_nodes_in_path
+                        and graph.nodes[neighbor].get(type_attribute_name)
+                        == expected_next_type
+                    ):
+                        new_path_nodes = list(current_nodes_in_path)  # Make a copy
+                        new_path_nodes.append(neighbor)
+                        dfs_stack.append((new_path_nodes, next_def_idx))
+    return instances
+
+
+def generate_synthetic_graph_dataset(
+    n_graphs=100,
+    avg_n_nodes=15,
+    std_n_nodes=5,
+    graph_density=0.3,
+    n_node_types=5,
+    anchor_node_types: list | None = None,  # New parameter
+    n_numerical_node_features=2,  # e.g., feature_1, feature_2
+    n_edge_features=1,
+    n_true_paths=3,
+    avg_true_path_length=3,
+    std_true_path_length=1,
+    numerical_feature_idx_for_label=1,  # 0 for feature_0 (type), 1 for feature_1 etc.
+    noise_std=0.5,
+    random_state=42,
+):
+    """
+    Generates a synthetic dataset of graphs.
+    Labels 'y' are derived from predefined "true paths" found in the graphs.
+    Node types are stored in 'feature_0'. Numerical features are 'feature_1', 'feature_2', ...
+    """
+    rng = np.random.RandomState(random_state)
+
+    possible_node_types = list(range(n_node_types))
+
+    # Determine which types can start a true path
+    valid_starting_types_for_true_paths = possible_node_types
+    if anchor_node_types is not None and len(anchor_node_types) > 0:
+        # Ensure anchor_node_types are valid w.r.t. n_node_types
+        if not all(t in possible_node_types for t in anchor_node_types):
+            raise ValueError(
+                f"All anchor_node_types must be within the range [0, {n_node_types-1}]"
+            )
+        valid_starting_types_for_true_paths = anchor_node_types
+
+    # 1. Define True Paths and their weights
+    true_paths_definitions = []
+    for _ in range(n_true_paths):
+        path_len = int(max(1, rng.normal(avg_true_path_length, std_true_path_length)))
+        if path_len == 0:
+            continue
+
+        # First element of the path must be from valid_starting_types_for_true_paths
+        first_node_type = rng.choice(valid_starting_types_for_true_paths)
+
+        if path_len == 1:
+            path_def = tuple([int(first_node_type)])
+        else:
+            remaining_path_types = rng.choice(possible_node_types, size=path_len - 1)
+            path_def = tuple(
+                [int(first_node_type)] + [int(x) for x in remaining_path_types]
+            )
+
+        # Add all prefixes of the path that start with an anchor type
+        for i in range(len(path_def)):
+            prefix = path_def[: i + 1]
+            if (
+                prefix[0] in valid_starting_types_for_true_paths
+            ):  # Ensure prefix starts with a valid anchor
+                true_paths_definitions.append(prefix)
+
+    true_paths_definitions = list(set(true_paths_definitions))  # Remove duplicates
+
+    # Adjust number of weights if true_paths_definitions changed size due to prefix addition and set conversion
+    actual_n_true_paths = len(true_paths_definitions)
+    true_path_weights = rng.uniform(-2, 2, size=actual_n_true_paths)
+
+    graphs = []
+    y_labels = []
+
+    # Determine the name of the numerical feature to use for label calculation
+    # feature_0 is type, feature_1 is the first numerical, etc.
+    label_feature_name = f"feature_{numerical_feature_idx_for_label}"
+
+    for i_graph in range(n_graphs):
+        # 2. Generate a random graph
+        num_nodes = int(max(2, rng.normal(avg_n_nodes, std_n_nodes)))
+        G = nx.erdos_renyi_graph(num_nodes, graph_density, seed=random_state + i_graph)
+        if not nx.is_connected(
+            G
+        ):  # Ensure graph is connected for more interesting paths
+            G = nx.erdos_renyi_graph(
+                num_nodes, graph_density, seed=random_state + i_graph + n_graphs
+            )
+            if not nx.is_connected(G):  # If still not connected, take largest component
+                if G.number_of_nodes() > 0 and G.number_of_edges() > 0:
+                    largest_cc = max(nx.connected_components(G), key=len)
+                    G = G.subgraph(largest_cc).copy()
+                if G.number_of_nodes() < 2:  # if too small, regenerate a simple one
+                    G = nx.path_graph(max(2, num_nodes // 2), create_using=nx.Graph())
+
+        # 3. Assign node features
+        for node_idx in G.nodes:
+            G.nodes[node_idx]["feature_0"] = rng.choice(
+                possible_node_types
+            )  # Node type
+            for f_idx in range(n_numerical_node_features):
+                G.nodes[node_idx][f"feature_{f_idx + 1}"] = rng.uniform(-1, 1)
+
+        # 4. Assign edge features
+        for u, v in G.edges:
+            for ef_idx in range(n_edge_features):
+                G.edges[u, v][f"edge_feature_{ef_idx}"] = rng.uniform(-1, 1)
+
+        # 5. Calculate label y for the graph
+        current_y = 0.0
+        for path_idx, path_def in enumerate(true_paths_definitions):
+            path_weight = true_path_weights[path_idx]
+            path_instances = _find_path_instances(
+                G, path_def, type_attribute_name="feature_0"
+            )
+
+            for instance_nodes in path_instances:
+                feature_sum_on_instance = 0.0
+                if label_feature_name == "feature_0":  # if using the type itself
+                    feature_sum_on_instance = sum(
+                        G.nodes[node][label_feature_name]
+                        for node in instance_nodes
+                        if label_feature_name in G.nodes[node]
+                    )
+                else:  # if using numerical features
+                    feature_sum_on_instance = sum(
+                        G.nodes[node].get(label_feature_name, 0)
+                        for node in instance_nodes
+                    )
+                current_y += path_weight * feature_sum_on_instance
+
+        current_y += rng.normal(0, noise_std)
+
+        graphs.append(G)
+        y_labels.append(current_y)
+
+    return graphs, np.array(y_labels), true_paths_definitions, true_path_weights
+
+
+if __name__ == "__main__":
+    N_NODE_TYPES = 5  # Total distinct types of nodes, e.g., 0, 1, 2, 3, 4
+    # Define which node types will be considered as anchors for true path generation AND for PathBoost
+    anchor_types_for_generation_and_boosting = [
+        0,
+        1,
+        2,
+    ]  # Example: types 0, 1, and 2 are anchors
+
+    # Generate synthetic dataset
+    nx_graphs, y, true_paths, true_weights = generate_synthetic_graph_dataset(
+        n_graphs=100,
+        avg_n_nodes=12,
+        std_n_nodes=3,
+        graph_density=0.4,
+        n_node_types=N_NODE_TYPES,
+        anchor_node_types=anchor_types_for_generation_and_boosting,  # Pass the anchor types here
+        n_numerical_node_features=2,  # feature_1, feature_2
+        n_edge_features=1,
+        n_true_paths=4,  # This will be the number of "base" true paths, prefixes will be added
+        avg_true_path_length=3,
+        std_true_path_length=1,
+        numerical_feature_idx_for_label=1,  # Use feature_1 for label calculation
+        noise_std=0.1,
+        random_state=42,
+    )
+
+    print(f"Generated {len(nx_graphs)} graphs.")
+    print(f"Example y values: {y[:5]}")
+    print(f"True paths definitions (may include prefixes): {true_paths}")
+    print(f"True path weights: {true_weights}")
+
+    list_anchor_nodes_labels = (
+        anchor_types_for_generation_and_boosting  # Use the same for PathBoost
+    )
+    anchor_nodes_label_name_for_fitting = "feature_0"  # Node types are in 'feature_0'
+
+    parameters_variable_importance: dict = {
+        "criterion": "absolute",
+        "error_used": "mse",
+        "use_correlation": False,
+        "normalize": True,
+    }
+
+    X_train, X_test, y_train, y_test = train_test_split(
+        nx_graphs, y, test_size=0.25, random_state=42
+    )
+
+    eval_set = [(X_test, y_test)]
+
+    # --- GridSearchCV for hyperparameter tuning ---
+    print("\nStarting GridSearchCV for hyperparameter tuning...")
+
+    # Define the parameter grid
+    param_grid = {
+        "learning_rate": [0.01, 0.1, 0.8],
+        "max_path_length": [3, 4],
+        "kwargs_for_base_learner": [{"max_depth": 3}, {"max_depth": 5}],
+    }
+
+    # Initialize a base PathBoost model for GridSearchCV
+    # n_iter is set to a smaller value for faster CV.
+    # Other parameters like n_of_cores, verbose are set for CV.
+    base_pb_for_cv = PathBoost(
+        n_iter=20,  # smaller n_iter for quicker CV
+        n_of_cores=1,
+        verbose=False,
+        parameters_variable_importance=None,  # Disable var importance during CV
+    )
+
+    grid_search = GridSearchCV(
+        estimator=base_pb_for_cv,
+        param_grid=param_grid,
+        scoring="neg_mean_squared_error",
+        cv=3,
+        verbose=1,
+        n_jobs=1,
+    )
+
+    # Fit GridSearchCV
+    # Pass anchor_nodes_label_name and list_anchor_nodes_labels as they are needed by PathBoost.fit
+    grid_search.fit(
+        X_train,
+        y_train,
+        anchor_nodes_label_name=anchor_nodes_label_name_for_fitting,
+        list_anchor_nodes_labels=list_anchor_nodes_labels,
+    )
+
+    print("\nGridSearchCV finished.")
+    print(f"Best parameters found: {grid_search.best_params_}")
+    print(f"Best cross-validation score (Negative MSE): {grid_search.best_score_}")
+
+    # --- Fit final model with best parameters ---
+    print("\nFitting final PathBoost model with best parameters...")
+    best_params_from_cv = grid_search.best_params_
+
+    path_boost_final = PathBoost(
+        max_path_length=best_params_from_cv["max_path_length"],
+        learning_rate=best_params_from_cv["learning_rate"],
+        kwargs_for_base_learner=best_params_from_cv["kwargs_for_base_learner"],
+        verbose=True,
+        parameters_variable_importance=parameters_variable_importance,
+    )
+
+    # Fit the final model
+    path_boost_final.fit(
+        X=X_train,
+        y=y_train,
+        eval_set=eval_set,
+        list_anchor_nodes_labels=list_anchor_nodes_labels,
+        anchor_nodes_label_name=anchor_nodes_label_name_for_fitting,
+    )
+
+    print("\nPlotting results for the final tuned model...")
+    path_boost_final.plot_training_and_eval_errors(
+        skip_first_n_iterations=0, plot_eval_sets_error=True
+    )
+    if path_boost_final.parameters_variable_importance is not None and hasattr(
+        path_boost_final, "variable_importance_"
+    ):
+        path_boost_final.plot_variable_importance(top_n_features=10)
+    else:
+        print("Variable importance not computed or available for the final model.")
+
+    print("\nExample run with GridSearchCV finished.")

path_boost/utils/discovery.py

@@ -0,0 +1,217 @@
+"""
+The :mod:`path_boost.utils.discovery` module includes utilities to discover
+objects (i.e. estimators, displays, functions) from the `path_boost` package.
+"""
+
+# Adapted from scikit-learn
+# Authors: scikit-learn-contrib developers
+# License: BSD 3 clause
+
+import inspect
+import pkgutil
+from importlib import import_module
+from operator import itemgetter
+from pathlib import Path
+
+from sklearn.base import (
+    BaseEstimator,
+    ClassifierMixin,
+    ClusterMixin,
+    RegressorMixin,
+    TransformerMixin,
+)
+from sklearn.utils._testing import ignore_warnings
+
+_MODULE_TO_IGNORE = {"tests"}
+
+
+def all_estimators(type_filter=None):
+    """Get a list of all estimators from `path_boost`.
+
+    This function crawls the module and gets all classes that inherit
+    from `BaseEstimator`. Classes that are defined in test-modules are not
+    included.
+
+    Parameters
+    ----------
+    type_filter : {"classifier", "regressor", "cluster", "transformer"} \
+            or list of such str, default=None
+        Which kind of estimators should be returned. If None, no filter is
+        applied and all estimators are returned.  Possible values are
+        'classifier', 'regressor', 'cluster' and 'transformer' to get
+        estimators only of these specific types, or a list of these to
+        get the estimators that fit at least one of the types.
+
+    Returns
+    -------
+    estimators : list of tuples
+        List of (name, class), where ``name`` is the class name as string
+        and ``class`` is the actual type of the class.
+
+    Examples
+    --------
+    >>> from path_boost.utils.discovery import all_estimators
+    >>> estimators = all_estimators()
+    >>> type(estimators)
+    <class 'list'>
+    """
+
+    def is_abstract(c):
+        if not (hasattr(c, "__abstractmethods__")):
+            return False
+        if not len(c.__abstractmethods__):
+            return False
+        return True
+
+    all_classes = []
+    root = str(Path(__file__).parent.parent)  # path_boost package
+    # Ignore deprecation warnings triggered at import time and from walking
+    # packages
+    with ignore_warnings(category=FutureWarning):
+        for _, module_name, _ in pkgutil.walk_packages(
+            path=[root], prefix="path_boost."
+        ):
+            module_parts = module_name.split(".")
+            if any(part in _MODULE_TO_IGNORE for part in module_parts):
+                continue
+            module = import_module(module_name)
+            classes = inspect.getmembers(module, inspect.isclass)
+            classes = [
+                (name, est_cls) for name, est_cls in classes if not name.startswith("_")
+            ]
+
+            all_classes.extend(classes)
+
+    all_classes = set(all_classes)
+
+    estimators = [
+        c
+        for c in all_classes
+        if (issubclass(c[1], BaseEstimator) and c[0] != "BaseEstimator")
+    ]
+    # get rid of abstract base classes
+    estimators = [c for c in estimators if not is_abstract(c[1])]
+
+    if type_filter is not None:
+        if not isinstance(type_filter, list):
+            type_filter = [type_filter]
+        else:
+            type_filter = list(type_filter)  # copy
+        filtered_estimators = []
+        filters = {
+            "classifier": ClassifierMixin,
+            "regressor": RegressorMixin,
+            "transformer": TransformerMixin,
+            "cluster": ClusterMixin,
+        }
+        for name, mixin in filters.items():
+            if name in type_filter:
+                type_filter.remove(name)
+                filtered_estimators.extend(
+                    [est for est in estimators if issubclass(est[1], mixin)]
+                )
+        estimators = filtered_estimators
+        if type_filter:
+            raise ValueError(
+                "Parameter type_filter must be 'classifier', "
+                "'regressor', 'transformer', 'cluster' or "
+                "None, got"
+                f" {repr(type_filter)}."
+            )
+
+    # drop duplicates, sort for reproducibility
+    # itemgetter is used to ensure the sort does not extend to the 2nd item of
+    # the tuple
+    return sorted(set(estimators), key=itemgetter(0))
+
+
+def all_displays():
+    """Get a list of all displays from `path_boost`.
+
+    Returns
+    -------
+    displays : list of tuples
+        List of (name, class), where ``name`` is the display class name as
+        string and ``class`` is the actual type of the class.
+
+    Examples
+    --------
+    >>> from path_boost.utils.discovery import all_displays
+    >>> displays = all_displays()
+    """
+    all_classes = []
+    root = str(Path(__file__).parent.parent)  # path_boost package
+    # Ignore deprecation warnings triggered at import time and from walking
+    # packages
+    with ignore_warnings(category=FutureWarning):
+        for _, module_name, _ in pkgutil.walk_packages(
+            path=[root], prefix="path_boost."
+        ):
+            module_parts = module_name.split(".")
+            if any(part in _MODULE_TO_IGNORE for part in module_parts):
+                continue
+            module = import_module(module_name)
+            classes = inspect.getmembers(module, inspect.isclass)
+            classes = [
+                (name, display_class)
+                for name, display_class in classes
+                if not name.startswith("_") and name.endswith("Display")
+            ]
+            all_classes.extend(classes)
+
+    return sorted(set(all_classes), key=itemgetter(0))
+
+
+def _is_checked_function(item):
+    if not inspect.isfunction(item):
+        return False
+
+    if item.__name__.startswith("_"):
+        return False
+
+    mod = item.__module__
+    if not mod.startswith("path_boost.") or mod.endswith("estimator_checks"):
+        return False
+
+    return True
+
+
+def all_functions():
+    """Get a list of all functions from `path_boost`.
+
+    Returns
+    -------
+    functions : list of tuples
+        List of (name, function), where ``name`` is the function name as
+        string and ``function`` is the actual function.
+
+    Examples
+    --------
+    >>> from path_boost.utils.discovery import all_functions
+    >>> functions = all_functions()
+    """
+    all_functions = []
+    root = str(Path(__file__).parent.parent)  # path_boost package
+    # Ignore deprecation warnings triggered at import time and from walking
+    # packages
+    with ignore_warnings(category=FutureWarning):
+        for _, module_name, _ in pkgutil.walk_packages(
+            path=[root], prefix="path_boost."
+        ):
+            module_parts = module_name.split(".")
+            if any(part in _MODULE_TO_IGNORE for part in module_parts):
+                continue
+
+            module = import_module(module_name)
+            functions = inspect.getmembers(module, _is_checked_function)
+            functions = [
+                (func.__name__, func)
+                for name, func in functions
+                if not name.startswith("_")
+            ]
+            all_functions.extend(functions)
+
+    # drop duplicates, sort for reproducibility
+    # itemgetter is used to ensure the sort does not extend to the 2nd item of
+    # the tuple
+    return sorted(set(all_functions), key=itemgetter(0))