[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7EBK87B2APA57VZXP4EMSJR":3,"skill-same:01M7EBK87B2APA57VZXP4EMSJR":62},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":30,"commitSha":31,"skillDirectory":32,"forksCount":14,"repositoryHtmlUrl":33,"repositoryHomepageUrl":33,"ownerHtmlUrl":34,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":35,"install":36,"resources":49},"01M7EBK87B2APA57VZXP4EMSJR","bio-bam-statistics",null,"Generate alignment statistics using samtools flagstat, stats, depth, coverage, and mosdepth. Use when assessing alignment quality, calculating coverage, or generating QC reports.","Mr-Nobody-Anonymous\u002FAll-skills","Mr-Nobody-Anonymous","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F184253119?v=4","01M7AEXFJHKTYQW5R0ZCQQTWFV","anonymous","01M7C00M3GQR4QKP9GZA42GFAK",0,"MIT","https:\u002F\u002Fgithub.com\u002FMr-Nobody-Anonymous\u002FAll-skills\u002Fblob\u002Fmain\u002Fawesome_skills\u002Fbiology\u002Fbio-bam-statistics\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: bio-bam-statistics\ndescription: Generate alignment statistics using samtools flagstat, stats, depth, coverage, and mosdepth. Use when assessing alignment quality, calculating coverage, or generating QC reports.\ntool_type: cli\nprimary_tool: samtools\nsource: \"https:\u002F\u002Fgithub.com\u002FGPTomics\u002FbioSkills\"\nsource_repository: \"GPTomics\u002FbioSkills\"\nsource_path: \"alignment-files\u002Fbam-statistics\u002FSKILL.md\"\nlicense: \"MIT\"\nimported_at: \"2026-09-20\"\n---\n\n## Version Compatibility\n\nReference examples tested with: pysam 0.22+, samtools 1.19+\n\nBefore using code patterns, verify installed versions match. If versions differ:\n- Python: `pip show \u003Cpackage>` then `help(module.function)` to check signatures\n- CLI: `\u003Ctool> --version` then `\u003Ctool> --help` to confirm flags\n\nIf code throws ImportError, AttributeError, or TypeError, introspect the installed\npackage and adapt the example to match the actual API rather than retrying.\n\n# BAM Statistics\n\n**\"Get alignment statistics and coverage from my BAM file\"** -> Generate read counts, mapping rates, per-chromosome statistics, depth profiles, and coverage summaries.\n- CLI: `samtools flagstat`, `samtools stats`, `samtools depth`, `samtools coverage` (samtools)\n- Python: `pysam.AlignmentFile` with `pileup()` and `get_index_statistics()` (pysam)\n\nGenerate alignment statistics using samtools and pysam.\n\n## Quick Summary Commands\n\n| Question | Best tool | Why |\n|----------|-----------|-----|\n| Quick read counts by FLAG category | `samtools flagstat` | Fast; counts secondary+supp in totals |\n| Per-chromosome counts | `samtools idxstats` | Fast (needs index); **counts secondary+supp** |\n| Insert size, MAPQ, error, GC | `samtools stats -r ref.fa` | Comprehensive; feeds MultiQC |\n| Per-position depth (small region) | `samtools depth` or pysam pileup | Slow on full genome |\n| Per-position depth (genome-wide) | **`mosdepth`** | 3-10x faster than `samtools depth` |\n| Per-region coverage (BED) | `mosdepth --by regions.bed` | Production default |\n| Coverage histogram \u002F cumulative | `mosdepth -t 4 --no-per-base` | Single-pass histogram |\n| Breadth at depth thresholds | `mosdepth --thresholds 1,10,30,100` | Standard exome QC |\n| Targeted enrichment QC | `picard CollectHsMetrics` | PCT_OFF_BAIT, FOLD_80_BASE_PENALTY, AT\u002FGC dropout |\n| Cross-sample contamination | `verifybamid2`, `somalier` | FREEMIX \u003C 0.01 expected |\n\n### What Each Tool Counts (and Doesn't)\n\n| Counting category | flagstat | stats | idxstats |\n|-------------------|----------|-------|----------|\n| Primary alignments | `in total` minus supp | `raw total sequences` | mapped column |\n| Secondary | `secondary` line | filtered out | counted in mapped |\n| Supplementary | `supplementary` line | filtered out | counted in mapped |\n| Mapping rate denominator | total *including* supp | primary only | mapped+unmapped |\n\nFor long-read data where one read produces many supplementary alignments, the senior cross-check:\n```\ninput_read_count = flagstat_total - secondary - supplementary\n                 = stats_raw_total_sequences\n```\nReports of \"the file has 1.2M reads\" where the input was actually 800k with 400k supplementary chimeric splits trace to flagstat misinterpretation.\n\n## samtools flagstat\n\nFast summary of alignment flags.\n\n```bash\nsamtools flagstat input.bam\n```\n\nOutput:\n```\n10000000 + 0 in total (QC-passed reads + QC-failed reads)\n9950000 + 0 primary\n0 + 0 secondary\n50000 + 0 supplementary\n0 + 0 duplicates\n0 + 0 primary duplicates\n9800000 + 0 mapped (98.00% : N\u002FA)\n9750000 + 0 primary mapped (97.99% : N\u002FA)\n9950000 + 0 paired in sequencing\n4975000 + 0 read1\n4975000 + 0 read2\n9700000 + 0 properly paired (97.49% : N\u002FA)\n9720000 + 0 with itself and mate mapped\n30000 + 0 singletons (0.30% : N\u002FA)\n15000 + 0 with mate mapped to a different chr\n10000 + 0 with mate mapped to a different chr (mapQ>=5)\n```\n(samtools 1.13+ adds the `primary`, `primary duplicates`, and `primary mapped` lines shown above.)\n\n### Multi-threaded\n```bash\nsamtools flagstat -@ 4 input.bam\n```\n\n### Output to File\n```bash\nsamtools flagstat input.bam > flagstat.txt\n```\n\n## samtools idxstats\n\nPer-chromosome read counts (requires index).\n\n```bash\nsamtools idxstats input.bam\n```\n\nOutput format: `chrom length mapped unmapped`\n```\nchr1    248956422    5000000    1000\nchr2    242193529    4800000    800\nchrM    16569        50000      100\n*       0            0          150000\n```\n\n### Parse idxstats\n```bash\n# Total mapped reads\nsamtools idxstats input.bam | awk '{sum += $3} END {print sum}'\n\n# Mitochondrial percentage\nsamtools idxstats input.bam | awk '\n    \u002F^chrM\u002F {mt = $3}\n    {total += $3}\n    END {print mt\u002Ftotal*100 \"% mitochondrial\"}'\n```\n\n## samtools stats\n\nComprehensive statistics including insert size, base quality, and more.\n\n```bash\nsamtools stats input.bam > stats.txt\n```\n\n### View Summary Numbers\n```bash\nsamtools stats input.bam | grep \"^SN\"\n```\n\nKey summary fields:\n- `raw total sequences` - Total reads\n- `reads mapped` - Mapped reads\n- `reads mapped and paired` - Properly paired\n- `insert size average` - Mean insert size\n- `insert size standard deviation` - Insert size spread\n- `average length` - Mean read length\n- `error rate` - Mismatch rate\n\n### Generate Plots (with plot-bamstats)\n```bash\nsamtools stats input.bam > stats.txt\nplot-bamstats -p plots\u002F stats.txt\n```\n\n### Stats for Specific Region\n```bash\nsamtools stats input.bam chr1:1000000-2000000 > region_stats.txt\n```\n\n## samtools depth\n\nPer-position read depth.\n\n### Basic Depth\n```bash\nsamtools depth input.bam > depth.txt\n```\n\nOutput: `chrom position depth`\n\n### Depth at Specific Positions\n```bash\nsamtools depth -r chr1:1000-2000 input.bam\n```\n\n### Include Zero-Depth Positions\n```bash\nsamtools depth -a input.bam > depth_with_zeros.txt\n```\n\n### Maximum Depth Cap (Critical Trap)\n```bash\n# samtools mpileup historically capped depth at 8000 per position -- the cap was in mpileup, not depth.\n# samtools depth -d\u002F--max-depth is deprecated in 1.13+ (silently ignored).\n# For mpileup, raise the cap explicitly when working with deep targeted\u002Famplicon data:\nsamtools mpileup -d 1000000 -f ref.fa input.bam\n```\n\nPipelines that historically break the 8000 mpileup cap: targeted oncology hotspots (5000-50000x), mitochondrial DNA (small genome, large read share), amplicon viral (ARTIC: 1000-100000x per amplicon), UMI-deduped capture (14000-17000x post-collapse), highly expressed transcripts (rRNA, mt-RNA).\n\n### Overlapping Pair Correction\n```bash\n# When fragment length \u003C 2 * read_length, R1 and R2 overlap.\n# Default samtools depth double-counts overlap; -s deducts:\nsamtools depth -s input.bam\n```\nWithout `-s`, doubled support inflates somatic VAFs at sites covered by overlapping pairs (especially in fragmented samples: FFPE, cfDNA). `mosdepth` does not double-count overlap. `samtools mpileup` and `bcftools mpileup` both enable overlap detection by default; pass `-x` to disable (long form `--disable-overlap-removal` in samtools, `--ignore-overlaps` in bcftools).\n\n### mosdepth (Modern Default)\n```bash\nmosdepth -t 4 sample input.bam                                                       # genome-wide per-base\nmosdepth -t 4 --by exome.bed --thresholds 1,10,20,30,100 --no-per-base sample input.bam   # exome QC\nmosdepth -t 4 --quantize 0:1:10:100: sample input.bam                                # CNV-style bands\nmosdepth -t 4 -f ref.fa sample input.cram                                            # CRAM with reference\n```\n`mosdepth` excludes unmapped, secondary, QC-fail, and duplicate reads by default (`--flag 1796`); supplementary reads are NOT excluded (use `--flag 3844` to drop them too). Configurable via `--flag`. Memory ~ 4 bytes x longest chrom (1 GB for human chr1, 12+ GB for axolotl). Does not honor base quality; use `samtools depth -q INT` if needed.\n\n### Depth from BED Regions\n```bash\nsamtools depth -b regions.bed input.bam\n```\n\n### Calculate Mean Depth\n```bash\nsamtools depth input.bam | awk '{sum += $3; n++} END {print sum\u002Fn}'\n```\n\n## samtools coverage\n\nPer-chromosome or per-region coverage statistics (faster than depth).\n\n```bash\nsamtools coverage input.bam\n```\n\nOutput columns:\n- `#rname` - Reference name\n- `startpos` - Start position\n- `endpos` - End position\n- `numreads` - Number of reads\n- `covbases` - Bases with coverage\n- `coverage` - Percentage of bases covered\n- `meandepth` - Mean depth\n- `meanbaseq` - Mean base quality\n- `meanmapq` - Mean mapping quality\n\n### Coverage for Specific Region\n```bash\nsamtools coverage -r chr1:1000000-2000000 input.bam\n```\n\n### Coverage from BED\n```bash\nsamtools coverage -b regions.bed input.bam\n```\n\n### Histogram Output\n```bash\nsamtools coverage -m input.bam\n```\n\n## pysam Python Alternative\n\n### Count Reads\n```python\nimport pysam\n\nwith pysam.AlignmentFile('input.bam', 'rb') as bam:\n    total = mapped = paired = proper = 0\n    for read in bam:\n        total += 1\n        if not read.is_unmapped:\n            mapped += 1\n        if read.is_paired:\n            paired += 1\n        if read.is_proper_pair:\n            proper += 1\n\n    print(f'Total: {total}')\n    print(f'Mapped: {mapped} ({mapped\u002Ftotal*100:.1f}%)')\n    print(f'Properly paired: {proper} ({proper\u002Fpaired*100:.1f}%)')\n```\n\n### Per-Chromosome Counts\n```python\nimport pysam\n\nwith pysam.AlignmentFile('input.bam', 'rb') as bam:\n    for stat in bam.get_index_statistics():\n        print(f'{stat.contig}: {stat.mapped} mapped, {stat.unmapped} unmapped')\n```\n\n### Calculate Depth at Position\n```python\nimport pysam\n\nwith pysam.AlignmentFile('input.bam', 'rb') as bam:\n    for pileup in bam.pileup('chr1', 1000000, 1000001):\n        print(f'Position {pileup.pos}: depth {pileup.n}')\n```\n\n### Mean Depth in Region\n```python\nimport pysam\n\ndef mean_depth(bam_path, chrom, start, end):\n    depths = []\n    with pysam.AlignmentFile(bam_path, 'rb') as bam:\n        for pileup in bam.pileup(chrom, start, end, truncate=True):\n            depths.append(pileup.n)\n\n    if depths:\n        return sum(depths) \u002F len(depths)\n    return 0\n\ndepth = mean_depth('input.bam', 'chr1', 1000000, 2000000)\nprint(f'Mean depth: {depth:.1f}x')\n```\n\n### Coverage Statistics\n\n**Goal:** Compute coverage breadth and depth for a genomic region from a BAM file.\n\n**Approach:** Iterate pileup columns in the region, count covered positions and accumulate depth, then derive percentages and means.\n\n**Reference (pysam 0.22+):**\n```python\nimport pysam\n\ndef coverage_stats(bam_path, chrom, start, end):\n    covered = 0\n    total_depth = 0\n\n    with pysam.AlignmentFile(bam_path, 'rb') as bam:\n        for pileup in bam.pileup(chrom, start, end, truncate=True):\n            covered += 1\n            total_depth += pileup.n\n\n    length = end - start\n    pct_covered = covered \u002F length * 100\n    mean_depth = total_depth \u002F length if length > 0 else 0\n\n    return {\n        'length': length,\n        'covered_bases': covered,\n        'pct_covered': pct_covered,\n        'mean_depth': mean_depth\n    }\n\nstats = coverage_stats('input.bam', 'chr1', 1000000, 2000000)\nprint(f'Coverage: {stats[\"pct_covered\"]:.1f}%')\nprint(f'Mean depth: {stats[\"mean_depth\"]:.1f}x')\n```\n\n### Insert Size Distribution\n\n**Goal:** Compute the insert size distribution to assess library preparation quality.\n\n**Approach:** Iterate properly paired read1 records, accumulate template lengths into a Counter, then compute summary statistics.\n\n**Reference (pysam 0.22+):**\n```python\nimport pysam\nfrom collections import Counter\n\ninsert_sizes = Counter()\n\nwith pysam.AlignmentFile('input.bam', 'rb') as bam:\n    for read in bam:\n        if read.is_proper_pair and read.is_read1 and read.template_length > 0:\n            insert_sizes[read.template_length] += 1\n\nsizes = list(insert_sizes.keys())\nmean_insert = sum(s * c for s, c in insert_sizes.items()) \u002F sum(insert_sizes.values())\nprint(f'Mean insert size: {mean_insert:.0f}')\nprint(f'Min: {min(sizes)}, Max: {max(sizes)}')\n```\n\n## Quick Reference\n\n| Task | Command |\n|------|---------|\n| Quick counts | `samtools flagstat input.bam` |\n| Per-chrom counts | `samtools idxstats input.bam` |\n| Full stats | `samtools stats input.bam` |\n| Coverage summary | `samtools coverage input.bam` |\n| Per-position depth | `samtools depth input.bam` |\n| Mean depth | `samtools depth input.bam \\| awk '{sum+=$3;n++}END{print sum\u002Fn}'` |\n\n## QC Thresholds Are Assay-Specific\n\nA single \"mapping rate > 95%\" rule rejects valid ATAC, ChIP, RNA-seq, metagenomics, and aDNA samples. The threshold question is \"is this rate normal for this assay?\" not \"is this rate above 95%?\"\n\n| Metric | WGS PCR-free | WGS PCR | WES | Targeted panel | Deep panel (UMI) | RNA-seq | scRNA (10x) | ATAC | ChIP | Long-read | aDNA |\n|--------|--------------|---------|-----|----------------|------------------|---------|-------------|------|------|-----------|------|\n| Mapping rate | >99% | >98% | >95% | >95% | >95% | >90% | >70% | >50% | >60% | >95% | 1-50% |\n| Duplicate rate | \u003C5% | 5-15% | 20-50% | 20-50% | 50-90% pre-consensus | (skip) | (use UMI) | 10-30% | 5-30% | n\u002Fa | 20-60% |\n| Proper pair rate | >95% | >95% | >85% | >80% | >80% | >70% | n\u002Fa | >50% | >70% | n\u002Fa | >60% |\n| Mean MAPQ | bimodal at 0\u002F60 | bimodal | bimodal | bimodal | bimodal | bimodal incl 255 (STAR) | 0\u002F1\u002F3\u002F255 | 30-55 | 30-55 | 30-50 | 20-40 |\n| Mt fraction | 0.1-2% | 0.1-2% | \u003C1% | \u003C0.1% | \u003C0.1% | varies | varies | **\u003C10% (Omni-ATAC goal; original Buenrostro-2013 libraries were often majority-mito)** | \u003C2% | n\u002Fa | varies |\n\nMean MAPQ is misleading; the distribution is bimodal (0 and aligner-max). The fraction at MAPQ >= 30 is more informative:\n```bash\nsamtools view -c -F 2308 -q 30 in.bam   # primary, mapped, MAPQ>=30\nsamtools view -c -F 2308 in.bam          # primary, mapped (denominator)\n# For STAR\u002FSTARsolo, use -q 255 instead of -q 30 (255 is the unique-mapping sentinel)\n```\n\n## What Flagstat Does Not Reveal\n\nA 99% flagstat mapping rate does NOT mean the data is usable. Common false-positive scenarios:\n\n1. **Adapter readthrough**: short fragments (insert \u003C 2 * read_length) sequence into adapter; aligners soft-clip the adapter portion and flag the read as MAPPED. Detect:\n   ```bash\n   samtools stats input.bam | grep \"bases soft-clipped\"   # >5% suggests adapter contamination\n   ```\n2. **Off-target enrichment** (capture\u002FWES): detect via `picard CollectHsMetrics` PCT_OFF_BAIT or PCT_SELECTED_BASES.\n3. **Low-complexity pile-up**: telomere\u002Fcentromere reads mass at MAPQ-0; counted as mapped but useless. Detect via MAPQ distribution.\n4. **Cross-sample contamination**: detect via `verifybamid2` or `somalier` (FREEMIX > 1% degrades somatic calling; > 5% breaks germline calling).\n5. **Wrong reference build**: a BAM aligned to GRCh37 viewed against GRCh38 looks fine to flagstat but produces nonsense pileups. Compare `@SQ M5:` from BAM header with `samtools dict ref.fa` -- see alignment-validation.\n\n## Insert Size Caveats\n\n`samtools stats` reports the IS section only for FR-oriented properly paired reads. So:\n- Mate-pair libraries (RF orientation): IS section *empty* -- proper-pair flag not set for RF\n- ATAC-seq: bimodal\u002Fmultimodal expected (nucleosome ladder ~50\u002F~180\u002F~370 bp). Unimodal suggests poor transposition.\n- RNA-seq: TLEN includes intron span -- mean meaningless\n- Bisulfite (PBAT): orientation reversed; samtools may not flag proper pair\n\n## Related Skills\n\n- sam-bam-basics - View alignment files; aligner-aware MAPQ semantics\n- alignment-indexing - idxstats requires index; secondary+supp counted\n- alignment-validation - Insert size by library, contamination, sample-swap detection\n- duplicate-handling - Library-aware duplicate rate expectations\n- alignment-filtering - Filter before stats\n- sequence-io\u002Fsequence-statistics - FASTA\u002FFASTQ statistics\n","## Version Compatibility\n\nReference examples tested with: pysam 0.22+, samtools 1.19+\n\nBefore using code patterns, verify installed versions match. If versions differ:\n- Python: `pip show \u003Cpackage>` then `help(module.function)` to check signatures\n- CLI: `\u003Ctool> --version` then `\u003Ctool> --help` to confirm flags\n\nIf code throws ImportError, AttributeError, or TypeError, introspect the installed\npackage and adapt the example to match the actual API rather than retrying.\n\n# BAM Statistics\n\n**\"Get alignment statistics and coverage from my BAM file\"** -> Generate read counts, mapping rates, per-chromosome statistics, depth profiles, and coverage summaries.\n- CLI: `samtools flagstat`, `samtools stats`, `samtools depth`, `samtools coverage` (samtools)\n- Python: `pysam.AlignmentFile` with `pileup()` and `get_index_statistics()` (pysam)\n\nGenerate alignment statistics using samtools and pysam.\n\n## Quick Summary Commands\n\n| Question | Best tool | Why |\n|----------|-----------|-----|\n| Quick read counts by FLAG category | `samtools flagstat` | Fast; counts secondary+supp in totals |\n| Per-chromosome counts | `samtools idxstats` | Fast (needs index); **counts secondary+supp** |\n| Insert size, MAPQ, error, GC | `samtools stats -r ref.fa` | Comprehensive; feeds MultiQC |\n| Per-position depth (small region) | `samtools depth` or pysam pileup | Slow on full genome |\n| Per-position depth (genome-wide) | **`mosdepth`** | 3-10x faster than `samtools depth` |\n| Per-region coverage (BED) | `mosdepth --by regions.bed` | Production default |\n| Coverage histogram \u002F cumulative | `mosdepth -t 4 --no-per-base` | Single-pass histogram |\n| Breadth at depth thresholds | `mosdepth --thresholds 1,10,30,100` | Standard exome QC |\n| Targeted enrichment QC | `picard CollectHsMetrics` | PCT_OFF_BAIT, FOLD_80_BASE_PENALTY, AT\u002FGC dropout |\n| Cross-sample contamination | `verifybamid2`, `somalier` | FREEMIX \u003C 0.01 expected |\n\n### What Each Tool Counts (and Doesn't)\n\n| Counting category | flagstat | stats | idxstats |\n|-------------------|----------|-------|----------|\n| Primary alignments | `in total` minus supp | `raw total sequences` | mapped column |\n| Secondary | `secondary` line | filtered out | counted in mapped |\n| Supplementary | `supplementary` line | filtered out | counted in mapped |\n| Mapping rate denominator | total *including* supp | primary only | mapped+unmapped |\n\nFor long-read data where one read produces many supplementary alignments, the senior cross-check:\n```\ninput_read_count = flagstat_total - secondary - supplementary\n                 = stats_raw_total_sequences\n```\nReports of \"the file has 1.2M reads\" where the input was actually 800k with 400k supplementary chimeric splits trace to flagstat misinterpretation.\n\n## samtools flagstat\n\nFast summary of alignment flags.\n\n```bash\nsamtools flagstat input.bam\n```\n\nOutput:\n```\n10000000 + 0 in total (QC-passed reads + QC-failed reads)\n9950000 + 0 primary\n0 + 0 secondary\n50000 + 0 supplementary\n0 + 0 duplicates\n0 + 0 primary duplicates\n9800000 + 0 mapped (98.00% : N\u002FA)\n9750000 + 0 primary mapped (97.99% : N\u002FA)\n9950000 + 0 paired in sequencing\n4975000 + 0 read1\n4975000 + 0 read2\n9700000 + 0 properly paired (97.49% : N\u002FA)\n9720000 + 0 with itself and mate mapped\n30000 + 0 singletons (0.30% : N\u002FA)\n15000 + 0 with mate mapped to a different chr\n10000 + 0 with mate mapped to a different chr (mapQ>=5)\n```\n(samtools 1.13+ adds the `primary`, `primary duplicates`, and `primary mapped` lines shown above.)\n\n### Multi-threaded\n```bash\nsamtools flagstat -@ 4 input.bam\n```\n\n### Output to File\n```bash\nsamtools flagstat input.bam > flagstat.txt\n```\n\n## samtools idxstats\n\nPer-chromosome read counts (requires index).\n\n```bash\nsamtools idxstats input.bam\n```\n\nOutput format: `chrom length mapped unmapped`\n```\nchr1    248956422    5000000    1000\nchr2    242193529    4800000    800\nchrM    16569        50000      100\n*       0            0          150000\n```\n\n### Parse idxstats\n```bash\n# Total mapped reads\nsamtools idxstats input.bam | awk '{sum += $3} END {print sum}'\n\n# Mitochondrial percentage\nsamtools idxstats input.bam | awk '\n    \u002F^chrM\u002F {mt = $3}\n    {total += $3}\n    END {print mt\u002Ftotal*100 \"% mitochondrial\"}'\n```\n\n## samtools stats\n\nComprehensive statistics including insert size, base quality, and more.\n\n```bash\nsamtools stats input.bam > stats.txt\n```\n\n### View Summary Numbers\n```bash\nsamtools stats input.bam | grep \"^SN\"\n```\n\nKey summary fields:\n- `raw total sequences` - Total reads\n- `reads mapped` - Mapped reads\n- `reads mapped and paired` - Properly paired\n- `insert size average` - Mean insert size\n- `insert size standard deviation` - Insert size spread\n- `average length` - Mean read length\n- `error rate` - Mismatch rate\n\n### Generate Plots (with plot-bamstats)\n```bash\nsamtools stats input.bam > stats.txt\nplot-bamstats -p plots\u002F stats.txt\n```\n\n### Stats for Specific Region\n```bash\nsamtools stats input.bam chr1:1000000-2000000 > region_stats.txt\n```\n\n## samtools depth\n\nPer-position read depth.\n\n### Basic Depth\n```bash\nsamtools depth input.bam > depth.txt\n```\n\nOutput: `chrom position depth`\n\n### Depth at Specific Positions\n```bash\nsamtools depth -r chr1:1000-2000 input.bam\n```\n\n### Include Zero-Depth Positions\n```bash\nsamtools depth -a input.bam > depth_with_zeros.txt\n```\n\n### Maximum Depth Cap (Critical Trap)\n```bash\n# samtools mpileup historically capped depth at 8000 per position -- the cap was in mpileup, not depth.\n# samtools depth -d\u002F--max-depth is deprecated in 1.13+ (silently ignored).\n# For mpileup, raise the cap explicitly when working with deep targeted\u002Famplicon data:\nsamtools mpileup -d 1000000 -f ref.fa input.bam\n```\n\nPipelines that historically break the 8000 mpileup cap: targeted oncology hotspots (5000-50000x), mitochondrial DNA (small genome, large read share), amplicon viral (ARTIC: 1000-100000x per amplicon), UMI-deduped capture (14000-17000x post-collapse), highly expressed transcripts (rRNA, mt-RNA).\n\n### Overlapping Pair Correction\n```bash\n# When fragment length \u003C 2 * read_length, R1 and R2 overlap.\n# Default samtools depth double-counts overlap; -s deducts:\nsamtools depth -s input.bam\n```\nWithout `-s`, doubled support inflates somatic VAFs at sites covered by overlapping pairs (especially in fragmented samples: FFPE, cfDNA). `mosdepth` does not double-count overlap. `samtools mpileup` and `bcftools mpileup` both enable overlap detection by default; pass `-x` to disable (long form `--disable-overlap-removal` in samtools, `--ignore-overlaps` in bcftools).\n\n### mosdepth (Modern Default)\n```bash\nmosdepth -t 4 sample input.bam                                                       # genome-wide per-base\nmosdepth -t 4 --by exome.bed --thresholds 1,10,20,30,100 --no-per-base sample input.bam   # exome QC\nmosdepth -t 4 --quantize 0:1:10:100: sample input.bam                                # CNV-style bands\nmosdepth -t 4 -f ref.fa sample input.cram                                            # CRAM with reference\n```\n`mosdepth` excludes unmapped, secondary, QC-fail, and duplicate reads by default (`--flag 1796`); supplementary reads are NOT excluded (use `--flag 3844` to drop them too). Configurable via `--flag`. Memory ~ 4 bytes x longest chrom (1 GB for human chr1, 12+ GB for axolotl). Does not honor base quality; use `samtools depth -q INT` if needed.\n\n### Depth from BED Regions\n```bash\nsamtools depth -b regions.bed input.bam\n```\n\n### Calculate Mean Depth\n```bash\nsamtools depth input.bam | awk '{sum += $3; n++} END {print sum\u002Fn}'\n```\n\n## samtools coverage\n\nPer-chromosome or per-region coverage statistics (faster than depth).\n\n```bash\nsamtools coverage input.bam\n```\n\nOutput columns:\n- `#rname` - Reference name\n- `startpos` - Start position\n- `endpos` - End position\n- `numreads` - Number of reads\n- `covbases` - Bases with coverage\n- `coverage` - Percentage of bases covered\n- `meandepth` - Mean depth\n- `meanbaseq` - Mean base quality\n- `meanmapq` - Mean mapping quality\n\n### Coverage for Specific Region\n```bash\nsamtools coverage -r chr1:1000000-2000000 input.bam\n```\n\n### Coverage from BED\n```bash\nsamtools coverage -b regions.bed input.bam\n```\n\n### Histogram Output\n```bash\nsamtools coverage -m input.bam\n```\n\n## pysam Python Alternative\n\n### Count Reads\n```python\nimport pysam\n\nwith pysam.AlignmentFile('input.bam', 'rb') as bam:\n    total = mapped = paired = proper = 0\n    for read in bam:\n        total += 1\n        if not read.is_unmapped:\n            mapped += 1\n        if read.is_paired:\n            paired += 1\n        if read.is_proper_pair:\n            proper += 1\n\n    print(f'Total: {total}')\n    print(f'Mapped: {mapped} ({mapped\u002Ftotal*100:.1f}%)')\n    print(f'Properly paired: {proper} ({proper\u002Fpaired*100:.1f}%)')\n```\n\n### Per-Chromosome Counts\n```python\nimport pysam\n\nwith pysam.AlignmentFile('input.bam', 'rb') as bam:\n    for stat in bam.get_index_statistics():\n        print(f'{stat.contig}: {stat.mapped} mapped, {stat.unmapped} unmapped')\n```\n\n### Calculate Depth at Position\n```python\nimport pysam\n\nwith pysam.AlignmentFile('input.bam', 'rb') as bam:\n    for pileup in bam.pileup('chr1', 1000000, 1000001):\n        print(f'Position {pileup.pos}: depth {pileup.n}')\n```\n\n### Mean Depth in Region\n```python\nimport pysam\n\ndef mean_depth(bam_path, chrom, start, end):\n    depths = []\n    with pysam.AlignmentFile(bam_path, 'rb') as bam:\n        for pileup in bam.pileup(chrom, start, end, truncate=True):\n            depths.append(pileup.n)\n\n    if depths:\n        return sum(depths) \u002F len(depths)\n    return 0\n\ndepth = mean_depth('input.bam', 'chr1', 1000000, 2000000)\nprint(f'Mean depth: {depth:.1f}x')\n```\n\n### Coverage Statistics\n\n**Goal:** Compute coverage breadth and depth for a genomic region from a BAM file.\n\n**Approach:** Iterate pileup columns in the region, count covered positions and accumulate depth, then derive percentages and means.\n\n**Reference (pysam 0.22+):**\n```python\nimport pysam\n\ndef coverage_stats(bam_path, chrom, start, end):\n    covered = 0\n    total_depth = 0\n\n    with pysam.AlignmentFile(bam_path, 'rb') as bam:\n        for pileup in bam.pileup(chrom, start, end, truncate=True):\n            covered += 1\n            total_depth += pileup.n\n\n    length = end - start\n    pct_covered = covered \u002F length * 100\n    mean_depth = total_depth \u002F length if length > 0 else 0\n\n    return {\n        'length': length,\n        'covered_bases': covered,\n        'pct_covered': pct_covered,\n        'mean_depth': mean_depth\n    }\n\nstats = coverage_stats('input.bam', 'chr1', 1000000, 2000000)\nprint(f'Coverage: {stats[\"pct_covered\"]:.1f}%')\nprint(f'Mean depth: {stats[\"mean_depth\"]:.1f}x')\n```\n\n### Insert Size Distribution\n\n**Goal:** Compute the insert size distribution to assess library preparation quality.\n\n**Approach:** Iterate properly paired read1 records, accumulate template lengths into a Counter, then compute summary statistics.\n\n**Reference (pysam 0.22+):**\n```python\nimport pysam\nfrom collections import Counter\n\ninsert_sizes = Counter()\n\nwith pysam.AlignmentFile('input.bam', 'rb') as bam:\n    for read in bam:\n        if read.is_proper_pair and read.is_read1 and read.template_length > 0:\n            insert_sizes[read.template_length] += 1\n\nsizes = list(insert_sizes.keys())\nmean_insert = sum(s * c for s, c in insert_sizes.items()) \u002F sum(insert_sizes.values())\nprint(f'Mean insert size: {mean_insert:.0f}')\nprint(f'Min: {min(sizes)}, Max: {max(sizes)}')\n```\n\n## Quick Reference\n\n| Task | Command |\n|------|---------|\n| Quick counts | `samtools flagstat input.bam` |\n| Per-chrom counts | `samtools idxstats input.bam` |\n| Full stats | `samtools stats input.bam` |\n| Coverage summary | `samtools coverage input.bam` |\n| Per-position depth | `samtools depth input.bam` |\n| Mean depth | `samtools depth input.bam \\| awk '{sum+=$3;n++}END{print sum\u002Fn}'` |\n\n## QC Thresholds Are Assay-Specific\n\nA single \"mapping rate > 95%\" rule rejects valid ATAC, ChIP, RNA-seq, metagenomics, and aDNA samples. The threshold question is \"is this rate normal for this assay?\" not \"is this rate above 95%?\"\n\n| Metric | WGS PCR-free | WGS PCR | WES | Targeted panel | Deep panel (UMI) | RNA-seq | scRNA (10x) | ATAC | ChIP | Long-read | aDNA |\n|--------|--------------|---------|-----|----------------|------------------|---------|-------------|------|------|-----------|------|\n| Mapping rate | >99% | >98% | >95% | >95% | >95% | >90% | >70% | >50% | >60% | >95% | 1-50% |\n| Duplicate rate | \u003C5% | 5-15% | 20-50% | 20-50% | 50-90% pre-consensus | (skip) | (use UMI) | 10-30% | 5-30% | n\u002Fa | 20-60% |\n| Proper pair rate | >95% | >95% | >85% | >80% | >80% | >70% | n\u002Fa | >50% | >70% | n\u002Fa | >60% |\n| Mean MAPQ | bimodal at 0\u002F60 | bimodal | bimodal | bimodal | bimodal | bimodal incl 255 (STAR) | 0\u002F1\u002F3\u002F255 | 30-55 | 30-55 | 30-50 | 20-40 |\n| Mt fraction | 0.1-2% | 0.1-2% | \u003C1% | \u003C0.1% | \u003C0.1% | varies | varies | **\u003C10% (Omni-ATAC goal; original Buenrostro-2013 libraries were often majority-mito)** | \u003C2% | n\u002Fa | varies |\n\nMean MAPQ is misleading; the distribution is bimodal (0 and aligner-max). The fraction at MAPQ >= 30 is more informative:\n```bash\nsamtools view -c -F 2308 -q 30 in.bam   # primary, mapped, MAPQ>=30\nsamtools view -c -F 2308 in.bam          # primary, mapped (denominator)\n# For STAR\u002FSTARsolo, use -q 255 instead of -q 30 (255 is the unique-mapping sentinel)\n```\n\n## What Flagstat Does Not Reveal\n\nA 99% flagstat mapping rate does NOT mean the data is usable. Common false-positive scenarios:\n\n1. **Adapter readthrough**: short fragments (insert \u003C 2 * read_length) sequence into adapter; aligners soft-clip the adapter portion and flag the read as MAPPED. Detect:\n   ```bash\n   samtools stats input.bam | grep \"bases soft-clipped\"   # >5% suggests adapter contamination\n   ```\n2. **Off-target enrichment** (capture\u002FWES): detect via `picard CollectHsMetrics` PCT_OFF_BAIT or PCT_SELECTED_BASES.\n3. **Low-complexity pile-up**: telomere\u002Fcentromere reads mass at MAPQ-0; counted as mapped but useless. Detect via MAPQ distribution.\n4. **Cross-sample contamination**: detect via `verifybamid2` or `somalier` (FREEMIX > 1% degrades somatic calling; > 5% breaks germline calling).\n5. **Wrong reference build**: a BAM aligned to GRCh37 viewed against GRCh38 looks fine to flagstat but produces nonsense pileups. Compare `@SQ M5:` from BAM header with `samtools dict ref.fa` -- see alignment-validation.\n\n## Insert Size Caveats\n\n`samtools stats` reports the IS section only for FR-oriented properly paired reads. So:\n- Mate-pair libraries (RF orientation): IS section *empty* -- proper-pair flag not set for RF\n- ATAC-seq: bimodal\u002Fmultimodal expected (nucleosome ladder ~50\u002F~180\u002F~370 bp). Unimodal suggests poor transposition.\n- RNA-seq: TLEN includes intron span -- mean meaningless\n- Bisulfite (PBAT): orientation reversed; samtools may not flag proper pair\n\n## Related Skills\n\n- sam-bam-basics - View alignment files; aligner-aware MAPQ semantics\n- alignment-indexing - idxstats requires index; secondary+supp counted\n- alignment-validation - Insert size by library, contamination, sample-swap detection\n- duplicate-handling - Library-aware duplicate rate expectations\n- alignment-filtering - Filter before stats\n- sequence-io\u002Fsequence-statistics - FASTA\u002FFASTQ statistics\n",{"name":5,"source":24,"license":15,"tool_type":25,"description":7,"imported_at":26,"source_path":27,"primary_tool":28,"source_repository":29},"https:\u002F\u002Fgithub.com\u002FGPTomics\u002FbioSkills","cli","2026-09-20","alignment-files\u002Fbam-statistics\u002FSKILL.md","samtools","GPTomics\u002FbioSkills","main","2d1750717747097b602acf30bd09a7cbd4b4c6ea","awesome_skills\u002Fbiology\u002Fbio-bam-statistics","https:\u002F\u002Fgithub.com\u002FMr-Nobody-Anonymous\u002FAll-skills","https:\u002F\u002Fgithub.com\u002FMr-Nobody-Anonymous","2026-11-09 11:45:36",{"source":8,"skillName":5,"commands":37,"prompt":47,"zipAvailable":48},[38,41,44],{"tool":39,"command":40},"npx","npx skills add Mr-Nobody-Anonymous\u002FAll-skills --skill bio-bam-statistics",{"tool":42,"command":43},"bunx","bunx skills add Mr-Nobody-Anonymous\u002FAll-skills --skill bio-bam-statistics",{"tool":45,"command":46},"pnpm","pnpm dlx skills add Mr-Nobody-Anonymous\u002FAll-skills --skill bio-bam-statistics","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FMr-Nobody-Anonymous\u002FAll-skills\u002Fblob\u002Fmain\u002Fawesome_skills\u002Fbiology\u002Fbio-bam-statistics\u002FSKILL.md",true,[50,56],{"path":51,"resourceType":52,"resourceTypeDesc":53,"sizeBytes":54,"sourceHtmlUrl":55},"examples\u002Fqc_report.py","SCRIPT","脚本",2057,"https:\u002F\u002Fgithub.com\u002FMr-Nobody-Anonymous\u002FAll-skills\u002Fblob\u002Fmain\u002Fawesome_skills\u002Fbiology\u002Fbio-bam-statistics\u002Fexamples\u002Fqc_report.py",{"path":57,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":60,"sourceHtmlUrl":61},"usage-guide.md","REFERENCE","参考文档",6762,"https:\u002F\u002Fgithub.com\u002FMr-Nobody-Anonymous\u002FAll-skills\u002Fblob\u002Fmain\u002Fawesome_skills\u002Fbiology\u002Fbio-bam-statistics\u002Fusage-guide.md",[63,71,78,85,92,99],{"skillNo":64,"name":65,"nameZh":6,"description":66,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":67,"categories":68,"keywords":69,"publishedAt":70},"01M7FFFZPC2025JQQHPHDX154J","dei-assessment","Assess diversity, equity, and inclusion with metrics. TRIGGERS - Use when user needs help with dei-assessment related tasks.","https:\u002F\u002Fgithub.com\u002FMr-Nobody-Anonymous\u002FAll-skills\u002Fblob\u002Fmain\u002Fawesome_skills\u002Fhr-people\u002Fdei-assessment\u002FSKILL.md",[],[],"2026-11-16 10:05:34",{"skillNo":72,"name":73,"nameZh":6,"description":74,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":75,"categories":76,"keywords":77,"publishedAt":70},"01M7FFFWN8H4WA7A6Y398QKB6J","dei-action-plan","Create DEI action plans with goals and initiatives. TRIGGERS - Use when user needs help with dei-action-plan related tasks.","https:\u002F\u002Fgithub.com\u002FMr-Nobody-Anonymous\u002FAll-skills\u002Fblob\u002Fmain\u002Fawesome_skills\u002Fhr-people\u002Fdei-action-plan\u002FSKILL.md",[],[],{"skillNo":79,"name":80,"nameZh":6,"description":81,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":82,"categories":83,"keywords":84,"publishedAt":70},"01M7FFFSHTM0QZRVZ2NRJTJ0PY","culture-fit-assessment","Design culture add assessment processes. TRIGGERS - Use when user needs help with culture-fit-assessment related tasks.","https:\u002F\u002Fgithub.com\u002FMr-Nobody-Anonymous\u002FAll-skills\u002Fblob\u002Fmain\u002Fawesome_skills\u002Fhr-people\u002Fculture-fit-assessment\u002FSKILL.md",[],[],{"skillNo":86,"name":87,"nameZh":6,"description":88,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":89,"categories":90,"keywords":91,"publishedAt":70},"01M7FFFMA12RKEQA38KHJSXXPS","cowork-to-code-bridge","Use an already-installed, independently verified cowork-to-code bridge to run narrowly approved actions on the user's own macOS, Linux, or WSL2 machine through a local file queue.","https:\u002F\u002Fgithub.com\u002FMr-Nobody-Anonymous\u002FAll-skills\u002Fblob\u002Fmain\u002Fawesome_skills\u002Fhr-people\u002Fcowork-to-code-bridge\u002FSKILL.md",[],[],{"skillNo":93,"name":94,"nameZh":6,"description":95,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":96,"categories":97,"keywords":98,"publishedAt":70},"01M7FFFH1F6M8YRGW5V487GH1K","counter-offer-response","Draft counter-offer responses for retention. TRIGGERS - Use when user needs help with counter-offer-response related tasks.","https:\u002F\u002Fgithub.com\u002FMr-Nobody-Anonymous\u002FAll-skills\u002Fblob\u002Fmain\u002Fawesome_skills\u002Fhr-people\u002Fcounter-offer-response\u002FSKILL.md",[],[],{"skillNo":100,"name":101,"nameZh":6,"description":102,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":103,"categories":104,"keywords":105,"publishedAt":70},"01M7FFFDGEHV8Y7J9N40HZXW52","continuous-feedback-system","Design continuous feedback systems. TRIGGERS - Use when user needs help with continuous-feedback-system related tasks.","https:\u002F\u002Fgithub.com\u002FMr-Nobody-Anonymous\u002FAll-skills\u002Fblob\u002Fmain\u002Fawesome_skills\u002Fhr-people\u002Fcontinuous-feedback-system\u002FSKILL.md",[],[]]