ecotyper-py 0.1.0__tar.gz

ecotyper_py-0.1.0/LICENSE.md

@@ -0,0 +1,8 @@
+STANFORD NON-COMMERCIAL SOFTWARE LICENSE AGREEMENT <br>
+<br> 1. The Board of Trustees of the Leland Stanford Junior University (“Stanford”) provides EcoTyper software and code (“Service”) free of charge for non-commercial use only. Use of the Service by any commercial entity for any purpose, including research, is prohibited.
+<br> 2. By using the Service, you agree to be bound by the terms of this Agreement. Please read it carefully.
+<br> 3. You agree not to use the Service for commercial advantage, or in the course of for-profit activities. You agree not to use the Service on behalf of any organization that is not a non-profit organization. Commercial entities wishing to use this Service should contact Stanford University’s Office of Technology Licensing and reference docket S19-484.
+<br> 4. THE SERVICE IS OFFERED “AS IS”, AND, TO THE EXTENT PERMITTED BY LAW, STANFORD MAKES NO REPRESENTATIONS AND EXTENDS NO WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED. STANFORD SHALL NOT BE LIABLE FOR ANY CLAIMS OR DAMAGES WITH RESPECT TO ANY LOSS OR OTHER CLAIM BY YOU OR ANY THIRD PARTY ON ACCOUNT OF, OR ARISING FROM THE USE OF THE SERVICE. YOU HEREBY AGREE TO DEFEND AND INDEMNIFY STANFORD, ITS TRUSTEES, EMPLOYEES, OFFICERS, STUDENTS, AGENTS, FACULTY, REPRESENTATIVES, AND VOLUNTEERS (“STANFORD INDEMNITEES”) FROM ANY LOSS OR CLAIM ASSERTED AGAINST STANFORD INDEMNITEES ARISING FROM YOUR USE OF THE SERVICE.
+<br> 5. All rights not expressly granted to you in this Agreement are reserved and retained by Stanford or its licensors or content providers. This Agreement provides no license under any patent.
+<br> 6. You agree that this Agreement and any dispute arising under it is governed by the laws of the State of California, United States of America, applicable to agreements negotiated, executed, and performed within California.
+<br> 7. Subject to your compliance with the terms and conditions set forth in this Agreement, Stanford grants you a revocable, non-exclusive, non-transferable right to access and make use of the Service.

ecotyper_py-0.1.0/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: ecotyper-py
+Version: 0.1.0
+Summary: Python/AnnData port of EcoTyper (Luca, Steen et al., Cell 2021) with numerical parity to the R implementation
+Author: Ho Seok Lee
+License-Expression: LicenseRef-Stanford-NonCommercial
+Project-URL: Documentation, https://hoseok-lee.github.io/ecotyper-py/
+Project-URL: Original EcoTyper (R), https://github.com/digitalcytometry/ecotyper
+Keywords: ecotyper,anndata,scverse,single-cell,spatial transcriptomics,cell states,NMF
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: C
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Requires-Dist: pandas>=2.0
+Requires-Dist: anndata>=0.10
+Requires-Dist: numba>=0.59
+Requires-Dist: pyyaml>=6
+Provides-Extra: icu
+Requires-Dist: PyICU>=2.10; extra == "icu"
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.7; extra == "plot"
+Provides-Extra: sklearn
+Requires-Dist: scikit-learn>=1.3; extra == "sklearn"
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Provides-Extra: docs
+Requires-Dist: sphinx>=7; extra == "docs"
+Requires-Dist: furo; extra == "docs"
+Requires-Dist: myst-parser>=2; extra == "docs"
+Requires-Dist: sphinx-copybutton; extra == "docs"
+Requires-Dist: sphinx-design; extra == "docs"
+Dynamic: license-file
+
+# ecotyper-py (Python port of EcoTyper)
+
+A Python/AnnData port of **EcoTyper**
+(<https://github.com/digitalcytometry/ecotyper>), the framework for
+identifying cell states and multicellular communities (ecotypes) from bulk,
+single-cell and spatial transcriptomes, by the Newman lab (Stanford).
+
+The port reproduces the R implementation: on the README tutorials (compared
+against R on x86-64/glibc), every discrete output is identical, about 60% of the
+files are byte-identical, and all numeric outputs agree to ≤8e-11 relative. See
+the [validation report](https://hoseok-lee.github.io/ecotyper-py/validation.html) for the comparison.
+
+## Documentation
+
+<https://hoseok-lee.github.io/ecotyper-py/>. Sphinx docs (installation, API reference, step-by-step tutorials, Python vs R
+benchmarks with charts) live in `docs/`. They are built and published by `.github/workflows/docs.yml` on every
+push to `main`. To build them locally:
+
+```bash
+pip install -e ".[docs]"
+sphinx-build -b html docs docs/_build/html   # open docs/_build/html/index.html
+```
+
+## Credit and license
+
+EcoTyper was developed by Bogdan A. Luca, Chloé B. Steen, Aaron M. Newman and
+colleagues. If you use it, cite:
+
+- Luca/Steen et al., *Atlas of clinically distinct cell states and ecosystems
+  across human solid tumors*, Cell 2021, <https://doi.org/10.1016/j.cell.2021.09.014>
+- Steen/Luca et al., *The landscape of tumor cell states and ecosystems in
+  diffuse large B cell lymphoma*, Cancer Cell 2021,
+  <https://doi.org/10.1016/j.ccell.2021.08.011>
+
+This port is a derivative of EcoTyper and is distributed under the same
+**Stanford non-commercial license** (`LICENSE.md`, included in the package): free for
+non-commercial use only. It is an independent port, not affiliated with or endorsed by
+the EcoTyper authors.
+
+CIBERSORTx is closed source and is **not** part of the port. Steps that need it
+(cell type fractions and high-resolution purification) take precomputed
+CIBERSORTx outputs as inputs.
+
+## Installation
+
+```bash
+pip install ecotyper-py           # the import name is `ecotyper`
+pip install "ecotyper-py[icu]"    # optional: R-identical string sorting via PyICU
+```
+
+A C compiler (`cc`, `gcc` or `clang`) is needed at run time: the exact-parity kernels ship as C source and are
+compiled on first use. From a source checkout, or with conda:
+
+```bash
+conda create -n ecotyper-py -c conda-forge python=3.12 numpy scipy pandas anndata numba pyicu pyyaml pytest
+conda activate ecotyper-py
+pip install -e .          # from this folder
+```
+
+PyICU is optional; it is used to sort strings the way R does in a UTF-8 locale
+(`ECOTYPER_COLLATION=C` switches to byte order, like R with `LC_COLLATE=C`).
+
+## Usage
+
+### AnnData (scverse style)
+
+```python
+import ecotyper as et
+
+# recovery: bulk, single-cell or Visium, inferred from the AnnData
+et.recovery(adata, "Carcinoma", cell_type_key="cell_type", sample_key="patient")
+adata.obs["ecotyper_state_Fibroblasts"]           # S01, S02, ... (NaN = other cell types)
+adata.obs["ecotyper_ecotype"]                     # CE1..CE10
+adata.obsm["ecotyper_abundance_Fibroblasts"]      # state abundances
+
+# discovery from annotated single cells -> in-memory model
+model = et.discovery(adata, cell_type_key="cell_type", sample_key="patient", n_jobs=16)
+et.recovery(new_adata, model, cell_type_key="cell_type")
+model.save("models/crc")                          # R layout, usable by R EcoTyper too
+model = et.EcoTyperModel.load("models/crc")
+```
+
+- Data types: `bulk` (samples x genes), `scRNA` (cells x genes with cell type labels in
+  `obs`), `visium` (spots, with CIBERSORTx fractions passed as `fractions=`). Inferred
+  from `obsm["spatial"]` and the cell type column; override with `data_type=`.
+- `X` or `layer=` holds raw-scale expression; sparse matrices are accepted.
+- The built-in Carcinoma and Lymphoma models are downloaded (~5 MB each) from a pinned
+  commit of the R repository on first use and cached (`ECOTYPER_CACHE`; set
+  `ECOTYPER_MODELS` to a local `EcoTyper/` folder to skip the download).
+- Bulk discovery takes CIBERSORTx HiRes (or presorted) profiles:
+  `et.discovery({"B.cells": adata_b, "Fibroblasts": adata_fib, ...})`.
+
+Results are identical to the file-based workflows below (`tests/test_api.py`).
+
+### pandas and files (mirrors the R wrappers)
+
+`ecotyper.workflows` has `*_frame` functions (genes x samples DataFrames plus annotation,
+returning every intermediate table) and `*_files` functions that read the R wrappers'
+input files and write the R output layout file for file.
+
+### Command line (mirrors the R wrappers, writes the R file layout)
+
+```bash
+ecotyper-py recover-bulk  -m bulk_lung_data.txt -a bulk_lung_annotation.txt -d Carcinoma -o out   # built-in model
+ecotyper-py recover-scrna -m scRNA_CRC_data.txt -a scRNA_CRC_annotation.txt -d Carcinoma --models ecotyper/EcoTyper -o out
+ecotyper-py recover-visium -i VisiumBreast -f visium_fractions_example.txt -n VisiumBreast -d Carcinoma --models ecotyper/EcoTyper -o out
+ecotyper-py discover -i Tutorial_6/PresortedDiscovery -a Tutorial_6/PresortedDiscovery_annotation.txt -n PresortedDiscovery -o out -t 8
+ecotyper-py discover-scrna -m scRNA_CRC_data.txt -a scRNA_CRC_annotation.txt -n discovery_scRNA_CRC -o out -t 8
+```
+
+### Speed and alternative solver
+
+- `exact=True` (default) reproduces R bit-for-bit where R's arithmetic is deterministic (optimised C/numba kernels
+  with R's operation order; typically 3-7x faster than R on the single-cell and presorted tutorials).
+- `exact=False` (`--fast` on the CLI) uses BLAS updates and skips R's text round trips. Numerics stay within
+  about 1e-10 relative of R, and discrete outputs match on tutorials 1-4 and 6. On tutorial 5, 5 of 11 cell types
+  land in a different NMF consensus partition (NMF local optima), so use exact mode when you need R parity.
+- `nmf_method="cd"` (discovery only, `pip install ecotyper-py[sklearn]`) swaps the Brunet updates for scikit-learn's
+  coordinate-descent NMF with a Frobenius loss. It is not R-equivalent: chosen ranks and states differ from R.
+  See the [performance page](https://hoseok-lee.github.io/ecotyper-py/performance.html) for timings and agreement numbers.
+
+### Randomness
+
+R's random number generator (Mersenne-Twister with R's seeding, `runif`,
+`sample()` with rejection sampling) is reimplemented in
+`ecotyper.rcompat.rng.RRandom`. Discovery is deterministic as in R
+(`set.seed(1234 + restart)` per NMF run). R's recovery scripts call
+`NMF::rnmf()` **without** seeding, so R's own recovery results change slightly
+from run to run; the port takes an explicit `seed` (default 42), and an R run
+started with `set.seed(42)` (see `validation/r_reference/Rprofile.R`) gives
+the same output.
+
+## Layout
+
+| module | contents |
+|---|---|
+| `ecotyper.rcompat` | R semantics: RNG, `sample`, number parsing/formatting, `hclust`/`cutree`/`dist`/`silhouette`, `cor`/`var`/`mean`, quantiles, BH, t-test, Wilcoxon, collation, `merge`/`order` |
+| `ecotyper.nmf` | NMF package 0.28: Brunet updates, seeding, connectivity stopping, restarts merging, cophenetic/silhouette/dispersion, `NMFpredict` |
+| `ecotyper.recovery_steps` | state and ecotype recovery (bulk, scRNA, Visium) |
+| `ecotyper.discovery_steps`, `ecotyper.discovery_scrna` | state and ecotype discovery |
+| `ecotyper.api` | `recovery`, `discovery`, `infer_data_type` (scverse-style AnnData API) |
+| `ecotyper.workflows` | pandas and file-based workflows mirroring the R wrappers |
+| `ecotyper.model`, `ecotyper.builtin` | `EcoTyperModel` (load/save/from discovery), built-in model download |
+| `ecotyper.io`, `ecotyper.rlayout` | readers, R-format writers |
+| `ecotyper.validate` | file-by-file comparison with R outputs |
+
+Plots (heatmaps) are not ported.
+
+## Tests
+
+```bash
+pytest -m "not e2e"     # unit parity tests against R fixtures in tests/data
+pytest -m e2e           # tutorials vs R reference outputs (needs the R references, see validation/)
+```

ecotyper_py-0.1.0/README.md

@@ -0,0 +1,154 @@
+# ecotyper-py (Python port of EcoTyper)
+
+A Python/AnnData port of **EcoTyper**
+(<https://github.com/digitalcytometry/ecotyper>), the framework for
+identifying cell states and multicellular communities (ecotypes) from bulk,
+single-cell and spatial transcriptomes, by the Newman lab (Stanford).
+
+The port reproduces the R implementation: on the README tutorials (compared
+against R on x86-64/glibc), every discrete output is identical, about 60% of the
+files are byte-identical, and all numeric outputs agree to ≤8e-11 relative. See
+the [validation report](https://hoseok-lee.github.io/ecotyper-py/validation.html) for the comparison.
+
+## Documentation
+
+<https://hoseok-lee.github.io/ecotyper-py/>. Sphinx docs (installation, API reference, step-by-step tutorials, Python vs R
+benchmarks with charts) live in `docs/`. They are built and published by `.github/workflows/docs.yml` on every
+push to `main`. To build them locally:
+
+```bash
+pip install -e ".[docs]"
+sphinx-build -b html docs docs/_build/html   # open docs/_build/html/index.html
+```
+
+## Credit and license
+
+EcoTyper was developed by Bogdan A. Luca, Chloé B. Steen, Aaron M. Newman and
+colleagues. If you use it, cite:
+
+- Luca/Steen et al., *Atlas of clinically distinct cell states and ecosystems
+  across human solid tumors*, Cell 2021, <https://doi.org/10.1016/j.cell.2021.09.014>
+- Steen/Luca et al., *The landscape of tumor cell states and ecosystems in
+  diffuse large B cell lymphoma*, Cancer Cell 2021,
+  <https://doi.org/10.1016/j.ccell.2021.08.011>
+
+This port is a derivative of EcoTyper and is distributed under the same
+**Stanford non-commercial license** (`LICENSE.md`, included in the package): free for
+non-commercial use only. It is an independent port, not affiliated with or endorsed by
+the EcoTyper authors.
+
+CIBERSORTx is closed source and is **not** part of the port. Steps that need it
+(cell type fractions and high-resolution purification) take precomputed
+CIBERSORTx outputs as inputs.
+
+## Installation
+
+```bash
+pip install ecotyper-py           # the import name is `ecotyper`
+pip install "ecotyper-py[icu]"    # optional: R-identical string sorting via PyICU
+```
+
+A C compiler (`cc`, `gcc` or `clang`) is needed at run time: the exact-parity kernels ship as C source and are
+compiled on first use. From a source checkout, or with conda:
+
+```bash
+conda create -n ecotyper-py -c conda-forge python=3.12 numpy scipy pandas anndata numba pyicu pyyaml pytest
+conda activate ecotyper-py
+pip install -e .          # from this folder
+```
+
+PyICU is optional; it is used to sort strings the way R does in a UTF-8 locale
+(`ECOTYPER_COLLATION=C` switches to byte order, like R with `LC_COLLATE=C`).
+
+## Usage
+
+### AnnData (scverse style)
+
+```python
+import ecotyper as et
+
+# recovery: bulk, single-cell or Visium, inferred from the AnnData
+et.recovery(adata, "Carcinoma", cell_type_key="cell_type", sample_key="patient")
+adata.obs["ecotyper_state_Fibroblasts"]           # S01, S02, ... (NaN = other cell types)
+adata.obs["ecotyper_ecotype"]                     # CE1..CE10
+adata.obsm["ecotyper_abundance_Fibroblasts"]      # state abundances
+
+# discovery from annotated single cells -> in-memory model
+model = et.discovery(adata, cell_type_key="cell_type", sample_key="patient", n_jobs=16)
+et.recovery(new_adata, model, cell_type_key="cell_type")
+model.save("models/crc")                          # R layout, usable by R EcoTyper too
+model = et.EcoTyperModel.load("models/crc")
+```
+
+- Data types: `bulk` (samples x genes), `scRNA` (cells x genes with cell type labels in
+  `obs`), `visium` (spots, with CIBERSORTx fractions passed as `fractions=`). Inferred
+  from `obsm["spatial"]` and the cell type column; override with `data_type=`.
+- `X` or `layer=` holds raw-scale expression; sparse matrices are accepted.
+- The built-in Carcinoma and Lymphoma models are downloaded (~5 MB each) from a pinned
+  commit of the R repository on first use and cached (`ECOTYPER_CACHE`; set
+  `ECOTYPER_MODELS` to a local `EcoTyper/` folder to skip the download).
+- Bulk discovery takes CIBERSORTx HiRes (or presorted) profiles:
+  `et.discovery({"B.cells": adata_b, "Fibroblasts": adata_fib, ...})`.
+
+Results are identical to the file-based workflows below (`tests/test_api.py`).
+
+### pandas and files (mirrors the R wrappers)
+
+`ecotyper.workflows` has `*_frame` functions (genes x samples DataFrames plus annotation,
+returning every intermediate table) and `*_files` functions that read the R wrappers'
+input files and write the R output layout file for file.
+
+### Command line (mirrors the R wrappers, writes the R file layout)
+
+```bash
+ecotyper-py recover-bulk  -m bulk_lung_data.txt -a bulk_lung_annotation.txt -d Carcinoma -o out   # built-in model
+ecotyper-py recover-scrna -m scRNA_CRC_data.txt -a scRNA_CRC_annotation.txt -d Carcinoma --models ecotyper/EcoTyper -o out
+ecotyper-py recover-visium -i VisiumBreast -f visium_fractions_example.txt -n VisiumBreast -d Carcinoma --models ecotyper/EcoTyper -o out
+ecotyper-py discover -i Tutorial_6/PresortedDiscovery -a Tutorial_6/PresortedDiscovery_annotation.txt -n PresortedDiscovery -o out -t 8
+ecotyper-py discover-scrna -m scRNA_CRC_data.txt -a scRNA_CRC_annotation.txt -n discovery_scRNA_CRC -o out -t 8
+```
+
+### Speed and alternative solver
+
+- `exact=True` (default) reproduces R bit-for-bit where R's arithmetic is deterministic (optimised C/numba kernels
+  with R's operation order; typically 3-7x faster than R on the single-cell and presorted tutorials).
+- `exact=False` (`--fast` on the CLI) uses BLAS updates and skips R's text round trips. Numerics stay within
+  about 1e-10 relative of R, and discrete outputs match on tutorials 1-4 and 6. On tutorial 5, 5 of 11 cell types
+  land in a different NMF consensus partition (NMF local optima), so use exact mode when you need R parity.
+- `nmf_method="cd"` (discovery only, `pip install ecotyper-py[sklearn]`) swaps the Brunet updates for scikit-learn's
+  coordinate-descent NMF with a Frobenius loss. It is not R-equivalent: chosen ranks and states differ from R.
+  See the [performance page](https://hoseok-lee.github.io/ecotyper-py/performance.html) for timings and agreement numbers.
+
+### Randomness
+
+R's random number generator (Mersenne-Twister with R's seeding, `runif`,
+`sample()` with rejection sampling) is reimplemented in
+`ecotyper.rcompat.rng.RRandom`. Discovery is deterministic as in R
+(`set.seed(1234 + restart)` per NMF run). R's recovery scripts call
+`NMF::rnmf()` **without** seeding, so R's own recovery results change slightly
+from run to run; the port takes an explicit `seed` (default 42), and an R run
+started with `set.seed(42)` (see `validation/r_reference/Rprofile.R`) gives
+the same output.
+
+## Layout
+
+| module | contents |
+|---|---|
+| `ecotyper.rcompat` | R semantics: RNG, `sample`, number parsing/formatting, `hclust`/`cutree`/`dist`/`silhouette`, `cor`/`var`/`mean`, quantiles, BH, t-test, Wilcoxon, collation, `merge`/`order` |
+| `ecotyper.nmf` | NMF package 0.28: Brunet updates, seeding, connectivity stopping, restarts merging, cophenetic/silhouette/dispersion, `NMFpredict` |
+| `ecotyper.recovery_steps` | state and ecotype recovery (bulk, scRNA, Visium) |
+| `ecotyper.discovery_steps`, `ecotyper.discovery_scrna` | state and ecotype discovery |
+| `ecotyper.api` | `recovery`, `discovery`, `infer_data_type` (scverse-style AnnData API) |
+| `ecotyper.workflows` | pandas and file-based workflows mirroring the R wrappers |
+| `ecotyper.model`, `ecotyper.builtin` | `EcoTyperModel` (load/save/from discovery), built-in model download |
+| `ecotyper.io`, `ecotyper.rlayout` | readers, R-format writers |
+| `ecotyper.validate` | file-by-file comparison with R outputs |
+
+Plots (heatmaps) are not ported.
+
+## Tests
+
+```bash
+pytest -m "not e2e"     # unit parity tests against R fixtures in tests/data
+pytest -m e2e           # tutorials vs R reference outputs (needs the R references, see validation/)
+```

ecotyper_py-0.1.0/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ecotyper-py"
+version = "0.1.0"
+description = "Python/AnnData port of EcoTyper (Luca, Steen et al., Cell 2021) with numerical parity to the R implementation"
+readme = "README.md"
+license = "LicenseRef-Stanford-NonCommercial"
+license-files = ["LICENSE.md"]
+requires-python = ">=3.10"
+authors = [{ name = "Ho Seok Lee" }]
+keywords = ["ecotyper", "anndata", "scverse", "single-cell", "spatial transcriptomics", "cell states", "NMF"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: C",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+]
+dependencies = [
+    "numpy>=1.24",
+    "scipy>=1.10",
+    "pandas>=2.0",
+    "anndata>=0.10",
+    "numba>=0.59",
+    "pyyaml>=6",
+]
+
+[project.optional-dependencies]
+icu = ["PyICU>=2.10"]
+plot = ["matplotlib>=3.7"]
+sklearn = ["scikit-learn>=1.3"]
+test = ["pytest>=7"]
+docs = ["sphinx>=7", "furo", "myst-parser>=2", "sphinx-copybutton", "sphinx-design"]
+
+[project.urls]
+Documentation = "https://hoseok-lee.github.io/ecotyper-py/"
+"Original EcoTyper (R)" = "https://github.com/digitalcytometry/ecotyper"
+
+[project.scripts]
+ecotyper-py = "ecotyper.cli:main"
+
+[tool.setuptools.package-data]
+ecotyper = ["*.c", "rcompat/*.c"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "r: needs the ecotyper-r conda environment (Rscript) to generate references",
+    "e2e: end-to-end comparison against R reference outputs (slow)",
+]

ecotyper_py-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ecotyper_py-0.1.0/src/ecotyper/__init__.py

@@ -0,0 +1,17 @@
+"""EcoTyper in Python, with numerical parity to the R implementation.
+
+scverse-style API::
+
+    import ecotyper as et
+
+    et.recovery(adata, model="Carcinoma")         # bulk, scRNA-seq or Visium (inferred)
+    model = et.discovery(adata_sc)                 # scRNA-seq discovery -> EcoTyperModel
+    model.save("my_model"); et.EcoTyperModel.load("my_model")
+
+File-based workflows mirroring the R scripts are in :mod:`ecotyper.workflows`.
+"""
+from .api import discovery, infer_data_type, recovery
+from .model import EcoTyperModel
+
+__version__ = "0.1.0"
+__all__ = ["EcoTyperModel", "discovery", "infer_data_type", "recovery"]

ecotyper_py-0.1.0/src/ecotyper/_ckernel.py

@@ -0,0 +1,102 @@
+"""Build and load the C kernels shipped as source (``_nmfk.c``) with the system C compiler.
+
+The R-exact Brunet loop (:func:`ecotyper.nmf.run_brunet`) uses ``_nmfk.c`` when it can be
+compiled: same operations as the numba kernels, blocked so that the compiler vectorises them
+(bit-identical results, verified in ``tests/test_nmf.py``). ``ECOTYPER_NMF_KERNEL=numba``
+forces the numba kernels. Built libraries are cached in ``$ECOTYPER_CACHE`` (default: the
+temporary directory).
+"""
+from __future__ import annotations
+
+import ctypes as C
+import hashlib
+import os
+import platform
+import subprocess
+import sys
+import tempfile
+import warnings
+from pathlib import Path
+
+from .rcompat._ld import _compiler
+from .rcompat.fma import USE_FMA
+
+_SRC = Path(__file__).with_name("_nmfk.c")
+
+
+def _avx512() -> bool:
+    try:
+        with open("/proc/cpuinfo") as fh:
+            return any(line.startswith("flags") and " avx512f" in line for line in fh)
+    except OSError:
+        return False
+
+
+def _flags() -> list[str]:
+    f = ["-O3", "-ffp-contract=off", "-fno-math-errno", "-fPIC", "-shared"]
+    if platform.machine().lower() in ("x86_64", "amd64"):
+        # AVX2/AVX-512 and an inlined fma(); cached per machine below. Block width = columns
+        # processed together: 4 x BW accumulators should fill the vector registers (measured
+        # on a Xeon Gold 6258R: BW=64 with 512-bit vectors 3.5-4x faster than the numba kernel).
+        f.append("-march=native")
+        f += ["-mprefer-vector-width=512", "-DBW=64"] if _avx512() else ["-DBW=32"]
+    else:
+        f.append("-DBW=16")  # Apple silicon: 32 x 128-bit registers
+    if USE_FMA:
+        f.append("-DUSE_FMA")
+    return f
+
+
+def build(src: Path, flags: list[str], optional: tuple = ()) -> Path:
+    """Compile ``src`` into a shared library (cached by source, flags and machine), with the
+    ``optional`` flags (e.g. ``-fopenmp``) if the compiler accepts them."""
+    cc = _compiler()
+    if cc is None:
+        raise RuntimeError("no C compiler found")
+    key = src.read_bytes() + " ".join([sys.platform, platform.machine(), platform.node(), cc] + flags).encode()
+    tag = hashlib.sha1(key).hexdigest()[:12]
+    cache = Path(os.environ.get("ECOTYPER_CACHE", Path(tempfile.gettempdir()) / "ecotyper_ld"))
+    cache.mkdir(parents=True, exist_ok=True)
+    so = cache / f"{src.stem}_{tag}.so"
+    if so.exists():
+        return so
+    tmp = cache / f"{src.stem}_{tag}.{os.getpid()}.so"
+    for extra in ([list(optional)] if optional else []) + [[]]:
+        r = subprocess.run([cc, *flags, *extra, str(src), "-o", str(tmp), "-lm"], capture_output=True, text=True)
+        if r.returncode == 0:
+            os.replace(tmp, so)
+            return so
+    raise RuntimeError(f"building {src.name} failed:\n{r.stderr}")
+
+
+def _build() -> Path:
+    return build(_SRC, _flags(), ("-fopenmp",))
+
+
+def _load():
+    if os.environ.get("ECOTYPER_NMF_KERNEL", "c") == "numba":
+        return None
+    try:
+        lib = C.CDLL(str(_build()))
+    except Exception as e:  # pragma: no cover
+        warnings.warn(f"C NMF kernel unavailable ({e}); using the (slower) numba kernels")
+        return None
+    dp = C.POINTER(C.c_double)
+    i64 = C.c_int64
+    lib.brunet_loop.restype = i64
+    lib.brunet_loop.argtypes = [dp, dp, dp, dp, i64, i64, i64, i64, C.c_int, i64, i64, C.c_double, C.POINTER(i64),
+                                C.c_int]
+    return lib
+
+
+_LIB = None
+_LOADED = False
+
+
+def nmf_lib():
+    """The loaded ``_nmfk`` library, or ``None`` (numba fallback)."""
+    global _LIB, _LOADED
+    if not _LOADED:
+        _LIB = _load()
+        _LOADED = True
+    return _LIB