alphatonic 0.1.1__tar.gz

alphatonic-0.1.1/.gitignore

@@ -0,0 +1,199 @@
+# 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
+*.lcov
+.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/*
+!.pixi/config.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs/Zensical 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/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Documentation site: `zensical build` writes both
+site/
+.cache/
+
+# The README example writes its tearsheet to the working directory
+/tearsheet.html

alphatonic-0.1.1/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes are listed here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project aims to follow
+[Semantic Versioning](https://semver.org/) once it reaches 1.0.
+
+## [Unreleased]
+
+## [0.1.1] - 2026-10-29
+
+### Added
+
+- alphatonic is on [PyPI](https://pypi.org/project/alphatonic/): install it with
+  `python -m pip install "alphatonic[report]"`.
+
+## [0.1.0] - 2026-10-29
+
+First public version.

alphatonic-0.1.1/CONTRIBUTING.md

@@ -0,0 +1,174 @@
+# Contributing
+
+Bug reports with a minimal, runnable example are welcome. Use
+`alphatonic.demo.synthetic_market` to share an example without market data. For usage questions,
+check the [documentation](README.md) or open an issue.
+
+Statistical changes need a source or a fixed-seed simulation in `tests/test_inference.py`, plus an
+update to [the methodology](docs/explanation/methodology.md). Add a changelog entry for changes
+users would notice. Work on a branch and open a pull request.
+
+By contributing, you agree that your contribution is licensed under the MIT License.
+
+## Set up local development
+
+Local development uses Python 3.13 (`.python-version`); the library supports Python 3.11–3.14. Use
+[uv](https://docs.astral.sh/uv/). Run commands from the repository root:
+
+```sh
+uv sync --all-extras --locked      # create .venv with the dev tools and the report extra
+uv run pytest                      # in parallel, under 40 seconds
+uv run ruff check .
+uv run ruff format --check .
+uv run pyright                     # type-check src/ using Python 3.11 compatibility
+```
+
+Pyright checks `src/` in standard mode using the settings in `pyproject.toml`. The dev group
+includes pandas type stubs. Select the project's `.venv` interpreter in your editor so Pylance uses
+the same dependencies; it also reads the shared Pyright settings.
+
+The tests use synthetic data and temporary directories only. They run with every warning turned into
+an error (`filterwarnings = ["error"]`), so a deprecation in pandas, NumPy or plotly fails the suite
+instead of reaching users.
+
+The suite runs on all cores with [pytest-xdist](https://pytest-xdist.readthedocs.io/) and must
+finish in under 40 seconds. Add `-n 0` to run it in one process, for example with `--pdb`, and
+`--durations=10` to see the slowest tests. Keep new tests fast: use small synthetic panels,
+`time_series={"bootstrap_samples": 0}` when the bootstrap is not under test, and a coarse
+`rolling_step` when the rolling windows are not.
+
+## Where changes belong
+
+| Change | Module | Tests |
+| --- | --- | --- |
+| Options and their validation | `config.py` | `test_config.py` |
+| Input checks, alignment, the evaluation window | `inputs.py` | `test_inputs.py`, `test_calendar.py` |
+| Forward-return labels | `returns.py` | `test_returns.py` |
+| Correlations, HAC, score buckets | `stats.py` | `test_stats.py` |
+| Cross-sectional IC | `cross_section.py` | `test_cross_section.py` |
+| Time-series windows, bootstrap, monthly statistics | `time_series.py` | `test_time_series.py` |
+| Signal persistence | `signal_persistence.py` | `test_signal_persistence.py` |
+| `evaluate`, `Evaluation`, metrics | `evaluation.py` | `test_evaluation.py` |
+| JSON values of results (`to_dict`) | `export.py` | `test_export.py` |
+| Saving and loading | `persistence.py` | `test_persistence.py` |
+| Studies: trials, the holdout, the board | `study.py` | `test_study.py` |
+| The tearsheet | `report/__init__.py`, `report/*figures.py`, `report/templates/` | `test_report.py` |
+| Styles shared by both pages | `report/page.py`, `report/static/` | `test_report.py` |
+| The list of trials and its server | `report/board.py`, `server.py` | `test_server.py` |
+| The `alphatonic` command | `cli.py` | `test_cli.py` |
+| Demo data | `demo.py` | `test_demo.py` |
+| Documentation examples | `docs/` | `test_docs.py` |
+
+Preserve the explicit handling of gaps, ties, constants and unavailable statistics: a statistic that
+cannot be computed is `NaN` with a status, never zero.
+
+## The pages' stylesheet
+
+The tearsheet and the list of trials share one stylesheet, written into each page: [Pico
+CSS](https://picocss.com) followed by `report/static/alphatonic.css`. Pico styles the elements
+themselves, so templates use semantic HTML (`article`, `details`, `nav`, `table`) and add a class
+only where Pico has nothing to say, such as a dense numeric table. Put new rules in
+`alphatonic.css`; never edit the vendored file. The accent colour, royal blue (`#4169e1`), is set
+there by overriding Pico's `--pico-primary` variables, with a lighter tint for dark mode. The
+charts' colours are in `report/figures.py`.
+
+`report/static/pico.classless.min.css` is Pico 2.1.1 from the npm package `@picocss/pico`, with its
+licence beside it as `pico.LICENSE.md`. To update it, download the package tarball from the npm
+registry, check it against the registry's `integrity` hash, copy the same file and the licence,
+change the version in `report/page.py` and `tests/test_report.py`, and look at both pages in a
+browser. Check the study board in light and dark mode; the tearsheet uses a light theme.
+
+## The reference implementation
+
+`tests/reference.py` holds the original, straightforward formulation of the cross-sectional and
+time-series evaluation: one timestamp or window at a time, with pandas. The optimised code in `src/`
+must produce the same tables, and `tests/test_reference_equivalence.py` asserts it on randomised
+data with gaps, ties, delays, constants and varied bucket counts. When you change statistical
+behaviour on purpose, change the reference in the same commit and say so in the pull request. When
+you optimise, leave the reference alone.
+
+`tests/test_inference.py` runs fixed-seed simulations that pin the calibration of the inference: a
+factor without skill must not be declared significant much more often than 5% of the time.
+
+## Supported versions
+
+CI runs the suite on Python 3.11 to 3.14, on the newest dependencies, and on the **lowest**
+supported versions (`uv run --resolution lowest-direct`). When you raise a lower bound in
+`pyproject.toml` say why in the pull request. Run the lowest-bound check locally with:
+
+```sh
+uv run --isolated --resolution lowest-direct --python 3.11 pytest
+```
+
+## Documentation
+
+The site is built with [Zensical](https://zensical.org/) and the API pages are rendered by
+mkdocstrings from docstrings (Google style):
+
+```sh
+uv run --group docs zensical serve            # preview
+uv run --group docs zensical build --strict   # what CI runs
+```
+
+Python code blocks in the root Markdown files and `docs/` are executed by `tests/test_docs.py`, in order, within
+one namespace per page and in a temporary directory. Put `<!-- notest -->` on the line above a block
+that must not run (for example one that needs another library). The structure follows
+[Diátaxis](https://diataxis.fr/): tutorials, how-to guides, reference, explanation. Keep reference
+pages factual, and put reasons in the explanation pages. Tutorials should lead a new user through
+one working example. How-to guides should solve a specific task. Use short, direct sentences and
+British spelling. Check descriptions against the code when editing; a runnable example alone does
+not prove that the surrounding explanation is correct.
+
+### Shared pages
+
+Edit `README.md` for the site home page, `CHANGELOG.md` for the changelog, and this file for
+contributor guidance. The matching pages under `docs/` include these files at build time using
+Zensical's built-in Jinja support. `docs/_includes/` contains symlinks to the three root files;
+it is excluded from site navigation and output. The page filters adapt repository-relative links for the
+site. Use inline Markdown links rather than reference-style links so these filters can adjust them.
+
+The example tests expand the same includes before running code blocks. After changing links,
+build the site with `--strict` and check the rendered destinations. Shared files are watched
+when running `zensical serve`.
+
+## Releasing
+
+A release is a tag `X.Y.Z` on `master`, without a `v` prefix, equal to the version in
+`pyproject.toml`. Pushing the tag runs `.github/workflows/release.yml`, which builds the
+documentation from the tag and publishes it to GitHub Pages at
+<https://mblum.github.io/alphatonic/>, and builds the distributions from the tag and uploads them
+to [PyPI](https://pypi.org/project/alphatonic/). The workflow stops before it publishes anything if
+the tag is not on `master`, does not match the version, or has no section in `CHANGELOG.md`, or if
+the documentation does not build. Tags of any other form, such as `v1.0.0` or `1.0.0rc1`, do not
+start it.
+
+1. On a branch, set the version with `uv version X.Y.Z` (or `uv version --bump minor`), which
+   updates `pyproject.toml` and `uv.lock`. In `CHANGELOG.md`, rename `[Unreleased]` to
+   `[X.Y.Z] - YYYY-MM-DD` and add an empty `[Unreleased]` above it. Open a pull request and
+   merge it once CI is green.
+2. Tag the merge commit on `master` and push the tag:
+
+    ```sh
+    git switch master && git pull --ff-only
+    git tag -a X.Y.Z -m "alphatonic X.Y.Z"
+    git push origin X.Y.Z
+    ```
+
+3. Check that the Release workflow succeeds. If the check or the documentation build fails,
+   nothing has been published: delete the tag (`git push --delete origin X.Y.Z`, then
+   `git tag -d X.Y.Z`), fix the cause on `master` and tag again. If the deployment or the upload
+   fails, fix the settings below and re-run the failed jobs. PyPI never accepts a version twice,
+   even after it is deleted, so once the upload has succeeded a fix needs a new version.
+
+GitHub Pages needs two settings, made once by a repository admin. Under **Settings → Pages**, set
+the source to **GitHub Actions**. Under **Settings → Environments → github-pages**, add a
+deployment tag rule `[0-9]*.[0-9]*.[0-9]*`: by default the environment accepts deployments only
+from `master`, and it rejects the tag.
+
+The upload uses [trusted publishing](https://docs.pypi.org/trusted-publishers/), so the
+repository keeps no PyPI token. On PyPI, add a GitHub publisher with owner `mblum`, repository
+`alphatonic`, workflow `release.yml` and environment `pypi`. Before the first release the project
+does not exist yet, so add it as a pending publisher at
+<https://pypi.org/manage/account/publishing/>; later, a project owner manages it under the
+project's **Publishing** settings. In GitHub, under **Settings → Environments**, create the
+environment `pypi` and give it the same deployment tag rule, so that only release tags can upload.

alphatonic-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Manuel Blum
+
+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.

alphatonic-0.1.1/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.5
+Name: alphatonic
+Version: 0.1.1
+Summary: Evaluate predictive signals with cross-sectional and time-series information coefficients, dependence-aware uncertainty, and offline tearsheets.
+Project-URL: Homepage, https://github.com/mblum/alphatonic
+Project-URL: Documentation, https://mblum.github.io/alphatonic/
+Project-URL: Source, https://github.com/mblum/alphatonic
+Project-URL: Issues, https://github.com/mblum/alphatonic/issues
+Project-URL: Changelog, https://github.com/mblum/alphatonic/blob/HEAD/CHANGELOG.md
+Author: Manuel Blum
+License-Expression: MIT
+License-File: LICENSE
+Keywords: alpha,backtesting,factor,finance,information coefficient,quant,signal
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Topic :: Scientific/Engineering
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: numpy>=1.26
+Requires-Dist: pandas>=2.2.2
+Requires-Dist: pydantic>=2.6
+Provides-Extra: report
+Requires-Dist: jinja2<4,>=3.1; extra == 'report'
+Requires-Dist: plotly<7,>=6.1; extra == 'report'
+Description-Content-Type: text/markdown
+
+# alphatonic
+
+[![CI](https://github.com/mblum/alphatonic/actions/workflows/ci.yml/badge.svg)](https://github.com/mblum/alphatonic/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+alphatonic is a Python library for testing trading signals. Give it scores and prices to measure how
+well the scores predict future returns. Inspect the results as pandas tables or open an interactive
+HTML report offline.
+
+```python
+from alphatonic import evaluate
+from alphatonic.demo import synthetic_market
+
+factor, prices = synthetic_market(n_assets=30, n_bars=500, ic=0.04, seed=7)  # or your own tables
+result = evaluate(factor, prices, horizons=[1, 5])
+
+result.summary.query("method == 'spearman'")[["horizon", "mean", "ci95_lower", "ci95_upper"]]
+result.tearsheet("tearsheet.html")
+```
+
+## What it measures
+
+An **information coefficient (IC)** measures the association between a score and a future return. A
+positive IC means higher scores tend to precede higher returns.
+
+- **Cross-sectional IC:** do higher-scored assets outperform lower-scored assets at each bar?
+- **Time-series IC:** does each asset earn higher returns after higher scores? This also works
+  with a single asset. By default, returns are divided by volatility estimated from past prices.
+- **Signal persistence:** how much do scores, ranks and bucket membership change over time?
+
+Both IC analyses run on every evaluation. Confidence intervals account for temporal dependence using
+Newey–West standard errors and a block bootstrap. If a statistic cannot be computed, it is `NaN`
+with a reason, such as `constant_signal` or `insufficient_assets`.
+
+Horizons count rows of your price table. A return needs an unbroken path of prices; missing prices
+are never filled. Results can be saved, reloaded and used to rebuild reports.
+
+For repeated experiments, a `Study` saves each completed trial, counts variants of the same idea and
+keeps in-sample return labels out of a holdout period. Browse its results with `alphatonic serve`.
+
+## Install
+
+Python 3.11 or newer. Install from [PyPI](https://pypi.org/project/alphatonic/):
+
+```sh
+python -m pip install "alphatonic[report]"
+```
+
+`alphatonic[report]` adds plotly and jinja2 for the tearsheet; evaluation itself depends only on
+NumPy, pandas and pydantic.
+
+## Inputs
+
+- `prices`: a `DataFrame`, one row per bar, one column per asset, positive prices, `NaN` for
+  missing.
+- `factor`: a `DataFrame` of scores, or a long-format `Series` indexed by
+  `(timestamp, asset)`. Scores may cover a subset of the price rows and assets. Higher scores
+  mean higher expected returns.
+
+See [prepare factor and prices](docs/how-to/prepare-inputs.md) for alignment rules, timing, and a
+look-ahead check.
+
+## Documentation
+
+| Need | Guide |
+| --- | --- |
+| First run | [Your first evaluation](docs/tutorials/first-evaluation.md) |
+| Your own data | [Prepare factor and prices](docs/how-to/prepare-inputs.md) |
+| Choose windows and sample requirements | [Configure an evaluation](docs/how-to/configure-evaluation.md) |
+| Read the report | [Read a tearsheet](docs/how-to/read-a-tearsheet.md) |
+| Save results | [Save and reload results](docs/how-to/save-and-reload.md) |
+| A statistic is missing | [Troubleshooting](docs/how-to/troubleshooting.md) |
+| Many variants, one holdout | [Keep every trial in a study](docs/how-to/run-a-study.md) |
+| Tables and metric names | [Results and metrics](docs/reference/results.md) |
+| What the numbers mean | [Evaluation methodology](docs/explanation/methodology.md) |
+| What it does not do | [Design decisions](docs/explanation/design.md) |
+
+See the [changelog](CHANGELOG.md) for release notes.
+
+Preview the site with `uv run --group docs zensical serve`.
+
+## What it does not do
+
+alphatonic measures predictive association and signal persistence. It does not simulate portfolios,
+traded turnover, costs or P&L. It does not build factors or neutralise them by group. It cannot
+check whether your factor uses future information, and a `Study` counts only the trials it saves.
+See [design decisions](docs/explanation/design.md).
+
+## Development
+
+```sh
+uv sync --all-extras --locked
+uv run pytest
+uv run ruff check . && uv run ruff format --check .
+uv run pyright
+```
+
+See [Contributing](CONTRIBUTING.md) for setup, tests and the release process.
+
+## License
+
+[MIT License](LICENSE). Copyright 2026 Manuel Blum.

alphatonic-0.1.1/README.md

@@ -0,0 +1,102 @@
+# alphatonic
+
+[![CI](https://github.com/mblum/alphatonic/actions/workflows/ci.yml/badge.svg)](https://github.com/mblum/alphatonic/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+alphatonic is a Python library for testing trading signals. Give it scores and prices to measure how
+well the scores predict future returns. Inspect the results as pandas tables or open an interactive
+HTML report offline.
+
+```python
+from alphatonic import evaluate
+from alphatonic.demo import synthetic_market
+
+factor, prices = synthetic_market(n_assets=30, n_bars=500, ic=0.04, seed=7)  # or your own tables
+result = evaluate(factor, prices, horizons=[1, 5])
+
+result.summary.query("method == 'spearman'")[["horizon", "mean", "ci95_lower", "ci95_upper"]]
+result.tearsheet("tearsheet.html")
+```
+
+## What it measures
+
+An **information coefficient (IC)** measures the association between a score and a future return. A
+positive IC means higher scores tend to precede higher returns.
+
+- **Cross-sectional IC:** do higher-scored assets outperform lower-scored assets at each bar?
+- **Time-series IC:** does each asset earn higher returns after higher scores? This also works
+  with a single asset. By default, returns are divided by volatility estimated from past prices.
+- **Signal persistence:** how much do scores, ranks and bucket membership change over time?
+
+Both IC analyses run on every evaluation. Confidence intervals account for temporal dependence using
+Newey–West standard errors and a block bootstrap. If a statistic cannot be computed, it is `NaN`
+with a reason, such as `constant_signal` or `insufficient_assets`.
+
+Horizons count rows of your price table. A return needs an unbroken path of prices; missing prices
+are never filled. Results can be saved, reloaded and used to rebuild reports.
+
+For repeated experiments, a `Study` saves each completed trial, counts variants of the same idea and
+keeps in-sample return labels out of a holdout period. Browse its results with `alphatonic serve`.
+
+## Install
+
+Python 3.11 or newer. Install from [PyPI](https://pypi.org/project/alphatonic/):
+
+```sh
+python -m pip install "alphatonic[report]"
+```
+
+`alphatonic[report]` adds plotly and jinja2 for the tearsheet; evaluation itself depends only on
+NumPy, pandas and pydantic.
+
+## Inputs
+
+- `prices`: a `DataFrame`, one row per bar, one column per asset, positive prices, `NaN` for
+  missing.
+- `factor`: a `DataFrame` of scores, or a long-format `Series` indexed by
+  `(timestamp, asset)`. Scores may cover a subset of the price rows and assets. Higher scores
+  mean higher expected returns.
+
+See [prepare factor and prices](docs/how-to/prepare-inputs.md) for alignment rules, timing, and a
+look-ahead check.
+
+## Documentation
+
+| Need | Guide |
+| --- | --- |
+| First run | [Your first evaluation](docs/tutorials/first-evaluation.md) |
+| Your own data | [Prepare factor and prices](docs/how-to/prepare-inputs.md) |
+| Choose windows and sample requirements | [Configure an evaluation](docs/how-to/configure-evaluation.md) |
+| Read the report | [Read a tearsheet](docs/how-to/read-a-tearsheet.md) |
+| Save results | [Save and reload results](docs/how-to/save-and-reload.md) |
+| A statistic is missing | [Troubleshooting](docs/how-to/troubleshooting.md) |
+| Many variants, one holdout | [Keep every trial in a study](docs/how-to/run-a-study.md) |
+| Tables and metric names | [Results and metrics](docs/reference/results.md) |
+| What the numbers mean | [Evaluation methodology](docs/explanation/methodology.md) |
+| What it does not do | [Design decisions](docs/explanation/design.md) |
+
+See the [changelog](CHANGELOG.md) for release notes.
+
+Preview the site with `uv run --group docs zensical serve`.
+
+## What it does not do
+
+alphatonic measures predictive association and signal persistence. It does not simulate portfolios,
+traded turnover, costs or P&L. It does not build factors or neutralise them by group. It cannot
+check whether your factor uses future information, and a `Study` counts only the trials it saves.
+See [design decisions](docs/explanation/design.md).
+
+## Development
+
+```sh
+uv sync --all-extras --locked
+uv run pytest
+uv run ruff check . && uv run ruff format --check .
+uv run pyright
+```
+
+See [Contributing](CONTRIBUTING.md) for setup, tests and the release process.
+
+## License
+
+[MIT License](LICENSE). Copyright 2026 Manuel Blum.

alphatonic-0.1.1/docs/_includes/CHANGELOG.md

@@ -0,0 +1 @@
+../../CHANGELOG.md

alphatonic-0.1.1/docs/_includes/CONTRIBUTING.md

@@ -0,0 +1 @@
+../../CONTRIBUTING.md

alphatonic-0.1.1/docs/_includes/README.md

@@ -0,0 +1 @@
+../../README.md

alphatonic-0.1.1/docs/changelog.md

@@ -0,0 +1,6 @@
+---
+render_macros: true
+---
+
+{# Edit CHANGELOG.md in the repository root. #}
+{% include "CHANGELOG.md" %}

alphatonic-0.1.1/docs/contributing/development.md

@@ -0,0 +1,8 @@
+---
+render_macros: true
+---
+
+{# Edit CONTRIBUTING.md in the repository root. #}
+{% filter replace("](docs/", "](../") | replace("](README.md)", "](../index.md)") | replace("](CHANGELOG.md)", "](../changelog.md)") %}
+{% include "CONTRIBUTING.md" %}
+{% endfilter %}