pgalign 1.1.0__py3-none-any.whl

pgalign/PeakCalling.py

@@ -0,0 +1,282 @@
+"""Peak calling and peak grouping (PGAlign Steps 1 and 2).
+
+Implements the "Peak calling" and "Peak grouping: a greedy algorithm"
+subsections of the Methods in Deng, Zhang & Zhang (2026).
+"""
+
+import warnings
+
+import numpy as np
+
+from .util import (
+    in_range_lookup,
+    comp_clusters,
+    get_unk_comp_clusters,
+)
+
+
+class PeakCalling(object):
+    """Two-spectrum peak calling and joint peak grouping.
+
+    Parameters
+    ----------
+    AnnDataUnk : anndata.AnnData
+        The "unknown" spectrum to be aligned.
+    AnnDataRef : anndata.AnnData
+        The reference spectrum.
+    """
+
+    def __init__(self, AnnDataUnk, AnnDataRef):
+        self.AnnDataUnk = AnnDataUnk
+        self.AnnDataRef = AnnDataRef
+        self.mz_valueUnk = AnnDataUnk.var
+        self.mz_valueRef = AnnDataRef.var
+        self.meanspectrumUnk = np.mean(AnnDataUnk.X, axis=0)
+        self.meanspectrumRef = np.mean(AnnDataRef.X, axis=0)
+
+    def get_peaks(self, mz, intensity, threshold):
+        deriv = np.divide(np.diff(intensity), np.diff(mz))
+        cutpoint = np.quantile(np.abs(deriv), threshold)
+        increase = deriv > cutpoint
+        increase = np.insert(increase, 0, False)
+        decrease = deriv < - cutpoint
+        decrease = np.append(decrease, False)
+        peak = np.logical_or(increase, decrease)
+        ### Exclude the single peak
+        e_left = np.empty_like(peak)
+        e_right = np.empty_like(peak)
+        e_left[-1] = False
+        e_left[:-1] = peak[1:]
+        e_right[0] = False
+        e_right[1:] = peak[:-1]
+        simplet = np.logical_and(peak, np.logical_not(np.logical_or(e_left, e_right)))
+        d_left = np.empty_like(simplet)
+        d_right = np.empty_like(simplet)
+        d_left[-1] = False
+        d_left[:-1] = simplet[1:]
+        d_right[0] = False
+        d_right[1:] = simplet[:-1]
+        peak = np.logical_or(peak, np.logical_or(d_left, d_right))
+        return peak
+
+    def point_clusters(self, points, percentile=0.75):
+        points_sorted = np.sort(points)
+        dist_points = np.diff(points_sorted)
+        dist_points_sort = np.quantile(dist_points, percentile)
+        #
+        clusters = []
+        eps = dist_points_sort
+        curr_point = points_sorted[0]
+        curr_cluster = [curr_point]
+        for point in list(points_sorted[1:]):
+            if point <= curr_point + eps:
+                curr_cluster.append(point)
+            else:
+                clusters.append(curr_cluster)
+                curr_cluster = [point]
+            curr_point = point
+        clusters.append(curr_cluster)
+        return clusters
+
+    def peak_calling(self, threshold=0.9):
+        """PGAlign Step 1: identify peaks in the unknown and reference mean spectra.
+
+        Default ``threshold=0.9`` corresponds to the 90% quantile (alpha in the paper).
+        """
+        self.peakUnk = self.get_peaks(
+            mz=np.array(self.mz_valueUnk["m/z"]),
+            intensity=self.meanspectrumUnk,
+            threshold=threshold,
+        )
+        self.peakRef = self.get_peaks(
+            mz=np.array(self.mz_valueRef["m/z"]),
+            intensity=self.meanspectrumRef,
+            threshold=threshold,
+        )
+        self.meanspectrumUnkpeak = self.meanspectrumUnk[self.peakUnk]
+        self.meanspectrumRefpeak = self.meanspectrumRef[self.peakRef]
+
+    def callpeak(self, threshold=0.9):
+        warnings.warn(
+            "callpeak() is deprecated; use peak_calling() to match the manuscript terminology.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.peak_calling(threshold=threshold)
+
+    def peak_grouping(self, percentile=0.9):
+        """PGAlign Step 2: partition adjacent peaks into joint peak groups.
+
+        Default ``percentile=0.9`` uses the top 10% of pairwise m/z distances
+        as cut points (peak grouping parameter in the paper).
+        """
+        self.clusterUnk = self.point_clusters(
+            np.array(self.mz_valueUnk["m/z"][list(self.peakUnk)]),
+            percentile=percentile,
+        )
+        self.clusterRef = self.point_clusters(
+            np.array(self.mz_valueRef["m/z"][list(self.peakRef)]),
+            percentile=percentile,
+        )
+        self.mzcombine = np.concatenate((
+            np.array(self.mz_valueUnk["m/z"][list(self.peakUnk)]),
+            np.array(self.mz_valueRef["m/z"][list(self.peakRef)]),
+        ))
+        self.jointcluster = self.point_clusters(np.sort(self.mzcombine), percentile)
+
+    def grouppeaks(self, percentile=0.9):
+        warnings.warn(
+            "grouppeaks() is deprecated; use peak_grouping() to match the manuscript terminology.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.peak_grouping(percentile=percentile)
+
+    def filter_clusters(self, mzboundary):
+        self.jointcluster = [clusteri for clusteri in self.jointcluster if clusteri[-1] < mzboundary]
+
+    def importpeak(self, peakUnk, peakRef):
+        self.peakUnk = np.zeros(self.mz_valueUnk.shape[0], dtype=bool)
+        self.peakRef = self.peakUnk
+        for i in range(peakUnk.shape[0]):
+            self.peakUnk[peakUnk[i]] = True
+        for j in range(peakRef.shape[0]):
+            self.peakRef[peakRef[j]] = True
+        self.meanspectrumUnkpeak = self.meanspectrumUnk[self.peakUnk]
+        self.meanspectrumRefpeak = self.meanspectrumRef[self.peakRef]
+
+
+class PeakCalling_single(PeakCalling):
+    def __init__(self, AnnData):
+        super().__init__(AnnData, AnnData)
+
+    def peak_calling(self, threshold=0.9):
+        """Single-spectrum variant of Step 1 (reference only)."""
+        self.peakRef = self.get_peaks(
+            mz=np.array(self.mz_valueRef["m/z"]),
+            intensity=self.meanspectrumRef,
+            threshold=threshold,
+        )
+        self.meanspectrumRefpeak = self.meanspectrumRef[self.peakRef]
+
+    def callpeak(self, threshold=0.9):
+        warnings.warn(
+            "callpeak() is deprecated; use peak_calling() to match the manuscript terminology.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.peak_calling(threshold=threshold)
+
+    def peak_grouping(self, percentile=0.9):
+        """Single-spectrum variant of Step 2 (reference only)."""
+        self.clusterRef = self.point_clusters(
+            np.array(self.mz_valueRef["m/z"][list(self.peakRef)]),
+            percentile,
+        )
+        self.jointcluster = self.clusterRef
+
+    def grouppeaks(self, percentile=0.9):
+        warnings.warn(
+            "grouppeaks() is deprecated; use peak_grouping() to match the manuscript terminology.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.peak_grouping(percentile=percentile)
+
+    def filter_clusters(self, mzboundary):
+        self.jointcluster = [clusteri for clusteri in self.jointcluster if clusteri[-1] < mzboundary]
+
+    def importpeak(self, peakUnk, peakRef):
+        self.peakRef = self.peakUnk
+        for j in range(peakRef.shape[0]):
+            self.peakRef[peakRef[j]] = True
+        self.meanspectrumRefpeak = self.meanspectrumRef[self.peakRef]
+
+
+class PeakCallingmv(object):
+    """Moving-average variant of PeakCalling."""
+
+    def __init__(self, AnnDataUnk, AnnDataRef):
+        self.AnnDataUnk = AnnDataUnk
+        self.AnnDataRef = AnnDataRef
+        self.mz_valueUnk = AnnDataUnk.var
+        self.mz_valueRef = AnnDataRef.var
+        self.meanspectrumUnk = np.mean(AnnDataUnk.X, axis=0)
+        self.meanspectrumRef = np.mean(AnnDataRef.X, axis=0)
+        self.meanspectrumUnkmv = np.convolve(self.meanspectrumUnk, np.ones(3) / 3, mode='valid')
+        self.meanspectrumRefmv = np.convolve(self.meanspectrumRef, np.ones(3) / 3, mode='valid')
+        self.mz_valueUnk_mv = self.mz_valueUnk[1:(self.mz_valueUnk.shape[0] - 1)]
+        self.mz_valueRef_mv = self.mz_valueRef[1:(self.mz_valueRef.shape[0] - 1)]
+
+    def get_peaks(self, mz, intensity, threshold):
+        deriv = np.divide(np.diff(intensity), np.diff(mz))
+        cutpoint = np.quantile(np.abs(deriv), threshold)
+        increase = deriv > cutpoint
+        increase = np.insert(increase, 0, False)
+        decrease = deriv < - cutpoint
+        decrease = np.append(decrease, False)
+        peak = np.logical_or(increase, decrease)
+        return peak
+
+    def point_clusters(self, points, percentile=0.75):
+        points_sorted = np.sort(points)
+        dist_points = np.diff(points_sorted)
+        dist_points_sort = np.quantile(dist_points, percentile)
+        #
+        clusters = []
+        eps = dist_points_sort
+        curr_point = points_sorted[0]
+        curr_cluster = [curr_point]
+        for point in list(points_sorted[1:]):
+            if point <= curr_point + eps:
+                curr_cluster.append(point)
+            else:
+                clusters.append(curr_cluster)
+                curr_cluster = [point]
+            curr_point = point
+        clusters.append(curr_cluster)
+        return clusters
+
+    def peak_calling(self, threshold=0.9):
+        """Moving-average variant of Step 1."""
+        self.peakUnk = self.get_peaks(
+            mz=np.array(self.mz_valueUnk_mv["m/z"]),
+            intensity=self.meanspectrumUnkmv,
+            threshold=threshold,
+        )
+        self.peakRef = self.get_peaks(
+            mz=np.array(self.mz_valueRef_mv["m/z"]),
+            intensity=self.meanspectrumRefmv,
+            threshold=threshold,
+        )
+        self.meanspectrumUnkpeak = self.meanspectrumUnkmv[self.peakUnk]
+        self.meanspectrumRefpeak = self.meanspectrumRefmv[self.peakRef]
+
+    def callpeak(self, threshold=0.9):
+        warnings.warn(
+            "callpeak() is deprecated; use peak_calling() to match the manuscript terminology.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.peak_calling(threshold=threshold)
+
+    def peak_grouping(self, percentile=0.9):
+        """Moving-average variant of Step 2."""
+        self.clusterUnk = self.point_clusters(np.array(self.mz_valueUnk_mv["m/z"][list(self.peakUnk)]))
+        self.clusterRef = self.point_clusters(np.array(self.mz_valueRef_mv["m/z"][list(self.peakRef)]))
+        self.mzcombine = np.concatenate((
+            np.array(self.mz_valueUnk_mv["m/z"][list(self.peakUnk)]),
+            np.array(self.mz_valueRef_mv["m/z"][list(self.peakRef)]),
+        ))
+        self.jointcluster = self.point_clusters(np.sort(self.mzcombine), percentile)
+
+    def grouppeaks(self, percentile=0.9):
+        warnings.warn(
+            "grouppeaks() is deprecated; use peak_grouping() to match the manuscript terminology.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.peak_grouping(percentile=percentile)
+
+    def filter_clusters(self, mzboundary):
+        self.jointcluster = [clusteri for clusteri in self.jointcluster if clusteri[-1] < mzboundary]

pgalign/__init__.py

@@ -0,0 +1,87 @@
+"""PGAlign: peak group alignment of mass spectrometry data.
+
+Implementation accompanying the Deng, Zhang & Zhang (2026) manuscript (under review).
+The four pipeline steps in the paper map to these public objects:
+
+  Step 1  Peak Calling                  -> PeakCalling.peak_calling()
+  Step 2  Peak Grouping                 -> PeakCalling.peak_grouping()
+  Step 3  Peak Group Pairing            -> AnnDataMALDI.peak_group_pairing()
+  Step 4  Fine Alignment Assessment     -> AnnDataMALDI.fine_alignment_assessment()
+
+align() runs all four with the manuscript's defaults and returns the aligned dataset.
+"""
+
+__version__ = "1.1.0"
+
+from .util import (
+    prefilter_cells,
+    prefilter_genes,
+    prefilter_specialgenes,
+    save_clusterresults,
+    rotate,
+    group_range,
+    in_range_lookup,
+    comp_clusters,
+    find_nearest,
+    get_unk_comp_clusters,
+    spectrum_save,
+    GKernal,
+    gridding,
+)
+from .AnnDataMALDI import (
+    AnnDataMALDI,
+    MALDI_SIM,
+    PGmzalign,
+)
+from .PeakCalling import (
+    PeakCalling,
+    PeakCalling_single,
+    PeakCallingmv,
+)
+from .pipeline import (
+    AlignmentResult,
+    align,
+)
+from .readers import (
+    read_h5ad,
+    read_imzml,
+    read_scils_csv,
+    write_h5ad,
+)
+from . import datasets
+
+__all__ = [
+    "__version__",
+    # One-call pipeline
+    "align",
+    "AlignmentResult",
+    # Readers and .h5ad I/O
+    "read_imzml",
+    "read_scils_csv",
+    "read_h5ad",
+    "write_h5ad",
+    # AnnDataMALDI core
+    "AnnDataMALDI",
+    "MALDI_SIM",
+    "PGmzalign",
+    # Peak calling
+    "PeakCalling",
+    "PeakCalling_single",
+    "PeakCallingmv",
+    # Toy data
+    "datasets",
+    # Utilities
+    "prefilter_cells",
+    "prefilter_genes",
+    "prefilter_specialgenes",
+    "save_clusterresults",
+    "rotate",
+    "group_range",
+    "in_range_lookup",
+    "comp_clusters",
+    "find_nearest",
+    "get_unk_comp_clusters",
+    "spectrum_save",
+    "GKernal",
+    "gridding",
+]

pgalign/cli.py

@@ -0,0 +1,84 @@
+"""Command line interface: ``pgalign align UNKNOWN REFERENCE -o ALIGNED.h5ad``."""
+
+import argparse
+import sys
+from pathlib import Path
+
+from . import __version__
+from .pipeline import align
+from .readers import read_h5ad, read_imzml, read_scils_csv, write_h5ad
+
+
+def _read(path, spots, increment, mz_range):
+    suffix = Path(path).suffix.lower()
+    if suffix == ".imzml":
+        return read_imzml(path, increment=increment, mz_range=mz_range)
+    if suffix == ".h5ad":
+        return read_h5ad(path)
+    if suffix == ".csv":
+        return read_scils_csv(path, spots)
+    raise ValueError(f"cannot read {path}: expected an .imzML, .h5ad or SCiLS .csv file")
+
+
+def _parser():
+    parser = argparse.ArgumentParser(
+        prog="pgalign",
+        description="PGAlign: peak group alignment of mass spectrometry data.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    commands = parser.add_subparsers(dest="command", required=True)
+    cmd = commands.add_parser(
+        "align",
+        help="align an unknown dataset onto a reference",
+        description=(
+            "Align UNKNOWN onto REFERENCE with the full PGAlign pipeline. Each input is an "
+            ".imzML, .h5ad or SCiLS Lab .csv export. Writes the aligned unknown spectra to "
+            "OUT, and next to it the reference on the same bins (<stem>_reference.h5ad), "
+            "the per-group shifts (<stem>_shifts.csv) and the ambiguity table "
+            "(<stem>_ambiguity.csv)."
+        ),
+    )
+    cmd.add_argument("unknown", help="the dataset to align")
+    cmd.add_argument("reference", help="the dataset to align onto")
+    cmd.add_argument("-o", "--out", required=True, help="path of the aligned .h5ad to write")
+    cmd.add_argument("--unknown-spots", help="Region Spots.csv for a SCiLS .csv unknown")
+    cmd.add_argument("--reference-spots", help="Region Spots.csv for a SCiLS .csv reference")
+    cmd.add_argument("--increment", type=float,
+                     help="grid spacing in m/z for imzML input; required for processed imzML")
+    cmd.add_argument("--mz-range", type=float, nargs=2, metavar=("START", "END"),
+                     help="m/z range of that grid, END excluded")
+    cmd.add_argument("--no-smooth", dest="smooth", action="store_false",
+                     help="call peaks with PeakCalling instead of the moving average")
+    cmd.add_argument("--alpha", type=float, default=0.9, help="peak calling quantile (default 0.9)")
+    cmd.add_argument("--percentile", type=float, default=0.9,
+                     help="peak grouping parameter (default 0.9)")
+    cmd.add_argument("--delta", type=float, default=0, help="pairing criterion (default 0)")
+    cmd.add_argument("--tau", type=float, default=0.1,
+                     help="tolerance of the ambiguity diagnostic (default 0.1)")
+    cmd.add_argument("--no-normalize", dest="normalize", action="store_false",
+                     help="skip the per-spectrum normalization")
+    return parser
+
+
+def main(argv=None):
+    parser = _parser()
+    args = parser.parse_args(argv)
+    try:
+        unk = _read(args.unknown, args.unknown_spots, args.increment, args.mz_range)
+        ref = _read(args.reference, args.reference_spots, args.increment, args.mz_range)
+        res = align(unk, ref, smooth=args.smooth, alpha=args.alpha, percentile=args.percentile,
+                    delta=args.delta, tau=args.tau, normalize=args.normalize)
+    except (ValueError, ImportError) as err:
+        parser.exit(2, f"pgalign: error: {err}\n")
+    out = Path(args.out)
+    stem = out.with_suffix("")
+    write_h5ad(res.aligned, out)
+    write_h5ad(res.reference, f"{stem}_reference.h5ad")
+    res.shifts.to_csv(f"{stem}_shifts.csv", index=False)
+    res.ambiguity.to_csv(f"{stem}_ambiguity.csv", index=False)
+    print(res.summary())
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

pgalign/datasets.py

@@ -0,0 +1,39 @@
+"""Toy datasets bundled with PGAlign for tutorials and tests."""
+
+from importlib import resources
+
+import numpy as np
+import pandas as pd
+import scanpy as sc
+
+
+def load_mouse_pancreas_toy():
+    """Return two AnnData objects (unknown, reference) from a downsampled mouse-pancreas MALDI slice.
+
+    The data is a 120-spectrum, 601-bin slice of the public mouse pancreas dataset
+    (Zenodo `10.5281/zenodo.3607915`, Prade et al., 2020, CC BY 4.0), drawn from the
+    21 x 21 pixel window centred at (1636, 863) and the m/z range [100, 250] on a
+    0.25 m/z grid. The "unknown" companion is the same spectra shifted two bins higher
+    in m/z, with multiplicative lognormal noise (sigma 0.05), so PGAlign should recover
+    a shift of +2 bins. ``scripts/make_toy_data.py`` in the repository rebuilds it.
+
+    Returns
+    -------
+    unk : anndata.AnnData
+        The shifted "unknown" spectrum.
+    ref : anndata.AnnData
+        The unshifted reference spectrum.
+    """
+    with resources.files(__package__).joinpath("data/mouse_pancreas_toy.npz").open("rb") as f:
+        npz = np.load(f)
+        X_ref = npz["X_ref"]
+        X_unk = npz["X_unk"]
+        mz = npz["mz"]
+        x = npz["x"]
+        y = npz["y"]
+
+    var = pd.DataFrame({"m/z": mz.astype(float)}, index=[str(v) for v in mz])
+    obs = pd.DataFrame({"x": x, "y": y}, index=[f"s{i}" for i in range(len(x))])
+    ref = sc.AnnData(X=X_ref, var=var, obs=obs)
+    unk = sc.AnnData(X=X_unk, var=var.copy(), obs=obs.copy())
+    return unk, ref

pgalign/pipeline.py

@@ -0,0 +1,153 @@
+"""One-call interface to the PGAlign pipeline."""
+
+import numpy as np
+import pandas as pd
+import scanpy as sc
+import scipy.sparse as sp
+
+from .AnnDataMALDI import AnnDataMALDI, PGmzalign
+from .PeakCalling import PeakCalling, PeakCallingmv
+
+
+def _check_inputs(unk, ref):
+    """Raise a ValueError that names the problem and the fix for input pg.align cannot use."""
+    ranges = []
+    for name, adata in (("unk", unk), ("ref", ref)):
+        if "m/z" not in adata.var.columns:
+            hint = ("; a file saved with pg.write_h5ad stores them as 'mz', so read it with "
+                    "pg.read_h5ad") if "mz" in adata.var.columns else ""
+            raise ValueError(
+                f"{name}.var has no 'm/z' column (columns: {list(adata.var.columns)}); "
+                f"store the m/z values as {name}.var['m/z']{hint}"
+            )
+        mz = adata.var["m/z"].to_numpy(dtype=float)
+        if not np.isfinite(mz).all():
+            raise ValueError(f"{name}.var['m/z'] contains missing or infinite values")
+        if np.any(np.diff(mz) <= 0):
+            raise ValueError(
+                f"{name}.var['m/z'] must be strictly increasing; sort the bins with "
+                f"{name} = {name}[:, np.argsort({name}.var['m/z'].to_numpy())]"
+            )
+        values = adata.X.data if sp.issparse(adata.X) else np.asarray(adata.X)
+        n_bad = int(np.count_nonzero(~np.isfinite(values)))
+        if n_bad:
+            raise ValueError(
+                f"{name}.X contains {n_bad} missing or infinite intensities; "
+                "replace them, for example with 0"
+            )
+        mean = np.asarray(adata.X.mean(axis=0)).ravel()
+        if np.ptp(mean) == 0:
+            raise ValueError(
+                f"{name} carries no signal: its mean spectrum is constant at {mean[0]:g}, "
+                "so no peaks can be called"
+            )
+        ranges.append((mz[0], mz[-1]))
+    (unk_lo, unk_hi), (ref_lo, ref_hi) = ranges
+    if max(unk_lo, ref_lo) >= min(unk_hi, ref_hi):
+        raise ValueError(
+            f"the m/z ranges do not overlap: unk covers {unk_lo:g} to {unk_hi:g}, "
+            f"ref covers {ref_lo:g} to {ref_hi:g}"
+        )
+
+
+class AlignmentResult(object):
+    """The output of :func:`align`.
+
+    :ivar aligned: the unknown spectra on the reference m/z grid, as an
+        ``anndata.AnnData``. ``var["m/z"]`` holds the reference m/z values and
+        ``obs`` the unknown spectra. It is cut to the shorter of the two m/z axes,
+        so it can lack a few bins at the top of the range.
+    :ivar reference: the reference spectra on the same bins and the same scale as
+        ``aligned``, so the two can be analysed jointly. Both carry the
+        reference's bin labels as ``var_names``.
+    :ivar shifts: a DataFrame with one row per paired peak group: ``unknown_group``,
+        ``reference_group``, ``mz_start`` and ``mz_end`` (reference m/z range) and
+        ``offset``, the shift in grid points applied in Step 4.
+    :ivar ambiguity: the table of ``AnnDataMALDI.flag_ambiguous_alignments``, one
+        row per shifted group.
+    :ivar peaks: the peak calling object of Steps 1 and 2.
+    :ivar steps: the ``AnnDataMALDI`` object of Steps 3 and 4.
+    :ivar tau: the tolerance the ambiguity table was computed with.
+    """
+
+    def __init__(self, aligned, reference, shifts, ambiguity, peaks, steps, tau):
+        self.aligned = aligned
+        self.reference = reference
+        self.shifts = shifts
+        self.ambiguity = ambiguity
+        self.peaks = peaks
+        self.steps = steps
+        self.tau = tau
+
+    def summary(self):
+        """Return a one-line count of paired, shifted and flagged peak groups."""
+        n_flagged = int(self.ambiguity["flagged"].sum())
+        return (f"{len(self.shifts)} groups paired, {len(self.ambiguity)} shifted, "
+                f"{n_flagged} flagged at tau = {self.tau}")
+
+    def __repr__(self):
+        return f"AlignmentResult: {self.summary()}"
+
+
+def align(unk, ref, smooth=True, alpha=0.9, percentile=0.9, delta=0, tau=0.1, normalize=True):
+    """Align an unknown dataset onto a reference with the full PGAlign pipeline.
+
+    Runs the four steps of the Methods in order, then the diagnostic for ambiguous
+    alignments, and returns the aligned dataset. The defaults are those of the
+    Methods and of the atherosclerosis analysis in the manuscript. ``smooth=True``
+    calls peaks on the three-point moving average described in the Methods
+    ("Peak calling"), with ``PeakCallingmv``; ``smooth=False`` uses
+    ``PeakCalling``, as in the simulation study and the canine sarcoma analysis.
+    Step 4 applies the best offset to every paired group, as every analysis in the
+    manuscript did (``fine_alignment_assessment(ignore=True)``). The inputs are not
+    modified; a sparse intensity matrix is accepted and densified on the copy.
+    Input that cannot be aligned (no ``var["m/z"]``, m/z not increasing, missing
+    intensities, m/z ranges that do not overlap) raises a ``ValueError`` saying
+    what to fix.
+
+    :param unk: the unknown dataset, an ``anndata.AnnData`` with the m/z values in
+        ``var["m/z"]``.
+    :param ref: the reference dataset, in the same form.
+    :param smooth: call peaks on the moving average (``PeakCallingmv``) or on the
+        raw mean spectrum (``PeakCalling``). Defaults to True.
+    :param alpha: the peak calling quantile (alpha in the paper). Defaults to 0.9.
+    :param percentile: the peak grouping parameter. Defaults to 0.9.
+    :param delta: the pairing criterion (delta in the paper). Defaults to 0.
+    :param tau: the tolerance of the diagnostic for ambiguous alignments (tau in the
+        paper). Defaults to 0.1.
+    :param normalize: scale each spectrum to the median total intensity before
+        aligning (Methods, "Data normalization"), on copies of the inputs.
+        ``aligned`` and ``reference`` are returned on this normalized scale.
+        Defaults to True.
+    :return: an :class:`AlignmentResult`.
+    """
+    _check_inputs(unk, ref)
+    unk = unk.copy()
+    ref = ref.copy()
+    for adata in (unk, ref):
+        if sp.issparse(adata.X):
+            adata.X = adata.X.toarray()
+    if normalize:
+        sc.pp.normalize_total(unk)
+        sc.pp.normalize_total(ref)
+    peaks = (PeakCallingmv if smooth else PeakCalling)(unk, ref)
+    peaks.peak_calling(threshold=alpha)
+    peaks.peak_grouping(percentile=percentile)
+    steps = AnnDataMALDI(unk, ref)
+    steps.get_corr_peakgroup_refined(peaks.jointcluster)
+    steps.peak_group_pairing(criteria=delta)
+    steps.fine_alignment_assessment(ignore=True)
+    steps.summarize()
+    ambiguity = steps.flag_ambiguous_alignments(delta=tau)
+    aligned = PGmzalign(steps).getAnnSim()
+    reference = ref[:, :aligned.n_vars].copy()
+    aligned.var_names = reference.var_names
+    mz_ref = ref.var["m/z"].to_numpy(dtype=float)
+    shifts = pd.DataFrame({
+        "unknown_group": steps.align_group[:, 0].astype(int),
+        "reference_group": steps.align_group[:, 1].astype(int),
+        "mz_start": [mz_ref[group[0]] for group in steps.aligned_mz_clusters_ref],
+        "mz_end": [mz_ref[group[-1]] for group in steps.aligned_mz_clusters_ref],
+        "offset": np.asarray(steps.changerecord, dtype=int),
+    })
+    return AlignmentResult(aligned, reference, shifts, ambiguity, peaks, steps, tau)