mortis-spatial 0.1.0__tar.gz

mortis_spatial-0.1.0/CHANGELOG.md

@@ -0,0 +1,217 @@
+# Changelog
+
+Notable changes, in [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
+order, versioned with [SemVer](https://semver.org/).
+
+## [0.1.0], unreleased
+
+The first version worth putting a number on. Everything before this was me
+finding out what the package needed to be; the version counter is starting here
+because that is honest, even though the code has been through a lot more than
+"0.1" usually implies.
+
+It works, it is tested on real public data, and it is under review for
+publication. What it is not yet is released.
+
+### The four things that were quietly wrong
+
+Every one of these produced numbers. Wrong ones. Each was reproduced before it
+was fixed, and each now has a test that fails on the old code.
+
+- **Spatial coordinates collapsed when sections were combined.** Batches were
+  pushed apart by `i * 1e6` in float32, and float32 runs out of precision at
+  around 8.4 million, past which neighbouring pixels round onto each other. On
+  a real 52-section cohort, **35 sections lost roughly half their distinct pixel
+  positions**, which silently corrupted Moran's I, Geary's C, Gi\*, LISA,
+  co-occurrence, spatial domains and spatially-weighted NMF for all of them.
+  Now float64, with the offset derived from the actual coordinate range instead
+  of a hard-coded constant that assumed your microns were small.
+- **A cache that never noticed the data had changed.** `_get_X` memoised a dense
+  copy into `.uns` and never invalidated it, so anything that replaced `.X`,
+  `scale()`, `correct_batches()`, sparse normalisation, left every later call
+  reading pre-correction data. Wiping `.X` to all zeros still returned the
+  original statistics, cheerfully. It also kept up to four full copies of the
+  matrix (~2.4 GB on a 100k × 2000 dataset) and wrote them into every saved
+  `.h5ad`. Deleted. Rebuilding costs about half a second.
+- **Permutation tests were not reproducible.** `np.random.seed` inside a
+  `@njit(parallel=True)` function seeds exactly one worker thread and leaves the
+  rest to their own devices, so results depended on how many cores you had. Same
+  seed, 1 vs 4 threads, |Δz| up to 0.79, and not even repeatable twice in the
+  same process. Each permutation now draws its own independent seed stream.
+- **`compare_groups` was testing pixels as if they were patients.** On simulated
+  data with six patients and *no group difference at all*, it called **183 of
+  200** metabolites significant. It still exists for genuine within-section
+  comparisons, but it now warns and points at the sample-level path.
+
+### Added
+
+- **`mortis.stats`**: the sample-level statistics that make everything else
+  legitimate. `pseudobulk()`, `differential_abundance()` (Cliff's δ first,
+  Mann-Whitney and BH-FDR as supporting detail, optional bootstrap interval),
+  `paired_differential_abundance()` for before/after designs, and
+  `cliffs_delta()` on its own.
+- **`mortis.organization`**: differential spatial *organization*. Summarises
+  how each metabolite is arranged per section (Moran's I, normalised entropy,
+  Gi\* hotspot fraction, Gini), then tests those the same way abundance is
+  tested. `compare_abundance_and_organization()` labels which axis moved; the
+  "organization only" class is the one nothing else can find.
+
+  Benchmarked honestly: with 3 planted differences among 30 metabolites, effect
+  size alone over-called at every cohort size, while effect size plus FDR gave
+  exactly 3 true and 0 false **from six sections per group upward, and nothing
+  below it**. Six per arm is the floor, it is documented, and it is pinned by a
+  test.
+- **`mortis.compare`**: `cross_cohort_profile()` and `track_flow()`: do two
+  drugs move the same metabolites, and does a signature persist, reorganise or
+  flip over time.
+- **`mortis.annotate`**: layered chemical-class assignment, class-level
+  enrichment, and directional pathway over-representation. On a real
+  2,231-compound untargeted panel the built-in name rules leave about 55%
+  unclassified; a `reference=` mapping from HMDB or LIPID MAPS takes that to
+  28%. Both numbers are in the docstring rather than hidden, because a
+  classifier that quietly places two-thirds of a panel and says nothing about
+  the rest is the exact failure this module exists to avoid.
+- **`mortis.pathway`**: compound names → HMDB/KEGG identifiers → pathways →
+  enrichment, in one call, cached on disk. The original plan was to hand
+  enrichment to MetaboAnalyst; it turns out to document exactly one REST
+  endpoint and enrichment is not it. Doing the statistics locally is better
+  anyway, because the background set decides the answer and a web service
+  cannot know which compounds *your* instrument saw.
+- **`mortis.reproducibility`**: `export_manifest()` and `verify_manifest()`.
+  A sealed JSON recording the environment, every recorded step, and SHA-256
+  fingerprints of the inputs and every result table. Hand it to a reviewer:
+  they can confirm your analysis reproduces without you sending them any data,
+  because checksums only go one way. "Available on reasonable request" verifies
+  nothing; this verifies something.
+- **`mortis.viz`**: publication figures. PDF text stays *text* (embedded
+  TrueType with a character map), so a co-author can retype a label in
+  Illustrator instead of emailing you about it. Only dense scatter interiors get
+  rasterised. Every figure carries its parameters and a hash in the PDF
+  metadata, so `pdfinfo` will tell you which run made it long after you have
+  forgotten. `theme="light"/"dark"` renders on a transparent ground for slides
+  and web, and `ion_cmap()` replaces viridis as the ion-image default, still
+  perceptually ordered, just less obviously the work of a plotting library.
+- **`validation/run_validation.py`**: the package run end-to-end against a
+  public METASPACE study, no simulation and nothing else in the pipeline.
+- **A documentation site** in `web/`, with the API reference generated from the
+  installed package at build time so it cannot drift from the code.
+
+### Changed
+
+- **The bundled drug list is built from Wikidata instead of DrugBank.**
+  DrugBank releases its data under CC BY-NC, which does not permit shipping it
+  inside a wheel that anyone, including commercial users, can install from
+  PyPI. The vocabulary is now assembled from Wikidata, which is CC0: an entry
+  counts as a drug when Wikidata gives it a DrugBank or ATC identifier, or
+  files it under medication or pharmaceutical product. That comes to 20,181
+  names and 43,697 synonyms, against 17,430 and 45,731 before, and every drug
+  in a 19-compound spot check is still found. `tools/build_drug_vocabulary.py`
+  rebuilds it. `list_drug_matches()` returns `is_drug` in place of
+  `in_drugbank`, and adds an `endogenous` column, since taurine, cholesterol
+  and most amino acids carry drug identifiers and `remove_all=True` would
+  otherwise delete them from a metabolomics panel without comment.
+- **`leidenalg` and `python-igraph` moved to a `[cluster]` extra.** Both are
+  GPL while MORTIS is MIT, so installing them makes the whole environment GPL.
+  That is a decision for whoever installs it, not something `pip install
+  mortis-spatial` should make on their behalf. `cluster()` and
+  `spatial_domains()` raise with the install command when they are missing;
+  nothing else in the package touches them.
+- **The Leiden backend is named explicitly.** scanpy is switching its default
+  from `leidenalg` to `igraph`, and the two do not give the same partition, so
+  an unpinned call would have quietly changed everybody's clusters on a scanpy
+  upgrade. Minimum scanpy is now 1.10, which is where the argument appeared.
+- **`correct_batches()` raises when ComBat fails** instead of mean-centring
+  each batch and printing a line about it. Substituting a weaker method
+  returns data corrected by something other than what was asked for, and other
+  than what the methods section will say.
+- **Warnings go through `warnings.warn`.** Three modules printed them to
+  stdout, where they could not be filtered, caught or redirected, and were
+  invisible to `pytest.warns`.
+- **`mortis.audit` removed.** `export_manifest()` records everything it did,
+  plus a verification step it never had. Two receipt systems in one package
+  was one too many.
+- **`merge_samples()` no longer writes into the list it was given.** It
+  replaced the caller's elements with relabelled copies.
+
+- **Spatial statistics stream over metabolite tiles.** The direct formulation
+  held several full pixels × metabolites matrices at once. Since the reduction
+  is over pixels and every output is one scalar per metabolite, metabolites can
+  be processed in tiles, exactly the same arithmetic, reassociated. Combined
+  with deriving `W @ (X − mean)` from `W @ X` algebraically, on a 95,751 × 2,231
+  dataset: **1.23 s → 0.62 s, working set 4.30 GB → 0.99 GB, bit-identical
+  checksums.**
+
+  Tile size is picked from free RAM rather than cache size, because
+  cache-sized tiles measured *slowest*: SciPy walks the whole sparse structure
+  of the weights matrix once per tile regardless of how many columns come along
+  for the ride, so amortising that beats locality. This was genuinely
+  counter-intuitive and the measurement is in the code.
+- Sparse and disk-backed (`backed="r"`) inputs are now covered by tests proving
+  they give identical answers to dense ones.
+- `metabolite_colocalization()` gained `metric="cosine_median"`, the measure
+  that actually won the ColocML benchmark. Opt-in, not default, because it
+  rasterises by coordinate span and scattered coordinates would ask for an
+  enormous empty grid, now guarded, after it hung the test suite once.
+- The ColocML citation was wrong. It is Ovchinnikova, Stuart, Rakhlin,
+  Nikolenko & Alexandrov, *Bioinformatics* 2020;36(10):3215-3224, not
+  "Ryabchykov et al.", which is a paper about something else entirely.
+- `local_moran()` gained a docstring, including an explicit warning that its
+  p-values are approximate rather than Anselin's conditional permutation. Fine
+  for ranking pixels and drawing a LISA map; not something to report as
+  calibrated inference, and it now says so instead of calling them "fast
+  analytical p-values".
+- Comments and docstrings across the older modules were rewritten out of
+  marketing voice. "Seamless integration", "Intelligently detects",
+  "Ultra-fast index creation utilizing Python List Comprehensions" and a
+  section header reading `KILLER FEATURES` are all gone. None of it told a
+  reader anything they could use.
+- **Minimum Python is now 3.10**, not 3.9. 3.9 was declared and never tested;
+  the CI matrix has always started at 3.10. Verified rather than assumed.
+- `test_data/` is explicitly gitignored. The previous global `*.h5ad` rule
+  covered two fixtures and missed the patient CSV entirely.
+
+### Fixed
+
+- Progress messages crashed on a Windows console using a legacy code page.
+  `->`, `>=` and similar characters cannot be encoded in cp1252, so a
+  `print()` containing one raised `UnicodeEncodeError` instead of reporting
+  progress. The package source is ASCII now, bar a plus-minus in the
+  stereodescriptor regex and a micrometre sign in one axis label, and a test
+  keeps it that way.
+- Every public function has a docstring. Nineteen of them had none, so `help()`
+  and IDE tooltips came back blank even though the documentation site covered
+  them.
+- `neighborhood_enrichment(n_jobs=...)` crashed with `ValueError: The number of
+  threads must be between 1 and N` when asked for more threads than the machine
+  has. Numba fixes its ceiling at import; asking for more is a wish, not an
+  error, so the request is clamped.
+- Compatible with pandas 3 and anndata 0.13, both of which arrive by default on
+  Python 3.12. Two test assumptions broke there, pandas 3 string columns do not
+  support 2-D fancy indexing, and anndata 0.13 lists `.X` under a `None` key in
+  `layers`, while the package itself was already correct. Error messages that
+  list available layers now filter that `None` out, because showing it to
+  someone hunting for a metric name helps nobody.
+- `save_figure()` used `Path.with_suffix("")`, which eats everything after the
+  last dot: `two_axis.dark` quietly became `two_axis`, and `figure_v1.2` would
+  have lost its version.
+- Two runs of the same analysis produced different files. Result tables sorted
+  on effect size with no tiebreaker, so equally-ranked metabolites came out in
+  whatever order the sort happened to leave them; and figure PDFs carried the
+  wall-clock time. Ties now break on the compound name, and `SOURCE_DATE_EPOCH`
+  is honoured, so `diff` is a usable way to ask whether anything changed. The
+  public-data validation reproduces byte-for-byte apart from the manifest,
+  which records when the run happened on purpose.
+- Error messages said what was wrong but not what to do about it.
+  `'sample' not found in adata.obs.` is technically accurate and practically
+  useless; it now lists the columns that do exist and, when the name looks like
+  a typo, guesses which one you meant. Several also told you to call
+  `MORTIS.preprocess()`, which is not how the package is imported.
+- `plot_abundance_vs_organization` and `plot_signature_comparison` drew one dot
+  per coordinate, and on a small cohort Cliff's delta takes so few distinct
+  values that a whole panel collapses onto a handful of points. The figure
+  showed twelve dots while the legend said 160. Marker area now scales with how
+  many metabolites share a position, and the figure says so.
+- Group labels on `plot_organization_heatmap` were rotated, so on a two-section
+  arm the text was taller than its own band and the group names printed over
+  each other.
+

mortis_spatial-0.1.0/CITATION.cff

@@ -0,0 +1,42 @@
+cff-version: 1.2.0
+title: "MORTIS: cohort-scale analysis for spatial metabolomics"
+message: >-
+  Please cite the software using the metadata below, including the version
+  you actually ran. Once the paper is out the preferred citation will be the
+  article.
+version: 0.1.0
+date-released: "2026-09-30"
+license: MIT
+type: software
+authors:
+  - given-names: Faris
+    family-names: Hrvat
+    email: farishrvatit@gmail.com
+    # orcid: "https://orcid.org/0000-0000-0000-0000"
+repository-code: "https://github.com/FarisHrvat/mortis"
+url: "https://farishrvat.github.io/mortis/"
+abstract: >-
+  A Python package for downstream analysis of spatial metabolomics data
+  (MALDI-MSI, DESI and related imaging mass spectrometry). It tests at the
+  patient level rather than the pixel level, measures differential spatial
+  organization, whether a metabolite is arranged differently between groups
+  independently of how much of it there is, compares cohorts and timepoints,
+  and exports publication figures alongside a sealed manifest that lets a
+  reviewer verify an analysis reproduces without access to the underlying data.
+keywords:
+  - spatial metabolomics
+  - imaging mass spectrometry
+  - MALDI-MSI
+  - pseudobulk
+  - spatial statistics
+  - reproducibility
+  - bioinformatics
+  - anndata
+doi: 10.5281/zenodo.23056382
+identifiers:
+  - type: doi
+    value: 10.5281/zenodo.23056382
+    description: Concept DOI, always resolves to the newest version.
+  - type: doi
+    value: 10.5281/zenodo.23056383
+    description: DOI for version 0.1.0.

mortis_spatial-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,123 @@
+# Contributing
+
+Thanks for looking. This is a scientific package, which means a bug here does
+not crash. It prints a number that is wrong, and somebody puts that number in a
+paper. Most of what follows exists because of that.
+
+## Setting up
+
+```bash
+git clone https://github.com/FarisHrvat/mortis.git && cd mortis
+python -m venv .venv && source .venv/bin/activate   # or conda/micromamba
+pip install -e ".[dev]"
+```
+
+Python 3.10 or newer. CI runs 3.10, 3.11 and 3.12 on Linux and macOS, so those
+are the versions that are actually promised.
+
+Worth knowing: on 3.12 pip resolves **pandas 3 and anndata 0.13**, which behave
+differently from what 3.10 and 3.11 get. If a test passes locally and fails in
+CI, that is the first thing to check.
+
+## Before you open a pull request
+
+```bash
+pytest          # 520 tests, about 25 seconds
+ruff check .
+```
+
+Both have to pass. CI runs exactly these.
+
+## Tests
+
+The rule: **a test for a bug fix has to fail on the code before the fix.**
+
+If it passes both before and after, it is not testing what you think it is. When
+the four defects in `test_reproducibility.py` were fixed, the new tests were run
+against the old code first, 9 of 18 failed, which is how anyone knows they mean
+something.
+
+Some practical consequences:
+
+- **Check the artefact, not the setting.** "PDF text stays editable" is a
+  property of the bytes in the file, so the test looks for `/FontFile2` in the
+  PDF and round-trips it through `pdftotext`. Asserting that an rcParam was set
+  proves nothing about the file a co-author opens.
+- **Look at figures.** Three real bugs: clipped axis labels, a title landing on
+  the panel labels, and a legend sitting on top of the bars, passed every
+  assertion and were found by rendering a PNG and looking at it.
+- **Network tests are opt-in.** `tests/test_pathway.py` runs offline against
+  captured payloads. The live-service tests need `MORTIS_TEST_NETWORK=1`, so
+  the suite neither flakes nor hammers somebody else's free API.
+
+## Statistics
+
+One non-negotiable, because it is the whole reason this package exists:
+**pixels are not replicates.**
+
+Anything that compares groups of samples goes through `pseudobulk()` first.
+A section has tens of thousands of pixels and one patient; testing the pixels
+inflates *n* by four orders of magnitude. On simulated null data that is the
+difference between 0 findings and 183 of them.
+
+If you add a test that compares groups, it needs a null-data case showing it
+does not invent results.
+
+## Writing
+
+Comments explain **why**, not what. The code already says what.
+
+```python
+# Bad, restates the line below it
+# Set the number of threads
+nb.set_num_threads(n)
+
+# Good, says the thing you cannot see
+# Numba fixes its ceiling at import from the core count, so asking for more
+# than the machine has raises rather than just using what is available.
+nb.set_num_threads(int(np.clip(requested, 1, nb.config.NUMBA_NUM_THREADS)))
+```
+
+Please avoid marketing voice. "Seamless integration", "intelligently detects"
+and "ultra-fast" have all been removed from this codebase once already and none
+of them told a reader anything actionable. Plain sentences, and a joke now and
+then is fine, the package is named after rigor mortis.
+
+Document limits where they exist. `classify_compounds` says out loud that it
+leaves ~55% of an untargeted panel unclassified, and
+`compare_abundance_and_organization` says it needs six sections per arm. A
+number you are slightly embarrassed by is worth more than a claim nobody
+checked.
+
+## Data
+
+**Never commit patient data.** `test_data/` is gitignored and stays that way.
+Derived figures are fine; the arrays that made them are not.
+
+`validation/` runs on public METASPACE data. If you extend it, keep it that
+way, so that anybody can run it.
+
+## Docs
+
+The site lives in `web/`. `web/api.json` is generated from the installed
+package, so do not hand-edit it:
+
+```bash
+python web/build_api.py
+```
+
+CI regenerates it on every deploy, and fails if an exported function is missing
+from a group in `web/build_api.py`, which is how new functions avoid quietly
+going undocumented.
+
+## Releasing
+
+1. Update `CHANGELOG.md`, real sentences, not a list of commit subjects.
+2. Bump `version` in `pyproject.toml` and `CITATION.cff`.
+3. Tag it. The publish workflow does the rest.
+
+## Anything else
+
+Open an issue. A failing snippet and the output you expected is plenty, no
+template to fill in.
+

mortis_spatial-0.1.0/LICENSE

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

mortis_spatial-0.1.0/MANIFEST.in

@@ -0,0 +1,7 @@
+# The sdist should carry enough to rebuild and check the package, not just run
+# it: the tests, and the script that regenerates the bundled drug vocabulary.
+include CHANGELOG.md
+include CITATION.cff
+include CONTRIBUTING.md
+include tools/build_drug_vocabulary.py
+recursive-include tests *.py

mortis_spatial-0.1.0/PKG-INFO

@@ -0,0 +1,244 @@
+Metadata-Version: 2.4
+Name: mortis-spatial
+Version: 0.1.0
+Summary: Cohort-scale analysis for spatial metabolomics: patient-level statistics, differential spatial organization, and publication figures.
+Author-email: Faris Hrvat <farishrvatit@gmail.com>
+License: MIT
+Project-URL: Homepage, https://farishrvat.github.io/mortis/
+Project-URL: Documentation, https://farishrvat.github.io/mortis/
+Project-URL: Repository, https://github.com/FarisHrvat/mortis
+Project-URL: Changelog, https://github.com/FarisHrvat/mortis/blob/main/CHANGELOG.md
+Keywords: spatial metabolomics,imaging mass spectrometry,MALDI,DESI,bioinformatics,anndata,scanpy
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: anndata>=0.10.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: scipy>=1.10.0
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: scanpy>=1.10.0
+Requires-Dist: umap-learn>=0.5.0
+Requires-Dist: scikit-learn>=1.3.0
+Requires-Dist: matplotlib>=3.7.0
+Requires-Dist: seaborn>=0.12.0
+Requires-Dist: statsmodels>=0.14.0
+Requires-Dist: numba>=0.58.0
+Requires-Dist: threadpoolctl>=3.1.0
+Requires-Dist: h5py>=3.9.0
+Requires-Dist: openpyxl>=3.1.0
+Requires-Dist: tifffile>=2023.1.0
+Requires-Dist: psutil>=5.9.0
+Provides-Extra: cluster
+Requires-Dist: leidenalg>=0.10.0; extra == "cluster"
+Requires-Dist: python-igraph>=0.10.0; extra == "cluster"
+Provides-Extra: harmony
+Requires-Dist: harmonypy>=0.0.9; extra == "harmony"
+Provides-Extra: cli
+Requires-Dist: pyyaml>=6.0; extra == "cli"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: esda; extra == "dev"
+Requires-Dist: libpysal; extra == "dev"
+Requires-Dist: pyyaml>=6.0; extra == "dev"
+Requires-Dist: leidenalg>=0.10.0; extra == "dev"
+Requires-Dist: python-igraph>=0.10.0; extra == "dev"
+Provides-Extra: fast-io
+Requires-Dist: pyarrow; extra == "fast-io"
+Requires-Dist: python-calamine; extra == "fast-io"
+Provides-Extra: rds
+Requires-Dist: pyreadr>=0.5.0; extra == "rds"
+Provides-Extra: image-network
+Requires-Dist: networkx; extra == "image-network"
+Requires-Dist: adjustText; extra == "image-network"
+Dynamic: license-file
+
+<h1 align="center">
+  <img src="https://raw.githubusercontent.com/FarisHrvat/mortis/main/web/assets/logo.svg" width="46" alt=""><br>
+  MORTIS
+</h1>
+
+<p align="center">
+  <b>Cohort-scale analysis for spatial metabolomics.</b><br>
+  Patient-level statistics, differential spatial organization, and figures you can submit.
+</p>
+
+<p align="center">
+  <a href="https://farishrvat.github.io/mortis/"><b>Read the documentation</b></a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/FarisHrvat/mortis/actions/workflows/test.yml"><img src="https://github.com/FarisHrvat/mortis/actions/workflows/test.yml/badge.svg" alt="Tests"></a>
+  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.10%2B-blue.svg" alt="Python 3.10+"></a>
+  <img src="https://img.shields.io/badge/tested-Linux%20%7C%20macOS%20%7C%20Windows-lightgrey.svg" alt="Linux, macOS, Windows">
+  <a href="https://github.com/FarisHrvat/mortis/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-green.svg" alt="MIT licence"></a>
+  <img src="https://img.shields.io/badge/version-0.1.0-orange.svg" alt="version 0.1.0">
+  <a href="https://doi.org/10.5281/zenodo.23056382"><img src="https://zenodo.org/badge/DOI/10.5281/zenodo.23056382.svg" alt="DOI"></a>
+</p>
+
+---
+
+## What it does
+
+Imaging mass spectrometry tells you *where* a metabolite is. Most analyses then
+throw that away and ask only *how much*, which is the question bulk
+metabolomics already answered, more cheaply.
+
+MORTIS asks both, and asks them at the level where the statistics actually hold:
+
+- **Patient-level testing.** A section has 30,000 pixels and one patient. Test
+  the pixels and you inflate your sample size by four orders of magnitude. On
+  simulated null data that turns 0 real findings into 183 significant ones.
+  `pseudobulk()` comes first here, and it is not optional.
+- **Differential spatial *organization*.** A metabolite can sit at identical
+  abundance in two groups and be arranged completely differently, diffuse in
+  one, pooled into foci in the other. That finding is invisible to every
+  abundance test and to bulk metabolomics entirely.
+- **Cohorts, not sections.** Compare two drugs, or the same patients before and
+  after treatment, and ask whether a signature persists, reorganises, or flips.
+- **Figures and receipts.** Vector PDF, SVG and EPS whose text stays editable,
+  plus PNG, JPEG and TIFF at whatever DPI the journal asks for. Fonts, sizes,
+  colours and DPI are all yours to set. Every figure can carry a sealed
+  manifest a reviewer checks your re-run against, without you sending them a
+  single byte of patient data.
+
+## What it is not
+
+It is not an acquisition or peak-picking tool. It starts from a feature table
+or an `.h5ad`, so extraction, alignment and annotation happen upstream in
+SCiLS, METASPACE, Cardinal or the vendor software.
+
+It does not identify compounds. It takes the names your annotation pipeline
+gave you, and it cannot tell a confident match from a shaky one beyond the
+score your instrument software already wrote.
+
+It is not built for a single section. Most of what it adds is about comparing
+groups of patients, and on one section a good deal of it will refuse to run
+rather than give you a p-value that counts pixels as replicates.
+
+It does not read raw vendor formats or imzML. It starts from a peak-picked
+table: `.csv`, `.tsv`, `.txt`, `.xlsx`, `.parquet`, `.rds` or `.h5ad`. The
+delimiter and the decimal mark are worked out from the file, so a
+semicolon-and-comma export out of a European Excel reads without editing.
+For anything else, read it with whatever library does and hand the frame to
+`mt.from_dataframe()`.
+
+## Install
+
+```bash
+pip install mortis-spatial
+```
+
+Leiden clustering needs two GPL packages, which are not installed by default
+because MORTIS is MIT and the choice of pulling GPL code into your environment
+should be yours:
+
+```bash
+pip install "mortis-spatial[cluster]"
+```
+
+Everything else works without them, and `spatial_domains_kmeans()` finds
+tissue domains if you would rather not add GPL code at all.
+
+```python
+import mortis as mt
+
+adata = mt.preprocess(mt.read_metabolomics_data("section.h5ad"))
+
+# collapse pixels to patients, then test, in that order
+pb  = mt.pseudobulk(adata, sample_key="patient")
+ab  = mt.differential_abundance(pb, "response", "R", "NR")
+
+# and ask the question only imaging can answer
+org = mt.spatial_organization(adata, sample_key="section")
+do  = mt.differential_spatial_organization(org, "response", "R", "NR")
+
+mt.compare_abundance_and_organization(ab, do)   # which axis actually moved?
+```
+
+The [documentation](https://farishrvat.github.io/mortis/) has the guided tour,
+every function with its parameters, the figure gallery, and a validation run on
+a public METASPACE study using nothing but this package.
+
+## Or without writing any Python
+
+```bash
+mortis template > analysis.yaml     # a commented starting point
+mortis run analysis.yaml            # results, figures and a manifest
+```
+
+The config that produced a result is a better methods section than one written
+from memory, so every run writes it back out beside the results.
+
+**In a container**, when you would rather not install anything:
+
+```bash
+docker build -t mortis .
+docker run --rm -u "$(id -u):$(id -g)" -v "$PWD:/work" mortis run /work/analysis.yaml
+```
+
+**On a cluster**, [`hpc/`](https://github.com/FarisHrvat/mortis/blob/main/hpc) has Slurm and PBS templates, an Apptainer
+definition for sites that will not permit `pip install`, and a conda
+environment for the ones that will. The scripts derive thread limits from the
+scheduler's allocation and set them before Python starts, which is the
+difference between using your cores and oversubscribing a shared node.
+
+## Does it work?
+
+`validation/run_validation.py` downloads a public imaging study, rebuilds the
+pixel matrices from the ion images, and runs the whole pipeline, no simulation,
+no private data, no other package:
+
+```bash
+python validation/run_validation.py
+```
+
+24 sections, 250,514 pixels. The positive control (two different plant species)
+separates on 4 ions at FDR < 0.05. The deliberately underpowered control returns
+nothing, which is the right answer rather than a disappointing one.
+
+## Development
+
+```bash
+git clone https://github.com/FarisHrvat/mortis.git && cd mortis
+pip install -e ".[dev]"
+pytest && ruff check .
+```
+
+610 tests, run against Python 3.10 to 3.14 on Linux, Windows and Apple
+Silicon macOS. Intel macOS is not in CI because GitHub retired the last
+Intel runner; the dependencies all ship x86-64 wheels, so it should work
+there, but I have not tested it. See
+[CONTRIBUTING.md](https://github.com/FarisHrvat/mortis/blob/main/CONTRIBUTING.md).
+
+## Citation
+
+Cite the DOI, [10.5281/zenodo.23056382](https://doi.org/10.5281/zenodo.23056382),
+which always resolves to the newest version. To pin the exact version you ran,
+each release has its own DOI on the same record. Full metadata is in
+[`CITATION.cff`](https://github.com/FarisHrvat/mortis/blob/main/CITATION.cff),
+and the article will be the preferred citation once it is out.
+
+`filter_drugs()` matches against a drug-name list built from Wikidata, which
+is CC0. `run_harmony()` implements Korsunsky et al. 2019, and
+`annotate_pathways()` calls MetaboAnalyst and KEGG. Each is linked from the
+function's own documentation, and should be cited alongside MORTIS if you use
+it.
+
+
+## Licence
+
+MIT, see [LICENSE](https://github.com/FarisHrvat/mortis/blob/main/LICENSE).
+