annotate spyboat.xml @ 2:4626a83601d4 draft

"planemo upload for repository https://github.com/galaxyproject/tools-iuc/tree/master/packages/spyboat commit b5cdb8bbc5334d5ff05b3e2fcc13c574832d2dd9"

<tool id="spyboat" name="SpyBOAT" version="@TOOL_VERSION@" profile="20.01"  license="GPL-3.0-or-later">
<description>wavelet analyzes image stacks</description>
    <macros>
        <token name="@TOOL_VERSION@">0.1.1</token>
    </macros>
    <requirements>
        <requirement type="package" version="@TOOL_VERSION@">spyboat</requirement>
    </requirements>
    <version_command>python '$__tool_directory__/spyboat_cli.py' --version</version_command>
    <command detect_errors="exit_code"><![CDATA[
        ## needed for pulsar combat
        cat '$__tool_directory__/output_report.py' > /dev/null &&
        ## run tool
        python '$__tool_directory__/spyboat_cli.py'
        --input_path '$movie'
        #if str($PreProc.gauss_sigma):
            --gauss_sigma $PreProc.gauss_sigma
        #end if
        #if str($PreProc.rescale_factor):
            --rescale $PreProc.rescale_factor
        #end if

        #if $masking.selection_mode == "create_static_mask":
            --masking static
            --mask_frame $masking.mask_frame
            --mask_thresh $masking.mask_thresh
        #else if $masking.selection_mode == "create_dynamic_mask":
            --masking dynamic
            --mask_thresh $masking.mask_thresh
        #end if

        --dt $wavana.dt
        --Tmin $wavana.tmin
        --Tmax $wavana.tmax
        --nT $wavana.nt
        #if str($wavana.tcutoff)
             --Tcutoff $wavana.tcutoff
        #end if
        #if str($wavana.win_size):
             --win_size $wavana.win_size
        #end if

        #if 'save_phase' in $outputs:
            --phase_out '$phase_out'
        #end if

        #if 'save_period' in $outputs:
            --period_out '$period_out'
        #end if

        #if 'save_power' in $outputs:
            --power_out '$power_out'
        #end if

        #if 'save_amplitude' in $outputs:
            --amplitude_out '$amplitude_out'
        #end if

        #if 'save_preprocessed' in $outputs:
            --preprocessed_out '$preprocessed_out'
        #end if

        --html_fname '$html_out'
        --report_img_path '$html_out.extra_files_path'

        --ncpu "\${GALAXY_SLOTS:-8}"


      ]]></command>
    <inputs>
        <param name="movie" type="data" format="tiff" label="Movie to analyze" help="Select a movie to wavelet analyze"/>

        <!--
        The following Wavelet parameters must have the same numerical type as defined in the
        argparse parser in spyboat_cli.py
        -->
        <section name="PreProc" title="Preprocessing" expanded="true">
          <param argument="gauss_sigma" type="float" min="0" max="100" optional="true" label="Sigma"
               help="Width of the Gaussian smoothing kernel, leave blank if no pre-smoothing desired" />
          <param argument="rescale_factor" type="integer" value="" min="0" max="99" optional="true" label="Rescale factor"
               help="Downsamples the input movie by this factor given in %, leave blank to disable downsampling" />
        </section>
        <section name="wavana" title="Wavelet Analysis" expanded="true">
            <param name="dt" type="float" value="1" min="0" max="1000" label="Sampling interval" help="Time span between two frames" />
            <param name="tmin" type="float" value="20" min="0" max="2000" label="Smallest period" help="Lowest period for the wavelet transform" />
            <param name="tmax" type="float" value="30" min="0" max="10000" label="Largest period"
                help="Largest period for the wavelet transform" />
            <param name="nt" type="integer" value="150" min="0" max="1000" label="Number of periods to scan for"
                help="Determines period resolution of the Wavelet power spectra" />
            <param name="tcutoff" type="float" value="40" min="0" max="10000" label="T cutoff"
                help="Cut-off-period for sinc filter detrending, a blank field disables detrending" optional="true" />
            <param name="win_size" type="float" value="" min="0" max="10000" optional="true" label="Sliding window size"
                help="Window size for amplitude envelope estimation, leave blank to disable normalization" />
        </section>
        <conditional name="masking">
            <param name="selection_mode" type="select" label="Masking the output" help="Create a mask from the (blurred/rescaled) input to mask out regions without oscillations/signal in the output">
                <option selected="true" value="no_masking">No masking</option>
                <option value="create_static_mask">Create a static mask</option>
                <option value="create_dynamic_mask">Create a dynamic mask</option>
            </param>
            <when value="no_masking" />
            <when value="create_static_mask">
                <param name="mask_frame" type="integer" value="1" min="1" max="5000" label="Create mask from frame"
                       help="Creates a static mask from the chosen frame of the input movie." />
                <param name="mask_thresh" type="float" value="0" min="0" max="65000" label="Threshold"
                       help="All pixels below this threshold will be masked in the output." />
            </when>
            <when value="create_dynamic_mask">
                <param name="mask_thresh" type="float" value="0" min="0" max="65000" label="Threshold"
                       help="For each frame of the input, all pixels below this threshold will be masked in the output." />
            </when>
        </conditional>
        <param name="outputs" type="select" optional="true" multiple="true" label="Select optional outputs" help="" display="checkboxes">
            <option value="save_phase">Phase Movie</option>
            <option value="save_period">Period Movie</option>
            <option value="save_amplitude">Amplitude Movie</option>
            <option value="save_power">Power Movie</option>
            <option value="save_preprocessed">Preprocessed Movie</option>
        </param>
    </inputs>

    <outputs>
        <data name="phase_out" format="tiff" label="${movie.name[:-4]}_phase">
            <filter>outputs and 'save_phase' in outputs</filter>
        </data>
        <data name="period_out" format="tiff" label="${movie.name[:-4]}_period">
            <filter>outputs and 'save_period' in outputs</filter>
        </data>
        <data name="power_out" format="tiff" label="${movie.name[:-4]}_power">
            <filter>outputs and "save_power" in outputs</filter>
        </data>
        <data name="amplitude_out" format="tiff" label="${movie.name[:-4]}_amplitude">
            <filter>outputs and 'save_amplitude' in outputs</filter>
        </data>
        <data name="preprocessed_out" format="tiff" label="${movie.name[:-4]}_preproc">
            <filter>outputs and 'save_preprocessed' in outputs</filter>
        </data>
        <data name="html_out" format="html" label="Report ${movie.name[:-4]}" />
    </outputs>

    <tests>
        <test expect_num_outputs="2">
            <param name="movie" value="test-movie.tif" ftype="tiff"/>
            <param name="outputs" value="save_phase"/>
            <conditional name="masking">
                <param name="selection_mode" value="no_masking" />
            </conditional>
            <output name="phase_out" ftype="tiff">
                <assert_contents>
                    <has_size value="1764430" delta="10000" />
                </assert_contents>
            </output>
            <output name="html_out" file="output1.html" ftype="html"/>
        </test>
        <test expect_num_outputs="4">
            <section name="wavana">
                <param name="tmin" value="20"/>
                <param name="nt" value="150"/>
                <param name="tcutoff" value="40"/>
            </section>
            <conditional name="masking">
                <param name="selection_mode" value="create_static_mask" />
            </conditional>
            <param name="movie" value="test-movie.tif" ftype="tiff"/>
            <param name="outputs" value="save_phase,save_preprocessed,save_power"/>
            <output name="phase_out" ftype="tiff">
                <assert_contents>
                    <has_size value="1764430" delta="10000" />
                </assert_contents>
            </output>
        </test>
        <test expect_num_outputs="4">
            <section name="wavana">
                <param name="tmin" value="20"/>
                <param name="nt" value="150"/>
                <param name="tcutoff" value="40"/>
            </section>
            <conditional name="masking">
                <param name="selection_mode" value="create_dynamic_mask" />
            </conditional>
            <param name="movie" value="test-movie.tif" ftype="tiff"/>
            <param name="outputs" value="save_phase,save_preprocessed,save_power"/>
            <output name="phase_out" ftype="tiff">
                <assert_contents>
                    <has_size value="1764430" delta="10000" />
                </assert_contents>
            </output>
        </test>
    </tests>
    <help><![CDATA[
.. class:: infomark

**What it does**

-------------------

    Wavelet transforms a 3d-image stack (time,Y,X) pixel by pixel along the time axis and extracts/evaluates the wavelet ridge. Removal of low-frequency trends is provided via sinc filtering. 
    There are four output movies generated (phase, period, amplitude and power). They have exactly the same dimensions (time,Y,X) as the (rescaled) input.

    Pre-smoothing of the data with Gaussian kernels is supported and often recommendable.

    To limit the number of Wavelet transformations (computing time), downscaling of the input movie resolution is recommended. 
    Trimming away parts of the movie with no relevant data (e.g. outer dark edges) also speeds up the processing.

    If multiple channels are present in your data, extract the channel of interest beforehand (e.g. with Fiji).

    **Author**: Gregor Mönke ([e-mail]).

    **Wrapper by**: Jelle Scholtalbers ([e-mail]).

    **Know what you are doing**

    .. class:: warningmark

    You need to have a basic understanding of time-frequency analysis with Wavelets, find more information about the analysis strategy employed at https://github.com/tensionhead/pyBOAT or the publication cited below.

-------------------

**Parameter List**

    - Sigma:
        The Kernel bandwidth (in pixels) for the Gaussian kernels to use for pre-smoothing the input data. The default value of zero means that no pre-smoothing is done. Set this number to a desired kernel width to turn on pre-smoothing.

    - Rescale factor:
        Given in %, downsamples the spatial resolution of the input movie. This speeds up the whole analysis by a lot.

    - Masking:
       SpyBOAT offers 'static' and 'dynamic' masking. 'static' means that a single mask is created by thresholding from a user selected frame. 'dynamic' creates a mask for each frame by thresholding, works better for moving/expanding/shrinking oscillatory fields. 

    - Sampling interval:
        Time passed between consecutive measurements, e.g 'an image every 10 minutes'.

    - Smallest Period:
        The minimal period to scan for, this is the higher (in frequency) end of the spectrum. A warning will be given during processing if the chosen value deceeds the Nyquist limit (2 times the sampling interval).

    - Largest period:
        The maximal period to scan for, this is the lower (in frequency) end of the spectrum. The inbuild Sinc filter will remove any periods larger than this form the data. Due to the 'roll off' of the filter, this value should be chosen generously. A warning will be given during processing if the chosen value exceeds the length of the time series.

    - Number of periods to scan for:
        This is the the number of convolutions computed per pixel.

        Spectral resolution =  ( biggest period - smallest period ) / number of periods

    - Tcutoff:
        The cut-off period for the sinc filter, periods larger than this one will
        be removed from the signal before the transform. If no value is given,
        no detrending is performed. At least a gracious cut-off of around ~3 times
        the largest period to be expected is recommended.
    
    - Sliding window size
        Length (in time units, e.g. hours) of the sliding window to estimate
        an amplitude envelope. The signal then gets normalized by this envelope,
        meaning that all amplitudes will be around ~1 after the transform. The 
        advantage is that signal with strong amplitude trends will have more
        meaningful Wavelet powers after normalization.


    ]]></help>
    <citations>
        <citation type="doi">10.1101/2020.04.29.067744</citation>
   </citations>
</tool>