biotapy 0.0.1__tar.gz

biotapy-0.0.1/.codecov.yaml

@@ -0,0 +1,17 @@
+# Based on pydata/xarray
+codecov:
+  require_ci_to_pass: no
+
+coverage:
+  status:
+    project:
+      default:
+        # Require 1% coverage, i.e., always succeed
+        target: 1
+    patch: false
+    changes: false
+
+comment:
+  layout: diff, flags, files
+  behavior: once
+  require_base: no

biotapy-0.0.1/.cruft.json

@@ -0,0 +1,44 @@
+{
+  "template": "https://github.com/scverse/cookiecutter-scverse",
+  "commit": "6518dfa1abde7379ea7255daf0ce09c23f2b4c94",
+  "checkout": "v0.8.0",
+  "context": {
+    "cookiecutter": {
+      "project_name": "biotapy",
+      "package_name": "biotapy",
+      "project_description": "mia-style microbiome toolkit for Python on AnnData/TreeData",
+      "author_full_name": "Pedro Ribeiro",
+      "author_email": "pedrocasalribeiro@gmail.com",
+      "github_user": "pedrocr83",
+      "github_repo": "biotapy",
+      "license": "BSD 3-Clause License",
+      "ide_integration": true,
+      "issue_categorization": "labels",
+      "_copy_without_render": [
+        ".github/workflows/build.yaml",
+        ".github/workflows/test.yaml",
+        "docs/_templates/autosummary/**.rst"
+      ],
+      "_exclude_on_template_update": [
+        "CHANGELOG.md",
+        "LICENSE",
+        "README.md",
+        "docs/api.md",
+        "docs/index.md",
+        "docs/notebooks/example.ipynb",
+        "docs/references.bib",
+        "docs/references.md",
+        "src/**",
+        "tests/**"
+      ],
+      "_render_devdocs": false,
+      "_jinja2_env_vars": {
+        "lstrip_blocks": true,
+        "trim_blocks": true
+      },
+      "_template": "https://github.com/scverse/cookiecutter-scverse",
+      "_commit": "6518dfa1abde7379ea7255daf0ce09c23f2b4c94"
+    }
+  },
+  "directory": null
+}

biotapy-0.0.1/.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[{*.{yml,yaml,toml},.cruft.json}]
+indent_size = 2
+
+[Makefile]
+indent_style = tab

biotapy-0.0.1/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,93 @@
+name: Bug report
+description: Report something that is broken or incorrect
+labels: bug
+body:
+  - type: markdown
+    attributes:
+      value: |
+        **Note**: Please read [this guide](https://matthewrocklin.com/blog/work/2018/02/28/minimal-bug-reports)
+        detailing how to provide the necessary information for us to reproduce your bug. In brief:
+          * Please provide exact steps how to reproduce the bug in a clean Python environment.
+          * In case it's not clear what's causing this bug, please provide the data or the data generation procedure.
+          * Replicate problems on public datasets or share data subsets when full sharing isn't possible.
+
+  - type: textarea
+    id: report
+    attributes:
+      label: Report
+      description: A clear and concise description of what the bug is.
+    validations:
+      required: true
+
+  - type: textarea
+    id: versions
+    attributes:
+      label: Versions
+      description: |
+        Which version of packages.
+
+        Please install `session-info2`, run the following command in a notebook,
+        click the “Copy as Markdown” button, then paste the results into the text box below.
+
+        ```python
+        In[1]: import session_info2; session_info2.session_info(dependencies=True)
+        ```
+
+        Alternatively, run this in a console:
+
+        ```python
+        >>> import session_info2; print(session_info2.session_info(dependencies=True)._repr_mimebundle_()["text/markdown"])
+        ```
+      render: python
+      placeholder: |
+        anndata	0.11.3
+        ----	----
+        charset-normalizer	3.4.1
+        coverage	7.7.0
+        psutil	7.0.0
+        dask	2024.7.1
+        jaraco.context	5.3.0
+        numcodecs	0.15.1
+        jaraco.functools	4.0.1
+        Jinja2	3.1.6
+        sphinxcontrib-jsmath	1.0.1
+        sphinxcontrib-htmlhelp	2.1.0
+        toolz	1.0.0
+        session-info2	0.1.2
+        PyYAML	6.0.2
+        llvmlite	0.44.0
+        scipy	1.15.2
+        pandas	2.2.3
+        sphinxcontrib-devhelp	2.0.0
+        h5py	3.13.0
+        tblib	3.0.0
+        setuptools-scm	8.2.0
+        more-itertools	10.3.0
+        msgpack	1.1.0
+        sparse	0.15.5
+        wrapt	1.17.2
+        jaraco.collections	5.1.0
+        numba	0.61.0
+        pyarrow	19.0.1
+        pytz	2025.1
+        MarkupSafe	3.0.2
+        crc32c	2.7.1
+        sphinxcontrib-qthelp	2.0.0
+        sphinxcontrib-serializinghtml	2.0.0
+        zarr	2.18.4
+        asciitree	0.3.3
+        six	1.17.0
+        sphinxcontrib-applehelp	2.0.0
+        numpy	2.1.3
+        cloudpickle	3.1.1
+        sphinxcontrib-bibtex	2.6.3
+        natsort	8.4.0
+        jaraco.text	3.12.1
+        setuptools	76.1.0
+        Deprecated	1.2.18
+        packaging	24.2
+        python-dateutil	2.9.0.post0
+        ----	----
+        Python	3.13.2 | packaged by conda-forge | (main, Feb 17 2025, 14:10:22) [GCC 13.3.0]
+        OS	Linux-6.11.0-109019-tuxedo-x86_64-with-glibc2.39
+        Updated	2025-03-18 15:47

biotapy-0.0.1/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Scverse Community Forum
+    url: https://discourse.scverse.org/
+    about: If you have questions about “How to do X”, please ask them here.

biotapy-0.0.1/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,11 @@
+name: Feature request
+description: Propose a new feature for biotapy
+labels: enhancement
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Description of feature
+      description: Please describe your suggestion for a new feature. It might help to describe a problem or use case, plus any alternatives that you have considered.
+    validations:
+      required: true

biotapy-0.0.1/.github/dependabot.yml

@@ -0,0 +1,12 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    cooldown:
+      default-days: 7
+    groups:
+      actions-deps:
+        patterns:
+          - "*"

biotapy-0.0.1/.github/pull_request_template.md

@@ -0,0 +1,13 @@
+## Task
+Phase / task id from `.knowledge/roadmap/`:
+
+## Checklist (rules.md)
+- [ ] Task is in the active phase (R1.1); nothing outside it changed (R1.4)
+- [ ] Reused a library call, or explained why none fits (R2.1): `<call>`
+- [ ] No new parameter, abstraction or dependency without a test or approval (R2.3, R9.1)
+- [ ] Docstring (R equivalent, Guide, example) and docs page updated (R8.2)
+- [ ] Knowledge concepts updated, or confirmed unaffected (R12.1)
+- [ ] Compiled engine only: asv benchmark >= 5x attached (R10.3)
+
+## Verification
+Commands run and their result (R14):

biotapy-0.0.1/.github/workflows/build.yaml

@@ -0,0 +1,30 @@
+name: Check Build
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  package:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          filter: blob:none
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Install uv
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+      - name: Build package
+        run: uv build
+      - name: Check package
+        run: uvx twine check --strict dist/*.whl

biotapy-0.0.1/.github/workflows/release.yaml

@@ -0,0 +1,33 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+
+# Use "trusted publishing", see https://docs.pypi.org/trusted-publishers/
+permissions: {}
+
+jobs:
+  release:
+    name: Upload release to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/biotapy
+    permissions:
+      contents: read
+      id-token: write # IMPORTANT: this permission is mandatory for trusted publishing
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          filter: blob:none
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Install uv
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        with:
+          enable-cache: false
+      - name: Build package
+        run: uv build
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2

biotapy-0.0.1/.github/workflows/test.yaml

@@ -0,0 +1,168 @@
+name: Test
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+  schedule:
+    - cron: "0 5 1,15 * *"
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  # Get the test environment from hatch as defined in pyproject.toml.
+  # This ensures that the pyproject.toml is the single point of truth for test definitions and the same tests are
+  # run locally and on continuous integration.
+  # Check [[tool.hatch.envs.hatch-test.matrix]] in pyproject.toml and https://hatch.pypa.io/latest/environment/ for
+  # more details.
+  get-environments:
+    runs-on: ubuntu-slim
+    outputs:
+      envs: ${{ steps.get-envs.outputs.envs }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          filter: blob:none
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Install uv
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+      - name: Get test environments
+        id: get-envs
+        run: |
+          ENVS_JSON=$(uvx hatch env show --json | jq -c 'to_entries
+            | map(
+                select(.key | startswith("hatch-test"))
+                | {
+                    name: .key,
+                    label: (if (.key | contains("pre")) then .key + " (PRE-RELEASE DEPENDENCIES)" else .key end),
+                    python: .value.python
+                  }
+              )')
+          echo "envs=${ENVS_JSON}" | tee $GITHUB_OUTPUT
+
+  # Run tests through hatch. Spawns a separate runner for each environment defined in the hatch matrix obtained above.
+  test:
+    needs: get-environments
+    permissions:
+       id-token: write  # for codecov OIDC
+       contents: read
+
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        env: ${{ fromJSON(needs.get-environments.outputs.envs) }}
+
+    name: ${{ matrix.env.label }} (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    defaults:
+      run:
+        shell: bash  # steps use POSIX syntax; Windows defaults to PowerShell
+    continue-on-error: ${{ contains(matrix.env.name, 'pre') }}  # make "all-green" pass even if pre-release job fails
+
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          filter: blob:none
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Install uv
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        with:
+          python-version: ${{ matrix.env.python }}
+      - name: create hatch environment
+        run: uvx hatch env create ${{ matrix.env.name }}
+      - name: list all all installed package versions
+        run: uvx hatch run ${{ matrix.env.name }}:uv pip list
+      - name: run tests using hatch
+        env:
+          MPLBACKEND: agg
+          PLATFORM: ${{ matrix.os }}
+          DISPLAY: :42
+        run: uvx hatch run ${{ matrix.env.name }}:run-cov -v --color=yes -n auto
+      - name: generate coverage report
+        run: |
+          # See https://coverage.readthedocs.io/page/config.html#run-patch
+          test -f .coverage || uvx hatch run ${{ matrix.env.name }}:cov-combine
+          uvx hatch run ${{ matrix.env.name }}:cov-report   # report visibly
+          uvx hatch run ${{ matrix.env.name }}:coverage xml # create report for upload
+      - name: Upload coverage
+        uses: codecov/codecov-action@303a32d7a59b442fa8d48b6a1cc6825c09c847a5 # v7.1.1
+        with:
+          fail_ci_if_error: true
+          use_oidc: true
+
+  # The rules.md gate: ruff (lint, format, size limits, tree-import bans), mypy --strict,
+  # import-linter layers, pyproject-fmt, zizmor. Same hooks as local prek (rules.md R14).
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          filter: blob:none
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Install uv
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+      - name: Run all prek hooks
+        run: uvx prek run --all-files --show-diff-on-failure
+
+  # Optional dependencies must be imported lazily (decisions/optional-heavy-dependencies):
+  # importing with runtime dependencies only catches a module-level import of an extra.
+  import-without-extras:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          filter: blob:none
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Install uv
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+      - name: Import every biotapy module with runtime dependencies only
+        run: >-
+          uv run --no-dev python -c "import importlib, pkgutil, biotapy;
+          [importlib.import_module(m.name) for m in pkgutil.walk_packages(biotapy.__path__, 'biotapy.')]"
+
+  # Informational: lists knowledge concepts whose code changed in this PR (playbooks/maintain-knowledge).
+  # Flagged concepts go to the job summary; the job fails only when the script cannot diff (exit 2).
+  knowledge-touched:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          filter: blob:none
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Report concepts covering changed code
+        env:
+          BASE: ${{ github.base_ref }}
+        run: |
+          status=0
+          bash scripts/knowledge_stale.sh --touched --against "origin/$BASE" > knowledge-report.txt || status=$?
+          { echo "### Knowledge concepts to review"; echo '```'; cat knowledge-report.txt; echo '```'; } >> "$GITHUB_STEP_SUMMARY"
+          test "$status" -le 1
+
+  # Check that all tests defined above pass. This makes it easy to set a single "required" test in branch
+  # protection instead of having to update it frequently. See https://github.com/re-actors/alls-green#why.
+  check:
+    name: Tests pass in all hatch environments
+    if: always()
+    needs:
+      - get-environments
+      - test
+      - lint
+      - import-without-extras
+    runs-on: ubuntu-latest
+    steps:
+        - uses: re-actors/alls-green@b5b5b37504aa4183270bd3d855c52a67f212be35 # v1.3.0
+          with:
+            jobs: ${{ toJSON(needs) }}

biotapy-0.0.1/.gitignore

@@ -0,0 +1,23 @@
+# Temp files
+.DS_Store
+*~
+buck-out/
+
+# Compiled files
+.venv/
+__pycache__/
+.*cache/
+
+# Distribution / packaging
+/dist/
+# Library: resolve fresh in CI and for users; no committed lockfile
+/uv.lock
+
+# Tests and coverage
+/data/
+/node_modules/
+/.coverage*
+
+# docs
+/docs/generated/
+/docs/_build/

biotapy-0.0.1/.knowledge/contracts/data-model-slots.md

@@ -0,0 +1,82 @@
+---
+type: Contract
+title: Data-model slots
+description: Which AnnData/TreeData slot holds what, the exact result keys, the x_kind and provenance conventions, and which slots feature-changing operations drop.
+tags: [data-model, api]
+status: stable
+paths: ["src/biotapy/_core/**", "src/biotapy/io/**", "src/biotapy/pp/**", "src/biotapy/tl/**"]
+generated: { by: claude-code/claude-opus-5-5, at: 2026-09-26T08:21:10Z }
+commit: b77a226
+sources:
+  - id: spec
+    resource: ../../plan.md
+    title: Python Microbiome Toolkit development report
+    author: human:pedrocr83
+  - id: treedata
+    resource: https://github.com/YosefLab/treedata
+    title: treedata source (0.3.1)
+  - id: phyloseq-glom
+    resource: https://github.com/joey711/phyloseq/blob/master/R/transform_filter-methods.R
+    title: phyloseq tax_glom source
+---
+
+# Statement
+
+## Slots
+Extends the spec's data-model table with exact keys.[^spec]
+
+| Slot | Holds | Keys |
+|---|---|---|
+| `X` | samples x features, `scipy.sparse.csr_matrix` | kind recorded in `uns["biotapy"]["x_kind"]` |
+| `layers` | same-shape transforms of `X` | `relative`, `clr` |
+| `obs` | sample metadata; `tl` per-sample results with `inplace=True` | `alpha_<metric>` (e.g. `alpha_shannon`) |
+| `var` | taxonomy, one lowercase column per rank; sequences | ranks from `kingdom, phylum, class, order, family, genus, species`; `sequence` |
+| `vart` | phylogeny as `networkx.DiGraph`, leaves = `var_names`, edge attribute `length` | `phylo` only |
+| `obsm` | ordinations and embeddings | `X_pcoa`, `X_nmds`, `X_<plugin>` |
+| `obsp` | sample-sample distance matrices | metric name: `braycurtis`, `jaccard`, `unweighted_unifrac`, `weighted_unifrac` |
+| `uns["biotapy"]` | biotapy metadata, nothing else | `x_kind`, `provenance`, `pcoa` (eigenvalues, proportion explained) |
+
+## Conventions
+1. **Missing taxonomy** is `NaN`. Readers convert `""`, whitespace, `"NA"`, and
+   bare prefixes (`"g__"`) to `NaN`, strip `k__`-style prefixes, and map rank
+   aliases (`domain` -> `kingdom`) to the canonical lowercase names.
+2. **`x_kind`** is one of `counts`, `relative`, `rpk`, `cpm`, `abundance`.
+   Readers always set it. Missing key means `counts`. Functions that need raw
+   counts (rarefy, chao1) call `_core.require_counts` and raise otherwise.
+3. **Provenance** is `uns["biotapy"]["provenance"]`: a list of JSON strings
+   `{"step", "version", "params"}`, appended by `_core.add_provenance`.
+   JSON strings, not dicts, because h5ad cannot store a list of dicts.
+4. **Trees** are created only by `_core` ([tree-access](/contracts/tree-access.md))
+   with `label=None`, so TreeData adds no `tree` column to `var`.
+
+## Propagation
+| Operation | Keeps | Drops |
+|---|---|---|
+| Feature-changing (`pp.filter_features`, `pp.tax_glom`, `pp.rarefy`) | `obs`, `var` rows kept, `vart` (pruned by TreeData), `uns["biotapy"]` | all `layers`, `obsm`, `obsp`, `varm`, `varp`, other `uns` keys |
+| Sample-only (`pp.filter_samples`) | everything, subset by AnnData indexing | nothing |
+| Layer-adding (`pp.relative`, `pp.clr`) | everything | nothing; adds one layer |
+
+Feature-changing operations go through `_core.feature_subset`, the single place
+that implements the "Drops" column.
+
+## Aggregation semantics (`tax_glom`)
+Matches phyloseq:[^phyloseq-glom] features are grouped by the full lineage up
+to the rank (not the rank value alone, so `uncultured` genera in different
+families stay separate); the representative ("archetype") is the most abundant
+feature, first on ties; ranks below the target become `NaN`. The kept tree is
+the archetypes' subtree; TreeData keeps unary nodes, which leaves root-to-tip
+path lengths, and therefore Faith PD and UniFrac, unchanged.[^treedata]
+
+# Why
+A slot whose meaning depends on which function wrote it cannot be trusted by
+the next function. Dropping derived slots on feature changes prevents stale
+distances or ordinations from being plotted against new data.
+
+# Enforced by
+- `tests/core/test_slots.py` (Phase 1, task 1.2) for `feature_subset` and provenance.
+- `tests/datasets/test_toy.py` (task 1.3): h5td round-trip keeps every convention.
+- Per-function tests assert the documented keys.
+
+[^spec]: Python Microbiome Toolkit development report, section Data model
+[^treedata]: treedata source (0.3.1)
+[^phyloseq-glom]: phyloseq tax_glom source

biotapy-0.0.1/.knowledge/contracts/engine-parity.md

@@ -0,0 +1,38 @@
+---
+type: Contract
+title: Engine parity
+description: A compiled kernel is a drop-in behind an existing public function via `engine=`; the Python engine is the test oracle and both must match within a stated tolerance.
+tags: [performance, testing]
+status: stable
+paths: ["src/biotapy/**/*.py", "rust/**", "benchmarks/**"]
+generated: { by: claude-code/claude-opus-5-5, at: 2026-09-26T08:21:10Z }
+commit: b77a226
+sources:
+  - id: spec
+    resource: ../../plan.md
+    title: Python Microbiome Toolkit development report
+    author: human:pedrocr83
+---
+
+# Statement
+1. An engine is selected by `engine: Literal["python", "numba", "rust"] = "python"`
+   (or a delegated library's own switch, exposed under the same name).
+2. Adding an engine never changes the public signature or return type.
+3. The `"python"` engine is never removed; it is the reference oracle.
+4. The same test function runs across every available engine
+   (`@pytest.mark.parametrize("engine", available_engines())`) with an explicit
+   `rtol`/`atol` written in the test.
+5. Merge requires an `asv` benchmark on the 5,000 x 50,000 sparse synthetic
+   dataset showing >= 5x speedup, plus a note on the function's docs page.
+6. An engine whose optional dependency is missing raises `ImportError` naming
+   the extra; it never silently falls back to another engine.
+
+# Why
+Without an oracle, a fast kernel that is subtly wrong ships unnoticed; without
+the 5x bar, compiled code accumulates for marginal gains and raises the
+contributor bar for nothing. See [python-first-compiled-last](/decisions/python-first-compiled-last.md).
+
+# Enforced by
+- Parametrized engine tests (first instance: Phase 1 perf track, if any).
+- PR template checkbox "benchmark attached" (Phase 0, task 0.6).
+- Not otherwise automated: reviewers must check the asv result.

biotapy-0.0.1/.knowledge/contracts/function-shape.md

@@ -0,0 +1,73 @@
+---
+type: Contract
+title: Public function shape
+description: One task = one public function `verb(data, required, *, options) -> result`, fully typed, keyword-only options, seeded randomness, NumPy docstring with a parseable R-equivalent line.
+tags: [api, conventions, docs]
+status: stable
+paths: ["src/biotapy/**/*.py"]
+generated: { by: claude-code/claude-opus-5-5, at: 2026-09-26T08:21:10Z }
+commit: b77a226
+sources:
+  - id: spec
+    resource: ../../plan.md
+    title: Python Microbiome Toolkit development report
+    author: human:pedrocr83
+---
+
+# Statement
+
+Every public function in `io`, `datasets`, `pp`, `tl`, `fn`, `da`, `ml`, `pl`:
+
+1. **Signature**: `verb(data, <required args>, *, <options>) -> <result>`.
+   - `data` is annotated with the widest type that works: `AnnData` when no tree
+     is needed, `TreeData` when `vart` is read, `MuData` for multi-modal.
+   - Everything after the required arguments is keyword-only (`*`).
+   - No `**kwargs` pass-through, except a documented `plot_kwargs` in `pl`.
+2. **Return and mutation**: per [pure-by-default](/decisions/pure-by-default.md).
+3. **Randomness**: any stochastic function takes
+   `seed: int | np.random.Generator | None = None`, converted once with
+   `biotapy._core.as_generator(seed)`. No global RNG state is read or set.
+4. **Types**: full hints on parameters and return; no `Any`, no untyped
+   `dict`/`list` in public signatures; `Literal[...]` for string options.
+5. **Validation**: inputs are checked at the public boundary with
+   `biotapy._core` validators; errors are `ValueError`/`KeyError`/`TypeError`
+   naming the offending argument. Private helpers do not re-validate.
+6. **Docstring** (NumPy style, enforced by ruff `D` rules):
+
+   ```text
+   One-line summary ending with a period.
+
+   Parameters / Returns sections.
+
+   Notes
+   -----
+   R equivalent: ``phyloseq::tax_glom``, ``mia::agglomerateByRank``
+   Guide: :doc:`/guide/aggregation`
+
+   Examples
+   --------
+   >>> import biotapy as bt
+   >>> tdata = bt.datasets.toy()
+   >>> bt.pp.tax_glom(tdata, "phylum").n_vars
+   3
+   ```
+
+   - Exactly one line starting `R equivalent:`; comma-separated
+     ``pkg::fn`` items, or `none`. The "Coming from R" page is generated from it.
+   - Examples use `bt.datasets.toy()` (built in memory, no download) and run
+     under doctest in CI.
+
+# Why
+- Keyword-only options let parameters be added without breaking callers.
+- A seeded generator is the only way stochastic results are reproducible and testable.
+- A parseable `R equivalent:` line keeps the migration table generated, never hand-written.
+
+# Enforced by
+- ruff `D`, `PLR0913`, `PLR0917` and mypy strict (Phase 0, task 0.4).
+- `tests/test_docstrings.py` (Phase 1, task 1.19) parses every public function's `R equivalent:` line.
+- Doctests in CI (`--doctest-modules` in pytest config, Phase 0 task 0.4).
+- Purity: every `pp`/`tl` test asserts the input is unchanged.
+
+# Binds
+- [module-boundaries](/contracts/module-boundaries.md)
+- [data-model-slots](/contracts/data-model-slots.md)