<tool id="raceid_inspecttrajectory" name="Lineage Branch Analysis using StemID" version="@VERSION_RACEID@.@VERSION_WRAPPER@" >
    <description>inspects branches of a lineage tree</description>
    <macros>
        <import>macros.xml</import>
        <import>macros_cheetah.xml</import>
    </macros>
    <expand macro="requirements" />
    <expand macro="version_command_config" prog="trajectoryinspect.R" cheetah="INSPECTTRAJECTORIES_CHEETAH" />
    <inputs>
        <param name="inputrds" type="data" format="rdata" label="Input RDS" help="Requires the RDS output from the trajectory analysis" />
        <section name="trjsid" title="StemID Branch Link Examine" expanded="true" help="StemID derives cell lineage trees and predicts multipotent cell identities">
            <conditional name="basic" >
                <param name="doit" type="select" label="Perform StemID?" >
                    <expand macro="yesno_checkedno" />
                </param>
                <when value="no" />
                <when value="yes" >
                    <param name="i" type="integer" min="1" value="1" label="Cluster Number" />
                    <param name="br" type="text" label="Trajectory Path i, j, k" help="A path of three clusters starting at i, passing through j, and ending at k." >
                        <expand macro="sanitize_numeric_vector" />
                    </param>
                    <expand macro="use_defaults_no">
                        <param name="zscore" type="boolean" checked="false" label="Plot Z-score Transformed Projections" />
                        <param name="ndiffgenes" type="integer" min="1" value="10" label="Number of DE Genes" help="Number of differentially expressed genes to output per cluster" />
                    </expand>
                </when>
            </conditional>
        </section>
        <section name="trjfid" title="FateID Branch Link Examine" expanded="true" help="FateID infers cell fate bias in multipotent progenitor cells" >
            <conditional name="basic" >
                <param name="doit" type="select" label="Perform FateID?" >
                    <expand macro="yesno_checkedno" />
                </param>
                <when value="no" />
                <when value="yes" >
                    <param name="cellsfromz" type="text" value="" label="Cells from Clusters" help="Vector of valid cluster numbers ordered along the trajectory" >
                        <expand macro="sanitize_numeric_vector" />
                    </param>
                    <expand macro="use_defaults_no">
                        <param name="filterset_minexpr" type="integer" min="0" value="2" label="Min Expression" help="Minimum expression required for at least minnumber cells" />
                        <param name="filterset_minnumber" type="integer" min="0" value="1" label="Min Number of Cells" help="Minimum number of cells in which a gene needs to be expressed at least a level of minexpr."/>
                        <param name="getsom_nb" type="integer" min="1" value="1000" label="SOM Nodes" help="Number of nodes of the self-organizing map." />
                        <param name="getsom_alpha" type="float" min="0" value="0.5" label="Smoothing parameter" help="Pseudo-temporal expression profiles are derived by a local regression of expression values across the ordered cells using the function 'loess' from the package 'stats'. This is the parameter, which controls the degree of smoothing. Larger values return smoother profiles." />
                        <param name="procsom_corthr" type="float" min="0" max="1" value="0.85" label="Correlation threshold" help="The z-score of the average normalized pseudo-temporal expression profiles within each node of the self-organizing map is computed, and the correlation of these z-scores between neighbouring nodes is computed. If the correlation is greater than 'corthr', neighbouring nodes are merged" />
                        <param name="procsom_minsom" type="integer" min="0" value="3" label="Min SOM" help="Nodes of the self-organizing map with less than this number of transcripts are discarded" />
                        <param name="plotheat_xgrid" type="boolean" checked="false" label="Partitioning along the x-axis" />
                        <param name="plotheat_ygrid" type="boolean" checked="false" label="Partitioning along the y-axis" />
                        <param name="plotheat_xlab" type="boolean" checked="false" label="Average position is given for each partition along the x-axis" />
                    </expand>
                    <conditional name="som" >
                        <param name="doit" type="select" label="Perform Additional FateID Analysis with Self-Organised Map?" >
                            <expand macro="yesno_checkedno" />
                        </param>
                        <when value="no" />
                        <when value="yes" >
                            <conditional name="use_genes" >
                                <param name="typer" type="select" label="Genes to Inspect" >
                                    <option value="genelist">List of Genes</option>
                                    <option value="cln">Cluster</option>
                                </param>
                                <when value="genelist">
                                    <param name="use_genes" type="text" value="" label="Gene List" >
                                        <expand macro="sanitize_string_vector" />
                                    </param>
                                </when>
                                <when value="cln" >
                                    <param name="use_genes" type="integer" min="1" value="1" label="Cluster Number" />
                                </when>
                            </conditional>
                            <param name="use_types" type="text" value="\\_\\d+" label="Types Regex (select)" help="Regex to select types across cell names" >
                                <expand macro="sanitize_regex" />
                            </param>
                            <param name="title" type="text" value="Title" label="Plot title" />
                            <expand macro="use_defaults_no">
                                <param name="cluster" type="boolean" checked="false" label="Partitioning along the x-axis" />
                                <param name="alpha" type="float" min="0" max="1" value="0.5" label="Smoothing parameter" />
                            </expand>
                        </when>
                    </conditional>
                </when>
            </conditional>
        </section>
    </inputs>

    <outputs>
        <data name="outpdf" format="pdf" label="${tool.name} on ${on_string}: PDF Report" />
        <data name="outdiffgenes" format="tabular" label="${tool.name} on ${on_string}: TrajectoryInspect - Differential Genes" >
            <filter>trjsid['basic']['doit'] == "yes"</filter>
        </data>
        <data name="outlog" format="txt" label="${tool.name} on ${on_string}: Log" >
            <filter>use_log</filter>
        </data>

    </outputs>
    <tests>
        <test>
            <!-- default, generates a blank report -->
            <param name="inputrds" value="out_traject_default.ltree.rdat" />
            <output name="outpdf" value="out_traject_inspect_default.ltree.blank.pdf" compare="sim_size" delta="15" />
        </test>
        <test>
            <!-- stemID branch inspection: vignette search "getproj" -->
            <param name="inputrds" value="out_traject_default.ltree.rdat" />
            <section name="trjsid" >
                <conditional name="basic" >
                    <param name="doit" value="yes" />
                    <param name="i" value="3" />
                    <param name="br" value="1,3,8" />
                </conditional>
            </section>
            <output name="outpdf" value="out_traject_inspect_stemid.pdf" compare="sim_size" delta="30" />
            <output name="outdiffgenes" value="out_traject_inspect_stemid.tabular" />
        </test>
        <test>
            <!-- fateID trajectory inspection: vignette search "cellsfromtree" -->
            <param name="inputrds" value="out_traject_default.ltree.rdat" />
            <section name="trjfid" >
                <conditional name="basic" >
                    <param name="doit" value="yes" />
                    <param name="cellsfromz" value="2,1,4" />
                    <expand macro="test_nondef" >
                        <param name="filterset_minexpr" value="2" />
                        <param name="getsom_nb" value="1000" />
                        <param name="getsom_alpha" value="0.5" />
                        <param name="plotheat_xlab" value="true" />
                    </expand>
                </conditional>
            </section>
            <output name="outpdf" value="out_traject_inspect_fateid.pdf" compare="sim_size" delta="15" />
        </test>
        <test>
            <!-- fateID trajectory inspection with som: vignette search "SOM" -->
            <param name="inputrds" value="out_traject_default.ltree.rdat" />
            <section name="trjfid" >
                <conditional name="basic" >
                    <param name="doit" value="yes" />
                    <param name="cellsfromz" value="2,1,4" />
                    <conditional name="som" >
                        <param name="doit" value="yes" />
                        <expand macro="test_nondef" >
                            <param name="typer" value="cln" />
                            <param name="use_genes" value="12" />
                        </expand>
                    </conditional>
                </conditional>
            </section>
            <output name="outpdf" value="out_traject_inspect_fateid_som.pdf" compare="sim_size" delta="15" />
        </test>
        <test>
            <!-- uses all 3 sections with additional non-default params -->
            <param name="inputrds" value="out_traject_default.ltree.rdat" />
            <section name="trjsid" >
                <conditional name="basic" >
                    <param name="doit" value="yes" />
                    <param name="i" value="5" />
                    <param name="br" value="6,5,3" />
                    <expand macro="test_nondef" >
                        <param name="zscore" value="true" />
                        <param name="ndiffgenes" value="14" />
                    </expand>
                </conditional>
            </section>
            <section name="trjfid" >
                <conditional name="basic" >
                    <param name="doit" value="yes" />
                    <param name="cellsfromz" value="3,9,2" />
                    <expand macro="test_nondef" >
                        <param name="filterset_minexpr" value="1" />
                        <param name="filterset_minnumber" value="2" />
                        <param name="procsom_minsom" value="5" />
                        <param name="procsom_corthr" value="0.5" />
                        <param name="plotheat_ygrid" value="true" />
                    </expand>
                    <conditional name="som" >
                        <param name="doit" value="yes" />
                        <conditional name="use_genes" >
                            <param name="typer" value="genelist" />
                            <param name="use_genes" value="Clca4,Mki67,Defa24,Ybx1,Vasp,Apoa1" />
                            <expand macro="test_nondef" >
                                <param name="cluster" value="true" />
                                <param name="alpha" value="0.1" />
                            </expand>
                        </conditional>
                    </conditional>
                </conditional>
            </section>
            <output name="outdiffgenes" value="out_traject_inspect_allthree.tabular" />
            <output name="outpdf" value="out_traject_inspect_allthree.pdf" compare="sim_size" delta="15" />
        </test>
    </tests>
    <help><![CDATA[
StemID2 and FateID
=====================

Given a previous lineage tree generated an RDS file generated from the previous Trajectory step, we can explore the variation of gene expression for all cells that lie on a given branch or trajectory.

This will generate a PDF containing a heatmap of expression for all neighboring clusters that share links with  cluster 5, as well as a plot of all cells along the branches between 1 to 3 and 3 to 10. A table of the most differentially expressed genes across these projection will also be output, which will provide a more qualitative assessment of how signficant our Apoa-expressing genes are along this projection.

For more information on the different types cluster and trajectory inspection that can be performed, please consult the RaceID vignette_.

.. _vignette: https://github.com/dgrun/RaceID3_StemID2_package/blob/master/vignettes/RaceID.Rmd

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