ashlar-fast

Parallel, drop-in acceleration of ASHLAR, the stitching and registration step of nf-core/mcmicro and the pipeline's dominant single-threaded bottleneck.

ashlar-fast reuses ASHLAR's own algorithm classes unchanged and parallelizes only the stages that force serial execution, producing byte-identical output to stock ASHLAR v1.20.0. Developed under the rewrites.bio framework, with the original resurrected and baselined via the Lazarus approach.

Status

v0.1.0 — validated acceleration of the OME-TIFF path. Five stages are parallelized and verified byte-identical to golden ASHLAR on two real datasets. It is a drop-in for the OME-TIFF path but not yet a complete replacement for every ASHLAR feature (see Scope).

Results

Byte-identical to stock ASHLAR v1.20.0 (0 pixel difference across all pyramid levels and channels, identical alignment shifts and spanning tree) on both datasets. Single 8-core node, warm cache:

dataset	shape	end-to-end	dominant lever
CRC whole-slide (syn25826362)	609 tiles, 2 ch	2.30× (323 s → 141 s)	tile-parallel registration
exemplar-001 (ASHLAR CI)	6 tiles, 12 ch	2.06× (13.8 s → 6.7 s)	channel-parallel assembly/pyramid

Registration stage alone is 10.6× (59.9 s → 5.65 s, 1168 edges). Both axes grow at real mcmicro scale (10³ tiles × 12–40 channels × many cycles).

• Full benchmarks: docs/benchmarks/
• Per-claim source manifest (every number → the script that produced it): results/README.md
• Write-up: manuscript/manuscript.md
• Acceleration plan: ACCELERATION-PLAN.md

Install

Container (recommended; published to GHCR on each release):

docker run --rm -v "$PWD":/data -w /data \
  ghcr.io/mc2-center/ashlar-fast:latest \
  ashlar-fast cycle1.ome.tif cycle2.ome.tif -m 30 -o mosaic.ome.tif

From source:

pip install .            # provides the `ashlar-fast` console script
ashlar-fast --help

Image details and the planned migration to the nf-core registry are in docs/containers.md.

Usage (drop-in)

ashlar-fast mirrors ASHLAR's command-line interface flag-for-flag for the OME-TIFF path (same flag names, defaults, output/pyramid detection, and illumination handling), plus -j/--n-jobs (parallel workers, default all cores) and --max-prefetch. Unsupported paths fail loudly rather than mis-behaving: --plates and --barrel-correction are rejected with a clear message, and non-OME-TIFF inputs are rejected by the reader (use stock ASHLAR for those).

How it works

Reuses ASHLAR's EdgeAligner, LayerAligner, Mosaic, and writer classes so the registration mathematics is unchanged, and swaps only:

1. Reader — a JVM-free, picklable OME-TIFF reader (TifffileReader), verified byte-identical to BioFormats. Removes the JVM from the hot path and unblocks process parallelism.
2. Registration — process-parallel per-tile phase correlation for both intra-cycle (EdgeAligner) and inter-cycle (LayerAligner) stages.
3. Thumbnails / assembly / pyramid — parallel per-tile read+rescale and channel-parallel assembly and pyramid generation, with the blend-paste order preserved so output stays byte-identical.

Validation

ASHLAR ships no unit tests or numerical fixtures. ashlar-fast builds the equivalence harness that does not exist upstream (tests/equivalence/): it compares alignment shifts, spanning-tree topology, and per-pixel mosaic values against a pinned ASHLAR v1.20.0 reference container (reference/, with a PASS certificate in reference/REPRODUCE.md). Tolerances are in docs/validation-policy.md.

During validation the harness caught two self-inflicted regressions and surfaced a genuine metadata defect in a public dataset that causes stock ASHLAR to silently misregister; see docs/findings/ome-uuid-sibling-mismatch.md.

Scope and known limitations

• OME-TIFF only; vendor formats still require BioFormats (rejected, not mishandled).
• Flat per-channel TIFF output uses ASHLAR's serial writer; only the pyramidal OME-TIFF path is accelerated.
• Plate mode and barrel-distortion correction are not supported (fail loud).
• Not yet done: chunked/streamed assembly to fix the WSI memory ceiling (upstream #242), GPU (cuCIM) phase correlation, and an rFFT core. See CHANGELOG.md.

Original tool and how to cite

ashlar-fast is a rewrite of ASHLAR by Jeremy L. Muhlich, Yu-An Chen, Clarence Yapp, Douglas Russell, and Peter K. Sorger (Laboratory of Systems Pharmacology, Harvard Medical School). All algorithmic credit belongs to the original authors. This rewrite tracks ASHLAR v1.20.0.

If you use ashlar-fast, please cite the original (required):

Muhlich, J.L., Chen, Y.-A., Yapp, C., Russell, D. & Sorger, P.K. (2022). Stitching and registering highly multiplexed whole-slide images of tissues and tumors using ASHLAR. Bioinformatics 38(19):4613–4621. DOI: 10.1093/bioinformatics/btac544

Machine-readable citation: CITATION.cff.

AI assistance disclosure

Developed with assistance from Claude Code (Claude Opus 4.8), disclosed per the rewrites.bio framework. Every equivalence claim is backed by running stock ASHLAR and ashlar-fast on real data and comparing outputs; we do not rely on code review alone. See docs/validation-policy.md for method and gaps.

License

MIT, matching upstream ASHLAR. See LICENSE.