NAME

alignment-draw - Draw an alignment and interactively inspect character properties.

SYNOPSIS

alignment-draw alignment [AU file] [OPTIONS]

DESCRIPTION

Draw an alignment to HTML, optionally coloring cells by alignment uncertainty (AU). With --properties, the output is a self-contained interactive page: it embeds the scientific data, styles, and JavaScript and does not require a network connection.

The property selector supports linear, log10, and empirical-rank color scales. Linear and log10 scales can use the full range, a robust 2--98% range, or custom bounds. A property initially uses log10 only when it has enough nonnegative, distinct observations and logarithmic normalization uses the color range materially more evenly; otherwise it uses linear. posSelection remains linear because it is a probability. Names ending in -posSelection, such as foreground-posSelection, receive the same treatment. Positive-selection probabilities initially use the full probability domain from 0 to 1; choosing Robust or Custom overrides those bounds. Reset restores the initial defaults.

Zero is valid on a log10 property scale. It is clipped to the positive lower bound, while its tooltip continues to report zero and the legend identifies that the lower color includes zero. Negative values cannot use log10.

The default blue-to-light-gray-to-red diverging palette maps 0 to blue, 0.5 to gray, and 1 to red for positive-selection probabilities. For other properties it maps the median to gray and normalizes the lower and upper halves independently. The palette selector also provides Viridis and a blue-to-red sequential palette. Palette and scale choices are retained separately for each property.

The legend and cell colors update together. Pointing at or focusing a non-gap cell shows its posterior mean, posterior standard deviation, median, scale, and palette. The page displays the shared number of retained samples once rather than repeating it for every character.

The ranked panel selects one representative observed character per nonempty template-alignment column. Generic properties can be ordered by column, mean, or posterior standard deviation. Positive-selection properties can be filtered at probabilities 0.5, 0.95, and 0.99 and include the matching dNdS summary when available. Selecting a row highlights the complete template column and opens the representative character's tooltip.

The stored identity of a property value is the sequence name and zero-based ungapped character index. The displayed one-based column is only a way to locate related characters in the chosen template alignment; it does not imply that the column has a fixed identity across sampled alignments.

The Original colors checkbox restores alphabet colors without removing the active property or its tooltips. Compound symbols occupy one logical table cell. Codons show three nucleotide-colored spans, and their report rows use the configured genetic code for amino-acid translation.

When --AU and --properties are supplied together, the viewer can fade the property color toward white according to posterior alignment certainty. The light-gray center of the diverging palette remains distinguishable from this white uncertainty limit. Property values use ungapped sequence-character coordinates; AU values use alignment-grid coordinates. The AU file must therefore have exactly the same number of model-character columns as the displayed alignment.

GENERAL OPTIONS:

-h, --help

produce help message

--file arg

file with sequences and initial alignment

--legend

Print a legend showing how color-scheme indicates uncertainty.

--show-ruler

Print a ruler to show column numbers

--column-colors

Color-code column ticks by column certainty

--AU arg

file with alignment uncertainties

--properties arg

JSON property summary produced by character-properties summarize

--alphabet arg

alphabet used to tokenize and color model characters; required with --properties

--show-gaps arg (=yes)

Show gaps

--show-letters arg (=yes)

Show letters

--show-names arg (=yes)

Show names

--gaps-different arg (=yes)

Color gaps in grey.

--width arg

The number of columns per line

--start arg

The first column to plot

--end arg

The last column to plot

--format arg (=HTML)

produce a plot in this format

--min arg

Minimum value of scale function

--max arg

Maximum value of scale function

--color-scheme arg

Include a length of how certainties map to colors

--scale arg (=LOD)

scale for the uncertainties

EXAMPLES:

Create a property summary and an interactive DNA alignment:

character-properties summarize run-1/C1.P1.site-property-samples.jsonl run-2/C1.P1.site-property-samples.jsonl \
  --skip=1000 > P1.site-property-summary.json

alignment-draw P1.initial.fasta --alphabet DNA \
  --properties P1.site-property-summary.json > P1.initial.html

Add posterior alignment uncertainty to the same interactive page:

alignment-draw P1.initial.fasta --alphabet DNA \
  --properties P1.site-property-summary.json --AU P1.initial-AU.prob \
  > P1.initial-AU.html

REPORTING BUGS:

BAli-Phy online help: http://www.bali-phy.org/docs.php.

Please send bug reports to bali-phy-users@googlegroups.com.