Reusable bulk ATAC-seq tutorial¶

Each numbered chapter has Previous, Tutorial contents, and Next links at both the top and bottom, so you can read the tutorial in order without returning to this page between chapters.

This tutorial translates the internship workflow into a reviewable sequence for new bulk, paired-end ATAC-seq studies. It teaches the analytical logic and validation gates; it is not a promise that one fixed command set is correct for every organism, library preparation, or experimental design.

How to use the command blocks¶

The practical chapters include copy-and-adapt commands for one sample or one analysis stage. They target a Bash terminal on GNU/Linux, a managed Linux HPC system, or Windows Subsystem for Linux (WSL), and assume that the reader is standing in the project root. Bioconda also supports macOS, but macOS readers may need to adapt GNU system utilities such as sha256sum and zcat. Values such as CHANGE_ME, adapter sequences, reference paths, group names, and thresholds must be replaced before execution.

The commands are intentionally manual: complete one stage, inspect its outputs, and pass its validation gate before copying the next block. Do not paste the whole tutorial as one unattended script. Commands for a single example sample must be repeated deliberately for every sample in the metadata table. If an example output path already exists, preserve it and change the new run to an attempt-specific path instead of overwriting it.

Before using real sequencing files, run the dependency-free synthetic count-matrix smoke test. It gives a quick known-output check of metadata ordering and low-count filtering. Then review the resource-planning companion for rough time, memory, and disk expectations.

Scope¶

The guide assumes biological replicates, paired-end reads, a suitable reference genome, and a comparison that can be represented in a bulk count-based model. It does not cover single-cell ATAC-seq, multiome assays, allele-specific accessibility, or clinical-grade processing.

Workflow map¶

flowchart TD
    A[Define question and metadata] --> B[Verify reads and reference resources]
    B --> C[Raw-read QC]
    C --> D{Adapters or poor-quality tails?}
    D -- Yes --> E[Paired-end trimming]
    D -- No --> F[Alignment]
    E --> F
    F --> G[Pair-aware filtering and duplicate handling]
    G --> H[Blacklist filtering and alignment QC]
    H --> I[Peak calling per sample]
    I --> J[Consensus region universe]
    J --> K[Paired-fragment counting]
    K --> L[Metadata and design validation]
    L --> M[Differential accessibility]
    M --> N[QC, multiple testing, and effect-size review]
    N --> O{FDR-significant regions?}
    O -- Yes --> P[Annotation and enrichment with tested background]
    O -- No --> Q[Report the zero-FDR result]
    Q --> R[Optional, explicitly nominal exploration]
    P --> S[Interpretation and reproducible report]
    R --> S

Inputs, outputs, and gates at a glance¶

Stage	Starting input	Principal output	Continue only when
Metadata	Study design and file inventory	Ordered sample registry and declared contrast	identities, mates, replication, and model are coherent
Read QC	Paired FASTQ files	FastQC reports and focused MultiQC summary	file counts and important warnings are reviewed
Trimming	Raw paired FASTQ files	Paired trimmed FASTQ files	mate counts agree and post-trim QC is acceptable
Alignment	Validated reads and reference index	Alignment file and mapping log	reference identity and mapping summaries pass review
BAM processing	Alignments	Final coordinate-sorted BAM/BAI and QC metrics	structure, pairing, filters, and sample identity are valid
Peak calling	Final BAM for each sample	Per-sample peak sets	coordinates and cross-sample peak/QC patterns are plausible
Consensus/counting	Peak sets and final BAMs	Region-by-sample fragment-count matrix	features, count unit, matrix order, and assignment totals are valid
Differential analysis	Integer counts and ordered metadata	Effect estimates, adjusted p-values, diagnostics, and classification	design, contrast, thresholds, and output dimensions are validated
Downstream analysis	Declared target and tested background	Annotation or enrichment summaries	scope and language remain compatible with the primary evidence

Chapters¶

For a compact run plan, use QUICKSTART.md. Blank metadata and parameter files are provided in the config/templates/ guide.

Using the tutorial with an AI agent¶

The agent/ guide converts the chapter sequence into a machine-readable, human-supervised contract. It includes stage dependencies, approval gates, status vocabulary, schemas, configuration validation, and an example starting request. Agents must still stop for study-specific scientific decisions and may execute only an explicitly approved stage.

How this relates to the internship¶

The repository's main analysis is the worked example. Exact internship choices are recorded in config/analysis_parameters.yaml and docs/METHODS.md. Commands in the tutorial are patterns with placeholders. The scripts described in the workflow/ guide preserve case-study-specific validation and should be adapted deliberately for a new study rather than run unchanged.