RABEMA_EVALUATE(1)

📦
version 2.5.2 · 2 versions
, in ubuntu stonking

💖 RABEMA_EVALUATE 💖

okay bestie, welcome to rabema_evaluate (that's the 1 section of the manual, for the girlies keeping track) — the part of RABEMA that grades your read mapper's homework. ✨

✨ NAME ✨

rabema_evaluate — RABEMA Evaluation, aka the moment of truth for your aligner 🫶

🌸 SYNOPSIS 🌸

rabema_evaluate [OPTIONS] --reference REF.fa --in-gsi IN.gsi --in-bam
MAPPING.{sam,bam}

🦋 DESCRIPTION 🦋

so basically 💅 — you take the SAM/BAM output of any read mapper, all proud of itself, and you hold it up against the RABEMA gold standard you already built with rabema_build_gold_standard. comparison time. no cap.

your three inputs are: a reference FASTA file, a gold standard interval (GSI) file, and the SAM/BAM you wanna evaluate.

⚠️ listen. the input SAM/BAM file must be sorted by queryname. not optional, not a vibe, a requirement.

also, the program will create a FASTA index file REF.fa.fai so it can randomly access the reference fast ✨

👑 OPTIONS 👑

  • -h, --help — show the help message, bestie. it's giving helpful.
  • --version — show version info 💫
  • -v, --verbose — turn on verbose output, for when you want the tea 🍵
  • -vv, --very-verbose — even MORE verbose output. maximum yapping, but make it diagnostics 🔥

🎀 Input / Output 🎀

  • -r, --reference INPUT_FILE — path to load the reference FASTA from. valid filetypes are: .sam[.*], .raw[.*], .gbk[.*], .frn[.*], .fq[.*], .fna[.*], .ffn[.*], .fastq[.*], .fasta[.*], .fas[.*], .faa[.*], .fa[.*], .embl[.*], and .bam, where * is any of the following extensions: gz, bz2, and bgzf for transparent (de)compression. so many options, she's versatile 💅
  • -g, --in-gsi INPUT_FILE — path to load gold standard intervals from. if it's compressed with gzip, the file gets decompressed on the fly, no extra steps needed ✨ valid filetype is: .gsi[.*], where * is any of the following extensions: gz for transparent (de)compression.
  • -b, --in-bam INPUT_FILE — path to load the read mapper's SAM or BAM output from. valid filetypes are: .sam[.*] and .bam, where * is any of the following extensions: gz, bz2, and bgzf for transparent (de)compression.
  • --out-tsv OUTPUT_FILE — path to write the statistics to as TSV. valid filetype is: .rabema_report_tsv. the receipts 📊
  • --dont-check-sorting — do not check sortedness (by name) of input SAM/BAM files. this is required if the reads are not sorted by name in the original FASTQ files. files from the SRA and ENA generally are sorted. iykyk 🧚

🔥 Benchmark Parameters 🔥

  • --oracle-mode — enable oracle mode 👑 this is used for simulated data when the input GSI file gives exactly one position that is considered as the true sample position. for simulated data.
  • --only-unique-reads — consider only reads that a single alignment in the mapping result file. useful for precision computation. main character reads only 💅
  • --match-N — when set, N matches all characters without penalty. N is giving "i contain multitudes" 🌈
  • --distance-metric STRING — set distance metric. valid values: hamming, edit. default: edit. one of hamming and edit. default: edit. (yes girl, it said it twice, so i'm telling you twice 💖)
  • -e, --max-error INTEGER — maximal error rate to build gold standard for, in percent. this parameter is an integer and relative to the read length. the error rate is ignored in oracle mode — there, the distance of the read at the sample position is taken, individually for each read. default: 0. default: 0. (again: twice. committing to the bit 🫶)
  • -c, --benchmark-category STRING — set benchmark category. one of {all, all-best, any-best. default: all. one of all, all-best, and any-best. default: all. pick your fighter, all three are iconic ✨
  • --trust-NM — when set, we trust the alignment and distance from the SAM/BAM file and no realignment is performed. off by default. trusting the NM tag is a leap of faith, bestie 🙈
  • --extra-pos-tag STRING — if the CIGAR string is absent, the missing alignment end position can be provided by this BAM tag. backup plan behavior, we love to see it 🎀
  • --ignore-paired-flags — when set, we ignore all SAM/BAM flags related to pairing. this is necessary when analyzing SAM from SOAP's soap2sam.pl script. SOAP girlies rise 🧼
  • --DONT-PANIC — do not stop program execution if an additional hit was found that indicates that the gold standard is incorrect. yes it's in all caps, she's screaming it for emphasis 💀

💜 Logging 💜

  • --show-missed-intervals — show details for each missed interval from the GSI. the ones that got away 😭
  • --show-invalid-hits — show details for invalid hits (with too high error rate).
  • --show-additional-hits — show details for additional hits (low enough error rate but not in gold standard.
  • --show-hits — show details for hit intervals. the winners ✨
  • --show-try-hit — show details for each alignment in SAM/BAM input. every single attempt, we respect the hustle 🫡
⚠️ real talk: the occurrence of "invalid" hits in the read mapper's output is not an error. if there are additional hits, however, this shows an error in the gold standard. so don't come for the mapper when the gold standard is the one acting up, fr fr.

💫 RETURN VALUES 💫

a return value of 0 indicates success 🎉 any other value indicates an error 💀

🧠 MEMORY REQUIREMENTS 🧠

from version 1.1, great care has been taken to keep the memory requirements as low as possible. she's low-maintenance, she's efficient, she fits in your RAM 👑

the evaluation step needs to store the whole reference sequence in memory but little more memory. so, for the human genome, the memory requirements are below 4 GB, regardless of the size of the GSI or SAM/BAM file. literally slaying at scale 🌈

📚 REFERENCES 📚

  • M. Holtgrewe, A.-K. Emde, D. Weese and K. Reinert. A Novel And Well-Defined Benchmarking Method For Second Generation Read Mapping, BMC Bioinformatics 2011, 12:210.

https://www.seqan.de/rabema RABEMA Homepage

https://www.seqan.de/mason Mason Homepage

okay that's the whole page bestie, you're fully briefed ✨ and one last thing — this was rabema_evaluate 1.2.14 [tarball], brought to you by the fine people behind RABEMA. now go evaluate something, periodt 💅💖

📦 where this page comes from