BUILDCONSENSUS.PY(1)

💖 BUILDCONSENSUS.PY(1) — User Commands 💖

---

✨ NAME ✨

BuildConsensus.py - Builds a consensus sequence for each set of input sequences 💅

---

🦋 DESCRIPTION 🦋

Okay bestie, so this tool takes your input sequences and builds a consensus sequence for each set of them. Ngl the usage line looks like a whole essay, but it's just the list of everything you're allowed to pass in 🫶

usage: BuildConsensus.py [--version] [-h] -s SEQ_FILES [SEQ_FILES ...]

       [-o OUT_FILES [OUT_FILES ...]] [--outdir OUT_DIR]
              [--outname OUT_NAME] [--log LOG_FILE] [--failed] [--fasta]
              [--delim DELIMITER DELIMITER DELIMITER] [--nproc NPROC] [-n
              MIN_COUNT] [--bf BARCODE_FIELD] [-q MIN_QUAL] [--freq MIN_FREQ]
              [--maxgap MAX_GAP] [--pf PRIMER_FIELD] [--prcons PRIMER_FREQ]
              [--cf COPY_FIELDS [COPY_FIELDS ...]]  [--act
              {min,max,sum,set,majority} [{min,max,sum,set,majority} ...]]
              [--dep] [--maxdiv MAX_DIVERSITY | --maxerror MAX_ERROR]

Builds a consensus sequence for each set of input sequences. It's giving main character energy ✨

---

🌸 help 🌸

• --version — shows the program's version number and then exits 🎀
• -h, --help — shows this help message and exits 🧚

---

🍓 standard arguments 🍓

• -s SEQ_FILES [SEQ_FILES ...] — the list of FASTA/FASTQ files holding the sequences you want processed 💖 (default: None)
• -o OUT_FILES [OUT_FILES ...] — explicit output file name(s). Heads up, this one can't be used with --failed, --outdir, or --outname 🙈 If you don't set it, the output filename gets based on your input filename(s). (default: None)
• --outdir OUT_DIR — changes the output directory to wherever you point it. If you skip this, the input file directory is used instead 🌈 (default: None)
• --outname OUT_NAME — swaps the prefix of the successfully processed output file for the string you give it. Can't be used with multiple input files 💅 (default: None)
• --log LOG_FILE — writes verbose logging to a file. Also can't be used with multiple input files 📝 (default: None)
• --failed — creates files holding the records that fail processing 💀 (default: False)
• --fasta — forces the output to be FASTA instead of FASTQ 🦋 (default: None)
• --delim DELIMITER DELIMITER DELIMITER — a list of three delimiters. In order, they separate annotation blocks, field names from values, and values within a field 🫧 (default: ('|', '=', ','))
• --nproc NPROC — how many computational processes run at the same time (aka how many CPU cores you want to utilize) 🔥 (default: 4)

---

🧚 consensus generation arguments 🧚

• -n MIN_COUNT — the minimum number of sequences needed before a consensus counts as valid ✨ (default: 1)
• --bf BARCODE_FIELD — the position of the description barcode field you want to group sequences by 🍓 (default: BARCODE)
• -q MIN_QUAL — the consensus quality score cut-off. Anything under it gets an ambiguous character assigned. It doesn't apply when quality scores aren't available 🙈 (default: 0)
• --freq MIN_FREQ — the fraction of character occurrences under which an ambiguous character gets assigned 💜 (default: 0.6)
• --maxgap MAX_GAP — if you set this, it defines a cut-off for how often gap values are allowed at each position. Positions over the threshold get deleted from the consensus. If you don't define it, positions are always kept 🫶 (default: None)
• --pf PRIMER_FIELD — the field name of the primer annotations 🎀 (default: None)
• --prcons PRIMER_FREQ — sets a minimum primer frequency needed to assign a consensus primer. It also filters out sequences with minority primers from the consensus building step 👑 (default: None)
• --cf COPY_FIELDS [COPY_FIELDS ...] — extra annotation fields to copy into the consensus sequence annotations 🌸 (default: None)
• --act {min,max,sum,set,majority} [{min,max,sum,set,majority} ...] — a list of actions, one for each copy field, that decides how each annotation gets combined into a single value 💅
  • min, max, and sum do the matching math operation on numeric annotations 🧮
  • set mashes the annotations into a comma delimited list of unique values, and adds an annotation named <FIELD>_COUNT with the count of each item in the set 🍓
  • majority gives the consensus annotation the most frequent annotation, and adds an annotation named <FIELD>_FREQ with the frequency of that majority value 👑

(default: None)

• --dep — calculates consensus quality with a nonindependence assumption 🧠 (default: False)
• --maxdiv MAX_DIVERSITY — calculates the nucleotide diversity of each read group (average pairwise error rate) and removes groups going over the diversity threshold. The diversity is calculated for all positions in the read group, ignoring any character filtering from -q, --freq and --maxgap 🙅‍♀️ Mutually exclusive with --maxerror. (default: None)
• --maxerror MAX_ERROR — calculates the error rate of each read group (the rate of mismatches from the consensus) and removes groups over the error threshold. The error rate is calculated against the final consensus, which can include masked positions because of -q and --freq, and can have deleted positions because of --maxgap 🚫 Mutually exclusive with --maxdiv. (default: None)

---

🌈 output files 🌈

• consensus-pass — the consensus reads 🫧
• consensus-fail — the raw reads that fail the consensus filtering criteria 💀

---

💜 output annotation fields 💜

• PRIMER — a comma delimited list of the unique primer annotations found within the barcode read group 🎀
• PRCOUNT — a comma delimited list of the matching counts for those unique primer annotations 🔢
• PRCONS — the majority primer within the barcode read group 👑
• PRFREQ — the frequency of the majority primer 📈
• CONSCOUNT — the count of reads in the barcode read group that actually went into the consensus sequence. It's the total size of the read group minus any sequence excluded by your filtering criteria 🧁

---

🫶 AUTHOR 🫶

This manpage was written by Andreas Tille for the Debian distribution and can be used for any other usage of the program 🌷

---

Bestie, that's the whole tea ☕💖 BuildConsensus.py 0.6.0, May 2020, and we're signing off with main character energy 🦋✨