speed

var Command = &command.Command{
	Usage: `speed 
	[--tree <file-prefix>] [--step <number>]
	[--box <number>] [--tick <tick-value>]
	[--time] [--plot <file-prefix>]
	-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.

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

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