pgalign 1.1.0__py3-none-any.whl

pgalign/readers.py

@@ -0,0 +1,130 @@
+"""Readers that turn MSI exports into AnnData objects for :func:`pgalign.align`, and .h5ad I/O."""
+
+import math
+
+import numpy as np
+import pandas as pd
+import scanpy as sc
+
+from .util import gridding
+
+
+def read_imzml(path, increment=None, mz_range=None, epsilon=0.025):
+    """Read an imzML file into an AnnData that ``pg.align`` accepts.
+
+    In continuous mode every spectrum shares one m/z axis, which is used as it is.
+    In processed mode each spectrum carries its own m/z values, so ``increment`` is
+    required and every spectrum is put on a common grid with ``gridding``
+    (Nadaraya-Watson smoothing with bandwidth ``epsilon``), as the manuscript's
+    simulation study did with ``increment=0.25``. Passing ``increment`` grids the
+    spectra in either mode. Requires pyimzML: ``pip install "pgalign[imzml]"``.
+
+    :param path: the ``.imzML`` file; its ``.ibd`` file must sit beside it.
+    :param increment: grid spacing in m/z. Required when the spectra do not share
+        one m/z axis.
+    :param mz_range: ``(start, end)`` of the grid, end excluded. Defaults to one
+        below the floor of the smallest m/z in the file and one above the ceiling
+        of the largest, as in ``gridding``.
+    :param epsilon: bandwidth of the gridding kernel. Defaults to 0.025.
+    :return: an ``anndata.AnnData`` with the m/z values in ``var["m/z"]`` and the
+        pixel coordinates in ``obs`` (``x``, ``y``, ``z``).
+    """
+    try:
+        from pyimzml.ImzMLParser import ImzMLParser
+    except ImportError as err:
+        raise ImportError('read_imzml needs pyimzML: pip install "pgalign[imzml]"') from err
+    parser = ImzMLParser(path)
+    spectra = [parser.getspectrum(i) for i in range(len(parser.coordinates))]
+    if increment is None:
+        mz = np.asarray(spectra[0][0], dtype=float)
+        if not all(np.array_equal(mzs, mz) for mzs, _ in spectra):
+            raise ValueError(
+                f"the spectra in {path} do not share one m/z axis (processed imzML); "
+                "pass increment= to grid them, for example increment=0.25 as in the "
+                "manuscript's simulation study"
+            )
+        X = np.vstack([np.asarray(intensities, dtype=float) for _, intensities in spectra])
+    else:
+        observed = [mzs for mzs, _ in spectra if len(mzs)]
+        lo, hi = min(m.min() for m in observed), max(m.max() for m in observed)
+        if mz_range is None:
+            mz_range = (math.floor(lo) - 1, math.ceil(hi) + 1)
+        elif mz_range[0] > hi or mz_range[1] <= lo:
+            raise ValueError(
+                f"no m/z value in {path} falls inside mz_range {tuple(mz_range)}; "
+                f"the file covers {lo:g} to {hi:g}"
+            )
+        grids = [gridding(np.asarray(mzs, dtype=float), np.asarray(intensities, dtype=float),
+                          start=mz_range[0], end=mz_range[1], increment=increment, epsilon=epsilon)
+                 for mzs, intensities in spectra]
+        mz = grids[0][0]
+        X = np.vstack([grid[1] for grid in grids])
+    var = pd.DataFrame({"m/z": mz}, index=[str(v) for v in mz])
+    obs = pd.DataFrame(np.asarray(parser.coordinates)[:, :3], columns=["x", "y", "z"],
+                       index=[f"s{i}" for i in range(len(spectra))])
+    return sc.AnnData(X=X, var=var, obs=obs)
+
+
+def write_h5ad(adata, path):
+    """Write an AnnData to ``.h5ad``, storing ``var["m/z"]`` as ``var["mz"]``.
+
+    anndata 0.13 refuses to write a column whose name contains a slash, so the m/z
+    values are stored under ``mz``; :func:`read_h5ad` restores them. The object
+    passed in is not modified, and its data are written without being copied.
+
+    :param adata: the ``anndata.AnnData`` to write, for example ``res.aligned``.
+    :param path: the ``.h5ad`` file to write.
+    """
+    if "m/z" in adata.var.columns and "mz" in adata.var.columns:
+        raise ValueError("var has both an 'm/z' and an 'mz' column; drop one before writing")
+    out = sc.AnnData(
+        X=adata.X, obs=adata.obs, var=adata.var.rename(columns={"m/z": "mz"}),
+        uns=dict(adata.uns), obsm=dict(adata.obsm), varm=dict(adata.varm),
+        layers=dict(adata.layers), obsp=dict(adata.obsp), varp=dict(adata.varp),
+    )
+    out.write_h5ad(path)
+
+
+def read_h5ad(path):
+    """Read an ``.h5ad`` file written by :func:`write_h5ad` or by older anndata.
+
+    Restores ``var["mz"]`` to ``var["m/z"]`` when the file has no ``m/z`` column;
+    files that store ``m/z`` itself are read as they are.
+
+    :param path: the ``.h5ad`` file to read.
+    :return: an ``anndata.AnnData`` with the m/z values in ``var["m/z"]``.
+    """
+    adata = sc.read_h5ad(path)
+    if "m/z" not in adata.var.columns and "mz" in adata.var.columns:
+        adata.var = adata.var.rename(columns={"mz": "m/z"})
+    return adata
+
+
+def read_scils_csv(spectra_csv, spots_csv=None, sep=";"):
+    """Read a SCiLS Lab CSV export into an AnnData that ``pg.align`` accepts.
+
+    The spectra file holds one row per spot: the spot name in the first column,
+    then one intensity column per m/z value, with the m/z values as the column
+    headers. The optional spots file (``Region Spots.csv``) holds one row per spot,
+    in the same order, with its index and x and y coordinates; its columns are
+    copied into ``obs`` unchanged.
+
+    :param spectra_csv: path of the spectra export (``... - All Spectra.csv``).
+    :param spots_csv: path of the spot coordinates (``... - Region Spots.csv``).
+    :param sep: the field separator. Defaults to ``";"``, as SCiLS writes it.
+    :return: an ``anndata.AnnData`` with the m/z values in ``var["m/z"]``.
+    """
+    spectra = pd.read_csv(spectra_csv, sep=sep)
+    labels = list(spectra.columns[1:])
+    var = pd.DataFrame({"m/z": np.asarray(labels, dtype=float)}, index=labels)
+    obs = pd.DataFrame(index=spectra.iloc[:, 0].astype(str).to_numpy())
+    if spots_csv is not None:
+        spots = pd.read_csv(spots_csv, sep=sep)
+        if len(spots) != len(spectra):
+            raise ValueError(
+                f"{spots_csv} has {len(spots)} spots but {spectra_csv} has {len(spectra)} spectra"
+            )
+        for column in spots.columns:
+            obs[column] = spots[column].to_numpy()
+    X = spectra.iloc[:, 1:].to_numpy(dtype=float)
+    return sc.AnnData(X=X, var=var, obs=obs)

pgalign/util.py

@@ -0,0 +1,135 @@
+"""Utility helpers used by PGAlign's peak-calling and alignment routines."""
+
+import logging
+import math
+
+import numpy as np
+import pandas as pd
+import scanpy as sc
+
+logger = logging.getLogger(__name__)
+
+
+def prefilter_cells(adata, min_counts=None, max_counts=None, min_genes=200, max_genes=None):
+    if min_genes is None and min_counts is None and max_genes is None and max_counts is None:
+        raise ValueError('Provide one of min_counts, min_genes, max_counts or max_genes.')
+    id_tmp = np.asarray([True] * adata.shape[0], dtype=bool)
+    id_tmp = np.logical_and(id_tmp, sc.pp.filter_cells(adata.X, min_genes=min_genes)[0]) if min_genes is not None else id_tmp
+    id_tmp = np.logical_and(id_tmp, sc.pp.filter_cells(adata.X, max_genes=max_genes)[0]) if max_genes is not None else id_tmp
+    id_tmp = np.logical_and(id_tmp, sc.pp.filter_cells(adata.X, min_counts=min_counts)[0]) if min_counts is not None else id_tmp
+    id_tmp = np.logical_and(id_tmp, sc.pp.filter_cells(adata.X, max_counts=max_counts)[0]) if max_counts is not None else id_tmp
+    adata._inplace_subset_obs(id_tmp)
+    adata.raw = sc.pp.log1p(adata, copy=True)
+    logger.debug("adata.raw.var_names.is_unique = %s", adata.raw.var_names.is_unique)
+
+
+def prefilter_genes(adata, min_counts=None, max_counts=None, min_cells=10, max_cells=None):
+    if min_cells is None and min_counts is None and max_cells is None and max_counts is None:
+        raise ValueError('Provide one of min_counts, min_genes, max_counts or max_genes.')
+    id_tmp = np.asarray([True] * adata.shape[1], dtype=bool)
+    id_tmp = np.logical_and(id_tmp, sc.pp.filter_genes(adata.X, min_cells=min_cells)[0]) if min_cells is not None else id_tmp
+    id_tmp = np.logical_and(id_tmp, sc.pp.filter_genes(adata.X, max_cells=max_cells)[0]) if max_cells is not None else id_tmp
+    id_tmp = np.logical_and(id_tmp, sc.pp.filter_genes(adata.X, min_counts=min_counts)[0]) if min_counts is not None else id_tmp
+    id_tmp = np.logical_and(id_tmp, sc.pp.filter_genes(adata.X, max_counts=max_counts)[0]) if max_counts is not None else id_tmp
+    adata._inplace_subset_var(id_tmp)
+
+
+def prefilter_specialgenes(adata, Gene1Pattern="ERCC", Gene2Pattern="MT-"):
+    id_tmp1 = np.asarray([not str(name).startswith(Gene1Pattern) for name in adata.var_names], dtype=bool)
+    id_tmp2 = np.asarray([not str(name).startswith(Gene2Pattern) for name in adata.var_names], dtype=bool)
+    id_tmp = np.logical_and(id_tmp1, id_tmp2)
+    adata._inplace_subset_var(id_tmp)
+
+
+def save_clusterresults(cluster, filepath):
+    rangetxt = np.zeros((len(cluster), 2))
+    for i, points in enumerate(cluster):
+        rangetxt[i, 0] = points[0]
+        rangetxt[i, 1] = points[-1]
+    np.savetxt("{filepath}.csv".format(filepath=filepath), rangetxt, delimiter=",")
+
+
+def rotate(l, n):
+    return l[n:] + l[:n]
+
+
+def group_range(cluster):
+    lows = np.array([i[0] for i in cluster])
+    ups = np.array([i[-1] for i in cluster])
+    return [lows, ups]
+
+
+def in_range_lookup(mzvalues, cluster, expand=True):
+    lows, ups = group_range(cluster)
+    TFlist = [np.any((lows <= x) & (x <= ups)) for x in mzvalues]
+    if expand:
+        TFlistr = rotate(TFlist, 1)
+        TFlistl = rotate(TFlist, -1)
+        newTFlist = [any((mz1, mz2, mz3)) for (mz1, mz2, mz3) in zip(TFlist, TFlistr, TFlistl)]
+    else:
+        newTFlist = TFlist
+    return newTFlist
+
+
+def comp_clusters(TFlist, mzvalues):
+    clusters = []
+    curr_cluster = []
+    for i, curr_point in enumerate(TFlist):
+        if curr_point:
+            curr_cluster.append(mzvalues[i])
+        else:
+            if curr_cluster:
+                clusters.append(curr_cluster)
+                curr_cluster = []
+    return clusters
+
+
+def find_nearest(array, value):
+    """Index of the element in ``array`` closest to ``value``."""
+    nearest_idx = np.where(abs(array - value) == abs(array - value).min())[0]
+    return nearest_idx[0]
+
+
+def get_unk_comp_clusters(ref_clusters, mzvalues):
+    clusters = []
+    mzvalues_array = np.array(mzvalues)
+    mzvalues_array_float = np.asarray(mzvalues_array, dtype=np.float64, order='C')
+    for i, curr_cluster in enumerate(ref_clusters):
+        ref_ini_point = curr_cluster[0]
+        indexnearest_unk = find_nearest(mzvalues_array_float, float(ref_ini_point))
+        if ((indexnearest_unk + len(curr_cluster)) <= len(mzvalues)):
+            clusters.append(mzvalues[range(indexnearest_unk, indexnearest_unk + len(curr_cluster))])
+        curr_cluster = []
+    return clusters
+
+
+def spectrum_save(mz, intensity, name):
+    originaltable = pd.DataFrame(np.array(mz))
+    originaltable = originaltable.rename(columns={0: "mz"})
+    originaltable["intensity"] = intensity
+    originaltable.to_csv("{name}.csv".format(name=name))
+
+
+def GKernal(x0, x, y, sig=1.):
+    """Gaussian kernel smoother evaluated at ``x0``."""
+    ax = x - x0
+    Kernal = np.exp(-0.5 * np.square(ax) / np.square(sig))
+    Weighted = Kernal * y
+    return np.sum(Weighted) / np.sum(Kernal)
+
+
+def gridding(mz, intensity, start=None, end=None, increment=0.125, epsilon=0.025):
+    """Re-grid an irregular m/z axis onto a uniform grid with Nadaraya-Watson smoothing."""
+    if start is None:
+        start = math.floor(np.min(mz)) - 1
+    if end is None:
+        end = math.ceil(np.max(mz)) + 1
+    target_grid = np.arange(start, end, increment)
+    intensity_out = np.zeros(target_grid.shape[0])
+    for i in range(target_grid.shape[0]):
+        calculation = GKernal(target_grid[i], mz, intensity, sig=epsilon)
+        if calculation == calculation:
+            intensity_out[i] = calculation
+        else:
+            intensity_out[i] = 0
+    return [target_grid, intensity_out]

pgalign-1.1.0.dist-info/METADATA

@@ -0,0 +1,318 @@
+Metadata-Version: 2.4
+Name: pgalign
+Version: 1.1.0
+Summary: PGAlign: peak group alignment of mass spectrometry data for imaging and spatial metabolomics.
+Author: Anji Deng, Yuyang Zhang
+Author-email: Qihuang Zhang <qihuang.zhang@mcgill.ca>
+Maintainer-email: Qihuang Zhang <qihuang.zhang@mcgill.ca>
+License-Expression: MIT
+Project-URL: Homepage, https://stagill.github.io/PGAlign/
+Project-URL: Documentation, https://stagill.github.io/PGAlign/
+Project-URL: Repository, https://github.com/StaGill/PGAlign
+Project-URL: Issues, https://github.com/StaGill/PGAlign/issues
+Keywords: MALDI,mass spectrometry,spatial metabolomics,alignment,imaging,bioinformatics
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.20
+Requires-Dist: scipy>=1.7
+Requires-Dist: pandas>=1.3
+Requires-Dist: scanpy>=1.9.2
+Requires-Dist: anndata>=0.8
+Requires-Dist: tqdm
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Provides-Extra: imzml
+Requires-Dist: pyimzML>=1.5; extra == "imzml"
+Dynamic: license-file
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/StaGill/PGAlign/main/images/pgalign_logo_dark.svg">
+    <img src="https://raw.githubusercontent.com/StaGill/PGAlign/main/images/pgalign_logo.svg" alt="PGAlign" width="420">
+  </picture>
+</p>
+
+<p align="center">
+  <a href="https://github.com/StaGill/PGAlign/actions/workflows/tests.yml"><img src="https://github.com/StaGill/PGAlign/actions/workflows/tests.yml/badge.svg?branch=main" alt="tests"></a>
+  <a href="https://stagill.github.io/PGAlign/"><img src="https://github.com/StaGill/PGAlign/actions/workflows/docs.yml/badge.svg?branch=main" alt="docs"></a>
+  <a href="https://github.com/StaGill/PGAlign/releases"><img src="https://img.shields.io/github/v/release/StaGill/PGAlign" alt="release"></a>
+  <a href="https://github.com/StaGill/PGAlign/blob/main/LICENSE"><img src="https://img.shields.io/github/license/StaGill/PGAlign" alt="license"></a>
+</p>
+
+**PGAlign (Peak-Group Alignment of mass spectrometry data)** is a peak-group-based
+algorithm for aligning mass spectrometry (MS) spectra onto a common m/z grid.
+It is designed for imaging and spatial metabolomics data such as MALDI-MS,
+where spectra from different runs or tissues often exhibit small m/z shifts
+that prevent direct comparison.
+
+Anji Deng, Yuyang Zhang, and Qihuang Zhang\*
+McGill University (corresponding author: <qihuang.zhang@mcgill.ca>)
+
+**Documentation:** <https://stagill.github.io/PGAlign/>
+
+![Overview of the PGAlign workflow](https://raw.githubusercontent.com/StaGill/PGAlign/main/images/pgalign_workflow.png)
+
+By aligning an "unknown" spectrum (or dataset) to a reference while *forcing*
+matched spectra to share the same m/z values, PGAlign enables downstream
+analyses such as:
+
+- joint spatial segmentation across tissues or time points
+- classification using combined datasets
+- other multi-sample analyses that require a common m/z grid
+
+This repository contains the reference Python implementation accompanying the
+PGAlign manuscript (Deng, Zhang & Zhang, 2026; under peer review).
+
+---
+
+## Repository layout
+
+- `pgalign/`: Core Python implementation of PGAlign (alignment and peak-group functions).
+- `CodeInPaper/`: Scripts that reproduce the figures and results in the manuscript. See `CodeInPaper/README.md`.
+- `Tutorial_PGAlign.ipynb`: A Jupyter notebook that walks through aligning two MALDI datasets (e.g., Week 2 and Week 5 macrophage samples) and preparing them for joint segmentation.
+- `tests/`: Smoke tests (`pytest`).
+- `CITATION.cff`: Citation metadata.
+- `LICENSE`: MIT license.
+
+---
+
+## Installation
+
+```bash
+pip install pgalign            # or "pgalign[imzml]" to read imzML files
+```
+
+To work from the source, clone the repository and install it with `pip`:
+
+```bash
+git clone https://github.com/StaGill/PGAlign.git
+cd PGAlign
+pip install -e .
+```
+
+The package's importable name is `pgalign`:
+
+```python
+import pgalign as pg
+print(pg.__version__)
+```
+
+---
+
+## API at a glance
+
+The four-step pipeline in the paper maps to the following public methods:
+
+| Step | Manuscript section          | Object · method                                   |
+|-----:|-----------------------------|---------------------------------------------------|
+| 1    | Peak Calling                | `PeakCalling.peak_calling(threshold=0.9)`         |
+| 2    | Peak Grouping               | `PeakCalling.peak_grouping(percentile=0.9)`       |
+| 3    | Peak Group Pairing          | `AnnDataMALDI.peak_group_pairing(criteria=0)`     |
+| 4    | Fine Alignment Assessment   | `AnnDataMALDI.fine_alignment_assessment(threshold=0.2)` |
+
+Similarity is measured with Pearson's correlation; Step 3 uses a sliding
+window of +/- 4 grid points (see Methods of the paper). `pg.align(unk, ref)`
+runs all four steps in one call (see Quick start).
+
+The pre-2026 method names (`callpeak`, `grouppeaks`, `greedy_match`,
+`fine_align`) are kept as deprecated aliases and emit `DeprecationWarning`.
+
+---
+
+## Toy data
+
+A 120-spectrum / 601-m/z-bin slice of the public mouse pancreas dataset
+(Prade et al., 2020, Zenodo 10.5281/zenodo.3607915, CC BY 4.0) ships with the
+package for tutorials and tests:
+
+```python
+import pgalign as pg
+unk, ref = pg.datasets.load_mouse_pancreas_toy()
+```
+
+The "unknown" spectrum has a planted +2-bin rigid shift relative to the
+reference, so PGAlign should recover a shift of about +2 m/z bins.
+
+---
+
+## Reading your data
+
+```python
+unk = pg.read_imzml("unknown.imzML", increment=0.25)     # pip install "pgalign[imzml]"
+ref = pg.read_imzml("reference.imzML", increment=0.25)
+```
+
+`pg.read_imzml` reads continuous imzML as it is and puts processed imzML, where
+each spectrum carries its own m/z values, on a common grid. `pg.read_scils_csv`
+reads SCiLS Lab CSV exports, and `pg.read_h5ad` reads `.h5ad` files. Each gives an
+`AnnData` with the m/z values in `var["m/z"]`, ready for `pg.align`. Save results
+with `pg.write_h5ad(res.aligned, "aligned.h5ad")`: anndata 0.13 and later cannot write a column named `m/z`, so `pg.write_h5ad` stores
+it as `mz` and `pg.read_h5ad` restores it.
+
+---
+
+## Command line
+
+```bash
+pgalign align unknown.imzML reference.imzML -o aligned.h5ad --increment 0.25
+```
+
+This prints the summary line and writes the aligned unknown spectra to
+`aligned.h5ad`, the reference on the same bins to `aligned_reference.h5ad`, and
+the two tables to `aligned_shifts.csv` and `aligned_ambiguity.csv`; read the
+`.h5ad` files back with `pg.read_h5ad`. Inputs can be
+`.imzML`, `.h5ad` or SCiLS `.csv` exports. `pgalign align --help` lists the
+options, which mirror those of `pg.align`.
+
+---
+
+## Quick start
+
+```python
+import pgalign as pg
+
+unk, ref = pg.datasets.load_mouse_pancreas_toy()   # or your own two AnnData objects
+res = pg.align(unk, ref)
+print(res.summary())     # 7 groups paired, 7 shifted, 0 flagged at tau = 0.1
+aligned = res.aligned    # the unknown spectra on the reference m/z grid
+```
+
+`pg.align` normalizes each spectrum, runs the four steps with the manuscript's
+defaults and returns the aligned dataset with two tables: `res.shifts`, one row
+per paired peak group with its offset, and `res.ambiguity`, the diagnostic
+described under [Flagging ambiguous alignments](https://github.com/StaGill/PGAlign#flagging-ambiguous-alignments).
+By default it calls peaks on the three-point moving average described in the
+Methods; pass `smooth=False` for the peak caller used in the simulation study
+and the canine sarcoma analysis. The inputs are not modified.
+
+### Step by step
+
+The notebooks under `CodeInPaper/` run the pipeline one step at a time, and
+`Tutorial_PGAlign.ipynb` gives a worked example. The basic workflow is:
+
+1. Load two MALDI datasets (e.g., two time points or two tissues) with optional spatial coordinates.
+2. Wrap them as `AnnData` objects (via `scanpy` / `anndata`).
+3. Normalize intensities per spectrum.
+4. Run the four PGAlign steps.
+5. Extract the aligned spectra for joint downstream analyses (e.g., PCA + Harmony + clustering).
+
+```python
+import scanpy as sc
+import pgalign as pg
+
+# X = spectra, var = m/z table, obs = coordinates (see Tutorial_PGAlign.ipynb)
+MALDIdataAnn1 = ...   # unknown spectrum
+MALDIdataAnn2 = ...   # reference spectrum
+
+# Per-spectrum normalisation
+sc.pp.normalize_per_cell(MALDIdataAnn1)
+sc.pp.normalize_per_cell(MALDIdataAnn2)
+
+# Step 1 + Step 2: peak calling and peak grouping
+PeakGroup = pg.PeakCalling(MALDIdataAnn1, MALDIdataAnn2)   # pg.align uses pg.PeakCallingmv by default
+PeakGroup.peak_calling(threshold=0.9)
+PeakGroup.peak_grouping(percentile=0.9)
+
+# Step 3: peak group pairing
+ExactAlign = pg.AnnDataMALDI(MALDIdataAnn1, MALDIdataAnn2)
+ExactAlign.get_corr_peakgroup_refined(PeakGroup.jointcluster)
+ExactAlign.peak_group_pairing(criteria=0)
+
+# Step 4: fine alignment assessment
+ExactAlign.fine_alignment_assessment(threshold=0.2, ignore=True)
+ExactAlign.summarize()
+
+# The aligned dataset: the unknown spectra on the reference m/z grid
+MALDIdataAnn1_aligned = pg.PGmzalign(ExactAlign).getAnnSim()
+```
+
+`getAnnSim()` returns the unknown spectra as an `AnnData` whose `var["m/z"]`
+are the reference's m/z values, so it can be analysed jointly with the
+reference. Despite the method's name, nothing is simulated. The result is cut
+to the shorter of the two m/z axes, so it can lack a few bins at the top of the
+range.
+
+Please refer to `Tutorial_PGAlign.ipynb` for a fully worked example with real
+data and plots.
+
+### Flagging ambiguous alignments
+
+A shifted peak group always has one alternative: staying at its original
+position. After Step 4, `flag_ambiguous_alignments` flags a shifted group when
+staying scores within `delta` (default 0.1) of the chosen alignment, using the
+pairing similarity for groups matched to a different reference group and the
+zero-offset diagonal for groups moved by a non-zero offset. Flagged groups are
+reported with both scores, so you can inspect them before downstream analysis.
+
+```python
+ExactAlign.fine_alignment_assessment(threshold=0.2, ignore=True)
+table = ExactAlign.flag_ambiguous_alignments(delta=0.1)
+print(table[table["flagged"]])
+print(f"{table['flagged'].sum()} of {len(table)} shifted groups flagged")
+print(table.groupby("rule")["flagged"].agg(["sum", "size"]))
+```
+
+The `rule` column says which comparison a row was assessed by: `"group"` for
+a group paired with a different reference group, `"offset"` for a group
+paired at its own position but moved by a non-zero offset.
+
+---
+
+## Reproducing results from the manuscript
+
+Release v1.0.1 is the version that accompanies the manuscript. Later releases
+may change the results, so install that version to reproduce them:
+
+```bash
+pip install "git+https://github.com/StaGill/PGAlign@v1.0.1"
+```
+
+The notebooks under `CodeInPaper/` reproduce the main analyses; run them from a
+checkout of the same release (`git checkout v1.0.1`). Each subfolder has its
+own `README.md` with dataset access instructions:
+
+- **Simulation study (mouse pancreas MALDI)**: alignment error under
+  controlled peak shifts and noise. See `CodeInPaper/MousePancreate.ipynb`.
+- **Macrophage metabolomics (atherosclerosis regression)**: aligns Week 5
+  MALDI spectra to Week 2 and performs joint spatial segmentation. See
+  `CodeInPaper/Maaike/`.
+- **Canine sarcoma classification**: aligns cancer tissue spectra to normal
+  tissue and assesses classification performance before/after alignment. See
+  `CodeInPaper/Sarcomas/`.
+
+**Data sources:**
+
+- Mouse pancreas MALDI: <https://doi.org/10.5281/zenodo.3607915>
+- Atherosclerosis regression MALDI: mean spectra on Zenodo (<https://zenodo.org/records/20533948>); the per-spot
+  spectra that the notebooks read are available from the data owners upon reasonable request.
+- Canine sarcoma MALDI: ProteomeXchange PRIDE accession `PXD010990` (<https://proteomecentral.proteomexchange.org/cgi/GetDataset?ID=PXD010990>).
+
+---
+
+## Citation
+
+The PGAlign manuscript is currently under peer review. If you use PGAlign in
+your research, please cite this repository (see `CITATION.cff`, which GitHub
+renders as a "Cite this repository" button) and contact the corresponding
+author for the latest preprint:
+
+> Deng A, Zhang Y, Zhang Q. *PGAlign: peak group alignment of mass spectrometry data*.
+> Under review at the *Journal of Proteome Research*, 2026.
+
+---
+
+## License
+
+MIT (see `LICENSE`).

pgalign-1.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+pgalign/AnnDataMALDI.py,sha256=N5hwiB_8_IvuaQ9zpyhC7pfQkL8ZFIZhxr5LXSDtkvU,24072
+pgalign/PeakCalling.py,sha256=7JHcmmzz7q92cr9YsrMvpEafONPAApO1eiW2CwWVTP8,10821
+pgalign/__init__.py,sha256=0lDCwdEkQUgomwM-H5EIA0IS0no2D7WPScOR_160aIc,1936
+pgalign/cli.py,sha256=pjA6jHd5L1s4Ivixc19oBT3oAPyPPQbpCYa2vKscHQ4,3891
+pgalign/datasets.py,sha256=jP2WSjrbGhKi947lc_ngbd3Qmtky2vC2ghwZN9D0kb4,1503
+pgalign/pipeline.py,sha256=g3xqDD_-WVLRDydeeZpZrojnd5vzZWLJuqt25MxNF1A,7329
+pgalign/readers.py,sha256=bN1QxcttERIMbNGc2KBiaJvUrdf6cXnKlt2Ox5Ui6YE,6274
+pgalign/util.py,sha256=K9Cw2CrOfiNL5gXM9dmxFpPFGiAiRHYy1IF93lp8Px8,5657
+pgalign/data/mouse_pancreas_toy.npz,sha256=tNEPPLjNFqMQ3UiPJCJbS2ubRQIJrRCEdVfEmYyqKVk,236722
+pgalign-1.1.0.dist-info/licenses/LICENSE,sha256=SpAkCKdPBNgXyKpG5AH7RmQ3AwOXjQ2xHC4FIA8gP10,1070
+pgalign-1.1.0.dist-info/METADATA,sha256=Eo1VxipFpksCzbhHB4JSxCOU_-QdIQcD0UXSfOfGTac,12909
+pgalign-1.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+pgalign-1.1.0.dist-info/entry_points.txt,sha256=TWdzHsbYH-svOS5ZOlDPBaEIZjn03NXxpWW4Rm9X8ho,45
+pgalign-1.1.0.dist-info/top_level.txt,sha256=qGfhDsHZvQMAjnA44gyEEEirL1d0SZH3TKDuorxdtpM,8
+pgalign-1.1.0.dist-info/RECORD,,

pgalign-1.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pgalign-1.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pgalign = pgalign.cli:main

pgalign-1.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Qihuang Zhang
+
+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.

pgalign-1.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pgalign