Hyphy tool updates (2.5.81)

tools/hyphy/hyphy_absrel.xml

@@ -8,80 +8,113 @@
     <command detect_errors="exit_code"><![CDATA[
         @SYMLINK_FILES@
         ln -s '$absrel_output' ${input_file}.aBSREL.json &&
-        @HYPHYMPI@ absrel
+        #if $intermediate_fits_flag:
+        ln -s '$intermediate_fits_output' intermediate_fits.json &&
+        #end if
+        @HYPHYMP@ absrel
             --alignment ./$input_file
             @INPUT_TREE@
             --code '$gencodeid'
             @branch_options@
             --output '$absrel_output'
             --multiple-hits $multiple_hits
-            $srv
+            @srv_options@
+            --blb $blb
+            #if $intermediate_fits_flag:
+            --intermediate-fits "intermediate_fits.json"
+            #end if
+            --kill-zero-lengths $kill_zero_lengths > absrel_stdout.md
         @ERRORS@
         ]]></command>
     <inputs>
         <expand macro="inputs"/>
         <expand macro="gencode"/>
         <param argument="--multiple-hits" type="select" label="Include support for multiple nucleotide substitutions">
-            <option value="None">Use standard models which permit only single nucleotide changes to occur instantly</option>
             <option value="Double">Include branch-specific rates for double nucleotide substitutions</option>
             <option value="Double+Triple">Include branch-specific rates for double and triple nucleotide substitutions</option>
+            <option value="None" selected="true">Use standard models which permit only single nucleotide changes to occur instantly</option>
         </param>
-        <param argument="--srv" type="boolean" truevalue="--srv Yes" falsevalue="" label="Include synonymous rate variation" />
+        <param argument="--blb" type="float" value="1.0" label="Bag of little bootstrap alignment resampling rate" help="[Advanced option]"/>
+        <conditional name="srv_conditional">
+            <param name="srv_enabled" type="select" label="Include synonymous rate variation">
+                <option value="true" selected="true">Yes</option>
+                <option value="false">No</option>
+            </param>
+            <when value="true">
+                <param argument="--syn-rates" type="integer" value="3" min="1" max="10" label="Synonymous rate classes" help="The number of alpha rate classes to include in the model [1-10, default 3]"/>
+            </when>
+            <when value="false">
+            </when>
+        </conditional>
+        <param name="intermediate_fits_flag" type="boolean" truevalue="true" falsevalue="false" label="Save intermediate fits" help="Use/save parameter estimates from 'initial-guess' model fits to a JSON file"/>
+        <expand macro="kill_zero_lengths_param"/>
         <expand macro="branches"/>
     </inputs>
     <outputs>
+        <data name="absrel_md_report" format="markdown" from_work_dir="absrel_stdout.md" label="aBSREL Report (Markdown) for ${tool.name} on ${on_string}" />
         <data name="absrel_output" format="hyphy_results.json" />
+        <data name="intermediate_fits_output" format="json" from_work_dir="intermediate_fits.json" label="Intermediate Fits for ${tool.name} on ${on_string}">
+            <filter>intermediate_fits_flag</filter>
+        </data>
     </outputs>
     <tests>
-        <test>
+        <test expect_num_outputs="2">
             <param name="input_file" ftype="fasta" value="absrel-in1.fa"/>
             <param name="input_nhx" ftype="nhx" value="absrel-in1.nhx"/>
-            <param name="multiple_hits" value="None" />
             <output name="absrel_output">
                 <assert_contents>
-                    <has_size value="10512" delta="100"/>
+                    <has_size value="70000" delta="6000"/>
                     <has_text text="fits"/>
                     <has_text text="branch attributes"/>
                     <has_text text="Full adaptive model"/>
                 </assert_contents>
             </output>
-            <assert_stdout>
-                <has_text text="found **2** branches under selection among **5** tested"/>
-            </assert_stdout>
+            <output name="absrel_md_report">
+                <assert_contents>
+                    <has_text text="found **1** branches under selection among **5** tested"/>
+                </assert_contents>
+            </output>
         </test>
-        <test>
+        <test expect_num_outputs="2">
             <param name="input_file" ftype="fasta" value="absrel-in1.fa"/>
             <param name="input_nhx" ftype="nhx" value="absrel-in1.nhx"/>
             <param name="multiple_hits" value="Double" />
             <output name="absrel_output">
                 <assert_contents>
-                    <has_size value="11117" delta="100"/>
+                    <has_size value="60000" delta="5000"/>
                     <has_text text="fits"/>
                     <has_text text="branch attributes"/>
                     <has_text text="Full adaptive model"/>
                 </assert_contents>
             </output>
-            <assert_stdout>
-                <has_text text="found **0** branches under selection among **5** tested"/>
-            </assert_stdout>
+            <output name="absrel_md_report">
+                <assert_contents>
+                    <has_text text="found **0** branches under selection among **5** tested"/>
+                 <has_text text="Branch-level rate at which 2 nucleotides are changed instantly"/>
+                </assert_contents>
+            </output>
         </test>
-        <test>
+        <test expect_num_outputs="2">
             <param name="input_file" ftype="fasta" value="absrel-in1.fa"/>
             <param name="input_nhx" ftype="nhx" value="absrel-in1.nhx"/>
             <param name="multiple_hits" value="Double" />
-            <param name="srv" value="true" />
+            <param name="srv_conditional|srv_enabled" value="true" />
             <output name="absrel_output">
                 <assert_contents>
-                    <has_size value="23396" delta="100"/>
+                    <has_size value="58257" delta="1000"/>
                     <has_text text="fits"/>
                     <has_text text="branch attributes"/>
                     <has_text text="Full adaptive model"/>
                 </assert_contents>
             </output>
-            <assert_stdout>
-                <has_text text="found **0** branches under selection among **5** tested"/>
-            </assert_stdout>
-        </test>
+            <output name="absrel_md_report">
+                <assert_contents>
+                    <has_text text="found **0** branches under selection among **5** tested"/>
+               <has_text text="Branch-level rate at which 2 nucleotides are changed instantly"/>
+               <has_text text="The following rate distribution for site-to-site **synonymous** rate variation was inferred"/>
+                </assert_contents>
+            </output>
+         </test>
     </tests>
     <help><![CDATA[
 
@@ -91,21 +124,18 @@ aBSREL : Adaptive Branch-Site Random Effects Likelihood
 What question does this method answer?
 --------------------------------------
 
-Is some proportion of sites is subject to positive selection along specific branches or lineages of a phylogeny?
+aBSREL (adaptive Branch-Site Random Effects Likelihood) is a powerful method for detecting episodic positive selection. It identifies instances where a proportion of sites along specific branches or lineages of a phylogeny have undergone positive selection.
 
 Recommended Applications
 ------------------------
 
-1. Exploratory testing for evidence of lineage-specific positive diversifying selection in small to medium sized alignments (up to 100 sequences).
-2. Targeted testing of branches selected a priori for positive diversifying selection, including alignments with prohibitive runtimes under older branch-site models (up to 1,000 sequences)
+1.  **Detecting Episodic Diversifying Selection:** Ideal for exploratory testing to find evidence of lineage-specific positive diversifying selection in alignments of various sizes.
+2.  **Targeted Branch Testing:** Suitable for targeted testing of branches hypothesized to be under positive selection, even in alignments that would be computationally prohibitive for older branch-site models.
 
 Brief description
 -----------------
 
-aBSREL (Adaptive branch-site random effects likelihood) uses an adaptive
-random effects branch-site model framework to test whether each branch
-has evolved under positive selection, using a procedure which infers an
-optimal number of rate categories per branch.
+aBSREL (Adaptive Branch-Site Random Effects Likelihood) is a robust method for detecting episodic positive selection. It employs an adaptive random effects branch-site model framework, which allows the number of rate categories (including those for positive selection) to vary across different branches of the phylogenetic tree. This adaptive approach enables aBSREL to infer an optimal number of rate categories for each branch, providing a more nuanced and powerful test for positive selection compared to traditional fixed-rate models. The method tests whether each branch has evolved under positive selection, identifying instances where a proportion of sites along specific branches or lineages of a phylogeny have undergone positive selection.
 
 
 Input
@@ -137,21 +167,40 @@ Tool options
 ------------
 ::
 
+    --alignment         [required] An in-frame codon alignment in one of the formats supported by HyPhy
 
-    --code              Which genetic code to use
+    --tree              [conditionally required] A phylogenetic tree (optionally annotated with {})
+
+    --code              Which genetic code to use (see tool form for available options)
 
     --branches          Which branches should be tested for selection?
-                            All [default] : test all branches
+                            All [default]
+                            Internal
+                            Leaves
+                            Unlabeled branches
+                            Custom : Enter a branch label
+
+    --multiple-hits     Include support for multiple nucleotide substitutions
+                            Double : Include branch-specific rates for double nucleotide substitutions
+                            Double+Triple : Include branch-specific rates for double and triple nucleotide substitutions
+                            None [default] : Use standard models which permit only single nucleotide changes to occur instantly
+
+    --srv               Include synonymous rate variation (default: No)
+                            If Yes, then:
+                                --syn-rates         The number alpha rate classes to include in the model [1-10, default 3]
+
+    --blb               [Advanced option] Bag of Little Bootstraps (BLB) alignment resampling rate (default: 1.0). This parameter controls the fraction of sites to resample for each bootstrap replicate. BLB uses down/upsampling approaches to speed up inference for very long alignments by analyzing subsets of the data. For more details, see https://www.nature.com/articles/s43588-021-00129-5.
+
+    --output            Write the resulting JSON to this file (default is to save to the same path as the alignment file + 'ABSREL.json')
 
-                            Internal : test only internal branches (suitable for
-                            intra-host pathogen evolution for example, where terminal branches
-                            may contain polymorphism data)
+    --intermediate-fits Use/save parameter estimates from 'initial-guess' model fits to a JSON file (default is not to save)
 
-                            Leaves: test only terminal (leaf) branches
+    --kill-zero-lengths Automatically delete internal zero-length branches for computational efficiency
+                            Yes [default] : Automatically delete internal zero-length branches for computational efficiency (will not affect results otherwise)
+                            Constrain : Keep zero-length branches, but constrain their values to 0
+                            No : Keep all branches
 
-                            Unlabeled: if the Newick string is labeled using the {} notation,
-                            test only branches without explicit labels
-                            (see http://hyphy.org/tutorials/phylotree/)
+    --save-fit          Save full adaptive aBSREL model fit to this file (default is not to save)