diff pact.xml @ 0:d67268158946 draft

planemo upload commit a3f181f5f126803c654b3a66dd4e83a48f7e203b

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/pact.xml	Mon Oct 12 17:43:33 2015 -0400
@@ -0,0 +1,253 @@
+<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>