place_batch

The place_batch command places many alignments in one run, for example every user_msa_file.fasta of a large GTDB-Tk run. List them in a batchfile, one line per alignment: the alignment, its reference package and the output jplace file.

Alignments that share a reference package are placed together, so the work on each reference tree is done once. The results are exactly the same as placing each file separately with place.

The options of place work here too. --max_memory is applied to each reference package separately (see Large trees and memory limits). Reference files without a reference package, and query files holding the reference sequences, need place (see pplacer’s options).

Arguments

usage: gplace place_batch --batchfile BATCHFILE --out_dir OUT_DIR
                          [--cpus CPUS] [--fix_gamma_underflow] [--mrca_class]
                          [--discard_nonoverlapped] [--ranked_edges N]
                          [--tmpdir TMPDIR] [-h]
                          [--tile_edges TILE_EDGES | --max_memory MAX_MEMORY]
                          [--ml_tolerance FLOAT] [--start_pend FLOAT]
                          [--max_pend FLOAT] [--max_strikes INT]
                          [--strike_box FLOAT] [--max_pitches INT]
                          [--keep_at_most INT] [--keep_factor FLOAT]
                          [--no_pre_mask] [--always_refine]

required named arguments

--batchfile

tab-separated file with 3 columns: query alignment, reference package, output jplace; alignments sharing a reference package are placed together

--out_dir

directory to output files

optional arguments

--cpus

number of CPUs to use, or “auto”: the value saved by gplace benchmark on this machine, otherwise measured during the run (placement is memory-bandwidth bound, so the fastest value is often below the CPU count)

Default: '1'

--fix_gamma_underflow

gamma-model reference packages only: avoid pplacer’s rescaling underflow, which gives likelihood -inf on large trees. Results then differ from pplacer (slightly where pplacer is finite). Default: reproduce pplacer exactly

--mrca_class, --mrca-class

reference packages with a taxonomy: classify each placement by the taxonomic MRCA of the reference sequences below its edge, instead of by edge painting (pplacer’s –mrca-class)

--discard_nonoverlapped, --discard-nonoverlapped

drop queries that have no residue in any column where a reference sequence has one, instead of stopping (pplacer’s –discard-nonoverlapped)

--ranked_edges

untiled placement: keep only each query’s first N edges of pplacer’s ranking (164 covers pplacer’s default search) instead of its prefilter score for every edge, scoring queries in batches of 20,000. Memory then barely grows with the number of queries; results are identical (a query that needs more edges is ranked again in full). Tiled placement always works this way. Default: keep every score

--tmpdir

specify alternative directory for temporary files

Default: '/tmp'

mutually exclusive optional arguments

--tile_edges

place tile by tile, holding one tile of at most this many edges in memory at a time (exact; for reference trees too large for memory, such as the full GTDB bacterial tree). Default: no tiling

--max_memory

memory gPlace may use, e.g. 64G or 500M (a plain number is GiB). If the estimated peak fits, gPlace places without tiles; otherwise it picks the largest tile size that fits, from the reference tree and the number of queries (chosen separately for each reference package)

pplacer settings (default: pplacer’s; results stay identical to pplacer run with the same settings)

--ml_tolerance, --ml-tolerance

tolerance of the first-stage branch length optimisation (the kept placements are refined to 1e-5)

Default: 0.01

--start_pend, --start-pend

starting pendant branch length

Default: 0.1

--max_pend, --max-pend

maximum pendant branch length

Default: 2.0

--max_strikes, --max-strikes

stop trying edges after this many strikes (edges more than strike_box below the best so far); 0 tries every edge of the tree

Default: 6

--strike_box, --strike-box

size of the strike box in log-likelihood units

Default: 3.0

--max_pitches, --max-pitches

try at most this many edges (plus one) per query

Default: 40

--keep_at_most, --keep-at-most

maximum number of placements kept per query

Default: 7

--keep_factor, --keep-factor

keep placements whose likelihood is at least this fraction of the best one’s

Default: 0.01

--no_pre_mask, --no-pre-mask

do not pre-mask: keep every alignment column (query residues where no reference has one then count), do not check that queries overlap the reference sequences, and merge only queries with identical whole sequences into one record

--always_refine, --always-refine

refine the model before placing: CAT models get new site rate categories on the reference tree (pplacer always does this when the query alignment holds the reference sequences); no effect on gamma models

Files output

Example

# make a batchfile from GTDB-Tk output folders (script in the gPlace repository)
python scripts/make_gtdbtk_batchfile.py --msa_root gtdbtk_runs \
    --refpkg_root release226/split/class_level/pplacer > batch.tsv
gplace place_batch --batchfile batch.tsv --out_dir gplace_out --cpus 40

# within 32 GB: tiles only for the reference packages that need them
gplace place_batch --batchfile batch.tsv --out_dir gplace_out --cpus 40 --max_memory 32G