typola 0.1.1__tar.gz

typola-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,207 @@
+name: Continuous Integration (uv)
+on: [push, pull_request]
+
+# Note: Environment variables (PROJECT_NAME and vars from [tool.wads.ci.env])
+# are set by the read-ci-config action in the setup job and made available
+# to all subsequent jobs via GITHUB_ENV
+
+jobs:
+  # First job: Read configuration from pyproject.toml
+  setup:
+    name: Read Configuration
+    runs-on: ubuntu-latest
+    outputs:
+      project-name: ${{ steps.config.outputs.project-name }}
+      python-versions: ${{ steps.config.outputs.python-versions }}
+      pytest-args: ${{ steps.config.outputs.pytest-args }}
+      coverage-enabled: ${{ steps.config.outputs.coverage-enabled }}
+      exclude-paths: ${{ steps.config.outputs.exclude-paths }}
+      test-on-windows: ${{ steps.config.outputs.test-on-windows }}
+      build-sdist: ${{ steps.config.outputs.build-sdist }}
+      build-wheel: ${{ steps.config.outputs.build-wheel }}
+      metrics-enabled: ${{ steps.config.outputs.metrics-enabled }}
+      metrics-config-path: ${{ steps.config.outputs.metrics-config-path }}
+      metrics-storage-branch: ${{ steps.config.outputs.metrics-storage-branch }}
+      metrics-python-version: ${{ steps.config.outputs.metrics-python-version }}
+      metrics-force-run: ${{ steps.config.outputs.metrics-force-run }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        run: uv python install 3.11
+
+      - name: Read CI Config
+        id: config
+        uses: i2mint/wads/actions/read-ci-config@master
+        with:
+          pyproject-path: .
+
+  # Second job: Validation using the config
+  validation:
+    name: Validation
+    if: "!contains(github.event.head_commit.message, '[skip ci]')"
+    needs: setup
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ${{ fromJson(needs.setup.outputs.python-versions) }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: i2mint/wads/actions/setup-python-uv@master
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install System Dependencies
+        uses: i2mint/wads/actions/install-system-deps@master
+        with:
+          pyproject-path: .
+
+      - name: Install Dependencies
+        uses: i2mint/wads/actions/install-deps-uv@master
+
+      - name: Format Source Code
+        run: uvx ruff format .
+
+      - name: Lint Validation
+        run: uvx ruff check --output-format=github ${{ needs.setup.outputs.project-name }}
+
+      - name: Run Tests
+        uses: i2mint/wads/actions/run-tests-uv@master
+        with:
+          root-dir: ${{ needs.setup.outputs.project-name }}
+          pytest-args: ${{ needs.setup.outputs.pytest-args }}
+          exclude-paths: ${{ needs.setup.outputs.exclude-paths }}
+          coverage: ${{ needs.setup.outputs.coverage-enabled }}
+
+      - name: Track Code Metrics
+        if: needs.setup.outputs.metrics-enabled == 'true'
+        uses: i2mint/umpyre/actions/track-metrics@master
+        continue-on-error: true
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          config-path: ${{ needs.setup.outputs.metrics-config-path }}
+          storage-branch: ${{ needs.setup.outputs.metrics-storage-branch }}
+          python-version: ${{ needs.setup.outputs.metrics-python-version }}
+          force-run: ${{ needs.setup.outputs.metrics-force-run }}
+
+  # Optional Windows testing (if enabled in config)
+  windows-validation:
+    name: Windows Tests
+    if: "!contains(github.event.head_commit.message, '[skip ci]') && needs.setup.outputs.test-on-windows == 'true'"
+    needs: setup
+    runs-on: windows-latest
+    continue-on-error: true
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        uses: i2mint/wads/actions/setup-python-uv@master
+        with:
+          python-version: ${{ fromJson(needs.setup.outputs.python-versions)[0] }}
+
+      - name: Install System Dependencies
+        uses: i2mint/wads/actions/install-system-deps@master
+        with:
+          pyproject-path: .
+
+      - name: Install Dependencies
+        uses: i2mint/wads/actions/install-deps-uv@master
+
+      - name: Run Tests
+        uses: i2mint/wads/actions/run-tests-uv@master
+        with:
+          root-dir: ${{ needs.setup.outputs.project-name }}
+
+  # Publishing job
+  publish:
+    name: Publish
+    permissions:
+      contents: write
+    if: "!contains(github.event.head_commit.message, '[skip ci]') && (github.ref == 'refs/heads/master' || github.ref == 'refs/heads/main')"
+    needs: [setup, validation]
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        uses: i2mint/wads/actions/setup-python-uv@master
+        with:
+          python-version: ${{ fromJson(needs.setup.outputs.python-versions)[0] }}
+          create-venv: "false"
+
+      - name: Format Source Code
+        run: uvx ruff format .
+
+      - name: Update Version Number
+        id: version
+        uses: i2mint/isee/actions/bump-version-number@master
+
+      - name: Build Distribution
+        uses: i2mint/wads/actions/build-dist-uv@master
+        with:
+          sdist: ${{ needs.setup.outputs.build-sdist }}
+          wheel: ${{ needs.setup.outputs.build-wheel }}
+
+      - name: Publish to PyPI
+        uses: i2mint/wads/actions/pypi-publish-uv@master
+        with:
+          pypi-token: ${{ secrets.PYPI_PASSWORD }}
+
+      - name: Force SSH for git remote
+        run: git remote set-url origin git@github.com:${{ github.repository }}.git
+
+      - name: Commit Changes
+        uses: i2mint/wads/actions/git-commit@master
+        with:
+          commit-message: "**CI** Formatted code + Updated version to ${{ env.VERSION }} [skip ci]"
+          ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}
+          push: true
+
+      - name: Tag Repository
+        uses: i2mint/wads/actions/git-tag@master
+        with:
+          tag: ${{ env.VERSION }}
+          message: "Release version ${{ env.VERSION }}"
+          push: true
+
+  # Optional GitHub Pages
+  github-pages:
+    name: Publish GitHub Pages
+    permissions:
+      contents: write
+      pages: write
+      id-token: write
+    if: "!contains(github.event.head_commit.message, '[skip ci]') && github.ref == format('refs/heads/{0}', github.event.repository.default_branch)"
+    needs: publish
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: i2mint/epythet/actions/publish-github-pages@master
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          ignore: "tests/,scrap/,examples/"

typola-0.1.1/.gitignore

@@ -0,0 +1,91 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+.DS_Store
+
+# C extensions
+*.so
+
+# TLS certificates
+*.pem
+certs/
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+_build
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Sphinx documentation
+docs/_build/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Editors
+.vscode/
+.idea/
+.spyderproject
+.spyproject
+.ropeproject
+
+# mypy
+.mypy_cache/
+
+# Node / frontend
+node_modules/
+
+# typola data cache (downloaded CLDF datasets)
+data_cache/

typola-0.1.1/LICENSE

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

typola-0.1.1/PKG-INFO

@@ -0,0 +1,208 @@
+Metadata-Version: 2.4
+Name: typola
+Version: 0.1.1
+Summary: Probabilistic models over linguistic typology source data (WALS, Grambank, ...) with pluggable count-to-probability estimators.
+Project-URL: Homepage, https://github.com/thorwhalen/typola
+Project-URL: Repository, https://github.com/thorwhalen/typola
+Author: Thor Whalen
+License: MIT
+License-File: LICENSE
+Keywords: bayesian,cldf,grambank,linguistics,probabilistic-models,typology,wals
+Requires-Python: >=3.10
+Requires-Dist: dol>=0.3
+Requires-Dist: numpy>=1.23
+Requires-Dist: pandas>=1.5
+Requires-Dist: requests>=2.28
+Requires-Dist: scipy>=1.10
+Provides-Extra: bayesian
+Requires-Dist: ba>=0.3; extra == 'bayesian'
+Requires-Dist: spyn>=0.0.6; extra == 'bayesian'
+Provides-Extra: dev
+Requires-Dist: fastapi>=0.115; extra == 'dev'
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: ipykernel; extra == 'dev'
+Requires-Dist: jupyter; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: uvicorn>=0.30; extra == 'dev'
+Provides-Extra: web
+Requires-Dist: fastapi>=0.115; extra == 'web'
+Requires-Dist: httpx>=0.27; extra == 'web'
+Requires-Dist: uvicorn>=0.30; extra == 'web'
+Description-Content-Type: text/markdown
+
+# typola
+
+Probabilistic models over linguistic typology source data (WALS, Grambank, …).
+
+**The core idea** is separation of concerns:
+
+- **Data prep** — acquire and canonicalize. Raw CLDF datasets → pandas DataFrames, via one generic loader that works for WALS, Grambank, APiCS, and any other CLDF StructureDataset.
+- **Count-to-probability estimators** — first-class, pluggable, comparable. MLE, Laplace, Jeffreys, Dirichlet-Multinomial, empirical-Bayes, mixtures — pick one, configure it, or plug in your own. Same API.
+- **Probabilistic models** — `Marginal P(parameter|condition)` and `Conditional P(target|given)` built from counts + an estimator.
+- **Query / drill-down** — one entry point (`query`) plus a few small utilities (`compare_estimators`, `cross_validate_estimators`, `rank_associations`, `compare_conditions`) for actually interrogating the model.
+
+You can use any layer on its own. The prep layer is just pandas — no probabilistic-model imports required.
+
+## Install
+
+```bash
+pip install -e .
+# with optional bayesian extras (ba + spyn):
+pip install -e '.[bayesian]'
+# with web UI backend:
+pip install -e '.[web]'
+```
+
+## Web UI
+
+A React probability-console frontend (zodal + shadcn) ships in `webapp/`:
+
+```bash
+# 1. Start the API (from repo root):
+python -m webapp.api.main
+# 2. Start the UI:
+cd webapp/ui && npm install && npm run dev
+# open http://127.0.0.1:5173
+```
+
+See `webapp/README.md` for details.
+
+## 60-second tour
+
+```python
+from typola import load, query, estimators
+from typola.query import compare_estimators, cross_validate_estimators, rank_associations
+
+# 1. Load a typology. Downloaded & cached on first call.
+wals = load("wals")
+# Typology(name='wals', n_languages=3573, n_parameters=192, n_codes=1143, n_values=76475)
+
+# 2. P(Order of Subject and Verb) globally — Jeffreys smoothing.
+d = query(wals, target="81A", estimator=estimators.jeffreys())
+d.top_k(4)
+#              name  count  probability
+# 81A-1         SOV    564     0.409206
+# 81A-2         SVO    488     0.354114
+# 81A-7  No dominant    189     0.137369
+# 81A-3         VSO     95     0.069228
+
+# 3. Condition on language metadata.
+query(wals, target="81A", condition={"Family": "Niger-Congo"}).top_k(3)
+#              name  count  probability
+# 81A-2         SVO    277     0.911
+# 81A-7  No dominant     20     0.066
+# 81A-1         SOV      4     0.013
+
+# 4. Full conditional P(target | given) — a CPT.
+cpt = query(wals, target="83A", given="81A", estimator=estimators.laplace(0.5))
+cpt.as_matrix()          # DataFrame, rows sum to 1
+cpt.p_given("81A-2")     # row distribution when subject–verb order is SVO
+cpt.mutual_information() # bits
+
+# 5. Compare estimators on the same question.
+compare_estimators(
+    wals, target="81A",
+    condition={"Family": "Austronesian"},
+    estimators=[estimators.mle(), estimators.jeffreys(),
+                estimators.empirical_bayes(wals.counts("81A").values, strength=20)],
+)
+
+# 6. Actually test which estimator is best — cross-validated log-likelihood.
+cross_validate_estimators(
+    wals, target="81A",
+    estimators=[estimators.mle(), estimators.laplace(0.1),
+                estimators.laplace(0.5), estimators.laplace(1.0),
+                estimators.empirical_bayes(wals.counts("81A").values, strength=20)],
+    n_folds=5, random_state=0,
+    condition={"Family": "Austronesian"},
+)
+#                                                             log_likelihood  perplexity
+# laplace(alpha=1.0)                                                -44.2886      3.7548
+# laplace(alpha=0.5)                                                -44.3577      3.7648
+# laplace(alpha=0.1)                                                -44.8365      3.8244
+# empirical_bayes(global_counts=..., strength=20.0)                 -45.3420      3.8896
+# mle()                                                             -52.9648      5.2109
+
+# 7. Drill down: which parameters are most informative about Subject–Verb order?
+rank_associations(wals, target="81A", top_k=5, estimator=estimators.laplace(0.5))
+#   parameter_id  parameter_name                                         mutual_information  n_languages
+# 0         83A  Order of Object and Verb                                             1.06         1368
+# 1         84A  Order of Object, Oblique, and Verb                                   0.99          486
+# 2         97A  Rel. between OV and AdjN                                             0.97         1190
+# 3         95A  Rel. between OV and AdpN                                             0.96         1039
+# 4         96A  Rel. between OV and RelN                                             0.91          807
+```
+
+Run `python misc/example_bakeoff.py` for the same flow in full.
+
+## Architecture
+
+```
+typola
+├── sources/      ← source catalog (WALS, Grambank, ...) + downloader
+├── prep/         ← CLDF → Typology → dol stores
+├── estimators/   ← count → probability: MLE, Laplace, Jeffreys, Dirichlet, ...
+├── models/       ← Distribution, Marginal, Conditional
+└── query/        ← query(), compare_estimators(), cross_validate_estimators(), rank_associations(), compare_conditions()
+```
+
+Each layer only depends on the ones above it in the list — so you can use the prep layer without any probabilistic code, or you can use estimators on counts from any other source (not just typola).
+
+## Data sources
+
+Currently registered:
+
+| Name        | License      | Source |
+|-------------|--------------|--------|
+| `wals`      | CC BY-NC 4.0 | <https://wals.info/> — Dryer & Haspelmath 2013 |
+| `grambank`  | CC BY 4.0    | <https://grambank.clld.org/> — Skirgård et al. 2023 |
+
+Register more with:
+
+```python
+from typola.sources import register_source, SourceSpec
+register_source(SourceSpec(
+    name="apics",
+    url="https://github.com/cldf-datasets/apics/archive/refs/heads/master.zip",
+    citation="...",
+    license="CC-BY-4.0",
+    archive_type="zip",
+    strip_components=1,
+))
+```
+
+The loader handles any CLDF StructureDataset that provides `languages.csv`, `parameters.csv`, `codes.csv`, `values.csv`.
+
+## Custom estimators
+
+Subclass `Estimator` or just provide any callable with a `.name` attribute:
+
+```python
+from dataclasses import dataclass, field
+from typola.estimators import Estimator
+import numpy as np
+
+@dataclass(frozen=True, repr=False)
+class _HaldaneMix(Estimator):
+    name: str = "haldane_mix"
+    params: dict = field(default_factory=lambda: {"alpha": 0.01})
+
+    def _estimate(self, counts):
+        a = self.params["alpha"]
+        smoothed = counts + a
+        return smoothed / smoothed.sum()
+
+estimators_under_test = [_HaldaneMix(), estimators.jeffreys(), ...]
+```
+
+## Citing data sources
+
+Every `Typology` carries a `.citation` string. Cite it in any downstream output.
+
+- **WALS** requires attribution (CC BY-NC 4.0), no commercial use.
+- **Grambank** is CC BY 4.0.
+
+## License
+
+MIT.

typola-0.1.1/README.md

@@ -0,0 +1,175 @@
+# typola
+
+Probabilistic models over linguistic typology source data (WALS, Grambank, …).
+
+**The core idea** is separation of concerns:
+
+- **Data prep** — acquire and canonicalize. Raw CLDF datasets → pandas DataFrames, via one generic loader that works for WALS, Grambank, APiCS, and any other CLDF StructureDataset.
+- **Count-to-probability estimators** — first-class, pluggable, comparable. MLE, Laplace, Jeffreys, Dirichlet-Multinomial, empirical-Bayes, mixtures — pick one, configure it, or plug in your own. Same API.
+- **Probabilistic models** — `Marginal P(parameter|condition)` and `Conditional P(target|given)` built from counts + an estimator.
+- **Query / drill-down** — one entry point (`query`) plus a few small utilities (`compare_estimators`, `cross_validate_estimators`, `rank_associations`, `compare_conditions`) for actually interrogating the model.
+
+You can use any layer on its own. The prep layer is just pandas — no probabilistic-model imports required.
+
+## Install
+
+```bash
+pip install -e .
+# with optional bayesian extras (ba + spyn):
+pip install -e '.[bayesian]'
+# with web UI backend:
+pip install -e '.[web]'
+```
+
+## Web UI
+
+A React probability-console frontend (zodal + shadcn) ships in `webapp/`:
+
+```bash
+# 1. Start the API (from repo root):
+python -m webapp.api.main
+# 2. Start the UI:
+cd webapp/ui && npm install && npm run dev
+# open http://127.0.0.1:5173
+```
+
+See `webapp/README.md` for details.
+
+## 60-second tour
+
+```python
+from typola import load, query, estimators
+from typola.query import compare_estimators, cross_validate_estimators, rank_associations
+
+# 1. Load a typology. Downloaded & cached on first call.
+wals = load("wals")
+# Typology(name='wals', n_languages=3573, n_parameters=192, n_codes=1143, n_values=76475)
+
+# 2. P(Order of Subject and Verb) globally — Jeffreys smoothing.
+d = query(wals, target="81A", estimator=estimators.jeffreys())
+d.top_k(4)
+#              name  count  probability
+# 81A-1         SOV    564     0.409206
+# 81A-2         SVO    488     0.354114
+# 81A-7  No dominant    189     0.137369
+# 81A-3         VSO     95     0.069228
+
+# 3. Condition on language metadata.
+query(wals, target="81A", condition={"Family": "Niger-Congo"}).top_k(3)
+#              name  count  probability
+# 81A-2         SVO    277     0.911
+# 81A-7  No dominant     20     0.066
+# 81A-1         SOV      4     0.013
+
+# 4. Full conditional P(target | given) — a CPT.
+cpt = query(wals, target="83A", given="81A", estimator=estimators.laplace(0.5))
+cpt.as_matrix()          # DataFrame, rows sum to 1
+cpt.p_given("81A-2")     # row distribution when subject–verb order is SVO
+cpt.mutual_information() # bits
+
+# 5. Compare estimators on the same question.
+compare_estimators(
+    wals, target="81A",
+    condition={"Family": "Austronesian"},
+    estimators=[estimators.mle(), estimators.jeffreys(),
+                estimators.empirical_bayes(wals.counts("81A").values, strength=20)],
+)
+
+# 6. Actually test which estimator is best — cross-validated log-likelihood.
+cross_validate_estimators(
+    wals, target="81A",
+    estimators=[estimators.mle(), estimators.laplace(0.1),
+                estimators.laplace(0.5), estimators.laplace(1.0),
+                estimators.empirical_bayes(wals.counts("81A").values, strength=20)],
+    n_folds=5, random_state=0,
+    condition={"Family": "Austronesian"},
+)
+#                                                             log_likelihood  perplexity
+# laplace(alpha=1.0)                                                -44.2886      3.7548
+# laplace(alpha=0.5)                                                -44.3577      3.7648
+# laplace(alpha=0.1)                                                -44.8365      3.8244
+# empirical_bayes(global_counts=..., strength=20.0)                 -45.3420      3.8896
+# mle()                                                             -52.9648      5.2109
+
+# 7. Drill down: which parameters are most informative about Subject–Verb order?
+rank_associations(wals, target="81A", top_k=5, estimator=estimators.laplace(0.5))
+#   parameter_id  parameter_name                                         mutual_information  n_languages
+# 0         83A  Order of Object and Verb                                             1.06         1368
+# 1         84A  Order of Object, Oblique, and Verb                                   0.99          486
+# 2         97A  Rel. between OV and AdjN                                             0.97         1190
+# 3         95A  Rel. between OV and AdpN                                             0.96         1039
+# 4         96A  Rel. between OV and RelN                                             0.91          807
+```
+
+Run `python misc/example_bakeoff.py` for the same flow in full.
+
+## Architecture
+
+```
+typola
+├── sources/      ← source catalog (WALS, Grambank, ...) + downloader
+├── prep/         ← CLDF → Typology → dol stores
+├── estimators/   ← count → probability: MLE, Laplace, Jeffreys, Dirichlet, ...
+├── models/       ← Distribution, Marginal, Conditional
+└── query/        ← query(), compare_estimators(), cross_validate_estimators(), rank_associations(), compare_conditions()
+```
+
+Each layer only depends on the ones above it in the list — so you can use the prep layer without any probabilistic code, or you can use estimators on counts from any other source (not just typola).
+
+## Data sources
+
+Currently registered:
+
+| Name        | License      | Source |
+|-------------|--------------|--------|
+| `wals`      | CC BY-NC 4.0 | <https://wals.info/> — Dryer & Haspelmath 2013 |
+| `grambank`  | CC BY 4.0    | <https://grambank.clld.org/> — Skirgård et al. 2023 |
+
+Register more with:
+
+```python
+from typola.sources import register_source, SourceSpec
+register_source(SourceSpec(
+    name="apics",
+    url="https://github.com/cldf-datasets/apics/archive/refs/heads/master.zip",
+    citation="...",
+    license="CC-BY-4.0",
+    archive_type="zip",
+    strip_components=1,
+))
+```
+
+The loader handles any CLDF StructureDataset that provides `languages.csv`, `parameters.csv`, `codes.csv`, `values.csv`.
+
+## Custom estimators
+
+Subclass `Estimator` or just provide any callable with a `.name` attribute:
+
+```python
+from dataclasses import dataclass, field
+from typola.estimators import Estimator
+import numpy as np
+
+@dataclass(frozen=True, repr=False)
+class _HaldaneMix(Estimator):
+    name: str = "haldane_mix"
+    params: dict = field(default_factory=lambda: {"alpha": 0.01})
+
+    def _estimate(self, counts):
+        a = self.params["alpha"]
+        smoothed = counts + a
+        return smoothed / smoothed.sum()
+
+estimators_under_test = [_HaldaneMix(), estimators.jeffreys(), ...]
+```
+
+## Citing data sources
+
+Every `Typology` carries a `.citation` string. Cite it in any downstream output.
+
+- **WALS** requires attribution (CC BY-NC 4.0), no commercial use.
+- **Grambank** is CC BY 4.0.
+
+## License
+
+MIT.