A minimalist yet versatile workflow to process ChIP-seq (with or without
input/spikein), RNA-seq, MNase-seq, ATAC-seq, Hi-C and shotgun sequencing data.
Hi-C mode delegates to hicstuff and
cooler.
tinyMapper supports both paired-end and single-end reads. Hi-C mode requires paired-end data. Spikein calibration (ChIP) also requires paired-end. For single-end MNase, fragment-size filtering is skipped and only a standard CPM track is produced.
Note: tinyMapper is a Python package that orchestrates external CLI tools (bowtie2, STAR, samtools, deeptools, macs3, hicstuff). It does not re-implement alignment or peak-calling.
DISCLAIMER:
- This is by no means the "best" or "only" way to process sequencing data. Feedback and suggestions are welcome.
- This workflow does NOT include QC / validation. Run
fastqcon raw reads at a minimum.
tinyMapper is a Python package. The recommended install creates a micromamba environment that bundles the Python package together with all bioinformatics tools (bowtie2, STAR, samtools, deeptools, macs3, hicstuff, cooler, bedtools).
Requires micromamba.
micromamba env create -n tinymapper -f https://raw.githubusercontent.com/js2264/tinyMapper/refs/heads/master/env/conda-lock.yml -y
micromamba activate tinymapper
tinymapper --helpIf all bioinformatics tools are already available in your environment:
uv venv
uv pip install git+https://github.com/js2264/tinyMapper.git
tinymapper --helpAfter activating the environment, there are two equivalent ways to call tinyMapper:
| Command | Description |
|---|---|
tinymapper --mode ChIP ... |
Primary Python CLI (recommended) |
tinyMapper.sh --mode ChIP ... |
Legacy bash wrapper — forwards all arguments verbatim to tinymapper |
Both accept exactly the same flags. tinyMapper.sh is kept for compatibility
with existing Slurm scripts and autotinymapper.
Usage: tinymapper [OPTIONS]
tinyMapper — map and process sequencing reads.
Modes:
ChIP — ChIP-seq (bowtie2 → samtools → bamCoverage → macs3)
RNA — RNA-seq (STAR → samtools → bamCoverage × 3)
ATAC — ATAC-seq (bowtie2 → samtools → bamCoverage → macs3)
MNase — MNase-seq (bowtie2 → samtools → size filter → 3 tracks)
HiC — Hi-C (hicstuff pipeline → cooler → mcool)
shotgun — Shotgun (bowtie2 single-end → samtools → bamCoverage)
Examples:
tinymapper -m ChIP -s ~/HB44 -g ~/genomes/R64-1-1/R64-1-1 -o ~/results
tinymapper -m RNA -s ~/AB4 -g ~/genomes/W303/W303 -o ~/results
tinymapper -m HiC -s ~/CH266 -g ~/genomes/W303/W303 --binning 1000
╭─ Required ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ * --mode -m [chip|rna|atac|mnase|hic|shotgun] Mapping mode (ChIP, MNase, ATAC, RNA, HiC, shotgun). [required] │
│ * --sample -s TEXT Path prefix to sample FASTQ files. For ~/reads/JS001_R{1,2}.fq.gz use --sample ~/reads/JS001 [required] │
│ * --genome -g TEXT Path prefix to reference genome. For ~/genome/W303/W303.fa use --genome ~/genome/W303/W303 [required] │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Core optional ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --output -o PATH Directory to store results. [default: results] │
│ --input -i TEXT (ChIP) Path prefix to input/control sample. │
│ --calibration -c TEXT (ChIP) Path prefix to spikein/calibration genome. │
│ --threads -t INTEGER Number of CPU threads. [default: 8] │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Alignment / filtering ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --alignment -a TEXT Extra options passed to bowtie2 (use single quotes). [default: --maxins 1000] │
│ --filter -f TEXT Filtering options for samtools view (use single quotes). [default: -f 0x001 -f 0x002 -F 0x004 -F 0x008 -q 10] │
│ --blacklist -bl TEXT BED file of blacklist regions for bamCoverage. │
│ --gsize -gs TEXT Effective genome size for macs3 peak calling. [default: 13000000] │
│ --duplicates -d Keep duplicate reads (default: remove duplicates). │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ HiC ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --hicstuff -hic TEXT Extra arguments passed to hicstuff pipeline. [default: --mapping iterative --duplicates --filter --plot --no-cleanup] │
│ --restriction -re TEXT Restriction enzyme(s) for HiC (e.g. DpnII,HinfI). [default: HpaII,HinfI] │
│ --binning -b TEXT Minimum bin resolution for HiC matrix (bp); comma-separated for multi-res. [default: 500] │
│ --balance -ba TEXT Balancing options for cooler zoomify. [default: --cis-only --min-nnz 3 --mad-max 7] │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ MNase ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --MNaseSizes -M TEXT Min,Max fragment size for MNase track. [default: 130,200] │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Output ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --keepIntermediate -k Keep intermediate SAM / unmapped FASTQ files. │
│ --dry-run Log commands without executing them. │
│ --help -h Show this message and exit. │
│ --version -v Show the version and exit. │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
FASTQ files are detected automatically from the sample prefix. tinyMapper tries paired-end patterns first, then falls back to single-end:
Paired-end patterns (both R1 and R2 must exist):
<SAMPLE>_R1.fq.gz/<SAMPLE>_R2.fq.gz(preferred)<SAMPLE>_R1.fastq.gz/<SAMPLE>_R2.fastq.gz<SAMPLE>_nxq_R1.fq.gz/<SAMPLE>_nxq_R2.fq.gz<SAMPLE>.end1.fq.gz/<SAMPLE>.end2.fq.gz<SAMPLE>.end1.gz/<SAMPLE>.end2.gz- Illumina
<SAMPLE>_S##_R1_*.gz/<SAMPLE>_S##_R2_*.gz
Single-end fallback (R2 not found — only R1 required):
<SAMPLE>_R1.fq.gz<SAMPLE>_R1.fastq.gz<SAMPLE>_nxq_R1.fq.gz<SAMPLE>.fq.gz<SAMPLE>.fastq.gz
| Mode | SE support | Notes |
|---|---|---|
| ChIP | Yes | input control supported; spikein calibration requires PE |
| RNA | Yes | forward/reverse strand tracks still produced |
| ATAC | Yes | peaks called with --format BAM instead of BAMPE |
| MNase | Yes | fragment-size filter and nucleosome tracks skipped; CPM track only |
| shotgun | Yes | always single-end (R1+R2 concatenated as -U if both present) |
| HiC | No | paired-end required |
# Sample only (no input, no calibration)
tinymapper -m ChIP \
-s ~/reads/JS001 \
-g ~/genomes/R64-1-1/R64-1-1 \
-o ~/results
# With input control
tinymapper -m ChIP \
--sample ~/reads/JS001_IP \
--input ~/reads/JS001_input \
--genome ~/genomes/R64-1-1/R64-1-1 \
--output ~/results
# With input and spikein calibration
tinymapper -m ChIP \
--sample ~/reads/JS001_IP \
--input ~/reads/JS001_input \
--genome ~/genomes/R64-1-1/R64-1-1 \
--calibration ~/genomes/Cglabrata/Cglabrata \
--output ~/resultstinymapper -m RNA -s ~/reads/JS001 -g ~/genomes/W303/W303 -o ~/resultstinymapper -m MNase -s ~/reads/JS001 -g ~/genomes/W303/W303 -o ~/results \
--MNaseSizes 70,250tinymapper -m ATAC -s ~/reads/JS001 -g ~/genomes/W303/W303 -o ~/resultstinymapper -m HiC \
-s ~/reads/JS001 \
-g ~/genomes/W303/W303 \
-o ~/results \
--binning 1000,2000,8000 \
--restriction 'DpnII,HinfI'tinymapper -m shotgun -s ~/reads/JS001 -g ~/genomes/W303/W303 -o ~/resultsResults are written under --output with the following structure:
<output>/
bam/genome/ filtered BAM files (genome)
bam/spikein/ filtered BAM files (spikein, ChIP only)
tracks/ BigWig coverage tracks (CPM, calibrated, fwd/rev for RNA)
peaks/ MACS3 peak files (ChIP, ATAC)
pairs/ contact pairs (Hi-C only)
matrices/ .cool matrices (Hi-C only)
logs/ per-run log and command files
tmp/ temporary files (removed on success unless --keepIntermediate)
Files follow the naming convention <sample>^<operation>^<hash>.<ext> where
<hash> is a 6-character alphanumeric string unique to each run.
Activate the environment and submit with sbatch:
micromamba activate tinymapper
# Generic
sbatch --mem 40G -c 10 --wrap \
"tinymapper --mode ChIP --sample <SAMPLE> --genome <GENOME> --output <OUTPUT> --threads 8"
# ChIP examples
sbatch --mem 40G -c 10 --wrap \
"tinymapper -m ChIP -s ~/reads/JS001_IP -g ~/genomes/S288c/S288c --threads 8"
sbatch --mem 40G -c 10 --wrap \
"tinymapper -m ChIP -s ~/reads/JS001_IP -i ~/reads/JS001_input -g ~/genomes/S288c/S288c --threads 8"
# RNA
sbatch --mem 40G -c 10 --wrap \
"tinymapper -m RNA -s ~/reads/JS001 -g ~/genomes/S288c/S288c --threads 8"
# Hi-C
sbatch --mem 40G -c 10 --wrap \
"tinymapper -m HiC -s ~/reads/JS001 -g ~/genomes/S288c/S288c --threads 8"tinyMapper.sh can be used as a drop-in replacement for the legacy command
surface (e.g. from autotinymapper Slurm scripts):
sbatch --mem 40G -c 10 --wrap \
"tinyMapper.sh -m ChIP -s ~/reads/JS001_IP -g ~/genomes/S288c/S288c --threads 8"- Regenerate
uv.lockandenv.lockafter any dependency changes.
uv lock
uv run \
conda-lock lock \
--update \
--micromamba \
--file env/tinymapper.yaml \
--platform linux-64 \
--lockfile env/conda-lock.yml
conda-lock install --name <ENV_NAME> env/conda-lock.yml- A. Cournac, A. Bignaud & F. Girard for tests.
- H. Bordelet for sharing her mapping scripts and configuration.
- L. Meneu for suggestions of improvements in documentation and raising bugs.