view pact.xml @ 0:d67268158946 draft

planemo upload commit a3f181f5f126803c654b3a66dd4e83a48f7e203b

<tool id="ARGO_pact_run" name="Run PACT" version="1.0.0">
  <description>Analyze Argo Navis BEAST run using PACT</description>
  <requirements>
    <requirement type="package" version="0.1">argo_env</requirement>
    <requirement type="package" version="3.1.2">R</requirement>
  </requirements>
  <macros>
    <import>macros.xml</import>
  </macros>
  <command interpreter="bash">
    pact.sh ${config}
  </command>
  <stdio>
    <expand macro="basic_errors"/>
  </stdio>
  <inputs>

    <param name="treefile" type="data" format="nex" label="BEAST treefile"
      help="This should be the 'BEAST treefile' from your most recent run of BEAST.
      If you did a 'Resume' run, you should use the 'Trimmed' treefile."/>

    <param name="figures_title" type="text" label="Figures title" value="Argo Navis PACT Results"
      help="This string will be set as the title of the PDF figure file returned by this tool.
      Feel free to customize to help you keep track of your files/figures."/>

    <conditional name="tip_selection">
      <param name="method" type="select" label="Tip selection method"
        help="You may optionally choose to restrict these PACT analyses to a subset of the sequences.
        By default, all tips are included in the analysis.">
        <option value="all" selected="true">All tips (no subsetting)</option>
        <option value="demes">Select By Deme</option>
        <option value="names">Space separated tip names</option>
        <option value="file">Tip name file</option>
      </param>
      <when value="demes">
        <param name="demes" type="text" value="" label="Demes"
          help="Restrict analyses to the specified deme (space seprated if specifying multiple)."/>
      </when>
      <when value="names">
        <param name="tip_names" type="text" value="" label="Tip names"
          help="Restrict analyses to the specified tip names (space separated).">
          <sanitizer>
            <valid initial="string.printable">
             <remove value="&apos;"/>
            </valid>
            <mapping initial="none">
              <add source="&apos;" target="__sq__"/>
            </mapping>
          </sanitizer>
        </param>
      </when>
      <when value="file">
        <param name="file" type="data" format="txt" label="Tip names file"
          help="A file with one tip name per line."/>
      </when>
    </conditional>

    <conditional name="time_range">
      <param name="selector" type="select" label="Time range"
        help="As with the Tip selection, you have the choice of restricting the anlayses to a particular time
        range wihtin the tree.">
        <option value="all" selected="true">Don't restrict time range</option>
        <option value="custom">Custom time range</option>
      </param>
      <when value="all"/>
      <when value="custom">
        <param name="start" type="float" value="1.0" label="Start time"
          help="The age of the oldest ancestry which should be considered (as a positive number)."/>
        <param name="end" type="float" value="0.0" label="End time" optional="true"
          help="The age of the most recent ancestry which should be considered (as a non-negative number).
          Note: this will fail if you specify a time window which excludes all tips in your study."/>
      </when>
    </conditional>

    <conditional name="color">
      <param name="selector" type="select" label="Color specification"
        help="By default, the colors used in plots are automatically chosen for you.
        However, you can either specify your own semi-automatic color scheme using Colorbrewer, or
        for full control a CSV file mapping demes to colors.">
        <option value="default" selected="true">Default</option>
        <option value="brewer">Color brewer theme</option>
        <option value="file">Color spec file</option>
      </param>
      <when value="default"/> <!--Nothing-->
      <when value="brewer">
        <param name="brewer" type="text" value="RdBu" label="Deme and optionally date information"
          help="A valid colorbrewer2 color scheme name. See http://colorbrewer2.org/ for details."/>
      </when>
      <when value="file">
        <param name="file" type="data" format="csv" label="Color spec file"
          help="CSV file with 'deme' and 'color' columns, specifying what color (as RGB) each deme should be associated with.
          Note, the default color scheme is both highly contrast and friendly for most color-blind individuals."/>
      </when>
    </conditional>

    <param name="custom_pact_settings" type="data" format="txt" label="Custom PACT spec" optional="true"
      help="Not required. You can specify a custom PACT file if you would like to perform some custom anlayses.
      If you do, results will be place in the 'Full data' folder/archive."/>

  </inputs>

  <outputs>
    <data name="figures" format="pdf" label="PACT figures"/>
    <data name="full_data" format="txt" label="Full data">
      <discover_datasets pattern="__designation__" ext="txt" directory="working_dir" visible="true"/>
    </data>
  </outputs>

  <configfiles>
    <configfile name="config">

TREEFILE="${treefile}"

FIGURES_TITLE="${figures_title}"

TIP_SELECTION_METHOD="${tip_selection.method}"
#if $tip_selection.method == "demes"
DEMES="${tip_selection.demes}"
#else if $tip_selection.method == "names"
TIP_NAMES="${tip_selection.tip_names}"
#else if $tip_selection.method == "file"
TIP_FILE="${tip_selection.names}"
#end if

TIME_RANGE_SELECTOR="${time_range.selector}"
#if $time_range.selector == "custom"
TIME_RANGE_START="${time_range.start}"
#if str($time_range.end) != "None"
TIME_RANGE_END="${time_range.end}"
#else
TIME_RANGE_END=""
#end if
#end if

COLOR_SELECTOR="${color.selector}"
#if $color.selector == "default"
COLOR_SELECTOR="brewer"
COLOR_BREWER="RdBu"
#else if $color.selector == "brewer"
COLOR_BREWER="${color.brewer}"
#else
COLOR_FILE="${color.file}"
#end if

#if str($custom_pact_settings) != "None"
CUSTOM_PACT_SETTINGS="${custom_pact_settings}"
#else
CUSTOM_PACT_SETTINGS=""
#end if


FIGURES="${figures}"

    </configfile>
  </configfiles>

  <!-- The contents of the help tag is parsed as reStructuredText. Please see
       help-template.rst for examples of commonly-used sections in other Galaxy
       tools. -->
  <help>

.. class:: infomark

What it does
------------

This runs PACT (Posterior Analysis of Coalescent Trees) for an Argo Navis analysis.
PACT is a tool for analyzing the tree file output of Bayesian discrete trait ancestral analyses.
Like BEAST, PACT is very powerful and flexible, but can be challenging to get started with.
The Argo Navis wrapper automates a core set of PACT features, making it easy to operate for beginners.


How PACT works
--------------

PACT's power and flexibility is due largely to it's combination of

1. A wide range of statistics
2. Ability to subset the posterior trees, by both tree tips and time windows
3. Composability of the above features

This lets you ask pointed question about particular aspects of your evolutionary histories.

For example, imagine we're studying a virus which infects several species, including humans, and that we're interested in finding out how
this virus got into humans.
To investigate this, we could point PACT towards the viruses found in humans, and even restrict to the time window around when
transmission into humans occurred.
Within the context of this restriction, we could look at the proportions of tree length associated with each population, across all of
the trees in the posterior sample to get a sense of the most likely vector.
We could also analyze the number of transmissions into the human deme from each of the other host species, and from this estimate
migration probabilities.
Comparing these probabilities could also provide support for a particular deme being the zoonotic vector into humans.


What Argo Navis' PACT wrapper produces
--------------------------------------

Again, while PACT is a very powerful and versatile tool, for the sake of making it easier to use, we focus on a limited set of functionality.
Most of the information in summarized in a single PDF document with several plots and figures, and a table of statistics.

In particular, the PDF document will contain the following figures:

1. **Maximum likelihood ancestral state tree**: This is the tree from the posterior with the highest likelihood.
   It is colored by deme, and shows one possible history of how the discrete trait may have evolved along with the molecular sequences.
   Keep in mind though, this is only the *most likely* evolutionary course of the molecules and demes under study.
   It's possible the rest of the posterior sample looks quite different, and this should be taken into account when analyzing results.
   This tree is provided as a way of building some intuition about the data, and providing threads you can explore more formally with other tools.
2. **Skyline proportions**: In the section above about *How PACT works*, we described how you could look at the population proportions for a
   particular portion of the tree are distributed.
   We can take this one step further by using the ``skyline`` functionality of PACT, which enables us to compute a statistic for many different
   small time windows at once.
   By combining these windows, we get a picture of how the proportions are shifting over time.
3. **Migration rates**: As mentioned above, migration rates can be estimated based on the posterior trees.
   This is graphically represented via a table of boxplots, representing the mean and 95% confidence intervals of the migration rates to and
   from each population.
   The rows of this table correspond to migration "origin", and columns to "destination".
   Additionally, the boxes are colored by migration origin, with the same scheme as used for other plots.
4. **Additional statistics**: Additional statistics are presented in textual table format.


Argo Navis PACT controls
------------------------

All you need in order to run the PACT tool is the treefile output from your BEAST run.
Note that if you have done a *resume* run, you should use the **trimmed** version of the treefile, so PACT doesn't get too bogged down
with a large data set.
In addition to the data though, you can specify:

1. **Figure title**: A title to display at the top of your PDF document.
2. **Tip selection**: Restrict analyses to a particular set of tree tips.
   You're choices here include:
   a) leaving all tree tips in the analysis
   b) subsetting to just the tree tips corresponding to a specific deme
   c) subsetting to an arbitrary collection of tree tips via text field
   d) subsetting to an arbitrary collection of tree tips, as specified by an input file
3. **Temporal select**: Restrict analyses to a particular time window.
   You can specify either or both of start time and stop time.
   By default, analyses consider the entire history of the posterior trees, and the skyline proportions go as far back as the mean TMRCA.
4. **Color specification**: You can customize the color scheme used in the graphics, either using a `ColorBrewer`_ pallete, or a CSV file
   mapping demes to RGB color specifications

If you would like to run more customized analyses, you can also specify a custom PACT config file.
However, this tool does not support the PDF output for more customized analyses;
You will instead get individual textual output files, which you will have to process/interpret as you see fit.
For guidance in this, we recommend you take a look at the `PACT documentation`_.


.. _PACT documentation: https://github.com/trvrb/PACT/blob/master/pact_manual.pdf?raw=true
.. _ColorBrewer: http://colorbrewer2.org


  </help>
</tool>