adstk 0.0.1__tar.gz

adstk-0.0.1/.forgejo/workflows/ci.yaml

@@ -0,0 +1,22 @@
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: docker
+    steps:
+      - uses: actions/checkout@v4
+      - run: pip install ".[dev]"
+      - run: ruff check .
+      - run: mypy src/
+      - run: pytest
+
+  docs:
+    runs-on: docker
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+      - run: pip install ".[docs]"
+      - run: mkdocs build --strict

adstk-0.0.1/.gitignore

@@ -0,0 +1,236 @@
+# ---> Python
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+# ---> JupyterNotebooks
+# gitignore template for Jupyter Notebooks
+# website: http://jupyter.org/
+
+.ipynb_checkpoints
+*/.ipynb_checkpoints/*
+
+# IPython
+profile_default/
+ipython_config.py
+
+# Jupyter lab virtual documents
+# https://jupyterlab-lsp.readthedocs.io/en/2.x/Configuring.html#virtual_documents_dir
+.virtual_documents/
+
+# Remove previous ipynb_checkpoints
+#   git rm -r .ipynb_checkpoints/
+

adstk-0.0.1/AGENTS.md

@@ -0,0 +1,26 @@
+# AGENTS.md
+
+This document outlines the  AI policy of the ADSTK project at https://codeberg.org/ftranschel/adstk
+
+## General guidelines
+
+- No automated LLM PRs and bug reports. All submissions to the project have to go through a human. We expect that the human reporter / puller fully understands every single bit of their submission. If we find that not to be the case, the issue/PR in question will be diuscarded. (Yes, even if a hypothetical bug report is valid per se.)
+- If you submit code that is partly LLM-generated, we expect full disclosure. If we find violations of this, we will revoke access and, quite possibly, remove the submission(s).
+
+## AGENTS Instruction
+
+This file contains additional guidance for AI agents and other AI editors.
+
+**REQUIRED: AI/Agent Disclosure**
+
+Every summary, pull request description, or work description MUST include this disclosure:
+
+If human review has not occurred (use this initially):
+
+    This pull request includes code written with the assistance of AI. The code has not been reviewed by a human.
+
+This is a mandatory requirement, not optional. Include it at the end of every summary you generate.
+
+## Working on an issue
+
+Before working on any issue, run gh issue view <number> to check current labels. Do not open a PR against an issue labeled "Needs Triage" or another "Needs ..." label. Such PRs get closed without review until a maintainer clears the label.

adstk-0.0.1/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+Nothing worth a mention at all.
+
+## [Unreleased]
+
+### Added
+
+- Created empty project framework for adstk.
+
+## [0.0.1] - Initial Commit
+
+- Initial commit preparing the framework for pull requests of actual models. No PyPI hook yet.

adstk-0.0.1/CITATION.cff

@@ -0,0 +1,10 @@
+cff-version: 1.2.0
+message: "Wenn du adstk in wissenschaftlicher Arbeit nutzt, zitiere es bitte wie folgt:"
+title: "adstk: Actuarial Data Science Toolkit"
+version: 0.0.1
+date-released: 2026-09-17
+authors:
+  - family-names: "Transchel"
+    given-names: "Fabian"
+url: "https://codeberg.org/ftranschel/adstk"
+license: MIT

adstk-0.0.1/CODE_OF_CONDUCT.md

@@ -0,0 +1,25 @@
+# adstk code of conduct
+
+The aim of this CoC: Maximal inclusivity for humans, clear guardrails for agents and LLM submissions. Zero tolerance for misconduct of any kind.
+
+## Expected conduct
+
+- Be respectful and constructive in PRs, issues and all other interactions.
+- Be constructive w.r.t. the code. No ad hominems.
+
+## Inacceptable conduct
+
+- No insults and offenses.
+- No discrimination.
+
+## AI policy
+
+- No automated LLM PRs and bug reports. All submissions to the project have to go through a human. We expect that the human reporter / puller fully understands every single bit of their submission. If we find that not to be the case, the issue/PR in question will be diuscarded. (Yes, even if a hypothetical bug report is valid per se.)
+- If you submit code that is partly LLM-generated, we expect full disclosure. If we find violations of this, we will revoke access and, quite possibly, remove the submission(s).
+
+## Violations to this CoC
+
+Infractions are to be pointed at ftranschel@hs-harz.de.
+Dealings are confidential unless otherwise required.
+
+The codex is based on [Contributor Covenant](https://www.contributor-covenant.org/). All changes are our own interpretation of the aims and guidelines formulated therein.

adstk-0.0.1/CONTRIBUTING.md

@@ -0,0 +1,60 @@
+# Contributing to adstk
+
+We appreciate submissions to adstk as long as they allow progress for both the actuarial profession as well as the package scope and health.
+
+Here's how to help:
+
+## Setup
+
+```bash
+git clone https://codeberg.org/ftranschel/adstk.git
+cd adstk
+python -m venv .venv
+source .venv/bin/activate   # Windows: .venv\Scripts\activate
+pip install -e ".[dev,docs]"
+```
+
+## Tests & Lint lokal ausführen
+
+```bash
+pytest
+ruff check .
+mypy src/
+```
+
+## Contributing a new model
+
+1. Open an issue using the "Model request" template (or pick up an
+   existing one), including a professional reference (paper, textbook, standard).
+2. Create a new submodule under `src/adstk/<area>/` (e.g.
+   `src/adstk/explain/`, `src/adstk/telematics/` - depending on the topic area).
+3. Use NumPy-style docstrings (including the formula, parameters, returns,
+   examples) - this automatically generates the API documentation.
+4. Add tests under `tests/`, in particular numerical reference values
+   checked against an independent source (textbook, R package, etc.).
+5. Open a pull request. Note: any LLM involvement in your submission must
+   be fully disclosed - see [AGENTS.md](AGENTS.md).
+
+## Docstring style (NumPy format)
+
+```python
+def example(x: float, a: float) -> float:
+    """Short description.
+
+    Parameters
+    ----------
+    x : float
+        Description.
+    a : float
+        Description.
+
+    Returns
+    -------
+    float
+        Description.
+    """
+```
+
+## Verhaltenskodex
+
+Please follow our [Code of Conduct](CODE_OF_CONDUCT.md).

adstk-0.0.1/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.

adstk-0.0.1/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,71 @@
+# 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/docs/index.md

@@ -0,0 +1,13 @@
+# adstk
+
+Aktuarielle Modelle für Python - Bausteine, die im Python-Ökosystem
+bislang fehlen oder nur unvollständig implementiert sind.
+
+## Erste Schritte
+
+```bash
+pip install adstk
+```
+
+Die API-Referenz wird automatisch aus den Docstrings im Quellcode
+generiert (siehe `docs/api/`), sobald erste Module implementiert sind.

adstk-0.0.1/examples/README.md

@@ -0,0 +1,3 @@
+# Beispiele
+
+Hier folgen ausführlichere Beispiele/Notebooks zur Nutzung von adstk.

adstk-0.0.1/examples/plot_ice_curves.py

@@ -0,0 +1,69 @@
+"""
+ICE curves for model inspection
+================================
+
+This example shows how to compute and plot Individual Conditional
+Expectation (ICE) curves with :func:`adstk.inspect.create_ice_curves`
+and :func:`adstk.inspect.plot_ice_curves`.
+
+ICE curves show how a fitted model's prediction for a *single*
+instance changes as one feature is varied while every other feature is
+held fixed. Averaging ICE curves across instances recovers the
+Partial Dependence Plot (PDP).
+"""
+
+# %%
+# Fit a model on synthetic data
+# ------------------------------
+# We use a small toy marketing-mix-style dataset: spend on two
+# channels and a price, predicting some outcome.
+
+import numpy as np
+import pandas as pd
+from sklearn.ensemble import RandomForestRegressor
+
+from adstk.inspect import create_ice_curves, plot_ice_curves
+
+rng = np.random.default_rng(0)
+n_samples = 200
+X = pd.DataFrame(
+    {
+        "tv_spend": rng.uniform(0, 100, n_samples),
+        "social_spend": rng.uniform(0, 50, n_samples),
+        "price": rng.uniform(10, 30, n_samples),
+    }
+)
+y = (
+    0.8 * X["tv_spend"]
+    + 1.2 * X["social_spend"]
+    - 2.0 * X["price"]
+    + rng.normal(0, 5, n_samples)
+)
+
+model = RandomForestRegressor(n_estimators=100, random_state=0).fit(X, y)
+
+# %%
+# Compute raw ICE curve data for a single feature
+# -------------------------------------------------
+# ``create_ice_curves`` returns the grid of swept feature values and a
+# ``(n_instances, n_points)`` array of predictions -- one row per
+# instance, one column per grid point.
+
+sample = X.sample(30, random_state=0)
+feature_values, ice_curves = create_ice_curves(model, sample, "tv_spend")
+print(f"feature_values shape: {feature_values.shape}")
+print(f"ice_curves shape: {ice_curves.shape}")
+
+# %%
+# Plot ICE curves and the PDP for several features
+# ---------------------------------------------------
+# ``plot_ice_curves`` computes ICE curves for each feature in
+# ``feature_list`` and plots a sample of the individual curves in blue
+# alongside the averaged PDP in red.
+
+fig, axes = plot_ice_curves(
+    model,
+    sample,
+    feature_list=["tv_spend", "social_spend", "price"],
+    random_state=0,
+)

adstk-0.0.1/mkdocs.yml

@@ -0,0 +1,35 @@
+site_name: adstk
+site_description: Actuarial Data Science Toolkit
+repo_url: https://codeberg.org/ftranschel/adstk
+docs_dir: docs
+
+theme:
+  name: material
+  features:
+    - navigation.sections
+    - content.code.copy
+
+plugins:
+  - search
+  - mkdocstrings:
+      handlers:
+        python:
+          options:
+            docstring_style: numpy
+            show_source: true
+            show_root_heading: true
+
+markdown_extensions:
+  - pymdownx.arithmatex:
+      generic: true
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences
+
+extra_javascript:
+  - https://cdnjs.cloudflare.com/ajax/libs/mathjax/3.2.2/es5/tex-mml-chtml.min.js
+
+nav:
+  - Start: index.md
+  # API-Referenz: Seiten unter docs/api/ ergänzen, sobald erste Module existieren.
+  # Beispiel: "::: paket.modul.funktion" in eine .md-Datei, siehe mkdocstrings-Doku.

adstk-0.0.1/pyproject.toml

@@ -0,0 +1,71 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "adstk"
+version = "0.0.1"
+description = "ADSTK aims to bundle together relevant actuarial models, tools and code simplifications to enrich the Actuarial / Insurance Data Science experience in the Python ecosystem."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Fabian Transchel", email = "ftranschel@hs-harz.de" },
+]
+keywords = ["actuarial", "aktuariat", "pricing", "insurance","inspection","telematics","data science"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Office/Business :: Financial",
+    "Topic :: Scientific/Engineering :: Mathematics",
+    "Typing :: Typed",
+]
+
+dependencies = [
+    "numpy>=1.24",
+    "scipy>=1.10",
+    "pandas>=1.5",       # add this: adstk.inspect needs DataFrame input
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest",
+    "pytest-cov",
+    "matplotlib",
+    "scikit-learn",
+]
+
+docs = [
+    "mkdocs-material>=9.5",
+    "mkdocstrings[python]>=0.25",
+]
+
+[project.urls]
+Homepage = "https://codeberg.org/ftranschel/adstk"
+Repository = "https://codeberg.org/ftranschel/adstk"
+Issues = "https://codeberg.org/ftranschel/adstk/issues"
+Documentation = "https://ftranschel.codeberg.page/adstk/"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/adstk"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+packages = ["adstk"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--cov=adstk --cov-report=term-missing"

adstk-0.0.1/src/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-0.0.1/src/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-0.0.1/src/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/tests/inspect/test_ice.py

@@ -0,0 +1,81 @@
+"""Tests for adstk.inspect.ice."""
+
+import numpy as np
+import pandas as pd
+import pytest
+
+from adstk.inspect.ice import create_ice_curves, plot_ice_curves
+
+
+class _LinearStub:
+    """Deterministic stand-in for a fitted model: predict = row sum."""
+
+    def predict(self, X):
+        return X.sum(axis=1)
+
+
+@pytest.fixture
+def sample_data():
+    return pd.DataFrame(
+        {
+            "a": [0.0, 1.0, 2.0],
+            "b": [10.0, 10.0, 10.0],
+        }
+    )
+
+
+def test_create_ice_curves_shape(sample_data):
+    feature_values, ice_curves = create_ice_curves(_LinearStub(), sample_data, "a", n_points=5)
+    assert feature_values.shape == (5,)
+    assert ice_curves.shape == (len(sample_data), 5)
+
+
+def test_create_ice_curves_default_range_matches_data(sample_data):
+    feature_values, _ = create_ice_curves(_LinearStub(), sample_data, "a", n_points=5)
+    assert feature_values[0] == pytest.approx(sample_data["a"].min())
+    assert feature_values[-1] == pytest.approx(sample_data["a"].max())
+
+
+def test_create_ice_curves_explicit_range(sample_data):
+    feature_values, _ = create_ice_curves(
+        _LinearStub(), sample_data, "a", n_points=5, feature_range=(-5, 5)
+    )
+    assert feature_values[0] == pytest.approx(-5)
+    assert feature_values[-1] == pytest.approx(5)
+
+
+def test_create_ice_curves_values_correct(sample_data):
+    # predict = a + b, and b is fixed at 10 for every row here, so each
+    # ICE curve should equal 10 + the swept 'a' grid exactly, regardless
+    # of that row's original 'a' value.
+    feature_values, ice_curves = create_ice_curves(_LinearStub(), sample_data, "a", n_points=5)
+    expected = 10.0 + feature_values
+    for row in ice_curves:
+        np.testing.assert_allclose(row, expected)
+
+
+def test_create_ice_curves_missing_feature_raises(sample_data):
+    with pytest.raises(KeyError):
+        create_ice_curves(_LinearStub(), sample_data, "does_not_exist")
+
+
+def test_create_ice_curves_empty_X_raises(sample_data):
+    with pytest.raises(ValueError):
+        create_ice_curves(_LinearStub(), sample_data.iloc[0:0], "a")
+
+
+def test_create_ice_curves_invalid_range_raises(sample_data):
+    with pytest.raises(ValueError):
+        create_ice_curves(_LinearStub(), sample_data, "a", feature_range=(5, -5))
+
+
+def test_plot_ice_curves_returns_figure_and_axes(sample_data):
+    matplotlib = pytest.importorskip("matplotlib")
+    matplotlib.use("Agg")  # headless backend for CI
+
+    fig, axes = plot_ice_curves(
+        _LinearStub(), sample_data, feature_list=["a", "b"], n_points=5, random_state=0
+    )
+    assert len(axes) == 2
+    for ax in axes:
+        assert len(ax.lines) >= 1  # at least the PDP line was drawn