MASON_FRAG_SEQUENCING(1)

📦
version 2.5.2 · 2 versions
, in ubuntu stonking

💅 MASON_FRAG_SEQUENCING 💅

ok bestie, so mason_frag_sequencing is a manual page from section 1, and it's giving fragment sequencing simulation realness. let's get into it 🫶

✨ NAME ✨

mason_frag_sequencing — Fragment Sequencing Simulation

like literally, that's the whole name. short. iconic. no notes. 👑

🌸 SYNOPSIS 🌸

mason_frag_sequencing [OPTIONS] -i IN.fa -o OUT.{fa,fq} [-or OUT2.{fa,fq}]

so you feed it an input with -i (IN.fa), you get yourself an output with -o (OUT.{fa,fq}), and if you're feeling extra you can also drop a second output file with -or (OUT2.{fa,fq}). the {fa,fq} is doing the most — it means FASTA or FASTQ, whichever you vibe with. and yeah, [OPTIONS] is up there front and center bc there's a whole menu of them. iykyk. ✨

🦋 DESCRIPTION 🦋

okay so here's the tea: you hand it a FASTA file that's full of fragments, and it simulates the sequencing of those fragments. that's the whole gig. fragment in, reads out, slay. 💫

now let's talk about what it is vs what it isn't, bc this matters:

  • it's a more lightweight version of mason_sequencing — the cute minimalist sibling basically 🙈
  • it does not support the application of VCF 🌈 (no variant calling chaos here, sorry)
  • it does not support fragment sampling 🎀
  • output of SAM is also not available 💀 like, that format is simply not invited to this party

BUT — and this is the part where it eats — it uses the same code for the simulation of the reads as the more powerful mason_simulator. so even though it's the smaller one, the actual read-simulating engine is highkey the same. no cap. 🔥

so when should you reach for this one instead of the big kids? the manpage says: use mason_frag_sequencing if you want to implement your own fragmentation behaviour — like, for example, if you've already implemented your own bias models. that's your moment. main character energy, honestly. 🧚

fr fr, if you want VCF support, fragment sampling, or SAM output, this is not the tool for you — this one is deliberately the lightweight one. 👑

✨ OPTIONS ✨

okay bestie, here's the whole command-line menu 💅 every flag, every default, no skips, no cap.

  • -h, --help — pops up the help message. your emotional support flag 🫶
  • --version — tells you what version you're running.
  • -q, --quiet — low verbosity. she's shy.
  • -v, --verbose — higher verbosity. she's talking more.
  • -vv, --very-verbose — highest verbosity. she is telling you EVERYTHING 😭
  • --seed UINT64 — the seed for the random number generator. Default: 0.
  • -i, --in INPUT_FILE — path to your input file. 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 yes, the [.*] thing is just built-in (de)compression glow-up ✨
  • -o, --out OUTPUT_FILE — output for single-end reads / left end reads. valid filetypes are: .sam[.*], .raw[.*], .frn[.*], .fq[.*], .fna[.*], .ffn[.*], .fastq[.*], .fasta[.*], .fas[.*], .faa[.*], .fa[.*], and .bam, where * is any of the following extensions: gz, bz2, and bgzf for transparent (de)compression.
  • -or, --out-right OUTPUT_FILE — output for the right reads. giving this option is what turns on paired-end simulation 💖 valid filetypes are: .sam[.*], .raw[.*], .frn[.*], .fq[.*], .fna[.*], .ffn[.*], .fastq[.*], .fasta[.*], .fas[.*], .faa[.*], .fa[.*], and .bam, where * is any of the following extensions: gz, bz2, and bgzf for transparent (de)compression.
  • --force-single-end — forces single-end simulation even though you literally handed her --out-right. she said no paired-end today 🙈

🌈 Global Read Simulation Options

  • --seq-technology STRING — which sequencing technology to simulate. one of illumina, 454, and sanger. Default: illumina.
  • --seq-mate-orientation STRING — orientation for paired reads. go read the Read Orientation section below, bestie. one of FR, RF, FF, and FF2. Default: FR.
  • --seq-strands STRING — which strands to simulate from, only applies to paired sequencing simulation. one of forward, reverse, and both. Default: both.
  • --embed-read-info — whether or not to embed read information.
  • --read-name-prefix STRING — your read names get this prefix. Default: simulated..

🎀 BS-Seq Options

  • --enable-bs-seq — enables BS-seq simulation.
  • --bs-seq-protocol STRING — the protocol to use for BS-Seq simulation. one of directional and undirectional. Default: directional.
  • --bs-seq-conversion-rate DOUBLE — conversion rate for unmethylated Cs to turn into Ts. In range [0..1]. Default: 0.99.

🧚 Illumina Options

  • --illumina-read-length INTEGER — read length for Illumina simulation. In range [1..inf]. Default: 100.
  • --illumina-error-profile-file INPUT_FILE — path to the file with the Illumina error profile. it has to be a text file with floating point numbers separated by space, each one giving a positional error rate. valid filetype is: .txt.
  • --illumina-prob-insert DOUBLE — per-base probability of insertion in Illumina sequencing. In range [0..1]. Default: 0.00005.
  • --illumina-prob-deletion DOUBLE — per-base probability of deletion in Illumina sequencing. In range [0..1]. Default: 0.00005.
  • --illumina-prob-mismatch-scale DOUBLE — scaling factor for Illumina mismatch probability. In range [0..inf]. Default: 1.0.
  • --illumina-prob-mismatch DOUBLE — average per-base mismatch probability in Illumina sequencing. In range [0.0..1.0]. Default: 0.004.
  • --illumina-prob-mismatch-begin DOUBLE — per-base mismatch probability of the first base in Illumina sequencing. In range [0.0..1.0]. Default: 0.002.
  • --illumina-prob-mismatch-end DOUBLE — per-base mismatch probability of the last base in Illumina sequencing. In range [0.0..1.0]. Default: 0.012.
  • --illumina-position-raise DOUBLE — the point where the error curve raises, relative to read length. In range [0.0..1.0]. Default: 0.66.
  • --illumina-quality-mean-begin DOUBLE — mean PHRED quality for non-mismatch bases of the first base in Illumina sequencing. Default: 40.0.
  • --illumina-quality-mean-end DOUBLE — mean PHRED quality for non-mismatch bases of the last base in Illumina sequencing. Default: 39.5.
  • --illumina-quality-stddev-begin DOUBLE — standard deviation of PHRED quality for non-mismatch bases of the first base in Illumina sequencing. Default: 0.05.
  • --illumina-quality-stddev-end DOUBLE — standard deviation of PHRED quality for non-mismatch bases of the last base in Illumina sequencing. Default: 10.0.
  • --illumina-mismatch-quality-mean-begin DOUBLE — mean PHRED quality for mismatch bases of the first base in Illumina sequencing. Default: 40.0.
  • --illumina-mismatch-quality-mean-end DOUBLE — mean PHRED quality for mismatch bases of the last base in Illumina sequencing. Default: 30.0.
  • --illumina-mismatch-quality-stddev-begin DOUBLE — standard deviation of PHRED quality for mismatch bases of the first base in Illumina sequencing. Default: 3.0.
  • --illumina-mismatch-quality-stddev-end DOUBLE — standard deviation of PHRED quality for mismatch bases of the last base in Illumina sequencing. Default: 15.0.
  • --illumina-left-template-fastq INPUT_FILE — a FASTQ file to use as a template for the left-end reads. 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.
  • --illumina-right-template-fastq INPUT_FILE — a FASTQ file to use as a template for the right-end reads. 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.

🦋 Sanger Sequencing Options

  • --sanger-read-length-model STRING — the model used to sample the Sanger read length. one of normal and uniform. Default: normal.
  • --sanger-read-length-min INTEGER — the minimal read length when the read length is sampled uniformly. In range [0..inf]. Default: 400.
  • --sanger-read-length-max INTEGER — the maximal read length when the read length is sampled uniformly. In range [0..inf]. Default: 600.
  • --sanger-read-length-mean DOUBLE — the mean read length when the read length is sampled with a normal distribution. In range [0..inf]. Default: 400.
  • --sanger-read-length-error DOUBLE — the read length standard deviation when the read length is sampled uniformly. In range [0..inf]. Default: 40.
  • --sanger-prob-mismatch-scale DOUBLE — scaling factor for Sanger mismatch probability. In range [0..inf]. Default: 1.0.
  • --sanger-prob-mismatch-begin DOUBLE — per-base mismatch probability of the first base in Sanger sequencing. In range [0.0..1.0]. Default: 0.005.
  • --sanger-prob-mismatch-end DOUBLE — per-base mismatch probability of the last base in Sanger sequencing. In range [0.0..1.0]. Default: 0.001.
  • --sanger-prob-insertion-begin DOUBLE — per-base insertion probability of the first base in Sanger sequencing. In range [0.0..1.0]. Default: 0.0025.
  • --sanger-prob-insertion-end DOUBLE — per-base insertion probability of the last base in Sanger sequencing. In range [0.0..1.0]. Default: 0.005.
  • --sanger-prob-deletion-begin DOUBLE — per-base deletion probability of the first base in Sanger sequencing. In range [0.0..1.0]. Default: 0.0025.
  • --sanger-prob-deletion-end DOUBLE — per-base deletion probability of the last base in Sanger sequencing. In range [0.0..1.0]. Default: 0.005.
  • --sanger-quality-match-start-mean DOUBLE — mean PHRED quality for non-mismatch bases of the first base in Sanger sequencing. Default: 40.0.
  • --sanger-quality-match-end-mean DOUBLE — mean PHRED quality for non-mismatch bases of the last base in Sanger sequencing. Default: 39.5.
  • --sanger-quality-match-start-stddev DOUBLE — mean PHRED quality for non-mismatch bases of the first base in Sanger sequencing. Default: 0.1.
  • --sanger-quality-match-end-stddev DOUBLE — mean PHRED quality for non-mismatch bases of the last base in Sanger sequencing. Default: 2.
  • --sanger-quality-error-start-mean DOUBLE — mean PHRED quality for erroneous bases of the first base in Sanger sequencing. Default: 30.
  • --sanger-quality-error-end-mean DOUBLE — mean PHRED quality for erroneous bases of the last base in Sanger sequencing. Default: 20.
  • --sanger-quality-error-start-stddev DOUBLE — mean PHRED quality for erroneous bases of the first base in Sanger sequencing. Default: 2.
  • --sanger-quality-error-end-stddev DOUBLE — mean PHRED quality for erroneous bases of the last base in Sanger sequencing. Default: 5.

💜 454 Sequencing Options

  • --454-read-length-model STRING — the model used to sample the 454 read length. one of normal and uniform. Default: normal.
  • --454-read-length-min INTEGER — the minimal read length when the read length is sampled uniformly. In range [0..inf]. Default: 10.
  • --454-read-length-max INTEGER — the maximal read length when the read length is sampled uniformly. In range [0..inf]. Default: 600.
  • --454-read-length-mean DOUBLE — the mean read length when the read length is sampled with a normal distribution. In range [0..inf]. Default: 400.
  • --454-read-length-stddev DOUBLE — the read length standard deviation when the read length is sampled with a normal distribution. In range [0..inf]. Default: 40.
  • --454-no-sqrt-in-std-dev — for the error model: if this is set, (sigma = k * r)) is used, otherwise (sigma = k * sqrt(r)).
  • --454-proportionality-factor DOUBLE — proportionality factor for calculating the standard deviation proportional to the read length. In range [0..inf]. Default: 0.15.
  • --454-background-noise-mean DOUBLE — mean of the lognormal distribution used for the noise. In range [0..inf]. Default: 0.23.
  • --454-background-noise-stddev DOUBLE — standard deviation of the lognormal distribution used for the noise. In range [0..inf]. Default: 0.15.

⭐ SEQUENCING SIMULATION ⭐

couple of things you truly need to know before you hit enter, bestie:

  • base quality simulation is disabled when you're writing out FASTA files. so if you wanted qualities, FASTA is not the vibe 👑
  • paired-end sequencing simulation gets enabled when you specify two output files. two files in, two reads out, that's the math 💖

Reads are not all floating around doing their own thing, bestie — paired-end has ✨orientation✨ and you get to pick it with --mate-orientation. Here are the valid values, no cap:

  • FR — reads are inward-facing, same energy as Illumina paired-end reads: R1 --> <-- R2. The classic. The main character. 💅
  • RF — reads are outward-facing, exactly like Illumina mate-pair reads: R1 <-- --> R2. Backwards but make it fashion 🦋
  • FF — reads are on the same strand: R1 --> --> R2. Matching fits, slay 🌸
  • FF2 — reads are on the same strand BUT the "right" reads get sequenced to the left of the "left" reads, same as 454 paired: R2 --> --> R1. iconic chaotic energy fr fr 💀

✨ PARALLELISM ✨

🌈 General

So here's the vibe: the contigs are processed sequentially, one after another, no cutting the line 🚶♀️

But within each contig? Oh she's fast. The fragments/reads get simulated in parallel by --num-threads many threads, and each of those threads simulates batches of chunks-size many fragments at a time. They just keep going like little worker bees until no more fragments are left to be simulated 🐝✨

💖 CPU-Utilization

Okay so here's the tea, and it's lowkey important 👀

When the number of fragments to simulate per contig is low, it can happen that NOT all your threads get utilized. Not a bug, just math, bestie. Example time, because I know you love one:

When there are 20,000 fragments to simulate for a contig, 32 threads are available, and each thread simulates batches of 1000 (--chunk-size) fragments — only 20 threads are utilized. The other 12 are just sitting there, hydrated, unbothered, doing nothing 😭

So yeah: --chunk-size affects CPU-utilization. That's the whole point of mentioning it.

BUT. Very low chunk-sizes also lead to a large overhead, especially when you're using only one thread. The bookkeeping eats your gains, and it's giving diminishing returns 💀

We set a sensible default, so don't stress — but perfomance gains may be achieved by trying different chunk-sizes. Tinker, queen 👑

🎀 Randomization

Heads up: both --chunk-size and --num-threads affect randomization. Different values for these parameters yield different results. So if you're chasing reproducibility of a specific run, don't just go changing these and then act surprised, iykyk 🙈

⭐ tl;dr — sequential contigs, parallel fragments, --mate-orientation controls which way your pairs point, and --chunk-size + --num-threads quietly change your results too. Change them on purpose, not by accident 🫶

That's the whole page, bestie — this was mason_frag_sequencing 2.0.13, from the [tarball], living in the MASON_FRAG_SEQUENCING(1) manual. Now go simulate some fragments, you got this 💜✨🧚

📦 where this page comes from