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>]
	[--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, 10 pixels units will be used per
million year, 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 million years. By default, a timescale with
ticks every million years 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 million years, major ticks will be added every 5 million years, and
labels will be added every 5 million years.

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
	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
	x-050     the 5% of the distance for simulated CDF
	x-950     the 95% of the distance for simulated CDF
	slower    fraction of particles slower than the 5% of the simulations
	faster    fraction of particles faster than the 95% of the simulations

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,
}