[meta]
name = "featurecounts"
category = "rna-seq"
description = "Efficient and accurate read summarization for RNA-seq and ChIP-seq aligned reads against genomic features"
tags = ["rna-seq", "quantification", "counts", "gene-expression", "gtf", "subread", "chip-seq"]
author = "oxo-call built-in"
source_url = "https://subread.sourceforge.net/featureCounts.html"

[context]
concepts = [
    "featureCounts is part of the Subread package; it counts reads mapping to genomic features (genes, exons) from BAM files.",
    "Use -a to specify the GTF/GFF annotation file; -o for the output count file; input BAM files are positional arguments.",
    "Use -T N for multi-threading; -p for paired-end counting (count read pairs, not individual reads).",
    "Strandedness: -s 0 (unstranded), -s 1 (forward-stranded), -s 2 (reverse-stranded/dUTP) — must match library prep.",
    "Default feature type is 'exon' (-t exon) aggregated to 'gene_id' (-g gene_id) — matches standard RNA-seq workflows.",
    "Use -O to allow multi-mapping reads to be counted (each feature they overlap); default requires unique assignment.",
    "--primary counts only primary alignments; --ignoreDup ignores marked duplicates.",
    "The output file has 6 annotation columns followed by one count column per BAM file — easy to parse for DESeq2.",
]

pitfalls = [
    "Wrong strandedness (-s 0/1/2) is the most common error — check your library prep protocol or use Salmon/RSeQC to determine.",
    "For paired-end data, use -p flag — without it, each read is counted individually instead of each read pair.",
    "The GTF/GFF feature_type (-t) and attribute (-g) must match what is in your annotation file.",
    "featureCounts requires coordinate-sorted indexed BAM files — unsorted input produces incorrect counts.",
    "Reads counted in multiple features (multi-mapping) are discarded by default; add -O for permissive counting.",
    "The output file header begins with '# Program:featureCounts...' — strip this when importing into R/Python.",
]

[[examples]]
task = "count reads per gene for paired-end RNA-seq with reverse-strand library"
args = "-T 8 -a genes.gtf -o counts.txt -p -s 2 sample1.bam sample2.bam sample3.bam"
explanation = "-p paired-end; -s 2 reverse-strand (dUTP); -T 8 threads; multiple BAMs counted in one run"

[[examples]]
task = "count reads per gene for unstranded single-end RNA-seq"
args = "-T 8 -a genes.gtf -o counts.txt -s 0 sample.bam"
explanation = "-s 0 unstranded; outputs count matrix with 1 count column per BAM file"

[[examples]]
task = "count reads allowing multi-mapping reads to be counted"
args = "-T 8 -a genes.gtf -o counts.txt -p -s 2 --primary -M -O sample.bam"
explanation = "--primary counts only primary alignments; -M allows multi-mappers; -O allows reads to count to multiple features"

[[examples]]
task = "count ChIP-seq reads per peak region using BED file"
args = "-T 4 -a peaks.saf -F SAF -o chip_counts.txt sample_sorted.bam"
explanation = "-F SAF for simple annotation format (BED-like); -a peaks.saf; used for ChIP/ATAC peak quantification"

[[examples]]
task = "count exon-level reads for exon usage analysis"
args = "-T 8 -f -a genes.gtf -o exon_counts.txt -p -s 2 sample.bam"
explanation = "-f counts at feature level (exon) instead of meta-feature (gene); used for exon usage/splicing analysis"
