#

# shadow

Usage:

> `shadow [options] <tree> <alignment>`

Description:

> Perform phylogenetic shadowing on a given DNA alignment, using a given tree (Boffelli et al, Science 2003). This program is a simplified version of `motiph`, in which the equilibrium distribution is set equal to the background model, rather than being taken from a given motif.

Input:

- `<tree>` is a phylogenetic tree in Phylip Newick format. This tree may contain additional species not represented in the alignment.
- `<alignment>` is a DNA multiple alignment in ClustalW format.

Output:

> Shadow will create a directory, named `shadow_out` by default. Any existing output files in the directory will be overwritten. The directory will contain:

> - An XML file named `shadow.xml` using the CisML schema.
> - An HTML file named `shadow.html`
> - A plain text file named `shadow.text`

> The default can be overridden using the `--o` or `--oc` options which are described below.

> The `--text` will limit output to plain text sent to the standard output.

Options:

- `--bg <float>` - The mutation rate for sites in the background model. The default value is 1.
- `--bgfile <bfile>` - Read background frequencies from `<bfile>`. The file should be in MEME background file format. The default is to use frequencies embedded in the application from the non-redundant database. If the argument is the keyword `motif-file`, then the frequencies will be taken from the motif file.
- `--fg <float>` - The mutation rate for sites in the foreground model(s). The default value is 1.
- `--gap <method>` - Specifies the gap handling strategy. Allowed values for method are:
  - `skip` Skip those sites where any position in the alignment window contains a gap. This is the default gap handling strategy.
  - `fixed` Sites containing gaps are assigned a fixed score, specified by `--gap-cost`.
  - `wildcard` The gap character matches any base, and the score is the product of the corresponding probabilities.
  - `minimum` The gap character is assigned the score corresponding to the least likely letter at the given position.
  - `model` Use model-specific gap handling. Currently, the only model that supports this is `f81_gap`.
- `--gap-cost <float>` - Specifies the costs for gaps when using the `fixed` gap handling strategy. Default is 0.0.
- `--list` - Treat the second required input as a list of alignments, rather than a single alignment.
- `--max-stored-scores `<max>`` - Set the maximum number of scores that will be stored. Precise calculation of q-values depends on having a complete list of scores. However, keeping a complete list of scores may exceed available memory. Once the number of stored scores reaches the maximum allowed, the least significant 50% of scores will be dropped, and approximate q-values will be calculated. By default the maximum number of stored matches is 100,000.
- `--model [jc|k2|f81|f84|hky|tn]` - The evolutionary model to use. The available models are:
  - jc - Jukes-Cantor: equilibrium base frequencies are all 1/4; the only free parameter is the mutation rate.
  - k2 - Kimura 2-parameter: equilibrium base frequencies are all 1/4; the free parameters are the mutation rate and the transition/transversion rate ratio.
  - f81 - Felsenstein 1981: equilibrium base frequencies are taken from the alignment; the only free parameter is the mutation rate.
  - f84 - Felsenstein 1984: equilibrium base frequencies are taken from the alignment; the free parameters are the mutation rate and the transition/transversion rate ratio. The ratio of purine-purine to pyrimidine->pyrimidine transitions is assumed to be 1.
  - hky - Hasegawa-Kishino-Yano: equilibrium base frequencies are taken from the alignment; the free parameters are the mutation rate and the transition/transversion rate ratio. The ratio of purine-purine to pyrimidine-pyrimidine transitions is assumed to be equal to the ratio of purines to pyrimidines.
  - tn - Tamura-Nei: equilibrium base frequencies are taken from the alignment; the free parameters are the mutation rate, the transition/transversion rate ratio, and the ratio of purine-purine transitions to pyrimidine-pyrimidine transitions.

  The default model is f81. A description of the f81 model is available in chapter 13 of Statistical Methods in Bioinformatics by Ewens and Grant. The other models are described in chapters 9 and 13 of Inferring Phylogenies by Felsenstein.

- `--no-pvalue` - Skip the p-value calculation. This switch will be necessary when a large number n of species are in the tree, because the memory requirement is 4n. This also disables computation of q-values.
- `--no-qvalue` - Do not compute a q-value for each p-value. The q-value calculation is that of Benjamini and Hochberg (1995). By default, q-values are computed.
- `--o <dir name>` - Specifies the output directory. If the directory already exists, the contents will not be overwritten.
- `--oc <dir name>` - Specifies the output directory. If the directory already exists, the contents will be overwritten.
- `--output-pthresh <float>` - The p-value threshold for displaying search results. If the p-value of a match is greater than this value, then the match will not be printed. By default, a p-value threshold is not used. If any combination of `--output-ethresh`, `--output-pthresh`, or `--output-qthresh` is given, whichever option occurs last on the command line will determine the effective output filter.
- `--output-qthresh <float>` - The q-value threshold for displaying search results. If the q-value of a match is greater than this value, then the match will not be printed. By default, a q-value threshold is not used. If any combination of `--output-ethresh`, `--output-pthresh`, or `--output-qthresh` is given, whichever option occurs last on the command line will determine the effective output filter.
- `--pur-pyr <float>` - The ratio of the purine transition rate to pyrimidine transition rate. This parameter is used by the Tamura-nei model. The default value is 1.0.
- `--text` Limits output to plain text sent to standard out. For FIMO, the text output is unsorted, and q-values are not reported. This mode allows the program to search an arbitrarily large database, because results are not stored in memory.
- `--transition-transversion <float>` - The ratio of the transition rate to the transversion rate. This parameter is used by the Kimura 2-parameter, F84, HKY, and Tamura-nei models. The default value is 0.5.
- `--verbosity 1|2|3|4` - Set the verbosity of status reports to standard error. The default level is 2.

Warning messages: None