BUILDTREES.PY(1)

BUILDTREES.PY(1) 🎀 User Commands 💖 bestie, this is your guide to the one and only BuildTrees.py!! 🧚

✨ NAME ✨

BuildTrees.py - Repertoire clonal assignment toolkit (Python 3) 🦋

💅 DESCRIPTION 💅

okay so first, heads up 🙈 the tool throws some SyntaxWarnings about is being used with literals. they're just warnings, but they're lowkey annoying:

/usr/bin/BuildTrees.py:488: SyntaxWarning: "is" with a literal. Did you
mean "=="?

      if germline is "":

/usr/bin/BuildTrees.py:543: SyntaxWarning: "is" with a literal. Did you
mean "=="?

      if ngermline is "":

/usr/bin/BuildTrees.py:801: SyntaxWarning: "is not" with a literal. Did
you mean "!="?

      if regions["cdr3_imgt"] is not "" and regions["cdr3_imgt"] is not
      None:

/usr/bin/BuildTrees.py:827: SyntaxWarning: "is not" with a literal. Did
you mean "!="?

      elif regions["fwr3_imgt"] is not "" and regions["fwr3_imgt"] is
      not None:

here's the usage line, the full fit 👑:

usage: BuildTrees.py [--version] [-h] -d DB_FILES [DB_FILES ...]

       [--outdir OUT_DIR] [--outname OUT_NAME] [--log LOG_FILE]
       [--failed] [--format {airr,changeo}] [--collapse] [--ncdr3]
       [--nmask] [--md META_DATA [META_DATA ...]]  [--clones
       TARGET_CLONES [TARGET_CLONES ...]]  [--minseq MIN_SEQ] [--sample
       SAMPLE_DEPTH] [--append APPEND [APPEND ...]] [--igphyml] [--nproc
       NPROC] [--clean {none,all}] [--optimize {n,r,l,lr,tl,tlr}]
       [--omega {e,ce,e,e,ce,e,e,ce,ce,ce}] [-t {e,ce}] [--motifs
       MOTIFS] [--hotness HOTNESS] [--oformat {tab,txt}] [--nohlp]
       [--asr ASR]

so the whole thing basically converts TSV files into IgPhyML input files 🧬 it's giving data pipeline, and it's giving main character energy 💖

🎀 help

• --version — shows the program's version number and then exits 🌸
• -h, --help — shows the help message and exits 🫶

🌸 standard arguments

• -d DB_FILES [DB_FILES ...] — give it a list of tab delimited database files. the default is None 💅
• --outdir OUT_DIR — point this at a new folder if you want the output somewhere else. if you skip it, the input file's directory gets used. the default is None 📂
• --outname OUT_NAME — changes the prefix of the successfully processed output file to whatever string you pick. you can't use it with multiple input files ⚠️ the default is None 🦋
• --log LOG_FILE — writes verbose logging to a file. you can't use it with multiple input files either 🙈 the default is None 📝
• --failed — if you add this, it makes files holding the records that failed processing. the default is False 💀
• --format {airr,changeo} — sets the input and output format. the default is airr 🍓

💜 sequence processing arguments

• --collapse — if you flag it, identical sequences get collapsed before they're exported to fasta. the default is False ✨
• --ncdr3 — if you flag it, CDR3 gets removed from all sequences. the default is False 🌈
• --nmask — if you flag it, the tool won't try to mask split codons. the default is False 🙅‍♀️
• --md META_DATA [META_DATA ...] — a list of fields holding metadata that you want included in the sequence headers of the output fasta file. the default is None 🏷️
• --clones TARGET_CLONES [TARGET_CLONES ...] — a list of clone IDs to output, if you want that. the default is None 🎯
• --minseq MIN_SEQ — the minimum number of data sequences. any clones with fewer sequences than this get excluded 🧹 the default is 1
• --sample SAMPLE_DEPTH — the depth of reads to subsample, done before deduplication 🎲 the default is -1
• --append APPEND [APPEND ...] — a list of columns to append to the sequence ID so everything stays unique 🔑 the default is None

🧬 IgPhyML arguments (see igphyml -h for details)

• --igphyml — runs IgPhyML on the output. the default is False 🔥
• --nproc NPROC — how many threads IgPhyML gets spread across 🧵 the default is 1
• --clean {none,all} — deletes intermediate files. none leaves every intermediate file alone, all deletes all of them. the default is none 🗑️
• --optimize {n,r,l,lr,tl,tlr} — optimizes the combo of topology (t), branch lengths (l), and parameters (r), or nothing at all (n), for IgPhyML 🧠 the default is lr
• --omega {e,ce,e,e,ce,e,e,ce,ce,ce} — the omega parameters to estimate for FWR and CDR, respectively. e means estimate, and ce means estimate plus a confidence interval 📊 the default is e,e
• -t {e,ce} — the kappa parameters to estimate. e means estimate, ce means estimate plus a confidence interval 💫 the default is e
• --motifs MOTIFS — which motifs to estimate mutability for 🧩 the default is WRC_2:0,GYW_0:1,WA_1:2,TW_0:3,SYC_2:4,GRS_0:5
• --hotness HOTNESS — the mutability parameters to estimate. e means estimate, ce means estimate plus a confidence interval 🌡️ the default is e,e,e,e,e,e
• --oformat {tab,txt} — the IgPhyML output format 📄 the default is tab
• --nohlp — skips the HLP model 🙅 the default is False
• --asr ASR — the ancestral sequence reconstruction interval, from 0 to 1 🦖 the default is -1

🗂️ output files

• <folder> — the folder holding the fasta and partition files for each clone 📁
• lineages — the successfully processed records ✅
• lineages-fail — the database records that failed processing ❌
• igphyml-pass — the parameter estimates and lineage trees from running IgPhyML, if you asked for it 🌳

🔑 required fields

your input needs these fields, no cap 🧢: sequence_id, sequence, sequence_alignment, germline_alignment_d_mask or germline_alignment, v_call, j_call, clone_id, v_sequence_start

⚠️ bestie, the warnings above are about is vs == with literals. the tool still runs, but it's a good idea to keep an eye on them 👀

🧚 AUTHOR 🧚

Nilesh Patra wrote this manpage for the Debian distribution 🌈 and it can be used for any other usage of the program 💜

that's the whole tea, bestie 🫶 this was BuildTrees.py 1.0.1, from October 2020, and the manual page is BUILDTREES.PY(1) ✨ periodt 💅🦋