Subcommand: lwr histogram

Print a table with histograms of the likelihood weight ratios (LWRs) of all pqueries.

Usage: gappa examine lwr-histogram [options]

Options

Input
--jplace-path	Required. TEXT:PATH(existing)=[] ... List of jplace files or directories to process. For directories, only files with the extension .jplace[.gz] are processed.
Settings
--ignore-multiplicities	FLAG Set the multiplicity of each pquery to 1.0. The multiplicity is the equvalent of abundances for placements, and hence ignored with this flag.
--histogram-bins	UINT=20 Number of histogram bins for binning the LWR values. This is the number of rows of the output table.
--num-lwrs	UINT=5 Number of histograms to print. That is, how many of the LWRs per pquery to output (most likely, second most likely, etc), or in other words, how many LWR columns the output table should have.
Output
--out-dir	TEXT=. Directory to write output files to.
--file-prefix	TEXT File prefix for output files. Most gappa commands use the command name as the base name for file output. This option amends the base name, to distinguish runs with different data.
--file-suffix	TEXT File suffix for output files. Most gappa commands use the command name as the base name for file output. This option amends the base name, to distinguish runs with different data.
Global Options
--allow-file-overwriting	FLAG Allow to overwrite existing output files instead of aborting the command.
--verbose	FLAG Produce more verbose output.
--threads	UINT Number of threads to use for calculations.
--log-file	TEXT Write all output to a log file, in addition to standard output to the terminal.

Description

The command takes one or more jplace samples, and prints a histogram showing the likelihood weight ratios (LWRs) of all pqueries, as shown below.

Details

The command produces a histogram table that contains the --num-lwrs most likely likelihood weight ratios (LWRs) of the pqueries (query sequences) in the input jplace files. This can be used in spreadsheet tools to produce a graph that allows an overview of the LWRs for easy assessment and quality control. The output contains columns for the absolute values (summed multiplicities of all pqueries at the particular bin), relative values (as percentages), as well as accumulated absolute and relative values.

We provide an R script to plot these histograms, which for example visualizes a histogram like this:

The histogram shows the percentage of the first, second, and third most likely placement. The x-axis are likelihood weight ratios (always in the range 0.0 to 1.0), the y-axis shows how many of the query sequences have their first, second and third most likely placement at that LWR value. (More exactly, it shows the summed multiplicities of the pqueries.)

For example, the highest bin of LWR.1 on the right hand side of the plot indicates that ~20% of the query sequences have a first (most likely) placement position at or above an LWR of 0.95. That is, these placements have a high LWR and are hence placed with high certainty at their respective branches.

Note that the second most likely placement can never have a LWR of more than 1/2 (otherwise, it would be the most likely), the third most likely not more than 1/3 (otherwise, it would be the second most likely), and so forth.

See Supplementary Figure 14 of Mahé et al., Nature Ecology and Evolution, 2017 for an example of these histograms in practice.

Citation

When using this method, please do not forget to cite

Lucas Czech, Pierre Barbera, Alexandros Stamatakis. Genesis and Gappa: Processing, Analyzing and Visualizing Phylogenetic (Placement) Data. Bioinformatics, 2020. doi:10.1093/bioinformatics/btaa070