Skip to content

About

Open-source chromatin-accessibility platform: Chromap + libMACS3 (byte-identical narrow peaks) + libchromap callable library + MCP server. Composes with STAR Suite for end-to-end multiomic (RNA + ATAC) single-binary processing.

github.com/morphic-bio/chromap_suite_paper

Resources

Readme
MIT license
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository
BranchesTags

Repository files navigation

Chromap Suite

Chromap Suite is an open-source C++ chromatin-accessibility platform: ATAC-seq alignment with native BAM output and coordinate sorting, an in-process narrow peak caller (librapidmacs) byte-identical to MACS3 v3.0.3, an embeddable callable-library API (libchromap), and an MCP server with a browser Launchpad. Chromap Suite produces the MACS3 narrow peaks the field already uses and composes with STAR Suite for an end-to-end multiomic (RNA + ATAC) single-binary pipeline. Bulk ATAC, scATAC, ChIP-seq, and Hi-C all run through the same binary; multiomic processing is delivered through libchromap embedded in STAR Suite as a worker thread.

On the public 3K PBMC Multiome at 32 threads, the integrated multiomic pipeline (STAR Suite + libchromap + librapidmacs) completes in 18:17 / 64.8 GB peak RSS vs 40:04 / 79.1 GB for Cell Ranger ARC v2.2.0 (2.19× faster, ~18% lower memory), producing 50,274 narrowPeak peaks byte-identical to MACS3 v3.0.3 (md5 34f9f991…). Standalone librapidmacs runs 7.8× / 10.3× / 11.3× faster than Cython MACS3 v3.0.3 at 1 / 4 / 24 threads.

Agent quickstart: see AGENTS.md for repo-specific guardrails, tests, and recent changes.

Chromap Suite was spun off from Chromap in 2026 and no longer tracks upstream; see HISTORY.md for lineage.

Chromap Suite capabilities

The full set of capabilities is organised by scope, mirroring Table 2 of the Chromap Suite preprint:

Core capabilities

  • Native BAM output + coordinate sort (--BAM --sort-bam --write-index). Replaces the conventional chromap | samtools sort | samtools index chain via htslib + a k-way disk-merge spillover. Produces @HD VN:1.6 SO:coordinate headers and .bam.bai indexes in one process. Sort key: (tid, pos, flag, mtid, mpos, isize) with read_id tie-break (note: differs from samtools sort QNAME tie-break). See docs/sort_spec.md. Compatible with --low-mem.
  • In-process librapidmacs narrow peak calling (--call-macs3-frag-peaks). Fragments are handed to librapidmacs through the FragmentIterator API without an intermediate fragments.tsv.gz write, so a single chromap invocation produces sorted-and-indexed BAM, fragments, and MACS3-equivalent narrowPeak and summit outputs. The default threshold remains MACS-style p-mode (--macs3-frag-pvalue 1e-5); --macs3-frag-qvalue Q switches to q-value/FDR thresholding for macs3 callpeak -q compatibility. Bulk ATAC supported via --macs3-frag-peaks-source memory (no barcode required); scATAC/multiomic via barcoded fragments. Output is byte-identical to standalone MACS3 v3.0.3 in the default p-mode path (50,274 peaks, md5 34f9f991… on the 3K PBMC ATAC channel).
  • Y-chromosome filtering (--emit-Y-bam, --emit-noY-bam, --emit-Y-noY-fastq, --emit-Y-read-names). Three-stream output (all / Y-only / noY) for sex-aware analyses. Works with --sort-bam. Detection is case-insensitive and matches Y, chrY, CHR_Y, chr_y; decoy/random/alt contigs (chrY_random, etc.) are intentionally excluded. See the Y-chromosome filtering section below.
  • libchromap.a callable library. The full Chromap Suite ATAC pipeline is exposed through the libchromap API (RunAtacMapping(), ChromapAtacConfig, ChromapPermitHooks). The same library backs the chromap CLI binary and is the integration point used by STAR Suite for multiomic processing. See src/libchromap.h and src/libchromap.cc.
  • Direct minimizer-index loading. Existing Chromap index files are loaded through one aligned 256 MiB O_DIRECT stream when the filesystem supports it, bypassing pathological buffered/page-cache behavior on parallel file systems. The four historical khash/occurrence sections and their on-disk format are unchanged. Unsupported filesystems automatically fall back to positioned buffered reads; neither path performs a production checksum pass.
  • FASTQ intake shared with STAR Suite (--input-bgzf-mode {auto|on|off}, --input-bgzf-reader-threads N). A paired-end lane whose files are all BGZF (for example written by bgzip) is read with STAR Suite's BGZF reader, mirrored under src/star_input/: each file is inflated by parallel workers and consumed in order on its own thread, and records are paired by ordinal with STAR Suite's read-name check. Ordinary gzip is read with zlib, with read 1, read 2 and the barcode file decompressed on their own threads in every batch. The records Chromap maps, and therefore its outputs, are the same in every mode. See FASTQ intake.
  • --Tn5-shift-mode {classical|symmetric} picks the Tn5 cut-site offset convention on BED/BEDPE/PAF. classical (+4 / -5; Buenrostro 2013 / Cell Ranger ARC) is the default; symmetric (+4 / -4; ChromBPNet) is the alternative. Implies --Tn5-shift. Active offsets are echoed at startup. SAM/BAM output remains intentionally unshifted (shifting would require coordinated edits to POS, MPOS, TLEN, CIGAR, NM, MD).
  • --temp-dir DIR for custom temporary directory (helpful in Docker/container environments).
  • Optional materialized reference sidecar (--reference-sidecar). Index construction can store the decoded reference bases and contig dictionary in a versioned companion file. Mapping loads unchanged sidecars through aligned 256 MiB parallel direct-I/O pread blocks instead of reparsing the FASTA in every worker, with a positioned buffered fallback. The index binds the expected reference fingerprint; legacy FASTA/index operation is unchanged. See docs/materialized_reference_sidecar.md.

Reliability and tooling

  • Parallel low-memory merge for paired-end ATAC (--low-mem-finalize-threads N, default --num-threads). With --low-mem, sidecar-only, BED and TagAlign scATAC runs merge and deduplicate their spill files one reference per task, and write the same bytes as the serial merge. Embedding hosts opt in through MappingParameters::low_mem_finalize_threads; with permit hooks every task holds a host permit.
  • Low-memory spillover (rewritten architecture). Per-thread overflow writers feeding a k-way merge on read-back replace the prior shared-buffer + atomic-write design. Supports the full cross-product of --low-mem with --atac-fragments, BAM output, --macs3-frag-low-mem, and Y-filtering modes; production-scale runs (≳10⁹ reads) handled cleanly. A pre-existing race condition in the legacy spillover that produced silent read drops at ~1/10⁴ on typical datasets and intermittent hangs at production scale is resolved as a side effect of the rewrite. The legacy temp-file system is available via LEGACY_OVERFLOW=1 at compile time (single-threaded only). See HISTORY.md for file references and validation history.
  • Concurrency coordination across new collaborators. Worker threads coordinate with the native BAM writer, STAR Suite's permit allocator (when embedded), and librapidmacs peak-call paths under the existing OpenMP scheduler. The smoke matrix exercises all combinations of low-mem / BAM / peak-call / Y-filter modes.
  • Regression suite (C01–C11). An 11-area parity matrix covering the main user-visible surfaces: index build, paired BED output, ChIP and ATAC presets, scATAC barcode handling, sorted BAM and index, low-memory BED parity, ATAC BAM + fragments, librapidmacs narrow peak calling, Hi-C pairs, and Y/noY split. Three tiers: S0 hermetic synthetic for pre-commit smoke; S1 ENCODE downsample for real-assay confidence (paired ENCODE accessions and downsample manifests committed; FASTQs cached out-of-tree); S2 the 100K and paper-fixture tier reserved for heavier gates. The S0 tier is mandatory for pre-commit checks; S1 and S2 are opt-in.
  • MCP server + Launchpad (mcp_server/). Schema-driven workflow renderer for agents plus a browser recipe UI for humans. Both surfaces consume the same parameterised YAML recipe registry (mcp_server/recipes/registry.yaml). The MCP face exposes recipes to agents as schema-validated tool calls; the Launchpad face renders the same recipes as web forms. See the Chromap Launchpad section below.

ATAC-multiomic

  • ATAC fragment sidecar (AEV1 format, --atac-fragment-binary-output). Compact binary file emitted alongside BAM/CRAM plus fragments TSV: a 32-byte header followed by 24-byte fragment records keyed by the run's barcode length, with (size - 32) / 24 == record-count parity. Chromosome ids are paired with names in <sidecar>.chroms.tsv. The runtime spill harness decodes sidecar records back to full (chrom, start, end, barcode, count) tuples and compares them with the fragments TSV/BED baseline. Lets STAR Suite's libscrna empty-cells function call cells without re-parsing the gzipped fragments TSV. On the 3K PBMC headline run the sidecar contains 53,969,811 records (md5 a4251bbc…). See src/mapping_writer.h and docs/atac_runtime_spill_schema_runbook.md.
  • Opt-in mergeable ATAC spill (--create-mergeable-spill-record). Writes a versioned, pre-deduplication shard carrying mapped-record barcode payloads, input-level summary evidence, and a mergeable local whitelist histogram. Workers also publish a fixed-width, reference-partitioned ATACHOT1 companion for parallel BED correction/deduplication without reconstructing BAM-bearing records. The standalone chromap_atac_spill_materializer validates the exact shard ordinal/range set, performs global barcode correction, deduplication, and optional multimapping allocation, and writes the summary plus canonical fragments, AEV1, BAM, or CRAM. BED materialization, including translated-barcode dictionary assignment, remains binary through the merge and constructs text only in the parallel terminal exporter; --materialized-binary preserves the compact post-dedup blocks. BED/BAM gathering loads neither the genome nor mapping index; CRAM requires only its reference FASTA. See docs/mergeable_atac_spill.md.
  • Multiomic integration with STAR Suite. libchromap.a runs as a STAR Suite worker thread for concurrent ATAC + GEX processing in a single STAR invocation. STAR Suite's permit allocator partitions a shared thread budget across GEX mapping, feature processing, and ATAC mapping by observing per-domain drain rates and rebalancing toward simultaneous completion. End-to-end on 3K PBMC: 18:17 / 64.8 GB / 2.19× faster than Cell Ranger ARC v2.2.0. See STAR Suite for the integration entry point.
  • Native CBQ input (--input-format cbq, --read-pair-cbq, --barcode-cbq). Maps paired-end ATAC/scATAC reads straight from BINSEQ CBQ files with no intermediate FASTQ, producing fragments byte-identical (under canonical sort) to the FASTQ path. CBQ sequence decode writes directly into Chromap's SequenceBatch buffers, including Y/noY FASTQ sidecar emission. FASTQ remains the default. ATAC-only for this milestone; see the Native CBQ input (ATAC) sample command below.

Folder Structure

src/                  # Chromap Suite C++ sources and public libchromap header
libchromap.a          # Built static library
chromap               # Chromap Suite CLI
rapidmacs             # RapidMACS CLI copied from the vendored submodule
chromap_callpeaks     # Compatibility symlink to rapidmacs
third_party/
  htslib/             # Vendored htslib (BAM read/write/sort/index)
  rapidmacs/          # Vendored RapidMACS submodule (librapidmacs + CLI)
mcp_server/           # MCP server + Launchpad UI
  recipes/            # YAML recipe registry consumed by both MCP and Launchpad
  workflows/          # Workflow schemas
  launchpad/          # Browser UI (api.py + static assets)
tests/                # Regression matrix C01–C11, smoke harnesses
plans/                # Design notes and runbooks
docs/                 # User-facing docs (sort_spec, chromap_launchpad, ...)
scripts/              # Helper scripts (validators, launchpad runner, ...)

Modules

  • chromap (src/, bin/chromap) — the CLI binary covering bulk ATAC, scATAC, ChIP-seq, and Hi-C. Supports the standard ATAC, ChIP, scATAC, and Hi-C flag surfaces, plus the Chromap Suite additions above (BAM, sort, peak-call, sidecar, Y-filtering). Build: make.
  • libchromap (libchromap.a, src/libchromap.h) — the same code as a callable C++ library. The RunAtacMapping() entry point + ChromapAtacConfig + ChromapPermitHooks structs let a host process embed Chromap Suite's ATAC pipeline directly with shared thread coordination. Build: produced as a side effect of make.
  • RapidMACS / librapidmacs (third_party/rapidmacs/lib/librapidmacs.a) — vendored submodule providing a portable C++ implementation of MACS3's narrow peak-calling capability. The standalone rapidmacs CLI reads FRAG, BAMPE, BEDPE, or compatible BED inputs and emits narrowPeak plus summits. It also exposes opt-in MACS BED compatibility profiles, including --macs-profile signac-atac; Chromap/MorPHiC FRAG defaults remain unchanged. Build: make librapidmacs (or transitively via make). See the RapidMACS repo.
  • rapidmacs (rapidmacs) — canonical standalone peak-caller executable copied from the vendored submodule.
  • chromap_callpeaks (chromap_callpeaks) — compatibility symlink to rapidmacs, retained for existing Chromap Suite harnesses.
  • MCP server + Launchpad (mcp_server/) — agent automation service plus browser recipe UI. Initial recipes: chromap_index, chromap_atac_bed, chromap_atac_bam_fragments, chromap_hic_pairs. See mcp_server/README.md.

Benchmarks

Benchmarks below use public 10x PBMC 3K Multiome data unless noted. The STAR Suite headline run uses a 32-thread host (i9-13900KF, 126 GB RAM). The Chromap CLI parity benchmark uses 16 Chromap threads and 16 samtools threads, records /usr/bin/time -v for every step, and is intended to isolate the integrated Chromap Suite command from the established Chromap + samtools + MACS3 workflow.

Workflow Surface Baseline Result Note
Multiome (RNA + ATAC) Single STAR invocation: alignment + Solo + GEX EmptyDrops_CR + concurrent libchromap + librapidmacs narrow peaks + ATAC evidence-from-peaks (T=32, lease=256, pool=48) Cell Ranger ARC v2.2.0 (cellranger-arc count --create-bam=true --nosecondary --disable-cell-annotation --localcores=32); 40:04 / 79.07 GB peak RSS 18:17.52 / 64.80 GB; 2.19× faster, ~18% lower memory Apples-to-apples scope: alignment + GEX UMI counting + GEX EmptyDrops_CR + ATAC mapping + narrow peak calling + ATAC per-barcode cell call. ARC RSS read from cellranger's own _perf JSON (ARC forks 252 child processes at peak, so parent-process /usr/bin/time -v is misleading).
Narrow peaks vs MACS3 Same multiomic pipeline output MACS3 v3.0.3 standalone on the same input 50,274 peaks, byte-identical (md5 34f9f991…); summits also byte-identical (md5 b54a556…) The pipeline delivers the MACS3 narrow peaks downstream ATAC analyses already use; ARC produces 81,157 peaks via its own custom wide caller, which is not a parameterisation of MACS.
librapidmacs standalone Fragments TSV in → narrowPeak out MACS3 v3.0.3 single-threaded (721 s, 2.50 GB) 92 s / 2.77 GB at 1 thread (7.8×); 70 s at 4 threads (10.3×); 64 s at 24 threads (11.3×) All thread counts produce byte-identical narrowPeak. Memory parity at the practical 4-thread budget; sublinear scaling beyond 4 threads because the per-chromosome serial sweep dominates the remaining wall time.
ATAC fragment sidecar AEV1 binary, 32-byte header + 24-byte records + .chroms.tsv metadata gzipped fragments TSV re-parse 53,969,811 records, 1,295,275,496 B (md5 a4251bbc…) Consumed by libscrna::atac::RunAtacEvidenceFromBinary for ATAC cell calling; integration guard fires when atacAcquire=0 after --chromapAtacEnable 1 --dynamicThreadInterface 1.

The end-to-end multiomic comparison anchors on a fully public dataset for direct reproducibility.

Chromap CLI + librapidmacs parity benchmark

This benchmark compares the integrated Chromap Suite command against the established command-chain baseline:

# Baseline BAM path
chromap ... --SAM -o /dev/stdout | samtools view -b - | samtools sort -o possorted.bam -
samtools index possorted.bam

# Baseline peak path
chromap ... --BED -o fragments.tsv
macs3 callpeak -t fragments.tsv -f FRAG -g hs -p 1e-5 --min-length 200 --max-gap 30

# Integrated path
chromap ... --BAM --sort-bam --write-index \
  --atac-fragments fragments.tsv.gz \
  --call-macs3-frag-peaks \
  -o possorted.bam

Use --macs3-frag-qvalue 0.05 on the integrated path, or MACS3_QVALUE=0.05 in the benchmark scripts, when comparing against workflows that use MACS -q semantics.

The baseline uses unfixed upstream Chromap 0.3.3-r519 and standalone MACS3 v3.0.3. The integrated path uses Chromap Suite 0.3.3-r519. Both normal and --low-mem modes were run on the full 3K PBMC ATAC fixture with 16 threads.

Mode Integrated wall / RSS Full baseline wall / peak RSS Integrated speedup Fragment parity Peak parity
normal 7:34.23 / 101.1 GB 23:05.60 / 127.0 GB 3.05x faster; 67.2% less wall time 53,969,811 vs 53,969,811; exact sorted 5-col MD5 match 50,274 vs 50,274 peaks; BED3 Jaccard 1.0; all summit distances 0 bp
--low-mem 8:49.98 / 42.6 GB 22:39.71 / 24.2 GB 2.57x faster; 61.0% less wall time 53,969,811 vs 53,969,811; exact sorted 5-col MD5 match 50,274 vs 50,274 peaks; BED3 Jaccard 1.0; all summit distances 0 bp

The full baseline wall time includes Chromap SAM to sorted BAM, BAM indexing, Chromap FRAG output, and standalone MACS3 FRAG peak calling.

BAM record counts differ between the standalone SAM/samtools path and the integrated dual-fragment BAM path (108,066,582 baseline records vs 107,939,622 integrated records). This is reported as variation in non-biological read-level fields, especially read names and tie-selected duplicate representatives. Fragment coordinates, barcode, duplicate count, peak geometry, and summit positions are the parity gates, and they match exactly.

Reusable scripts and recorded outputs:

Building & Installing

Release packages

The release pipeline builds tarballs and Debian packages for Ubuntu 22.04 and 24.04 on amd64. Both formats include the command-line tools and static library SDK. Install a downloaded Debian package with sudo apt install ./<file>.deb, or extract a tarball and add its bin/ directory to PATH after installing its declared runtime dependencies. See the release procedure for package contents, compatibility checks, source bundles and local builds.

From source

# Initialise submodules (htslib + RapidMACS)
git submodule update --init --recursive

# Build chromap CLI + libchromap.a + rapidmacs (plus chromap_callpeaks compatibility symlink)
make

Requirements: GCC ≥ 7.3.0, GNU make, OpenMP, zlib, system libhts-dev, and the development libraries for libcurl, libcrypto, libbz2, liblzma and libdeflate. The Makefile uses vendored HTS headers and links against the system HTS library.

Compile-time switches:

# Address sanitizer
make asan=1

# Use the legacy single-threaded overflow path instead of the k-way merge default
make LEGACY_OVERFLOW=1

Validation

# Portable release gate: 16 targets with generated fixtures
# Requires Python 3, samtools, bgzip and GNU time in addition to build dependencies
make test-release

# Additional local qualification, including external 100K biological fixtures
make test-smoke

# Single-component validators (pre-spinoff correctness checks; still useful)
./scripts/validate_sam_fix.sh
./scripts/validate_low_mem_fix.sh
./scripts/test_overflow_basic.sh

Sample Commands

Index build

chromap -i -r ref.fa -o ref.index

To generate the optional binary reference representation together with the index:

chromap -i -r ref.fa -o ref.index \
  --reference-sidecar ref.chromapref -t 32

Mapping can then omit --ref and load the sidecar instead. CRAM output still requires --ref for HTSlib:

chromap --preset atac \
  -x ref.index --reference-sidecar ref.chromapref \
  -1 read1.fq.gz -2 read2.fq.gz -o aln.bed -t 32

Bulk ATAC (BED + inline narrow peaks, no barcode)

chromap --preset atac \
  -x ref.index -r ref.fa \
  -1 read1.fq.gz -2 read2.fq.gz \
  -o aln.bed \
  --call-macs3-frag-peaks \
  --macs3-frag-peaks-source memory

--macs3-frag-peaks-source memory is required for the bulk path because the file-source loader expects a 5-col fragments TSV (duplicate count in column 5), but bulk BED output puts MAPQ in column 5.

scATAC (BED + inline narrow peaks, barcoded)

chromap --preset atac \
  -x ref.index -r ref.fa \
  -1 read1.fq.gz -2 read2.fq.gz \
  -b barcode.fq.gz --barcode-whitelist whitelist.txt \
  -o aln.bed \
  --call-macs3-frag-peaks

scATAC (BAM dual + fragments TSV + sidecar + inline peaks)

chromap --preset atac \
  -x ref.index -r ref.fa \
  -1 read1.fq.gz -2 read2.fq.gz \
  -b barcode.fq.gz --barcode-whitelist whitelist.txt \
  --BAM --sort-bam --write-index \
  --atac-fragments fragments.tsv.gz \
  --atac-fragment-binary-output fragments.bin \
  --call-macs3-frag-peaks \
  -o aln.bam

Native CBQ input (ATAC)

Maps paired-end ATAC/scATAC directly from BINSEQ CBQ without writing intermediate FASTQ. The same options work with chromap_lib_runner.

chromap --preset atac \
  --input-format cbq \
  --read-pair-cbq lane1.reads.cbq,lane2.reads.cbq \
  --barcode-cbq lane1.barcode.cbq,lane2.barcode.cbq \
  --barcode-whitelist whitelist.txt \
  -x ref.index -r ref.fa \
  -o fragments.bed --BED

Rules: --input-format fastq is the default; --input-format cbq requires --read-pair-cbq; --barcode-cbq count must match --read-pair-cbq count; --barcode-whitelist requires --barcode-cbq; and FASTQ inputs (-1/-2/-b) cannot be mixed with CBQ. --emit-Y-noY-fastq is supported for CBQ inputs and writes FASTQ sidecars from the decoded sequence/quality buffers. The hermetic CBQ modality matrix covers ChIP, bulk paired, scATAC, Hi-C .pairs, BAM/CRAM writer output, --read-group auto, and Y/noY FASTQ parity.

Alignment contract: the read-pair and barcode CBQ lanes must be record-aligned — record i of each lane must be the same original read, in the same order. To make this verifiable, barcoded CBQ inputs must include read names (headers); both lanes are checked to carry headers at startup and read/barcode names are compared per record. Encode with an order-preserving encoder: encoders that reorder records across blocks under parallelism (e.g. bqtools at scale) break this alignment.

Full 3K PBMC ATAC timing on the 4-lane fixture, 8 threads, warmed cache, and BED output directed to /dev/null: FASTQ.gz took 3:04.47, uncompressed CBQ took 2:52.27, with identical read/mapping/output counts (53,969,811 output mappings). The manifest is under plans/artifacts/cbq_atac_full_timing/20260531T081906Z/.

FASTQ intake (gzip and BGZF)

No option is needed: with the default --input-bgzf-mode auto, a paired-end lane uses the BGZF reader when every one of its files (-1, -2 and -b) is a regular BGZF FASTQ file whose first records pair, and zlib otherwise. The barcode abundance pass reads a BGZF barcode file the same way. The stderr log names the reader chosen for each lane and the loader time.

# Require the BGZF reader (fails if a file does not qualify) and set the
# inflate threads for each lane, split across its files.
chromap --preset atac -t 32 -x ref.index -r ref.fa \
  -1 R1.fastq.gz -2 R3.fastq.gz -b R2.fastq.gz --read-format bc:8:23:- \
  --barcode-whitelist whitelist.txt -o fragments.tsv \
  --input-bgzf-mode on --input-bgzf-reader-threads 24
  • auto (default): BGZF reader when every file of the lane qualifies, otherwise zlib. FIFOs and other non-regular files always use zlib.
  • on: BGZF reader required; a file that is not regular BGZF FASTQ is an error. off: always zlib.
  • --input-bgzf-reader-threads 0 (default) derives the inflate workers from --num-threads (num_threads - files, at least one per file from three threads up); a positive value is the total for the lane.
  • The BGZF reader keeps STAR Suite's limits: four-line FASTQ records, header lines up to 512 characters and sequences up to 650 bases. auto checks the first record of each file; off reads anything kseq reads.
  • Records of a BGZF lane must pair: the same ordinal and read-name stem (a trailing /1, /2 or /3 removed) in every file. The zlib path pairs records by position only.
  • Library hosts set MappingParameters::input_bgzf_mode (FastqBgzfMode::kAuto|kOn|kOff) and input_bgzf_reader_threads.
  • Single-end mapping reads with zlib in every mode.

ChIP-seq

chromap --preset chip \
  -x ref.index -r ref.fa \
  -1 read1.fq.gz -2 read2.fq.gz \
  -o aln.bed

Hi-C (pairs format)

chromap --preset hic \
  -x ref.index -r ref.fa \
  -1 read1.fa -2 read2.fa \
  -o aln.pairs

Multiomic (RNA + ATAC) via STAR Suite

The multiomic integration is invoked through STAR Suite (libchromap is embedded as a worker thread). See the STAR Suite README — Multiome ATAC row for the full command.

Coordinate-sorted BAM standalone

chromap --BAM --sort-bam --write-index \
  -x ref.index -r ref.fa \
  -1 reads.fq -o output.bam

# Cap sort RAM
chromap --BAM --sort-bam --sort-bam-ram 512M \
  -x ref.index -r ref.fa -1 reads.fq -o output.bam

# Deterministic single-thread output across runs
chromap --BAM --sort-bam -t 1 --hts-threads 1 \
  -x ref.index -r ref.fa -1 reads.fq -o output.bam

--write-index requires --sort-bam. Without coordinate sorting, htslib on-the-fly indexing produces invalid/empty index files because records are written in non-deterministic order from multithreaded mapping. See docs/sort_spec.md.

Y-chromosome filtering

chromap --BAM --sort-bam --write-index \
  --emit-Y-bam --emit-noY-bam \
  -x ref.index -r ref.fa -1 reads_R1.fq -2 reads_R2.fq -o output.bam

Produces:

File Contents
output.bam All reads, coordinate-sorted
output.bam.bai Index for main BAM
output.noY.bam Non-Y reads only, coordinate-sorted
output.Y.bam Y-chromosome reads only, coordinate-sorted

Y-chromosome detection is case-insensitive and matches: Y, chrY, CHR_Y, chr_y. Decoy/random/alt contigs (chrY_random, Y_alt, chrY_hap1) are intentionally excluded.

To emit a normalised list of read names that hit Y, plus split FASTQ output:

chromap --SAM --emit-Y-read-names --emit-Y-noY-fastq \
  --emit-Y-noY-fastq-compression none \
  -x ref.index -r ref.fa -1 reads_R1.fq -2 reads_R2.fq -o output.sam

Read-name list: <output>.Y.names.txt by default, normalised (strip leading @, stop at first whitespace, strip trailing /1 or /2); no ordering guarantees.

FASTQ split naming:

  • Auto-named FASTQ sidecars are written under y_separated/ next to the primary output path, matching STAR Suite's Y-removal layout. Override this with --Y-noY-fastq-output-dir.
  • Inserts _Y / _noY before the last _R[0-9]+ token if present (e.g., sample_R1.fastq.gz → sample_Y_R1.fastq.gz).
  • Falls back to Y_reads.mateN.<ext>(.gz) / noY_reads.mateN.<ext>(.gz) otherwise.
  • Compression: gz (default) or none.
  • Paired-end routing: if either mate hits Y, both mates go to Y outputs.

Related flags: --emit-Y-read-names, --Y-read-names-output, --emit-Y-noY-fastq, --emit-Y-noY-fastq-compression {gz|none}, --Y-noY-fastq-output-dir, --Y-fastq-output-prefix, --noY-fastq-output-prefix.

Chromap Launchpad (Recipe Builder)

Browser-based recipe builder served from the Chromap Suite MCP server. Pick a workflow, fill in parameters through a guided form, and get a validated, copy-pasteable shell command. The same recipes are exposed as MCP tool calls for agents.

Quick start

# Install dependencies (once)
pip install -r mcp_server/requirements.txt

# Start Launchpad + MCP on one port
bash scripts/launchpad_server.sh up

# Open in your browser
# http://127.0.0.1:8765/launchpad/

MCP endpoints

When the server is running on port 8765:

  • http://127.0.0.1:8765/launchpad/ — Launchpad UI
  • http://127.0.0.1:8765/ — MCP streamable-HTTP endpoint
  • http://127.0.0.1:8765/sse — MCP SSE endpoint

MCP client setup

VS Code / GitHub Copilot

.vscode/mcp.json:

{
  "servers": {
    "chromapSuite": {
      "type": "http",
      "url": "http://127.0.0.1:8765/"
    }
  }
}

Cursor

{
  "mcpServers": {
    "chromap-suite": {
      "url": "http://127.0.0.1:8765/sse"
    }
  }
}

Claude

claude mcp add --transport http chromap-suite http://127.0.0.1:8765/

Initial public recipes: chromap_index, chromap_atac_bed, chromap_atac_bam_fragments, chromap_hic_pairs. See docs/chromap_launchpad.md and mcp_server/README.md.

More Detail

Citing

If you use Chromap Suite, please cite the preprint above plus the Chromap and MACS3 papers it builds on:

Zhang, H., Song, L., Wang, X., Cheng, H., Wang, C., Meyer, C. A., …, Liu, X. S., Li, H. (2021). Fast alignment and preprocessing of chromatin profiles with Chromap. Nature Communications, 12(1), 1-6. https://doi.org/10.1038/s41467-021-26865-w

Zhang, Y., Liu, T., Meyer, C. A., Eeckhoute, J., Johnson, D. S., Bernstein, B. E., Nusbaum, C., Myers, R. M., Brown, M., Li, W., Liu, X. S. (2008). Model-based Analysis of ChIP-Seq (MACS). Genome Biology, 9, R137. https://doi.org/10.1186/gb-2008-9-9-r137

The Chromap QC summary file format (carried forward unchanged in Chromap Suite) is described in:

Ahmed, O., Zhang, H., Langmead, B., Song, L. (2025). Quality control of single-cell ATAC-seq data without peak calling using Chromap. bioRxiv. https://doi.org/10.1101/2025.07.15.664951

Authors

Chromap Suite extensions copyright Ling-Hong Hung. Preprint co-authors: Ling-Hong Hung, Ka Yee Yeung. The GitHub Contributors graph reflects inherited git history from the pre-spinoff fork; see AUTHORS.md for current authorship and acknowledgments, and HISTORY.md for project lineage.

Licence

  • libchromap and the chromap CLI: MIT (see LICENSE).
  • librapidmacs: MIT — RapidMACS is an independent clean-room implementation validated against MACS3; see the RapidMACS repo for the methodology and third-party notices.
  • MCP server + Launchpad (mcp_server/): MIT.

About

Open-source chromatin-accessibility platform: Chromap + libMACS3 (byte-identical narrow peaks) + libchromap callable library + MCP server. Composes with STAR Suite for end-to-end multiomic (RNA + ATAC) single-binary processing.

github.com/morphic-bio/chromap_suite_paper

Resources

Readme
MIT license
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages