thyra 4.3.4__tar.gz → 4.5.0__tar.gz

{thyra-4.3.4 → thyra-4.5.0}/PKG-INFO

@@ -1,10 +1,11 @@
 Metadata-Version: 2.5
 Name: thyra
-Version: 4.3.4
+Version: 4.5.0
 Summary: A modern Python library for converting Mass Spectrometry Imaging (MSI) data into SpatialData/Zarr format - your portal to spatial omics
 Project-URL: Homepage, https://github.com/M4i-Imaging-Mass-Spectrometry/thyra
 Project-URL: Repository, https://github.com/M4i-Imaging-Mass-Spectrometry/thyra
 Project-URL: Documentation, https://M4i-Imaging-Mass-Spectrometry.github.io/thyra/
+Project-URL: Paper, https://doi.org/10.1021/jasms.6c00169
 Project-URL: Bug Tracker, https://github.com/M4i-Imaging-Mass-Spectrometry/thyra/issues
 Project-URL: Discussions, https://github.com/M4i-Imaging-Mass-Spectrometry/thyra/discussions
 Project-URL: Changelog, https://github.com/M4i-Imaging-Mass-Spectrometry/thyra/blob/main/CHANGELOG.md
@@ -13,7 +14,7 @@ Author-email: Theodoros Visvikis <t.visvikis@maastrichtuniversity.nl>
 Maintainer-email: Theodoros Visvikis <t.visvikis@maastrichtuniversity.nl>
 License-Expression: MIT
 License-File: LICENSE
-Keywords: bioinformatics,bruker,data-conversion,imaging,imzml,mass-spectrometry,msi,omics,scientific-computing,spatial-omics,spatialdata,zarr
+Keywords: bioinformatics,bruker,data-conversion,imaging,imzml,ion-mobility,mass-spectrometry,msi,msms,omics,pasef,scientific-computing,spatial-omics,spatialdata,tims,timstof,zarr
 Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Science/Research
@@ -66,8 +67,9 @@ Description-Content-Type: text/markdown
 **Thyra converts imaging mass spectrometry data into one open format.** It
 reads the files your instrument writes (Bruker, Waters, PHI, or imzML from any
 vendor) and saves them in [SpatialData](https://spatialdata.scverse.org/),
-which analysis and viewing tools can read. You do not need to know how to
-program.
+which analysis and viewing tools can read. It keeps ion mobility (TIMS 1/K0)
+and MS/MS (PASEF, iprm-PASEF) data, not only the spectra. You do not need to
+know how to program.
 
 **[Documentation](https://M4i-Imaging-Mass-Spectrometry.github.io/thyra)** | [Install](https://M4i-Imaging-Mass-Spectrometry.github.io/thyra/install/) | [Your first conversion](https://M4i-Imaging-Mass-Spectrometry.github.io/thyra/getting-started/) | [Tutorial](https://M4i-Imaging-Mass-Spectrometry.github.io/thyra/tutorial/) | [Technical reference](https://M4i-Imaging-Mass-Spectrometry.github.io/thyra/technical-reference/)
 
@@ -105,6 +107,10 @@ also converts the published example dataset
 | Any instrument that exports imzML | the `.imzML` file, with its `.ibd` file next to it |
 | mzPeak (experimental) | the `.mzpeak` file |
 
+imzML with a mobility array is read too. In continuous mode, as TIMSImaging
+writes it, the mobility is kept as its own table. In processed mode, as
+TIMSCONVERT writes it, add `--mobility-grid` for that table.
+
 Thyra reads timsTOF and Waters data on Windows and Linux; everything else
 also works on macOS. Shimadzu support is in development: until then, export
 imzML from IMAGEREVEAL MS.
@@ -120,12 +126,57 @@ One folder ending in `.zarr`, holding:
 - the spectrum of every pixel, on one shared m/z axis
 - an image of the total ion current (TIC)
 - the optical image of the slide, when the acquisition has one
-- ion mobility and MS/MS data from Bruker timsTOF, when the acquisition has them
+- ion mobility and MS/MS data, when the acquisition has them (below)
 - a validated description of the acquisition, ready for METASPACE
 
 Thyra handles datasets larger than your computer's memory, slides with
 several regions, and 3D data.
 
+## Ion mobility and MS/MS
+
+Thyra keeps the extra dimensions of Bruker timsTOF data instead of dropping
+them.
+
+- **By default** each spectrum is added up over mobility, so every tool can
+  read the main table. The table also carries a mass-mobility heatmap of the
+  whole image, `uns["mobility_heatmap"]`.
+- **`{table}_mobility`** has one column for each (m/z, 1/K0) pair. It is
+  written by itself from continuous imzML with a mobility array, and from
+  Bruker TDF and processed imzML with `--mobility-grid`. `var["ccs"]`
+  holds each pair's collision cross section (CCS) in square angstroms, for
+  an assumed charge of 1; `uns["ccs"]` records the assumptions.
+- **`{table}_msms`** splits PASEF and iprm-PASEF MS/MS by precursor: one
+  block of fragment columns per precursor, so every fragment has its own
+  image.
+
+Two ions at one m/z, told apart by mobility:
+
+```python
+import numpy as np
+import spatialdata as sd
+
+sdata = sd.read_zarr("output/sample.zarr")
+mob = sdata.tables["msi_dataset_z0_mobility"]
+mz, k0 = mob.var["mz"].to_numpy(), mob.var["mobility"].to_numpy()
+near = np.abs(mz - 600.25) < 0.01
+low = np.asarray(mob.X[:, near & (k0 < 1.3)].sum(axis=1)).ravel()   # one value per pixel
+high = np.asarray(mob.X[:, near & (k0 >= 1.3)].sum(axis=1)).ravel()
+```
+
+Tools should recognise these tables by their columns (`"mobility" in
+var.columns`, `"precursor_mz" in var.columns`), not by their names. The
+[Ion mobility and MS/MS guide](https://M4i-Imaging-Mass-Spectrometry.github.io/thyra/ion-mobility-and-msms/)
+walks through both, and the output format describes the
+[mobility](https://M4i-Imaging-Mass-Spectrometry.github.io/thyra/output-format/#ion-mobility)
+and [MS/MS](https://M4i-Imaging-Mass-Spectrometry.github.io/thyra/output-format/#demultiplexed-msms-table)
+tables in full.
+[For tool developers](https://M4i-Imaging-Mass-Spectrometry.github.io/thyra/for-tool-developers/)
+lists the rules a tool can rely on, and what may change.
+
+Waters Synapt runs with ion mobility on keep their drift times; older
+Synapt G1 mobility runs are refused. CCS is computed from 1/K0 only, never
+from a drift time.
+
 ## From Python
 
 ```python
@@ -172,6 +223,30 @@ MIT -- see [LICENSE](LICENSE).
 
 ## Citation
 
+If you use Thyra, please cite the paper:
+
+> Visvikis, T.; Vierdag, W.-M.; Marconato, L.; Birmpili, A.; Heeren, R. M. A.;
+> Cuypers, E. Native, Memory-Bounded Conversion of Mass Spectrometry Imaging
+> Data into the SpatialData Ecosystem. *J. Am. Soc. Mass Spectrom.* **2026**,
+> *37* (10), 2379-2387.
+> [doi:10.1021/jasms.6c00169](https://doi.org/10.1021/jasms.6c00169)
+
+```bibtex
+@article{visvikis2026thyra,
+  title   = {Native, Memory-Bounded Conversion of Mass Spectrometry Imaging Data into the {SpatialData} Ecosystem},
+  author  = {Visvikis, Theodoros and Vierdag, Wouter-Michiel and Marconato, Luca and Birmpili, Angeliki and Heeren, Ron M. A. and Cuypers, Eva},
+  journal = {Journal of the American Society for Mass Spectrometry},
+  year    = {2026},
+  volume  = {37},
+  number  = {10},
+  pages   = {2379--2387},
+  doi     = {10.1021/jasms.6c00169}
+}
+```
+
+The same entry is in [CITATION.cff](CITATION.cff), which GitHub's "Cite this
+repository" button reads. To cite the software itself:
+
 ```bibtex
 @software{thyra2024,
   title = {Thyra: Modern Mass Spectrometry Imaging Data Conversion},
@@ -181,6 +256,16 @@ MIT -- see [LICENSE](LICENSE).
 }
 ```
 
+### Papers
+
+| Paper | Published | DOI |
+|---|---|---|
+| Native, Memory-Bounded Conversion of Mass Spectrometry Imaging Data into the SpatialData Ecosystem (*J. Am. Soc. Mass Spectrom.*) | 2026-09 | [10.1021/jasms.6c00169](https://doi.org/10.1021/jasms.6c00169) |
+| Thyra: Bridging Mass Spectrometry Imaging and SpatialData for Unified Multi-Modal Analysis (bioRxiv preprint) | 2026-01 | [10.64898/2026.01.26.700792](https://doi.org/10.64898/2026.01.26.700792) |
+
+Ion mobility and MS/MS support came after both papers. If you use them,
+please also name the Thyra version you used.
+
 ## Acknowledgments
 
 - Built with [SpatialData](https://spatialdata.scverse.org/) ecosystem

{thyra-4.3.4 → thyra-4.5.0}/README.md

@@ -13,8 +13,9 @@
 **Thyra converts imaging mass spectrometry data into one open format.** It
 reads the files your instrument writes (Bruker, Waters, PHI, or imzML from any
 vendor) and saves them in [SpatialData](https://spatialdata.scverse.org/),
-which analysis and viewing tools can read. You do not need to know how to
-program.
+which analysis and viewing tools can read. It keeps ion mobility (TIMS 1/K0)
+and MS/MS (PASEF, iprm-PASEF) data, not only the spectra. You do not need to
+know how to program.
 
 **[Documentation](https://M4i-Imaging-Mass-Spectrometry.github.io/thyra)** | [Install](https://M4i-Imaging-Mass-Spectrometry.github.io/thyra/install/) | [Your first conversion](https://M4i-Imaging-Mass-Spectrometry.github.io/thyra/getting-started/) | [Tutorial](https://M4i-Imaging-Mass-Spectrometry.github.io/thyra/tutorial/) | [Technical reference](https://M4i-Imaging-Mass-Spectrometry.github.io/thyra/technical-reference/)
 
@@ -52,6 +53,10 @@ also converts the published example dataset
 | Any instrument that exports imzML | the `.imzML` file, with its `.ibd` file next to it |
 | mzPeak (experimental) | the `.mzpeak` file |
 
+imzML with a mobility array is read too. In continuous mode, as TIMSImaging
+writes it, the mobility is kept as its own table. In processed mode, as
+TIMSCONVERT writes it, add `--mobility-grid` for that table.
+
 Thyra reads timsTOF and Waters data on Windows and Linux; everything else
 also works on macOS. Shimadzu support is in development: until then, export
 imzML from IMAGEREVEAL MS.
@@ -67,12 +72,57 @@ One folder ending in `.zarr`, holding:
 - the spectrum of every pixel, on one shared m/z axis
 - an image of the total ion current (TIC)
 - the optical image of the slide, when the acquisition has one
-- ion mobility and MS/MS data from Bruker timsTOF, when the acquisition has them
+- ion mobility and MS/MS data, when the acquisition has them (below)
 - a validated description of the acquisition, ready for METASPACE
 
 Thyra handles datasets larger than your computer's memory, slides with
 several regions, and 3D data.
 
+## Ion mobility and MS/MS
+
+Thyra keeps the extra dimensions of Bruker timsTOF data instead of dropping
+them.
+
+- **By default** each spectrum is added up over mobility, so every tool can
+  read the main table. The table also carries a mass-mobility heatmap of the
+  whole image, `uns["mobility_heatmap"]`.
+- **`{table}_mobility`** has one column for each (m/z, 1/K0) pair. It is
+  written by itself from continuous imzML with a mobility array, and from
+  Bruker TDF and processed imzML with `--mobility-grid`. `var["ccs"]`
+  holds each pair's collision cross section (CCS) in square angstroms, for
+  an assumed charge of 1; `uns["ccs"]` records the assumptions.
+- **`{table}_msms`** splits PASEF and iprm-PASEF MS/MS by precursor: one
+  block of fragment columns per precursor, so every fragment has its own
+  image.
+
+Two ions at one m/z, told apart by mobility:
+
+```python
+import numpy as np
+import spatialdata as sd
+
+sdata = sd.read_zarr("output/sample.zarr")
+mob = sdata.tables["msi_dataset_z0_mobility"]
+mz, k0 = mob.var["mz"].to_numpy(), mob.var["mobility"].to_numpy()
+near = np.abs(mz - 600.25) < 0.01
+low = np.asarray(mob.X[:, near & (k0 < 1.3)].sum(axis=1)).ravel()   # one value per pixel
+high = np.asarray(mob.X[:, near & (k0 >= 1.3)].sum(axis=1)).ravel()
+```
+
+Tools should recognise these tables by their columns (`"mobility" in
+var.columns`, `"precursor_mz" in var.columns`), not by their names. The
+[Ion mobility and MS/MS guide](https://M4i-Imaging-Mass-Spectrometry.github.io/thyra/ion-mobility-and-msms/)
+walks through both, and the output format describes the
+[mobility](https://M4i-Imaging-Mass-Spectrometry.github.io/thyra/output-format/#ion-mobility)
+and [MS/MS](https://M4i-Imaging-Mass-Spectrometry.github.io/thyra/output-format/#demultiplexed-msms-table)
+tables in full.
+[For tool developers](https://M4i-Imaging-Mass-Spectrometry.github.io/thyra/for-tool-developers/)
+lists the rules a tool can rely on, and what may change.
+
+Waters Synapt runs with ion mobility on keep their drift times; older
+Synapt G1 mobility runs are refused. CCS is computed from 1/K0 only, never
+from a drift time.
+
 ## From Python
 
 ```python
@@ -119,6 +169,30 @@ MIT -- see [LICENSE](LICENSE).
 
 ## Citation
 
+If you use Thyra, please cite the paper:
+
+> Visvikis, T.; Vierdag, W.-M.; Marconato, L.; Birmpili, A.; Heeren, R. M. A.;
+> Cuypers, E. Native, Memory-Bounded Conversion of Mass Spectrometry Imaging
+> Data into the SpatialData Ecosystem. *J. Am. Soc. Mass Spectrom.* **2026**,
+> *37* (10), 2379-2387.
+> [doi:10.1021/jasms.6c00169](https://doi.org/10.1021/jasms.6c00169)
+
+```bibtex
+@article{visvikis2026thyra,
+  title   = {Native, Memory-Bounded Conversion of Mass Spectrometry Imaging Data into the {SpatialData} Ecosystem},
+  author  = {Visvikis, Theodoros and Vierdag, Wouter-Michiel and Marconato, Luca and Birmpili, Angeliki and Heeren, Ron M. A. and Cuypers, Eva},
+  journal = {Journal of the American Society for Mass Spectrometry},
+  year    = {2026},
+  volume  = {37},
+  number  = {10},
+  pages   = {2379--2387},
+  doi     = {10.1021/jasms.6c00169}
+}
+```
+
+The same entry is in [CITATION.cff](CITATION.cff), which GitHub's "Cite this
+repository" button reads. To cite the software itself:
+
 ```bibtex
 @software{thyra2024,
   title = {Thyra: Modern Mass Spectrometry Imaging Data Conversion},
@@ -128,6 +202,16 @@ MIT -- see [LICENSE](LICENSE).
 }
 ```
 
+### Papers
+
+| Paper | Published | DOI |
+|---|---|---|
+| Native, Memory-Bounded Conversion of Mass Spectrometry Imaging Data into the SpatialData Ecosystem (*J. Am. Soc. Mass Spectrom.*) | 2026-09 | [10.1021/jasms.6c00169](https://doi.org/10.1021/jasms.6c00169) |
+| Thyra: Bridging Mass Spectrometry Imaging and SpatialData for Unified Multi-Modal Analysis (bioRxiv preprint) | 2026-01 | [10.64898/2026.01.26.700792](https://doi.org/10.64898/2026.01.26.700792) |
+
+Ion mobility and MS/MS support came after both papers. If you use them,
+please also name the Thyra version you used.
+
 ## Acknowledgments
 
 - Built with [SpatialData](https://spatialdata.scverse.org/) ecosystem

{thyra-4.3.4 → thyra-4.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "thyra"
-version = "4.3.4"
+version = "4.5.0"
 description = "A modern Python library for converting Mass Spectrometry Imaging (MSI) data into SpatialData/Zarr format - your portal to spatial omics"
 authors = [{ name = "Theodoros Visvikis", email = "t.visvikis@maastrichtuniversity.nl" }]
 maintainers = [{ name = "Theodoros Visvikis", email = "t.visvikis@maastrichtuniversity.nl" }]
@@ -22,6 +22,11 @@ keywords = [
     "msi",
     "imzml",
     "bruker",
+    "timstof",
+    "ion-mobility",
+    "tims",
+    "msms",
+    "pasef",
     "spatial-omics",
     "data-conversion",
     "scientific-computing",
@@ -243,6 +248,7 @@ dependencies = [
 Homepage = "https://github.com/M4i-Imaging-Mass-Spectrometry/thyra"
 Repository = "https://github.com/M4i-Imaging-Mass-Spectrometry/thyra"
 Documentation = "https://M4i-Imaging-Mass-Spectrometry.github.io/thyra/"
+Paper = "https://doi.org/10.1021/jasms.6c00169"
 "Bug Tracker" = "https://github.com/M4i-Imaging-Mass-Spectrometry/thyra/issues"
 Discussions = "https://github.com/M4i-Imaging-Mass-Spectrometry/thyra/discussions"
 Changelog = "https://github.com/M4i-Imaging-Mass-Spectrometry/thyra/blob/main/CHANGELOG.md"
@@ -310,13 +316,6 @@ dev = [
     "flake8>=6.0.0",
     "mypy>=1.0.0",
     "pydocstyle>=6.3.0",
-    # This once capped `click <8.2`, and the note here said that dev-only cap
-    # was what held the lockfile's click at 8.1.8. Both halves are stale:
-    # 10.6.1, the locked version, requires `click>=8.1.0,<9.0.0`, and uv.lock
-    # resolves click 8.4.2. So the lockfile no longer exercises the floor of
-    # the `>=8.1, <9` range [project] publishes -- see the click comment above
-    # for which versions were verified by hand instead.
-    "python-semantic-release",
     "python-dotenv>=1.1.1,<2",
     "pre-commit>=3.0.0",
     "bandit[toml]>=1.7.0",
@@ -355,67 +354,6 @@ filterwarnings = [
     "ignore::UserWarning:spatialdata.models.models:1053"
 ]
 
-# =============================================================
-# === SEMANTIC RELEASE CONFIGURATION                         ===
-# =============================================================
-[tool.semantic_release]
-version_toml = ["pyproject.toml:project.version"]
-version_variables = [
-    "thyra/__init__.py:__version__",
-]
-# `uv lock` runs here rather than as a workflow step because the build
-# command is the only hook that executes AFTER semantic-release stamps the
-# new version into pyproject.toml and BEFORE it makes the release commit.
-# Without it, the lockfile's own `[[package]] name = "thyra"` entry keeps
-# the previous version. The release commit lands on main without a test run
-# (a GITHUB_TOKEN push starts no workflows), so nothing notices until the
-# first branch cut after the release fails every CI job at
-# `uv sync --locked` with "The lockfile at `uv.lock` needs to be updated" --
-# see the one-off repair on PR #177 after v3.5.0. Regenerating the lockfile
-# is only half the fix: `assets` below is what carries it into the release
-# commit. uv reaches this command's PATH via the same SHA-pinned setup-uv
-# step the test workflow uses (see release.yml).
-build_command = "uv lock && pip install build && python -m build"
-# Extra files to include in the release commit beyond the version-stamped
-# ones above.
-assets = ["uv.lock"]
-# There is deliberately no `upload_to_vcs_release` here. It used to sit at this
-# level and had never had any effect, for three independent reasons: it is a
-# field of PublishConfig, so it belongs under [tool.semantic_release.publish] and
-# is silently dropped here (RawConfig sets no `extra` policy, so pydantic ignores
-# unknown keys); its default is already true; and it is acted on only by
-# `semantic-release publish`, which calls hvcs_client.upload_dists, while
-# release.yml only ever runs `semantic-release version`, which never does.
-# Verified against python-semantic-release 10.6.2. The visible consequence was
-# that the releases for v3.23.0-v3.23.2 each carry exactly one asset, uv.lock,
-# and no wheel or sdist.
-#
-# The dist this build_command produces is not lost, though. release.yml uploads
-# it as a workflow artifact and the publish job takes it from there, which is
-# what makes one build per release. If you want it on the GitHub Release as well,
-# that is an upload step in release.yml, not this key.
-
-[tool.semantic_release.branches.main]
-match = "main"
-prerelease = false
-
-[tool.semantic_release.changelog]
-template_dir = "templates"
-changelog_file = "CHANGELOG.md"
-exclude_commit_patterns = [
-    "chore*",
-    "ci*",
-]
-
-[tool.semantic_release.commit_parser_options]
-allowed_tags = ["build", "chore", "ci", "docs", "feat", "fix", "perf", "style", "refactor", "test"]
-minor_tags = ["feat"]
-patch_tags = ["fix", "perf"]
-
-[tool.semantic_release.remote_settings]
-name = "origin"
-token = { env = "GITHUB_TOKEN" }
-
 # =============================================================
 # === CODE QUALITY TOOL CONFIGURATIONS                     ===
 # =============================================================

{thyra-4.3.4 → thyra-4.5.0}/thyra/__init__.py

@@ -21,8 +21,8 @@ The public names below resolve on first attribute access (:pep:`562`), so
 still cost what they always did -- paid by the caller who asks for them.
 
 ``__version__`` stays an ordinary module attribute rather than joining
-them. It is what ``python-semantic-release`` rewrites at release
-(``version_variables`` in ``pyproject.toml``), and
+them. It is what release-please rewrites in the release pull request
+(the ``python`` release type in ``release-please-config.json``), and
 ``thyra.metadata.schema.builder`` reads it through ``from thyra import
 __version__`` while building a document -- which is only affordable
 because reaching this module is now free.
@@ -51,8 +51,11 @@ from typing import TYPE_CHECKING, Any, List
 if TYPE_CHECKING:  # pragma: no cover - for type checkers, not at runtime
     from .convert import convert_msi
     from .converters.spatialdata.converter import SpatialDataConverter
+    from .mass_axis_plan import plan_mass_axis
     from .metadata.document import read_metadata_document
     from .preview import MsiPreview, preview_msi
+    from .regions import list_regions
+    from .resampling.plan import MassAxisPlan
 
 # Suppress remaining dependency warnings
 warnings.filterwarnings("ignore", category=FutureWarning, module="dask")
@@ -67,13 +70,16 @@ warnings.filterwarnings(
     category=FutureWarning,
 )
 
-__version__ = "4.3.4"
+__version__ = "4.5.0"
 
 #: Public name -> the module that defines it, imported on first access.
 _LAZY_ATTRS = {
+    "MassAxisPlan": ".resampling.plan",
     "MsiPreview": ".preview",
     "SpatialDataConverter": ".converters.spatialdata.converter",
     "convert_msi": ".convert",
+    "list_regions": ".regions",
+    "plan_mass_axis": ".mass_axis_plan",
     "preview_msi": ".preview",
     "read_metadata_document": ".metadata.document",
 }
@@ -88,7 +94,10 @@ __all__ = [
     "__version__",
     "convert_msi",
     "preview_msi",
+    "list_regions",
+    "plan_mass_axis",
     "read_metadata_document",
+    "MassAxisPlan",
     "MsiPreview",
     "SpatialDataConverter",
 ]