bella-companion 0.1.1__tar.gz → 0.1.20__tar.gz

{bella_companion-0.1.1 → bella_companion-0.1.20}/PKG-INFO

@@ -1,15 +1,17 @@
 Metadata-Version: 2.3
 Name: bella-companion
-Version: 0.1.1
+Version: 0.1.20
 Summary: Bayesian Evolutionary Layered Learning Architectures (BELLA) companion
 Author: gabriele-marino
 Author-email: gabriele-marino <gabmarino.8601@gmail.com>
-Requires-Dist: arviz>=0.22.0
-Requires-Dist: bella-lumiere>=0.1.0
+Requires-Dist: arviz==0.22.0
+Requires-Dist: autoregistry>=1.2.0
 Requires-Dist: dotenv>=0.9.9
-Requires-Dist: phylogenie>=3.1.4
-Requires-Dist: poetry>=2.2.1
+Requires-Dist: phylogenie>=3.1.14
+Requires-Dist: plotly>=6.5.0
+Requires-Dist: scipy>=1.15.3
 Requires-Dist: seaborn>=0.13.2
+Requires-Dist: shap>=0.49.1
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 

{bella_companion-0.1.1 → bella_companion-0.1.20}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "bella-companion"
-version = "0.1.1"
+version = "0.1.20"
 description = "Bayesian Evolutionary Layered Learning Architectures (BELLA) companion"
 readme = "README.md"
 authors = [
@@ -8,27 +8,32 @@ authors = [
 ]
 requires-python = ">=3.10"
 dependencies = [
-    "arviz>=0.22.0",
-    "bella-lumiere>=0.1.0",
+    "arviz==0.22.0",
+    "autoregistry>=1.2.0",
     "dotenv>=0.9.9",
-    "phylogenie>=3.1.4",
-    "poetry>=2.2.1",
+    "phylogenie>=3.1.14",
+    "plotly>=6.5.0",
+    "scipy>=1.15.3",
     "seaborn>=0.13.2",
+    "shap>=0.49.1",
 ]
 
-[project.scripts]
-bella = "bella_companion.cli:main"
-
-[build-system]
-requires = ["uv_build>=0.9.5,<0.10.0"]
-build-backend = "uv_build"
-
 [dependency-groups]
 dev = [
     "joblib-stubs>=1.5.2.0.20250831",
+    "pandas-stubs>=2.3.2.250926",
+    "plotly-stubs>=0.0.6",
     "pyright>=1.1.407",
+    "requests>=2.32.5",
+    "scipy-stubs>=1.15.3.0",
 ]
 
 [tool.pyright]
 typeCheckingMode = "strict"
 
+[project.scripts]
+bella = "bella_companion.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.9.5,<0.10.0"]
+build-backend = "uv_build"

bella_companion-0.1.20/src/bella_companion/backend/__init__.py

@@ -0,0 +1,94 @@
+from bella_companion.backend.activation_functions import (
+    ActivationFunction,
+    ActivationFunctionLike,
+    Identity,
+    RegisteredActivationFunction,
+    ReLU,
+    Sigmoid,
+    Softplus,
+    Tanh,
+    as_activation_function,
+)
+from bella_companion.backend.mlp import MLP, MLPEnsemble, mlp_ensembles_from_logs_dir
+from bella_companion.backend.plots import ribbon_plot, skyline_plot
+from bella_companion.backend.type_hints import Array, Model, Weights
+from bella_companion.backend.utils import (
+    ESS_POSTFIX,
+    LOWER_POSTFIX,
+    MEDIAN_POSTFIX,
+    UPPER_POSTFIX,
+    avg_ci_width_from_summaries,
+    coverage_from_summaries,
+    get_job_metadata,
+    mae_distribution_from_summaries,
+    mae_from_summaries,
+    mean_ess_per_hour_from_summaries,
+    normalize,
+    read_log_file,
+    read_weights,
+    read_weights_dir,
+    submit_beast_job,
+    submit_job,
+    summarize_log,
+    summarize_logs_dir,
+)
+from bella_companion.backend.xAI import (
+    get_median_partial_dependence_plot,
+    get_median_partial_dependence_plot_distribution,
+    get_median_shap_feature_importance_distribution,
+    get_partial_dependence_plot,
+    get_partial_dependence_plot_distribution,
+    get_partial_dependence_plots,
+    get_partial_dependence_plots_distribution,
+    get_shap_feature_importance_distribution,
+    get_shap_features_importance,
+    get_shap_values,
+)
+
+__all__ = [
+    "ActivationFunction",
+    "ActivationFunctionLike",
+    "Identity",
+    "RegisteredActivationFunction",
+    "ReLU",
+    "Sigmoid",
+    "Softplus",
+    "Tanh",
+    "as_activation_function",
+    "MLP",
+    "MLPEnsemble",
+    "mlp_ensembles_from_logs_dir",
+    "ribbon_plot",
+    "skyline_plot",
+    "Array",
+    "Model",
+    "Weights",
+    "ESS_POSTFIX",
+    "LOWER_POSTFIX",
+    "MEDIAN_POSTFIX",
+    "UPPER_POSTFIX",
+    "avg_ci_width_from_summaries",
+    "coverage_from_summaries",
+    "get_job_metadata",
+    "mae_distribution_from_summaries",
+    "mae_from_summaries",
+    "mean_ess_per_hour_from_summaries",
+    "normalize",
+    "read_log_file",
+    "read_weights",
+    "read_weights_dir",
+    "submit_beast_job",
+    "submit_job",
+    "summarize_log",
+    "summarize_logs_dir",
+    "get_median_partial_dependence_plot",
+    "get_median_partial_dependence_plot_distribution",
+    "get_median_shap_feature_importance_distribution",
+    "get_partial_dependence_plot",
+    "get_partial_dependence_plot_distribution",
+    "get_partial_dependence_plots",
+    "get_partial_dependence_plots_distribution",
+    "get_shap_feature_importance_distribution",
+    "get_shap_features_importance",
+    "get_shap_values",
+]

bella_companion-0.1.20/src/bella_companion/backend/activation_functions.py

@@ -0,0 +1,72 @@
+from abc import abstractmethod
+from typing import Callable
+
+import numpy as np
+from autoregistry import Registry
+from numpy.typing import ArrayLike
+
+from bella_companion.backend.type_hints import Array
+
+ActivationFunction = Callable[[ArrayLike], Array]
+ActivationFunctionLike = str | ActivationFunction
+
+
+class RegisteredActivationFunction(Registry):
+    @abstractmethod
+    def __call__(self, x: ArrayLike) -> Array: ...
+
+
+class Identity(RegisteredActivationFunction):
+    def __call__(self, x: ArrayLike) -> Array:
+        return np.asarray(x, dtype=np.float64)
+
+    def __repr__(self) -> str:
+        return "Identity()"
+
+
+class Sigmoid(RegisteredActivationFunction):
+    def __init__(self, lower: float = 0.0, upper: float = 1.0, shape: float = 1.0):
+        self._lower = lower
+        self._upper = upper
+        self._shape = shape
+
+    def __call__(self, x: ArrayLike) -> Array:
+        x = np.asarray(x, dtype=np.float64)
+        return self._lower + (self._upper - self._lower) / (
+            1 + np.exp(-self._shape * x)
+        )
+
+    def __repr__(self) -> str:
+        return f"Sigmoid(lower={self._lower}, upper={self._upper}, shape={self._shape})"
+
+
+class ReLU(RegisteredActivationFunction):
+    def __call__(self, x: ArrayLike) -> Array:
+        return np.maximum(0, x)
+
+    def __repr__(self) -> str:
+        return "ReLU()"
+
+
+class Softplus(RegisteredActivationFunction):
+    def __call__(self, x: ArrayLike) -> Array:
+        return np.log1p(np.exp(x))
+
+    def __repr__(self) -> str:
+        return "Softplus()"
+
+
+class Tanh(RegisteredActivationFunction):
+    def __call__(self, x: ArrayLike) -> Array:
+        return np.tanh(x)
+
+    def __repr__(self) -> str:
+        return "Tanh()"
+
+
+def as_activation_function(
+    activation: ActivationFunctionLike,
+) -> ActivationFunction:
+    if isinstance(activation, str):
+        return RegisteredActivationFunction[activation]()
+    return activation

bella_companion-0.1.20/src/bella_companion/backend/mlp.py

@@ -0,0 +1,284 @@
+from collections.abc import Iterator
+from pathlib import Path
+
+import numpy as np
+from joblib import Parallel, delayed
+from numpy.typing import ArrayLike
+from tqdm import tqdm
+
+from bella_companion.backend.activation_functions import (
+    ActivationFunctionLike,
+    as_activation_function,
+)
+from bella_companion.backend.type_hints import Array, Weights
+from bella_companion.backend.utils import read_weights
+
+
+class MLP:
+    def __init__(
+        self,
+        weights: Weights,
+        hidden_activation: ActivationFunctionLike = "relu",
+        output_activation: ActivationFunctionLike = "sigmoid",
+    ):
+        """
+        Initialize the MLP with given weights and activation functions.
+
+        Parameters
+        ----------
+        weights : Weights
+            A list of weight matrices for each layer in the MLP.
+            The length of the list determines the number of layers.
+            The shape of each weight matrix should be (n_inputs + 1, n_outputs),
+            where n_inputs is the number of inputs to the layer (excluding bias)
+            and n_outputs is the number of outputs from the layer.
+        hidden_activation : ActivationFunctionLike, optional
+            Activation function to use for hidden layers, by default "relu".
+        output_activation : ActivationFunctionLike, optional
+            Activation function to use for the output layer, by default "sigmoid".
+
+        Raises
+        ------
+        ValueError
+            If the output layer does not have a single output neuron.
+        """
+        if weights[-1].shape[1] != 1:
+            raise ValueError("Output layer must have a single output neuron.")
+
+        self._weights = weights
+        self._hidden_activation = as_activation_function(activation=hidden_activation)
+        self._output_activation = as_activation_function(activation=output_activation)
+        self._activations = [self._hidden_activation] * (self.n_layers - 1) + [
+            self._output_activation
+        ]
+
+    @property
+    def n_layers(self) -> int:
+        return len(self._weights)
+
+    def forward(self, inputs: ArrayLike) -> Array:
+        """
+        Perform a forward pass through the MLP.
+
+        Parameters
+        ----------
+        inputs : ArrayLike
+            Input data of shape (n_samples, n_features).
+
+        Returns
+        -------
+        Array
+            The output of the MLP after the forward pass, of shape (n_samples,).
+        """
+        x = np.asarray(inputs, dtype=np.float64)
+        n_samples, _ = x.shape
+        for layer_weights, activation in zip(self._weights, self._activations):
+            bias = np.ones((n_samples, 1))
+            x = np.hstack((bias, x))
+            x = np.dot(x, layer_weights)
+            x = activation(x)
+        return x.flatten()
+
+    def __call__(self, inputs: ArrayLike) -> Array:
+        return self.forward(inputs)
+
+    def __repr__(self) -> str:
+        return (
+            f"MLP(n_layers={self.n_layers}, "
+            f"hidden_activation={self._hidden_activation}, "
+            f"output_activation={self._output_activation})"
+        )
+
+
+class MLPEnsemble:
+    def __init__(
+        self,
+        weights_list: list[Weights],
+        hidden_activation: ActivationFunctionLike = "relu",
+        output_activation: ActivationFunctionLike = "sigmoid",
+    ):
+        """
+        Initialize the MLP ensemble with given weights and activation functions.
+
+        Parameters
+        ----------
+        weights_list : list[Weights]
+            A list of weight sets, where each set corresponds to an MLP in the ensemble.
+        hidden_activation : ActivationFunctionLike, optional
+            Activation function to use for hidden layers, by default "relu".
+        output_activation : ActivationFunctionLike, optional
+            Activation function to use for the output layer, by default "sigmoid".
+        """
+        self._mlps = [
+            MLP(
+                weights=weights,
+                hidden_activation=hidden_activation,
+                output_activation=output_activation,
+            )
+            for weights in weights_list
+        ]
+
+    @property
+    def n_models(self) -> int:
+        return len(self._mlps)
+
+    @property
+    def mlps(self) -> tuple[MLP, ...]:
+        return tuple(self._mlps)
+
+    def forward(
+        self,
+        inputs: ArrayLike,  # (n_samples, n_features)
+    ) -> Array:  # (n_models, n_samples)
+        """
+        Perform a forward pass through the MLP ensemble.
+
+        Parameters
+        ----------
+        inputs : ArrayLike
+            Input data of shape (n_samples, n_features).
+
+        Returns
+        -------
+        Array
+            The outputs of the MLP ensemble after the forward pass,
+            of shape (n_models, n_samples).
+        """
+        return np.array([mlp(inputs) for mlp in self._mlps])
+
+    def forward_median(
+        self,
+        inputs: ArrayLike,  # (n_samples, n_features)
+    ) -> Array:  # (n_samples,)
+        """
+        Perform a forward pass through the MLP ensemble and compute the median output.
+
+        Parameters
+        ----------
+        inputs : ArrayLike
+            Input data of shape (n_samples, n_features).
+
+        Returns
+        -------
+        Array
+            The median output of the MLP ensemble after the forward pass,
+            of shape (n_samples,).
+        """
+        outputs = self.forward(inputs)  # (n_models, n_samples)
+        return np.median(outputs, axis=0)  # (n_samples,)
+
+    @classmethod
+    def from_log_file(
+        cls,
+        log_file: str | Path,
+        target_name: str,
+        burn_in: int | float = 0.1,
+        n_samples: int | None = 100,
+        random_seed: int | None = 42,
+        hidden_activation: ActivationFunctionLike = "relu",
+        output_activation: ActivationFunctionLike = "sigmoid",
+    ) -> "MLPEnsemble":
+        """
+        Create an MLPEnsemble instance from a BEAST log file.
+
+        Parameters
+        ----------
+        log_file : str | Path
+            Path to the BEAST log file.
+        target_name : str
+            The target variable name for which to extract weights.
+        burn_in : int | float, optional
+            If int, number of initial samples to discard.
+            If float, fraction of samples to discard, by default 0.1.
+        n_samples : int | None, optional
+            Number of weight samples to return, by default 100.
+            If None, returns all available samples after burn-in.
+        random_seed : int | None, optional
+            Random seed for sampling weights when n_samples is specified, by default 42.
+        hidden_activation : ActivationFunctionLike, optional
+            Activation function to use for hidden layers, by default "relu".
+        output_activation : ActivationFunctionLike, optional
+            Activation function to use for the output layer, by default "sigmoid".
+
+        Returns
+        -------
+        MLPEnsemble
+            An instance of MLPEnsemble initialized with weights from the log file.
+        """
+        weights_list = read_weights(
+            log_file=log_file,
+            burn_in=burn_in,
+            n_samples=n_samples,
+            random_seed=random_seed,
+        )
+        return cls(
+            weights_list=weights_list[target_name],
+            hidden_activation=hidden_activation,
+            output_activation=output_activation,
+        )
+
+    def __call__(self, inputs: ArrayLike) -> Array:
+        return self.forward(inputs)
+
+    def __len__(self) -> int:
+        return self.n_models
+
+    def __iter__(self) -> Iterator[MLP]:
+        return iter(self._mlps)
+
+    def __repr__(self) -> str:
+        return f"MLPEnsemble(n_models={self.n_models})"
+
+
+def mlp_ensembles_from_logs_dir(
+    logs_dir: str | Path,
+    target_name: str,
+    burn_in: int | float = 0.1,
+    n_samples: int | None = 100,
+    random_seed: int | None = 42,
+    hidden_activation: ActivationFunctionLike = "relu",
+    output_activation: ActivationFunctionLike = "sigmoid",
+    n_jobs: int = -1,
+) -> list[MLPEnsemble]:
+    """
+    Create a list of MLPEnsemble instances from all BEAST log files in a directory.
+
+    Parameters
+    ----------
+    logs_dir : str | Path
+        Path to the directory containing BEAST log files.
+    target_name : str
+        The target variable name for which to extract weights.
+    burn_in : int | float, optional
+        If int, number of initial samples to discard.
+        If float, fraction of samples to discard, by default 0.1.
+    n_samples : int | None, optional
+        Number of weight samples to return, by default 100.
+        If None, returns all available samples after burn-in.
+    random_seed : int | None, optional
+        Random seed for sampling weights when n_samples is specified, by default 42.
+    hidden_activation : ActivationFunctionLike, optional
+        Activation function to use for hidden layers, by default "relu".
+    output_activation : ActivationFunctionLike, optional
+        Activation function to use for the output layer, by default "sigmoid".
+    n_jobs : int, optional
+        Number of parallel jobs to use, by default -1 (use all available cores).
+
+    Returns
+    -------
+    list[MLPEnsemble]
+        A list of MLPEnsemble instances initialized with weights from the log files.
+    """
+    log_files = list(Path(logs_dir).glob("*.log"))
+    return Parallel(n_jobs=n_jobs)(
+        delayed(MLPEnsemble.from_log_file)(
+            log_file=log_file,
+            target_name=target_name,
+            burn_in=burn_in,
+            n_samples=n_samples,
+            random_seed=random_seed,
+            hidden_activation=hidden_activation,
+            output_activation=output_activation,
+        )
+        for log_file in tqdm(log_files, desc="Loading MLP ensembles from logs")
+    )

bella_companion-0.1.20/src/bella_companion/backend/plots.py

@@ -0,0 +1,167 @@
+from typing import Any
+
+import matplotlib.pyplot as plt
+import numpy as np
+from matplotlib.axes import Axes
+from numpy.typing import ArrayLike
+
+Color = (
+    str
+    | np.typing.NDArray[np.floating]
+    | tuple[float, float, float]
+    | tuple[float, float, float, float]
+)
+
+
+def skyline_plot(
+    data: ArrayLike,
+    x: ArrayLike | None = None,
+    ax: Axes | None = None,
+    step_kwargs: dict[str, Any] | None = None,
+) -> Axes:
+    """
+    Plot a skyline (step) plot.
+
+    Parameters
+    ----------
+    data : ArrayLike
+        The y values for the skyline plot, of shape (n_points,).
+    x : ArrayLike | None, optional
+        The x values, of shape (n_points + 1,), by default None (uses indices).
+        The first x value corresponds to the start of the first step, the
+        last x value corresponds to the end of the last step.
+    ax : Axes | None, optional
+        The matplotlib Axes to plot on, by default None (uses current Axes).
+    step_kwargs : dict[str, Any] | None, optional
+        Additional keyword arguments for the step plot, by default None.
+
+    Returns
+    -------
+    Axes
+        The matplotlib Axes with the plot.
+    """
+    data = np.asarray(data, dtype=np.float64)
+    data = [data[0], *data]
+
+    if ax is None:
+        ax = plt.gca()
+    if x is None:
+        x = list(range(len(data)))
+    if step_kwargs is None:
+        step_kwargs = {}
+
+    ax.step(x, data, **(step_kwargs or {}))  # pyright: ignore
+    return ax
+
+
+def ribbon_plot(
+    y: ArrayLike,
+    x: ArrayLike | None = None,
+    color: Color | None = None,
+    label: str | None = None,
+    ax: Axes | None = None,
+    skyline: bool = False,
+    lower_percentile: float = 2.5,
+    upper_percentile: float = 97.5,
+    show_fill: bool = True,
+    fill_kwargs: dict[str, Any] | None = None,
+    show_samples: bool = True,
+    samples_kwargs: dict[str, Any] | None = None,
+    show_median: bool = True,
+    median_kwargs: dict[str, Any] | None = None,
+) -> Axes:
+    """
+    Plot a ribbon plot with uncertainty intervals.
+
+    Parameters
+    ----------
+    y : ArrayLike
+        The y values, of shape (n_samples, n_points).
+    x : ArrayLike | None, optional
+        The x values, by default None (uses indices).
+        If skyline is True, x should have shape (n_points + 1,),
+        where the first x value corresponds to the start of the first step,
+        the last x value corresponds to the end of the last step.
+        If skyline is False, x should have shape (n_points,).
+    color : str | None, optional
+        The color for the plot, by default None.
+    label : str | None, optional
+        The label for the median line, by default None.
+    ax : Axes | None, optional
+        The matplotlib Axes to plot on, by default None (uses current Axes).
+    skyline : bool, optional
+        Whether to use a skyline (step) plot, by default False.
+    lower_percentile : float, optional
+        The lower percentile for the percentile interval, by default 2.5.
+    upper_percentile : float, optional
+        The upper percentile for the percentile interval, by default 97.5.
+    show_fill : bool, optional
+        Whether to show the percentile interval fill, by default True.
+    fill_kwargs : dict[str, Any] | None, optional
+        Additional keyword arguments for the fill_between call, by default None.
+    show_samples : bool, optional
+        Whether to show individual sample lines, by default True.
+    samples_kwargs : dict[str, Any] | None, optional
+        Additional keyword arguments for the sample lines, by default None.
+    show_median : bool, optional
+        Whether to show the median line, by default True.
+    median_kwargs : dict[str, Any] | None, optional
+        Additional keyword arguments for the median line, by default None.
+
+    Returns
+    -------
+    Axes
+        The matplotlib Axes with the plot.
+    """
+    if ax is None:
+        ax = plt.gca()
+
+    y = np.asarray(y, dtype=np.float64)
+    if x is None:
+        _, n_points = y.shape
+        if skyline:
+            n_points += 1
+        x = list(range(n_points))
+
+    if show_fill:
+        lower = np.percentile(y, lower_percentile, axis=0)
+        high = np.percentile(y, upper_percentile, axis=0)
+        if fill_kwargs is None:
+            fill_kwargs = {}
+        if "alpha" not in fill_kwargs:
+            fill_kwargs["alpha"] = 0.25
+        if "color" not in fill_kwargs:
+            fill_kwargs["color"] = color
+        if skyline:
+            fill_kwargs["step"] = "pre"
+            lower = [lower[0], *lower]
+            high = [high[0], *high]
+        ax.fill_between(x, lower, high, **fill_kwargs)  # pyright: ignore
+
+    if show_samples:
+        if samples_kwargs is None:
+            samples_kwargs = {}
+        if "alpha" not in samples_kwargs:
+            samples_kwargs["alpha"] = 0.25
+        if "color" not in samples_kwargs:
+            samples_kwargs["color"] = color
+        for sample_y in y:
+            if skyline:
+                skyline_plot(data=sample_y, x=x, ax=ax, step_kwargs=samples_kwargs)
+            else:
+                ax.plot(x, sample_y, **samples_kwargs)  # pyright: ignore
+
+    if show_median:
+        median = np.median(y, axis=0)
+        if median_kwargs is None:
+            median_kwargs = {}
+        if "color" not in median_kwargs:
+            median_kwargs["color"] = color
+        if "label" not in median_kwargs:
+            median_kwargs["label"] = label
+        if skyline:
+            skyline_plot(data=median, x=x, ax=ax, step_kwargs=median_kwargs)
+        else:
+            ax.plot(x, median, **median_kwargs)  # pyright: ignore
+
+    return ax

bella_companion-0.1.20/src/bella_companion/backend/type_hints.py

@@ -0,0 +1,8 @@
+from collections.abc import Callable
+
+import numpy as np
+from numpy.typing import ArrayLike
+
+Array = np.typing.NDArray[np.float64]
+Weights = list[Array]
+Model = Callable[[ArrayLike], Array]