git:20260920.bc6cada to git:20260920.ce7840d

- description: "Execute ENCODE ATAC-seq processing pipeline from FASTQ to peaks and signal tracks. Child of pipeline-guide. Provides stage-by-stage Nextflow execution with Docker containers and cloud deployment. Handles Tn5 transposase offset correction, mitochondrial read removal, nucleosome-free fragment selection, and TSS enrichment scoring. Use when users need to process ATAC-seq data following ENCODE standards. Trigger on: ATAC-seq pipeline, run ATAC-seq, process ATAC-seq, chromatin accessibility, open chromatin, Tn5 shift, TSS enrichment."

- a complete Nextflow DSL2 implementation following ENCODE uniform analysis standards.

- transposase to probe open chromatin regions. The ENCODE pipeline processes ATAC-seq data

- through quality control, alignment with Bowtie2, Tn5 insertion site correction (+4/-5 bp

- offset), mitochondrial read removal, nucleosome-free fragment selection, peak calling

- with MACS2, and IDR-based replicate consistency analysis.

- transposase shift correction, aggressive mitochondrial read filtering (can be 30-80%

- of reads), nucleosomal fragment size distribution as a QC metric, and TSS enrichment

- score as the primary quality indicator.

- FASTQ ──> FastQC / Trim Galore ──> Bowtie2 ──> Mito Removal + Tn5 Shift

- │ │

- │ ┌──────────────────────────────────────────┘

- │ Picard MarkDup ──> Blacklist Filter ──> Size Selection

- │ │

- │ ┌─────────────────┬────────────┘

- │ v v

- │ NFR Fragments Mono-Nucleosome

- │ │

- │ v

- │ MACS2 Peak Calling ──> IDR Analysis

- │ │ │

- │ v v

- │ Signal Tracks QC Report (MultiQC + ataqv)

- Raw QC Report

- | 1. QC & Trimming | FastQC, Trim Galore | Raw FASTQ | Trimmed FASTQ | references/01-qc-trimming.md |

- | 2. Alignment | Bowtie2 | Trimmed FASTQ | Sorted BAM | references/02-alignment.md |

- | 3. Tn5 Shift & Filtering | Samtools, bedtools, Picard | Sorted BAM | Shifted, filtered BAM | references/03-tn5-filtering.md |

- | 4. Peak Calling & IDR | MACS2, IDR | Filtered BAM | Peaks (narrowPeak) | references/04-peak-calling.md |

- | 5. QC & Signal | deeptools, ataqv, MultiQC | Filtered BAM, Peaks | bigWig, QC report | references/05-qc-metrics.md |

- ### Required Files

- - **ATAC-seq FASTQ**: Paired-end reads (required: Tn5 shifting, nucleosome-free selection, and BAMPE peak calling depend on fragment length)

- - **Reference genome**: Bowtie2-indexed genome (GRCh38 for human, mm10 for mouse)

- ### Sample Sheet Format

- ```csv

- sample_id,read1,read2,replicate

- SAMPLE1_rep1,atac_R1.fq.gz,atac_R2.fq.gz,1

- SAMPLE1_rep2,atac_R1.fq.gz,atac_R2.fq.gz,2

- **No input control needed**: Unlike ChIP-seq, ATAC-seq does not require a separate

- input or IgG control. MACS2 calls peaks against a local background model.

- This correction is essential for accurate footprinting and motif analysis.

- For peak calling, use **nucleosome-free reads (<150 bp)** only.

- | Metric | Threshold | Category | Source |

- |--------|-----------|----------|--------|

- | Total sequenced reads | >=50M (recommended) | Read depth | ENCODE |

- | Mapping rate | >80% | Alignment | ENCODE |

- | Mitochondrial fraction | <20% (ideal <5%) | Sample quality | ENCODE |

- | NRF (non-redundant fraction) | >=0.8 | Library complexity | ENCODE |

- | PBC1 | >=0.8 | Library complexity | ENCODE |

- | TSS enrichment score | >=5 | Signal quality | ENCODE standard |

- | FRiP | >=0.3 | Peak quality | ENCODE |

- | NFR fraction | >0.4 of fragments <150bp | Fragment distribution | Buenrostro 2013 |

- | IDR optimal peaks | >50,000 | Reproducibility | ENCODE |

- ### TSS Enrichment Score

- informative QC metric for ATAC-seq:

- ### Google Cloud

- ```bash

- nextflow run scripts/main.nf \

- -profile gcp \

- --reads 'gs://bucket/fastq/*_R{1,2}.fq.gz' \

- --genome GRCh38 \

- --outdir 'gs://bucket/results/'

- ```

- ### AWS Batch

- nextflow run scripts/main.nf \

- -profile aws \

- --reads 's3://bucket/fastq/*_R{1,2}.fq.gz' \

- --genome GRCh38 \

- --outdir 's3://bucket/results/'

- | GCP | n1-standard-8 | ~$2-4 | 2-3 hours | Preemptible recommended |

- | SLURM | 8 cores, 32GB | Varies | 2-3 hours | Singularity recommended |

- fastqc/ # Raw and trimmed QC reports

- trimmed/ # Trimmed FASTQ files

- aligned/ # Sorted BAM files (pre-filtering)

- filtered/

- shifted/ # Tn5-corrected BAM files

- nfr/ # Nucleosome-free fragments (<150 bp)

- mononuc/ # Mono-nucleosome fragments (150-300 bp)

- narrow/ # MACS2 narrowPeak files

- idr/ # IDR-filtered reproducible peaks

- signal/ # bigWig signal tracks

- tss_enrichment/ # TSS enrichment scores and plots

- fragment_size/ # Fragment size distribution plots

- ataqv/ # Comprehensive ATAC-seq QC (ataqv)

- multiqc/ # Aggregated QC report

- logs/ # Nextflow execution logs

- of reads. This is the most common ATAC-seq quality issue. Filter chrM reads before

- analysis. If >50% mito, consider optimizing the cell lysis step.

- ### 2. Missing Tn5 Shift Correction

- Without the +4/-5 bp offset correction, cut-site positions are shifted by ~4.5 bp.

- This matters for footprinting and motif analysis but has minimal effect on peak calling.

- Always apply the shift for publication-quality results.

- than BWA-MEM. Use Bowtie2 with `--very-sensitive` for optimal ATAC-seq alignment.

- ### 4. Not Separating Nucleosomal Fractions

- Peak calling on all fragments mixes nucleosome-free signal (TF binding) with

- nucleosomal signal. Always size-select NFR (<150 bp) for peak calling.

- ### 5. Ignoring TSS Enrichment

- TSS enrichment is the most informative single metric for ATAC-seq quality.

- A score <5 indicates a failed experiment regardless of other metrics.

- | File | Description | Lines |

- |------|-------------|-------|

- | `scripts/main.nf` | Nextflow DSL2 pipeline | ~120 |

- | `scripts/nextflow.config` | Execution profiles (local/slurm/gcp/aws) | ~60 |

- | `scripts/Dockerfile` | Multi-stage Docker build with all tools | ~30 |

- - **Tn5 shift is critical**: ATAC-seq reads must be shifted +4/-5 bp to center on the Tn5 insertion site. Without this correction, footprinting analysis will be offset by ~5 bp and motif enrichment will be degraded.

- - **Mitochondrial reads dominate**: Expect 30-80% mitochondrial reads in ATAC-seq. Filter chrM reads AFTER alignment, BEFORE peak calling. High mitoChRM (>80%) indicates dead/dying cells or poor nuclei isolation.

- - **Fragment size distribution is diagnostic**: A nucleosomal ladder (sub-nucleosomal <150bp, mono-nucleosomal ~200bp, di-nucleosomal ~400bp) confirms successful transposition. Absence of the ladder suggests incomplete or failed transposition.

- - **TSS enrichment threshold**: ENCODE requires TSS enrichment ≥5 (GRCh38), ≥6 (hg19), or ≥10 (mm10) for ATAC-seq (ENCODE data standards). Values below 4 indicate poor signal-to-noise. This is the single most informative QC metric for ATAC-seq.

- - **Peak caller choice matters**: MACS2 with `--nomodel --shift -100 --extsize 200` is standard for ATAC-seq. Do NOT use the ChIP-seq default MACS2 settings — they assume sonicated fragment distributions.

- - **Paired-end vs single-end**: ATAC-seq should always be paired-end to capture fragment sizes. Single-end ATAC-seq cannot distinguish nucleosome-free from nucleosomal fragments.

- **Goal**: Process raw ATAC-seq FASTQ files through the ENCODE pipeline to generate nucleosome-free region peaks and signal tracks for chromatin accessibility analysis.

- **Context**: ATAC-seq requires Tn5 transposase insertion site correction (+4/-5 bp shift) and nucleosomal fragment size filtering, handled by the ENCODE ATAC-seq pipeline.

- encode_list_files(accession="ENCSR637ENO", file_format="fastq")

- {"accession": "ENCFF101ATQ", "output_type": "reads", "paired_end": "2", "biological_replicates": [1], "file_size_mb": 1900}

- ### Step 3: Run the ATAC-seq pipeline

- nextflow run pipeline-atacseq/main.nf \

- --fastq_r1 ENCFF100ATQ.fastq.gz \

- --fastq_r2 ENCFF101ATQ.fastq.gz \

- --blacklist encode_blacklist_v2.bed \

- --mitochondrial_chr chrM \

- -profile docker

- Key pipeline steps:

- 1. Adapter trimming (Trimmomatic/cutadapt)

- 2. Alignment (Bowtie2, very-sensitive mode)

- 3. Tn5 shift correction (+4/-5 bp)

- 4. Mitochondrial read removal

- 5. Nucleosome-free fragment selection (<150 bp)

- 6. Peak calling (MACS2, --nomodel --shift -75 --extsize 150)

- ### Step 4: Validate output quality

- | Metric | Threshold | Purpose |

- |---|---|---|

- | TSS enrichment | >= 5 (GRCh38), >= 6 (hg19), >= 10 (mm10) | Signal enrichment at transcription start sites |

- | Fragment size distribution | Nucleosomal ladder | ~200bp, ~400bp, ~600bp periodicity |

- | Mitochondrial reads | < 20% | Excessive = failed library |

- | FRiP | >= 0.2 | Fraction of reads in peaks |

- ### Step 5: Track and log provenance

- encode_track_experiment(accession="ENCSR637ENO", notes="GM12878 ATAC-seq processed through ENCODE pipeline")

- accession="ENCSR789PAN",

- | TSS enrichment scores | **quality-assessment** | Validate against ENCODE ATAC-seq standards |

- | Pipeline parameters | **data-provenance** | Record Tn5 shift, fragment filters, tool versions |

- - **TSS enrichment score**: Report the TSS enrichment score prominently -- this is the single most informative ATAC-seq QC metric. Include the quality tier (Excellent >=7, Good 5-7, Marginal 3-5, Poor <3)

- - **Fragment size distribution**: Report NFR fraction (% fragments <150 bp) and confirm the characteristic nucleosomal ladder pattern (NFR, mono-, di-, tri-nucleosome peaks)

- - **Peak counts**: Report IDR optimal peak count and total MACS2 peaks before IDR filtering

- - **NFR/mono-nucleosome ratio**: Present the ratio of nucleosome-free to mono-nucleosomal fragments as a library quality indicator

- - **Mitochondrial fraction**: Report % mitochondrial reads removed (ideal <5%, acceptable <20%)

- - **Key QC metrics**: Present mapping rate, FRiP (>=0.3 for ATAC-seq), NRF, and duplication rate in a summary table

- - **Output paths**: List key outputs (peaks/idr/, signal/, qc/tss_enrichment/, qc/fragment_size/)

- - **Next steps**: Suggest `motif-analysis` for TF footprinting and de novo motif discovery, or `visualization-workflow` for genome browser session generation