annotate SpyBOAT.xml @ 1:97fd3740f41c draft

"planemo upload commit eeba34c94465f41d13c2f5bcf68177d23c92d971"

<tool id="SpyBOAT" name="SpyBOAT" version="0.0.1">
    <requirements>
        <requirement type="package" version="0.0.4">spyboat</requirement>
    </requirements>
    <version_command>python $__tool_directory__/cl_wrapper.py --version</version_command>
    <command detect_errors="exit_code"><![CDATA[
        python $__tool_directory__/cl_wrapper.py
          --input_path '$movie'
          #if $gauss_sigma:
             --gauss_sigma $gauss_sigma
          #end if
          #if $rescale_factor:
              --rescale $rescale_factor
          #end if

          #if $masking.selection_mode == "create_fixed_mask":
	  --masking fixed
          --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 $dt
          --Tmin $tmin
          --Tmax $tmax
          --nT $nt
	  #if $tcutoff
             --Tcutoff $tcutoff
	  #end if
          #if $win_size:
             --win_size $win_size
          #end if

          --phase_out $phase_out
          --period_out $period_out
          --power_out $power_out
          --amplitude_out $amplitude_out
	  #if $preprocessed_out:
	     --preprocessed_out $preprocessed_out
	  #end if

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

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

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

        <!--
        The following Wavelet parameters must have the same numerical type as defined in the
        argparse parser in cl_wrapper.py
        -->

        <param name="gauss_sigma" type="float" label="Sigma" 
               help="Width of the Gaussian smoothing kernel, leave blank if no pre-smoothing desired." optional="true">
            <validator type="in_range" min="0" max="9999999"/>
        </param>

        <param name="rescale_factor" type="integer" value="" label="Rescale factor"
               help="Downsamples the input movie by this factor given in %, leave blank to disable downsampling"
               optional="true">
            <validator type="in_range" min="0" max="99"/>
        </param>

        <conditional name="masking">
            <param label="Masking the output" name="selection_mode" type="select" 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_fixed_mask">Create a fixed mask</option>
		<option value="create_dynamic_mask">Create a dynamic mask</option>
	    </param>
            <when value="create_fixed_mask">
                <param name="mask_frame" type="integer" value="1" label="Create mask from frame"
                       help="Creates a fixed mask from the chosen frame of the input movie.">
                    <validator type="in_range" min="1" max="99999"/>
                </param>
                <param name="mask_thresh" type="float" value="0" label="Threshold"
                       help="All pixels below this threshold will be masked in the output.">
                    <validator type="in_range" min="0" max="999999"/>
                </param>
            </when>
            <when value="create_dynamic_mask">
                <param name="mask_thresh" type="float" value="0" label="Threshold"
                       help="For each frame of the input, all pixels below this threshold will be masked in the output.">
                    <validator type="in_range" min="0" max="999999"/>
                </param>
            </when>	    
        </conditional>

        <param name="dt" type="float" value="1" label="Sampling interval" help="Time span between two frames">
            <validator type="in_range" min="0" max="9999999"/>
        </param>
        <param name="tmin" type="float" value="2" label="Smallest period" help="Minimal period to scan for">
            <validator type="in_range" min="0" max="9999999"/>
        </param>

        <param name="tmax" type="float" value="30" label="Largest period"
               help="Maximal period to scan for">
            <validator type="in_range" min="0" max="9999999"/>
        </param>

        <param name="nt" type="integer" value="150" label="Number of periods to scan for"
               help="Determines period resolution of the Wavelet power spectra">
            <validator type="in_range" min="0" max="9999999"/>
        </param>

        <param name="tcutoff" type="float" value="40" label="Tcutoff"
               help="Cut-off-period for sinc filter detrending, a blank field disables detrending" optional="true">
            <validator type="in_range" min="0" max="9999999"/>
        </param>

        <param name="win_size" type="float" value="" label="Sliding window size"
               help="Window size for amplitude envelope estimation, leave blank to disable normalization "
               optional="true">
            <validator type="in_range" min="0" max="9999999"/>
        </param>

        <conditional name="save_preprocessed">
            <param label="Save preprocessed input" name="selection" type="select" help="Save the blurred/rescaled input to history? ">
                <option selected="true" value="No">No</option>
                <option value="Yes">Yes</option>
	    </param>
	</conditional>
    </inputs>

    <outputs>
        <data name="phase_out" format="tiff" label="phase_${movie.name}"/>
        <data name="period_out" format="tiff" label="period_${movie.name}"/>
        <data name="power_out" format="tiff" label="power_${movie.name}"/>
        <data name="amplitude_out" format="tiff" label="amplitude_${movie.name}"/>
	<data name="preprocessed_out" format="tiff" label="preproc_${movie.name}">
	  <filter>save_preprocessed['selection'] == 'Yes'</filter>
	</data>
	
        <data name="log" format="txt" label="log_${movie.name}.txt"/>
	<data format="html" name="html_out" label="Report_${movie.name}"/>

    </outputs>

    <tests>
        <test>
            <param name="movie" value="test_movie.tif" ftype="tiff"/>
            <output name="phase_out" file="phase_out.tif" ftype="tiff" compare="sim_size"/>
            <output name="period_out" file="period_out.tif" ftype="tiff" compare="sim_size"/>
            <output name="power_out" file="power_out.tif" ftype="tiff" compare="sim_size"/>
            <output name="amplitude_out" file="amplitude_out.tif" ftype="tiff" compare="sim_size"/>
        </test>
    </tests>
    <help><![CDATA[
    **What it does**

    Wavelet transforms a 3d-image stack (time,Y,X) pixel by pixel 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 will want to have understood the basics of time-frequency analysis with Wavelets, find more information about the analysis strategy employed at https://github.com/tensionhead/pyBOAT

    **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.

    - 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>
</tool>