alignment-level-QC

# Alignment Quality Control for ChIP-seq/ATAC-seq

## Overview

Perform comprehensive **preliminary alignment-level quality control** for ChIP-seq and ATAC-seq BAM files using **samtools**, **Picard**, and **MultiQC**.  

Main steps include:
- Initialize the project directory.
- Refer to the **Inputs & Outputs** section to check inputs and build the output architecture. All the output file should located in `${proj_dir}` in Step 0.
- Sort and add read groups if missing in the BAM file.
- Run preliminary QC metrics
- **Generate MultiQC report**  

---

## When to use this skill

- Use skill when you want to perform alignment-level quality control for ChIP-seq or ATAC-seq BAM files.

---

## Inputs & Outputs

### Inputs

<sample>.bam

### Outputs

```bash
alignment_qc/
  ${sample}.bam                        # Original input
  ${sample}.sorted.bam                 # (Optional) Created if sorting was needed
  ${sample}.RG.bam                     # (Optional) Created if RG was needed
  ${sample}.RG.bam.bai                 # Index file
  qc_results/
    ${sample}.flagstat.txt
    ${sample}.stats.txt
    ${sample}.insertsize_metrics.txt
    ${sample}.dup_metrics.txt
    alignment_qc_report.html      # Visual MultiQC report
    qc_summary.txt                # Pass/Warn/Fail table
  temp/
    ${sample}.markdup.bam            # Intermediate file (safe to delete later)
    ...
```
---

## Decision Tree

### Step 0: Initialize Project

Call:

- `mcp__project-init-tools__project_init`

with:

- `sample`: all
- `task`: alignment_qc

The tool will:

- Create `${sample}_alignment_qc` directory.
- Return the full path of the `${sample}_alignment_qc` directory, which will be used as `${proj_dir}`.

### Step 1: Check and Fix BAMs
- Ensure all BAM files are coordinate-sorted, have Read Groups, and are indexed.
*This tool will skip files that are already correct and only create temporary files when fixes are needed.*

Call: 

- mcp__qc-tools__check_and_fix_bams

with:
- `bam_files`: List of BAM files to process.
- `temp_dir`: ${proj_dir}/temp

### Step 2: Run Alignment QC Metrics

Call:

- mcp__qc-tools__run_bam_qc

with:
- `bam_files`: List of BAM files to process.
- `qc_dir`: ${proj_dir}/qc_results
- `temp_dir`: ${proj_dir}/temp

Step 3: Generate Summary Report

Call:

- mcp__qc-tools__generate_qc_report

with:
- `qc_dir`: ${proj_dir}/qc_results

---

## Quality Assessment

### Key QC Metrics

- **Total reads** – overall sequencing depth  
- **Mapped reads (%)** – alignment efficiency  
- **Properly paired (%)** – valid pair fraction (paired-end)  
- **Duplicate rate (%)** – PCR duplication estimate  
- **Mitochondrial reads (%)** – mitochondrial contamination  
- **Insert size distribution** – fragment length profile  

All metrics are derived from `samtools`/`Picard` and summarized by MultiQC.

---

### Quality Thresholds

| Category | Criteria | Interpretation |
|-----------|-----------|----------------|
| **Pass** | All metrics within recommended thresholds | Suitable for downstream analysis |
| **Warn** | One or more borderline metrics | Likely acceptable; review recommended |
| **Fail** | Critical metrics outside acceptable ranges | Re-sequencing or reprocessing suggested |

---

## Report Generation

After MultiQC completes, generate a sample-wise summary (PASS/WARN/FAIL) per thresholds in `references/qc_metrics.md` and save it as:

```
qc_results/qc_summary.txt
```

---

## Resources

Use `references/qc_metrics.md` for:
- Metric definitions and recommended thresholds  
- Troubleshooting guidance  
- Readiness criteria for peak calling  
- Pointers to ENCODE/nf-core QC standards