annotate track_objects.xml @ 0:644e5e32a83c draft

"planemo upload for repository https://github.com/bgruening/galaxytools/tree/master/tools commit 35da2dcd86747c9bff138e100dbe08c6106f3780"

<tool id="cp_track_objects" name="TrackObjects" version="@CP_VERSION@" python_template_version="3.5">
    <description> tracking objects throughout sequential frames of a series of images</description>
    <macros>
        <import>macros.xml</import>
        <xml name="common">
            <conditional name="con_filter_by_lifetime">
                <param name="filter_by_lifetime" type="select" label="Filter objects by lifetime?" help = "Select Yes if you want objects to be filtered by their lifetime, i.e., total duration in frames. This is useful for marking objects which transiently appear and disappear, such as the results of a mis-segmentation.">
                    <option value="Yes">Yes</option>
                    <option value="No">No</option>
                </param>
                <when value="Yes">
                    <conditional name="con_use_min">
                        <param name="use_min" type="select" label="Filter using a minimum lifetime?" help = "Select Yes to filter the object on the basis of a minimum number of frames. ">
                            <option value="Yes">Yes</option>
                            <option value="No">No</option>
                        </param>
                        <when value="Yes">
                            <param name="min_lifetime" type="integer" value="1" label="Minimum lifetime" help = " Enter the minimum number of frames an object is permitted to persist. Objects which last this number of frames or lower are filtered out."/>
                        </when>
                        <when value="No">
                        </when>
                    </conditional>
                    <conditional name="con_use_max">
                        <param name="use_max" type="select" label="Filter using a maximum lifetime?" help = "Select Yes to filter the object on the basis of a maximum number of frames.">
                            <option value="Yes">Yes</option>
                            <option value="No">No</option>
                        </param>
                        <when value="Yes">
                            <param name="max_lifetime" type="integer" value="100" label="Maximum lifetime" help = "Enter the maximum number of frames an object is permitted to persist. Objects which last this number of frames or more are filtered out"/>
                        </when>
                        <when value="No">
                        </when>
                    </conditional>
                </when>
                <when value="No">
                </when>
            </conditional>
            <param name="display_option" type="select" label="Select display option">
                <option value="Color and Number">Color and Number</option>
                <option value="Color only">Color only</option>
            </param>
            <conditional name="con_save_coded_img">
                <param name="save_coded_img" type="select" label="Save color-coded image?">
                    <option value="Yes">Yes</option>
                    <option value="No">No</option>
                </param>
                <when value="Yes">
                    <param name="name_output_img" type="text" label="Name the output image"/>
                </when>
                <when value="No">
                </when>
            </conditional>
        </xml>

        <xml name="overlap_distance">
            <param name="max_distance" type="integer" value="50" label="Maximum pixel distance to consider matches">
                <help>
                    <![CDATA[
                        Objects in the subsequent frame will be considered potential matches if they are within this distance. 
                        To determine a suitable pixel distance, you can look at the axis increments on each image (shown in pixel units) or use the distance measurement tool. 
                        To measure distances in an open image, use the “Measure length” tool under Tools in the display window menu bar. If you click on an image and drag, a line will appear between the two endpoints, and the distance between them will be shown at the right-most portion of the bottom panel. 
                    ]]>
                </help>
            </param>
        </xml>

        <xml name="lap">
            <param name="movement_method" type="select" label="Select the movement model">
                <option value="Random">Random</option>
                <option value="Velocity">Velocity</option>
                <option value="Both">Both</option>
            </param>
            <param name="no_std_radius" type="float" value="3.0" label="Number of standard deviations for search radius" />
            <param name="min_radius" type="float" value="2.0" label="Minimum search radius in pixel units" />
            <param name="max_radius" type="float" value="10.0" label="Maximum search radius in pixel units" />

            <conditional name="con_second_lap">
                <param name="second_lap" type="select" label="Run the second phase of the LAP algorithm?">
                    <option value="Yes">Yes</option>
                    <option value="No">No</option>
                </param>
                <when value="Yes">
                    <param name="gap_closing" type="integer" value="50" label="Gap closing cost" />
                    <param name="split_alt" type="integer" value="50" label="Split alternative cost" />
                    <param name="merge_alt" type="integer" value="50" label="Merge alternative cost" />
                    <param name="mitosis_alt" type="integer" value="50" label="Mitosis alternative cost" />
                    <param name="max_gap_displacement" type="integer" value="50" label="Maximum gap displacement, in pixel units" />
                    <param name="max_split" type="integer" value="50" label="Maximum split score" />
                    <param name="max_merge" type="integer" value="50" label="Maximum merge score" />
                    <param name="max_temporal" type="integer" value="50" label="Maximum temporal gap, in frames" />
                    <param name="max_mitosis_distance" type="integer" value="50" label="Maximum mitosis distance, in pixel units" />
                </when>
                <when value="No">
                </when>
            </conditional>
        </xml>

        <xml name="measurements">
            <conditional name="con_measurement_category">
                <param name="measurement_category" type="select" label="Select object measurement category to use for tracking">
                    <option value="AreaShape">AreaShape</option>
                    <option value="Intensity">Intensity</option>
                    <option value="Location">Location</option>
                    <option value="Number">Number</option>
                </param>
                <when value="AreaShape">
                    <param name="measurement" type="select" label="Select object measurement to use for tracking">
                        <option value="Area">Area</option>
                        <option value="Center_X">Center_X</option>
                        <option value="Center_Y">Center_Y</option>
                        <option value="Center_Z">Center_Z</option>
                        <option value="Compactness">Compactness</option>
                        <option value="Eccentricity">Eccentricity</option>
                        <option value="EulerNumber">EulerNumber</option>
                        <option value="Extent">Extent</option>
                        <option value="FormFactor">FormFactor</option>
                        <option value="MajorAxisLength">MajorAxisLength</option>
                        <option value="MaxFeretDiameter">MaxFeretDiameter</option>
                        <option value="MaximumRadius">MaximumRadius</option>
                        <option value="MeanRadius">MeanRadius</option>
                        <option value="MedianRadius">MedianRadius</option>
                        <option value="MinFeretDiameter">MinFeretDiameter</option>
                        <option value="MinorAxisLength">MinorAxisLength</option>
                        <option value="Orientation">Orientation</option>
                        <option value="Perimeter">Perimeter</option>
                        <option value="Solidity">Solidity</option>
                    </param>
                </when>
                <when value="Intensity">
                    <param name="measurement" type="select" label="Select object measurement to use for tracking">
                        <option value="IntegratedIntensity">IntegratedIntensity</option>
                        <option value="IntegratedIntensityEdge">IntegratedIntensityEdge</option>
                        <option value="LowerQuartileIntensity">LowerQuartileIntensity</option>
                        <option value="MADIntensity">MADIntensity</option>
                        <option value="MassDisplacement">MassDisplacement</option>
                        <option value="MaxIntensity">MaxIntensity</option>
                        <option value="MaxIntensityEdge">MaxIntensityEdge</option>
                        <option value="MeanIntensity">MeanIntensity</option>
                        <option value="MeanIntensityEdge">MeanIntensityEdge</option>
                        <option value="MedianIntensity">MedianIntensity</option>
                        <option value="MinIntensity">MinIntensity</option>
                        <option value="MinIntensityEdge">MinIntensityEdge</option>
                        <option value="StdIntensity">StdIntensity</option>
                        <option value="StdIntensityEdge">StdIntensityEdge</option>
                        <option value="UpperQuartileIntensity">UpperQuartileIntensity</option>
                    </param>
                    <param name="img_measure" type="text" label="Image"/>
                </when>
                <when value="Location">
                    <param name="measurement" type="select" label="Select object measurement to use for tracking">
                        <option value="CenterMassIntensity_X">CenterMassIntensity_X</option>
                        <option value="CenterMassIntensity_Y">CenterMassIntensity_Y</option>
                        <option value="CenterMassIntensity_Z">CenterMassIntensity_Z</option>
                        <option value="Center_X">Center_X</option>
                        <option value="Center_Y">Center_Y</option>
                        <option value="Center_Z">Center_Z</option>
                        <option value="MaxIntensity_X">MaxIntensity_X</option>
                        <option value="MaxIntensity_Y">MaxIntensity_Y</option>
                        <option value="MaxIntensity_Z">MaxIntensity_Z</option>
                    </param>
                    <param name="img_measure" type="text" label="Image"/>
                </when>
                <when value="Number">
                    <param name="measurement" type="select" label="Select object measurement to use for tracking">
                        <option value="ObjectNumber">ObjectNumber</option>
                    </param>
                </when>
            </conditional>
            <param name="max_distance" type="integer" value="50" label="Maximum pixel distance to consider matches" >
                <help>
                    <![CDATA[
                        Objects in the subsequent frame will be considered potential matches if they are within this distance. 
                        To determine a suitable pixel distance, you can look at the axis increments on each image (shown in pixel units) or use the distance measurement tool. 
                        To measure distances in an open image, use the “Measure length” tool under Tools in the display window menu bar. If you click on an image and drag, a line will appear between the two endpoints, and the distance between them will be shown at the right-most portion of the bottom panel. " 
                    ]]>
                </help>
            </param>
        </xml>

        <xml name="follow_neighbors">
            <param name="max_distance" type="integer" value="50" label="Maximum pixel distance to consider matches">
                <help>
                    <![CDATA[
                        Objects in the subsequent frame will be considered potential matches if they are within this distance. 
                        To determine a suitable pixel distance, you can look at the axis increments on each image (shown in pixel units) or use the distance measurement tool.
                        To measure distances in an open image, use the “Measure length” tool under Tools in the display window menu bar. If you click on an image and drag, a line will appear between the two endpoints, and the distance between them will be shown at the right-most portion of the bottom panel. 
                    ]]>
                </help>
            </param>
            <param name="avg_diameter" type="float" value="35.0" label="Average cell diameter in pixels">
                <help>
                    <![CDATA[
                        The average cell diameter is used to scale many Follow Neighbors algorithm parameters.
                        To measure distances in an open image, use the “Measure length” tool under Tools in the display window menu bar. If you click on an image and drag, a line will appear between the two endpoints, and the distance between them will be shown at the right-most portion of the bottom panel. 
                    ]]>
                </help>
            </param>

            <conditional name="con_adv_parameter">
                <param name="adv_parameter" type="select" label="Use advanced configuration parameters">
                    <option value="Yes">Yes</option>
                    <option value="No">No</option>
                </param>
                <when value="Yes">
                    <param name="cost" type="float" value="15.0" label="Cost of cell to empty matching" />
                    <param name="weight" type="float" value="25.0" label="Weight of area difference in function matching cost" />
                </when>
                <when value="No">
                </when>
            </conditional>

        </xml>
    </macros>
    <expand macro="py_requirements"/>
    <command detect_errors="exit_code">
        <![CDATA[
            python '$__tool_directory__/track_objects.py' -p '$input_pipeline' -i '$input_json'
            ]]>
    </command>
    <configfiles>
        <inputs name="input_json"/>
    </configfiles>
    <inputs>
        <expand macro="input_pipeline_param"/>
        <param name="object_to_track" type="text" label="Enter the name of the objects to track" help="The object to track from previous IdentifyPrimaryObjects module" />
        <conditional name="con_tracking_method">
            <param name="tracking_method" type="select" label="Choose a tracking method">
                <help>
                    <![CDATA[
                        <i>Overlap:</i> Compares the amount of spatial overlap between identified objects in the previous frame with those in the current frame. The object with the greatest amount of spatial overlap will be assigned the same number.
                        <i>Distance:</i> Compares the distance between each identified object in the previous frame with that of the current frame. The closest objects to each other will be assigned the same number (label). Distances are measured from the perimeter of each object. 
                        <i>Measurements:</i> Compares each object in the current frame with objects in the previous frame based on a particular feature you have measured for the objects. This approach assumes objects move in a coordinated way (contrary to LAP). An object's movement direction is more likely to be in agreement with the movement directions of its neighbors. The problem is formulated as an optimization problem and solved using LAP algorithm (same as in LAP method).
                        <i>LAP:</i> Uses the linear assignment problem (LAP) framework. The linear assignment problem (LAP) algorithm (Jaqaman et al., 2008) addresses the challenges of high object density, motion heterogeneity, temporary disappearances, and object merging and splitting. 
                        <i>Follow Neighbors:</i> Uses the multiobject tracking approach described by Delgado-Gonzalo et al., 2010. This approach assumes objects move in a coordinated way (contrary to LAP). An object's movement direction is more likely to be in agreement with the movement directions of its "neighbor" The problem is formulated as an optimization problem and solved using LAP algorithm (same as in LAP method)."
                    ]]>
                </help>
                <option value="Overlap">Overlap</option>
                <option value="Distance">Distance</option>
                <option value="Measurements">Measurements</option>
                <option value="LAP">LAP</option>
                <option value="Follow Neighbors">Follow Neighbors</option>
            </param>
            <when value="Overlap">
                <expand macro="overlap_distance" />
                <expand macro="common" />
            </when>
            <when value="Distance">
                <expand macro="overlap_distance" />
                <expand macro="common" />
            </when>
            <when value="Measurements">
                <expand macro="measurements" />
                <expand macro="common" />
            </when>
            <when value="LAP">
                <expand macro="lap" />
                <expand macro="common" />
            </when>
            <when value="Follow Neighbors">
                <expand macro="follow_neighbors" />
                <expand macro="common" />
            </when>
        </conditional>
    </inputs>
    <outputs>
        <expand macro="output_pipeline_param" />
    </outputs>
    <tests>
        <test>
            <param name="input_pipeline" value="common.cppipe"/>
            <param name="object_to_track" value="Embryos" />
            <conditional name="con_tracking_method">
                <param name="tracking_method" value="Overlap" />
                <param name="max_distance" value="50" />
                <conditional name="con_filter_by_lifetime">
                    <param name="filter_by_lifetime" value="No" />
                </conditional>
                <param name="display_option" value="Color and Number" />
                <conditional name="con_save_coded_img">
                    <param name="save_coded_img" value="Yes" />
                    <param name="name_output_img" value="TrackedCells"/>
                </conditional>
            </conditional>
            <expand macro="test_out_file" file="track_object.cppipe" />
        </test>
        <test>
            <param name="input_pipeline" value="common.cppipe"/>
            <param name="object_to_track" value="DNA" />
            <conditional name="con_tracking_method">
                <param name="tracking_method" value="Overlap" />
                <param name="max_distance" value="40" />
                <conditional name="con_filter_by_lifetime">
                    <param name="filter_by_lifetime" value="Yes" />
                    <conditional name="con_use_min">
                        <param name="use_min" value="Yes" />
                        <param name="min_lifetime" value= "2"/>
                    </conditional>
                    <conditional name="con_use_max">
                        <param name="use_max" value = "No" />
                    </conditional>
                </conditional>
                <param name="display_option" value="Color only" />
                <conditional name="con_save_coded_img">
                    <param name="save_coded_img" value="Yes" />
                    <param name="name_output_img" value="ColorCodedImage"/>
                </conditional>
            </conditional>
            <expand macro="test_out_file" file="track_object_overlap_no_filter_max.cppipe" />
        </test>
        <test>
            <param name="input_pipeline" value="common.cppipe"/>
            <param name="object_to_track" value="DNA" />
            <conditional name="con_tracking_method">
                <param name="tracking_method" value="Distance" />
                <param name="max_distance" value="50" />
                <conditional name="con_filter_by_lifetime">
                    <param name="filter_by_lifetime" value="Yes" />
                    <conditional name="con_use_min">
                        <param name="use_min" value="No" />
                    </conditional>
                    <conditional name="con_use_max">
                        <param name="use_max" value = "Yes" />
                        <param name="max_lifetime" value= "80"/>
                    </conditional>
                </conditional>
                <param name="display_option" value="Color and Number" />
                <conditional name="con_save_coded_img">
                    <param name="save_coded_img" value="Yes" />
                    <param name="name_output_img" value="OutputImage"/>
                </conditional>
            </conditional>
            <expand macro="test_out_file" file="track_object_distance_no_filter_min.cppipe" />
        </test>
        <test>
            <param name="input_pipeline" value="common.cppipe"/>
            <param name="object_to_track" value="DNA" />
            <conditional name="con_tracking_method">
                <param name="tracking_method" value="Measurements" />
                <conditional name="con_measurement_category">
                    <param name="measurement_category" value = "Intensity" />
                    <param name="measurement" value = "MADIntensity"/>
                    <param name="img_measure" value = "Image1"/>
                </conditional>
                <param name="max_distance" value= "40" /> 
                <conditional name="con_filter_by_lifetime">
                    <param name="filter_by_lifetime" value="Yes" />
                    <conditional name="con_use_min">
                        <param name="use_min" value="No" />
                    </conditional>
                    <conditional name="con_use_max">
                        <param name="use_max" value = "Yes" />
                         <param name="max_lifetime" value= "120"/>
                    </conditional>
                </conditional>
                <param name="display_option" value="Color only" />
                <conditional name="con_save_coded_img">
                    <param name="save_coded_img" value="No" />
                </conditional>
            </conditional>
            <expand macro="test_out_file" file="track_object_measurement_intensity.cppipe" />
        </test>
        <test>
            <param name="input_pipeline" value="common.cppipe"/>
            <param name="object_to_track" value="DNA" />
            <conditional name="con_tracking_method">
                <param name="tracking_method" value="LAP" />
                <param name="movement_method" value="Velocity" />
                <param name="no_std_radius"  value="4.0" />
                <param name="min_radius" value="5.0"/>
                <param name="max_radius" value="11.0"/>
                <conditional name="con_second_lap">
                    <param name="second_lap" value="Yes" />
                    <param name="gap_closing" value = "6"/>
                    <param name="split_alt" value = "6" />
                    <param name="merge_alt" value = "6"/>
                    <param name="mitosis_alt" value = "6" />
                    <param name="max_gap_displacement" value = "6"/>
                    <param name="max_split" value = "6" />
                    <param name="max_merge" value = "6" />
                    <param name="max_temporal" value = "6" />
                    <param name="max_mitosis_distance" value = "6" />
                </conditional>
                <conditional name="con_filter_by_lifetime">
                    <param name="filter_by_lifetime" value="Yes" />
                    <conditional name="con_use_min">
                        <param name="use_min" value="Yes" />
                        <param name="min_lifetime" value= "1"/>
                    </conditional>
                    <conditional name="con_use_max">
                        <param name="use_max" value = "Yes" />
                        <param name="max_lifetime" value= "100"/>
                    </conditional>
                </conditional>
                <param name="display_option" value="Color and Number" />
                <conditional name="con_save_coded_img">
                    <param name="save_coded_img" value="Yes" />
                    <param name="name_output_img" value="OutputImage"/>
                </conditional>
            </conditional>
            <expand macro="test_out_file" file="track_object_lap_velocity.cppipe" />
        </test>
        <test>
            <param name="input_pipeline" value="common.cppipe"/>
            <param name="object_to_track" value="DNA" />
            <conditional name="con_tracking_method">
                <param name="tracking_method" value = "Follow Neighbors" />
                <param name="max_distance" value = "60" />
                <param name="avg_diameter" value = "36.0" />
                <conditional name="con_adv_parameter">
                    <param name="adv_parameter" value = "Yes" />
                    <param name="cost" value = "11.0" />
                    <param name="weight" value = "20.0" />
                </conditional>
                <conditional name="con_filter_by_lifetime">
                    <param name="filter_by_lifetime" value="Yes" />
                    <conditional name="con_use_min">
                        <param name="use_min" value="No" />
                    </conditional>
                    <conditional name="con_use_max">
                        <param name="use_max" value = "No" />
                    </conditional>
                </conditional>
                <param name="display_option" value="Color only" />
                <conditional name="con_save_coded_img">
                    <param name="save_coded_img" value="Yes" />
                    <param name="name_output_img" value="OutputImage"/>
                </conditional>
            </conditional>
            <expand macro="test_out_file" file="track_object_follow_neighbors.cppipe" />
        </test>
    </tests>
    
    <help>
        <![CDATA[

            .. class:: infomark

            **What it does**

            This module allows tracking objects throughout sequential frames of a series of images, so that from frame to frame each object maintains a unique identity in the output measurements.

            This module must be placed downstream of a module that identifies objects (e.g., IdentifyPrimaryObjects). TrackObjects will associate each object with the same object in the frames before and after. This allows the study of objects' lineages and the timing and characteristics of dynamic events in movies. 

            @COMMON_HELP@
            ]]>
    </help>
    <expand macro="citations"/>
</tool>