speed

Documentation

Overview

Package speed implements a command to measure the speed and distance traveled in a reconstruction.

Index

• Variables

Variables

var Command = &command.Command{
	Usage: `speed 
	[--tree <file-prefix>]
	[--step <number>] [--scale <value>]
	[--color <color-scale>] [--width <value>]
	[--box <number>] [--tick <tick-value>]
	[--time] [--plot <file-prefix>]
	[--null <number>]
	-i|--input <file> <project-file>`,
	Short: "calculates speed and distance for a reconstruction",
	Long: `
Command speed reads a file with a sampled pixels from stochastic mapping of
one or more trees in a project, and calculates the distance and speed of the
reconstructed histories.

The distance is a 'biological' distance, in the sense that the distance is the
product of the diffusion process. It is calculated using the great circle
distances between the beginning and ending pixel on each time segment in a
branch.

To test if particles move faster or slower than expected, a simulation is made
with the lambda value used for stochastic sampling and the branch segments of
each lineage. Then it reports the fraction of particles that move more than
95% of the simulations (i.e., they are faster) and the fraction of particles
that move less than 5% of the simulations (i.e., they are slowest). By
default, the number of simulations is 1000; this can be changed with the flag
--null.

The argument of the command is the name of the project file.

The flag --input, or -i, is required and indicates the input file.

If the flag --tree is defined with a file prefix, each tree will be saved as
SVG with each branch colored by the speed of the branch in a red(=fast)-green-
blue(=slow), scale. The scale was made using the log10 of the speed in
kilometers per million year. If the speed of the branch is zero, the minimum
value will used for the branch. The tree will be stored using the indicated
file prefix and the tree name. By default, the time scale is set in million
years. To change the time scale, use the flag --scale with the value in years
of the scale. By default, 10 pixels units will be used per units of the time
scale, use the flag --step to define a different value (it can have decimal
points). The flag --box defines shaded boxes each indicated time steps. The
size of the box is in time scale units. By default, a timescale with ticks
every time scale unit will be added at the bottom of the drawing. Use the flag
--tick to define the tick lines, using the following format:
"<min-tick>,<max-tick>,<label-tick>", in which min-tick indicates minor ticks,
max-tick indicates major ticks, and label-tick the ticks that will be labeled;
for example, the default is "1,5,5" which means that small ticks will be added
each time scale units, major ticks will be added every 5 time scale units, and
labels will be added every 5 time scale units. By default, a rainbow color
scale will be used, other color scales can be defined using the --scale flag.
Valid scale values are mostly based on Paul Tol color scales:

	- iridescent  <https://personal.sron.nl/~pault/#fig:scheme_iridescent>
	- rainbow     default value (from purple to red)
	        <https://personal.sron.nl/~pault/#fig:scheme_rainbow_smooth>
	- incandescent
		<https://personal.sron.nl/~pault/#fig:scheme_incandescent>
	- gray         a gray scale from black to mid gray (RGB: 127).
	- gray2        a gray scale from black to light gray (RBG: 200).

By default, the tree branches will be draw with a 4 pixels, to change the
width use the flag --width.	

The output will be printed in the standard output, as a Tab-delimited table
with the following columns:

	tree      the name of the tree
	node      the ID of the node in the tree
	distance  the median of the traveled distance in kilometers
	d-025     the 2.5% of the empirical CDF of the distance in Km
	d-975     the 97.5% of the empirical CDF of the distance in Km
	dist-rad  the median of the traveled distance in radians
	dr-025    the 2.5% of the empirical CDF of the distance in radians
	dr-975    the 97.5% of the empirical CDF of the distance in radians
	brLen     the length of the branch in million years
	x-050     the 5% of the distance for simulated CDF in kilometers
	x-950     the 95% of the distance for simulated CDF in kilometers
	slower    fraction of particles slower than the 5% of the simulations
	faster    fraction of particles faster than the 95% of the simulations
	speed     the median of the speed in kilometers per million year
	speed-rad the median of the speed in radians per million year

If the flag --time is used, instead of calculating the speed per branch, the
speed will be calculated for each time slice. In this case the whole traveled
distance of each branch segment that pass trough a time slice will be divided
by the total length of all branch segments. The output file will be a
tab-delimited file with the following columns:

	tree      the name of the tree
	age       age of the time slice
	distance  the median of the traveled distance in kilometers
	d-025     the 2.5% of the empirical CDF
	d-975     the 97.5% of the empirical CDF
	brLen     the length of the branch in million years
	speed     the median of the speed in kilometers per million year

If the flag --plot is defined with a file prefix, a box plot for each tree
will be produced, using the speed of each time segment.
	`,
	SetFlags: setFlags,
	Run:      run,
}