[meta]
name = "seqkit"
category = "sequence-manipulation"
description = "Cross-platform ultrafast toolkit for FASTA/Q file manipulation"
tags = ["fasta", "fastq", "sequence", "qc", "statistics", "manipulation", "filtering"]
author = "oxo-call built-in"
source_url = "https://bioinf.shenwei.me/seqkit/"

[context]
concepts = [
    "seqkit works on both FASTA and FASTQ files and auto-detects gzip/bzip2/xz compression.",
    "Use -j N to set the number of threads; use -o output.fa to write to a file.",
    "seqkit stats gives basic statistics; seqkit fx2tab converts to tabular format for downstream processing.",
    "seqkit grep uses regex by default; use -s to search in sequences, -n for names; -f for file of patterns.",
    "seqkit seq -m MIN -M MAX filters by sequence length; -g removes gaps; -r reverse complements.",
    "seqkit common finds sequences shared across multiple files by ID; seqkit rmdup removes duplicate sequences.",
]

pitfalls = [
    "seqkit grep -p matches the full sequence name — use -r (regex) or -n to limit to the ID portion.",
    "seqkit split/split2 creates many files; use -O to specify output directory.",
    "seqkit seq -n outputs only names (useful for getting a list of IDs), not the sequences themselves.",
    "seqkit sample for random subsampling requires -s SEED for reproducibility.",
    "seqkit translate expects DNA/RNA input; use -f 1 to specify forward strand reading frame.",
]

[[examples]]
task = "get basic statistics of a FASTQ file (read count, total bases, average length)"
args = "stats -a reads.fastq.gz"
explanation = "-a shows all statistics including N50, Q20/Q30 percentages"

[[examples]]
task = "filter reads shorter than 100 bp and write to a new file"
args = "seq -m 100 -j 4 -o filtered.fastq.gz input.fastq.gz"
explanation = "-m 100 keeps reads ≥100 bp; -j 4 uses 4 threads; auto-compresses based on output extension"

[[examples]]
task = "get the reverse complement of all sequences in a FASTA file"
args = "seq -r -p -j 4 input.fa -o revcomp.fa"
explanation = "-r reverses; -p complements (so -r -p gives reverse complement)"

[[examples]]
task = "extract sequences by name from a list file"
args = "grep -f id_list.txt input.fa -o subset.fa"
explanation = "-f reads patterns from a file (one per line); outputs matching sequences"

[[examples]]
task = "randomly sample 10000 reads from a large FASTQ file"
args = "sample -n 10000 -s 42 -j 4 -o sample.fastq.gz input.fastq.gz"
explanation = "-n specifies count; -s sets random seed for reproducibility"

[[examples]]
task = "convert FASTQ to FASTA"
args = "fq2fa -j 4 input.fastq.gz -o output.fa.gz"
explanation = "fq2fa subcommand handles the conversion; preserves compression if output ends in .gz"

[[examples]]
task = "split FASTA file into chunks of 1000 sequences each"
args = "split2 -s 1000 -j 4 -O split_output input.fa"
explanation = "-s sets sequences per file; -O specifies output directory"
