adstk 0.0.1__py3-none-any.whl

adstk/__init__.py

@@ -0,0 +1,10 @@
+"""adstk - Actuarial Data Science Toolkit (for Python)
+
+    ADSTK aims to bundle together relevant actuarial models, tools and code simplifications to enrich the insurance Data Science experience in the Python ecosystem.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

adstk/inspect/__init__.py

@@ -0,0 +1,8 @@
+"""adstk.inspect: model inspection utilities."""
+
+from .ice import create_ice_curves, plot_ice_curves
+
+__all__ = [
+    "create_ice_curves",
+    "plot_ice_curves"
+]

adstk/inspect/ice.py

@@ -0,0 +1,164 @@
+"""Individual Conditional Expectation (ICE) curves.
+
+Individual Conditional Expectation (ICE) curves show how a fitted model's
+prediction for a single instance changes as one feature is varied while
+all other features are held fixed. Averaging ICE curves across instances
+recovers the Partial Dependence Plot (PDP).
+
+Part of ``adstk.inspect``. Public API:
+
+- :func:`create_ice_curves` computes the raw ICE curve data.
+- :func:`plot_ice_curves` computes ICE curves for one or more features
+  and renders them, overlaying the PDP.
+"""
+
+from __future__ import annotations
+
+from typing import Optional, Sequence, Tuple
+
+import numpy as np
+import pandas as pd
+
+
+def create_ice_curves(
+    model,
+    X: pd.DataFrame,
+    feature_name: str,
+    n_points: int = 50,
+    feature_range: Optional[Tuple[float, float]] = None,
+) -> Tuple[np.ndarray, np.ndarray]:
+    """Compute Individual Conditional Expectation (ICE) curves.
+
+    For every row in ``X``, ``feature_name`` is swept across ``n_points``
+    values spanning ``feature_range`` (or the observed min/max) while all
+    other feature values are held at their originally observed values,
+    and the model's prediction is recorded at each point.
+
+    Parameters
+    ----------
+    model : object
+        A fitted estimator exposing ``predict(X: np.ndarray) -> np.ndarray``.
+    X : pandas.DataFrame
+        Instances to compute curves for, with columns in the same order
+        the model expects.
+    feature_name : str
+        Column of ``X`` to vary.
+    n_points : int, default=50
+        Number of grid points to evaluate the feature at.
+    feature_range : tuple(float, float), optional
+        ``(min, max)`` to sweep over. Defaults to the observed range of
+        ``feature_name`` in ``X``.
+
+    Returns
+    -------
+    feature_values : numpy.ndarray, shape (n_points,)
+        The grid ``feature_name`` was evaluated at.
+    ice_curves : numpy.ndarray, shape (len(X), n_points)
+        ``ice_curves[i, j]`` is the prediction for row ``i`` of ``X``
+        with ``feature_name`` fixed at ``feature_values[j]``.
+
+    Raises
+    ------
+    KeyError
+        If ``feature_name`` is not a column of ``X``.
+    ValueError
+        If ``X`` has no rows, or ``feature_range`` is decreasing.
+    """
+    if feature_name not in X.columns:
+        raise KeyError(
+            f"'{feature_name}' is not a column of X. "
+            f"Available columns: {list(X.columns)}"
+        )
+    if len(X) == 0:
+        raise ValueError("X must contain at least one row.")
+
+    if feature_range is None:
+        feature_min = X[feature_name].min()
+        feature_max = X[feature_name].max()
+    else:
+        feature_min, feature_max = feature_range
+    if feature_min > feature_max:
+        raise ValueError(
+            f"feature_range must not be decreasing, got ({feature_min}, {feature_max})."
+        )
+
+    feature_values = np.linspace(feature_min, feature_max, n_points)
+
+    n_samples = len(X)
+    feature_idx = X.columns.get_loc(feature_name)
+
+    # Build a single batch of (n_samples * n_points) modified rows so
+    # predict() is called once instead of n_samples * n_points times.
+    # This is the main cost driver for ICE curves at any real n_points.
+    batch = np.repeat(X.to_numpy(), n_points, axis=0)
+    batch[:, feature_idx] = np.tile(feature_values, n_samples)
+
+    predictions = np.asarray(model.predict(batch)).reshape(n_samples, n_points)
+
+    return feature_values, predictions
+
+
+def plot_ice_curves(
+    model,
+    X: pd.DataFrame,
+    feature_list: Sequence[str],
+    n_points: int = 50,
+    n_ice_lines: int = 25,
+    random_state: Optional[int] = None,
+):
+    """Plot ICE curves (with overlaid PDP) for one or more features.
+
+    Parameters
+    ----------
+    model : object
+        A fitted estimator exposing ``predict``.
+    X : pandas.DataFrame
+        Instances to compute curves for. Pass a sample rather than the
+        full dataset -- cost scales with ``len(X) * n_points``.
+    feature_list : sequence of str
+        Feature columns to plot, one subplot each.
+    n_points : int, default=50
+        Grid resolution per feature.
+    n_ice_lines : int, default=25
+        Number of individual ICE curves to draw per subplot (drawing
+        all of ``len(X)`` gets unreadable fast).
+    random_state : int, optional
+        Seed controlling which instances are sampled for display.
+
+    Returns
+    -------
+    fig : matplotlib.figure.Figure
+    axes : numpy.ndarray of matplotlib.axes.Axes
+    """
+    try:
+        import matplotlib.pyplot as plt
+    except ImportError as exc:  # pragma: no cover
+        raise ImportError(
+            "plot_ice_curves requires matplotlib. Install it with "
+            "`pip install matplotlib`."
+        ) from exc
+
+    rng = np.random.default_rng(random_state)
+
+    fig, axes = plt.subplots(1, len(feature_list), figsize=(5 * len(feature_list), 4))
+    axes = np.atleast_1d(axes)
+
+    for ax, feature in zip(axes, feature_list):
+        feature_vals, ice_data = create_ice_curves(model, X, feature, n_points)
+
+        n_lines = min(n_ice_lines, len(ice_data))
+        sample_indices = rng.choice(len(ice_data), n_lines, replace=False)
+        for idx in sample_indices:
+            ax.plot(feature_vals, ice_data[idx], alpha=0.4, color="tab:blue", linewidth=1)
+
+        pdp = np.mean(ice_data, axis=0)
+        ax.plot(feature_vals, pdp, color="tab:red", linewidth=2, label="PDP")
+
+        ax.set_xlabel(feature)
+        ax.set_ylabel("Prediction")
+        ax.set_title(f"ICE: {feature}")
+        ax.grid(True, alpha=0.3)
+        ax.legend()
+
+    fig.tight_layout()
+    return fig, axes

adstk-0.0.1.dist-info/METADATA

@@ -0,0 +1,107 @@
+Metadata-Version: 2.5
+Name: adstk
+Version: 0.0.1
+Summary: ADSTK aims to bundle together relevant actuarial models, tools and code simplifications to enrich the Actuarial / Insurance Data Science experience in the Python ecosystem.
+Project-URL: Homepage, https://codeberg.org/ftranschel/adstk
+Project-URL: Repository, https://codeberg.org/ftranschel/adstk
+Project-URL: Issues, https://codeberg.org/ftranschel/adstk/issues
+Project-URL: Documentation, https://ftranschel.codeberg.page/adstk/
+Author-email: Fabian Transchel <ftranschel@hs-harz.de>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: actuarial,aktuariat,data science,inspection,insurance,pricing,telematics
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=1.5
+Requires-Dist: scipy>=1.10
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.25; extra == 'docs'
+Provides-Extra: test
+Requires-Dist: matplotlib; extra == 'test'
+Requires-Dist: pytest; extra == 'test'
+Requires-Dist: pytest-cov; extra == 'test'
+Requires-Dist: scikit-learn; extra == 'test'
+Description-Content-Type: text/markdown
+
+# adstk
+
+ADSTK aims to bundle together relevant actuarial models, tools and code simplifications to enrich the Actuarial / Insurance Data Science experience in the Python ecosystem.
+---
+
+## Features
+
+ADSTK currently ships with a limited number of methods and use cases:
+
+* Partial dependence display with support for individual conditional expectation curves (ICE)
+
+### Dependencies
+
+adstk requires:
+
+- Python (>= 3.10)
+- NumPy (>= 1.24)
+- SciPy (>= 1.10)
+
+Optional requirements for plotting etc.
+
+- matplotlib ()
+- plotly ()
+
+### User installation
+
+The easiest way to install adstk will using `pip` once we publish on PyPi:
+
+    pip install -U adstk
+
+## Changelog
+
+See the [changelog](CHANGELOG.md) for a history of notable changes to adstk.
+
+## Development
+
+We welcome human contributors of all experience levels. The adstk community
+goals are to be helpful, welcoming, and effective. The
+[Contributing guide](CONTRIBUTING.md) has detailed information about
+contributing code, documentation, tests, and more. Please also note our
+[AI contribution policy](AGENTS.md) before submitting anything.
+
+### Important links
+
+- Official source code repo: https://codeberg.org/ftranschel/adstk
+- Download releases: https://pypi.org/project/adstk/
+- Issue tracker: https://codeberg.org/ftranschel/adstk/issues
+
+### Source code
+
+You can check the latest sources with the command:
+
+    git clone https://codeberg.org/ftranschel/adstk.git
+
+### Contributing
+
+To learn more about making a contribution to adstk, please see our
+[Contributing guide](CONTRIBUTING.md).
+
+### Testing
+
+After installation, you can launch the test suite from the source
+directory (you will need `pytest` installed):
+
+    pytest
+
+### Submitting a Pull Request
+
+Before opening a pull request, please read the
+[Contributing guide](CONTRIBUTING.md) and our [AI policy](AGENTS.md) to
+make sure your submission complies with our guidelines.

adstk-0.0.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+adstk/__init__.py,sha256=i1s3uKNCDPNGDrwjRwbGcTRwbVbf3Oe7LTXIUVjNRT8,311
+adstk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+adstk/inspect/__init__.py,sha256=nr4ahX1CCr-dHBCBFhJxXz1RpBCI60ZS5ziC6mGu7C4,164
+adstk/inspect/ice.py,sha256=Hv0Nf-AAnDjZSGY2ms_cLj5THUxoufQinDF716lZfgg,5597
+adstk-0.0.1.dist-info/METADATA,sha256=MtNTh4hwcmV-4Dtzwa9JCF2ltWHy7hQtq7S3Sc5KTeg,3526
+adstk-0.0.1.dist-info/WHEEL,sha256=THafob7ofN-NsuMN7Mg4qZyHaQI7KkD-QlcQatYhXPo,87
+adstk-0.0.1.dist-info/licenses/LICENSE,sha256=5aeYhO-7OQsJ9KjaxWdN8JYQ8YarQr700N15fdtejp4,1067
+adstk-0.0.1.dist-info/RECORD,,

adstk-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.3
+Root-Is-Purelib: true
+Tag: py3-none-any

adstk-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2026 ftranschel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
+LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+USE OR OTHER DEALINGS IN THE SOFTWARE.