immuneml_tools/immuneml_clustering.xml at main · uio-bmi/immuneml_tools · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
<tool id="immuneml_clustering" name="Clustering" version="@VERSION@.0">
    <description>Clustering</description>

    <macros>
        <import>prod_macros.xml</import>
    </macros>

    <expand macro="requirements" />

    <stdio>
        <exit_code range="1:" />
    </stdio>
    <command><![CDATA[
      #if $iml_input
         cp -r ${iml_input.extra_files_path}/galaxy_dataset/* . &&
	     (mv repertoires/* . &>/dev/null || :) &&
	     rm -rf repertoires &&
      #end if

      python '$__tool_directory__/build_clustering_yaml_wrapper.py'
      --output_path . --file_name clustering.yaml --encoding_k $encoding_k --n_clusters $n_clusters --training_percentage $training_percentage
      #if $dim_red_method
          --dim_red_method $dim_red_method
      #end if
      #if $include_label_cond.eval_metrics
          #set eval_metrics_splitted = str($include_label_cond.eval_metrics).replace(",", " ")
          --eval_metrics $eval_metrics_splitted
      #end if
      #if $include_label_cond.include_label == "Yes"
          --labels "$include_label_cond.labels"
      #end if

      && cp ./clustering.yaml ${specs} &&

      immune-ml ./clustering.yaml ${html_outfile.files_path} --tool GalaxyYamlTool || immuneml_exit_code=\$? &&
      mv ${html_outfile.files_path}/index.html ${html_outfile} &&
      mv ${html_outfile.files_path}/immuneML_output.zip $archive &&
      exit \$immuneml_exit_code
      ]]>
    </command>
    <inputs>
        <param name="iml_input" type="data" format="immuneml_receptors.html" label="immuneML dataset" optional="false" help="This field accepts an ImmuneML dataset, as created by the Create Dataset tool."/>

        <conditional name="include_label_cond">
            <param type="select" name="include_label" label="Would you like to include label information to assess clustering performance?" help="" display="radio">
              <option value="Yes">Yes</option>
              <option value="No">No</option>
            </param>
            <when value="Yes">
                <param type="text" name="labels" optional="false" label="Name of the label to compare clustering performance to:"/>
                <param type="select" name="eval_metrics" label="Which performance metrics would you like to compute?" help="Internal evaluation scores ignore label values evaluate clusters, external evaluation scores compare the found custers to label classes." display="checkboxes" multiple="true">
                  <option value="silhouette_score">Silhouette score (internal)</option>
<!--                  <option value="davies_bouldin_score">Davies-Bouldin score (internal)</option>-->
<!--                  <option value="calinski_harabasz_score">Calinski-Harabasz score (internal)</option>-->
                  <option value="rand_score">Rand Index (external)</option>
                  <option value="adjusted_rand_score">Adjusted Rand Index (external)</option>
                  <option value="mutual_info_score">Mutual Information (external)</option>
                  <option value="adjusted_mutual_info_score">Adjusted Mutual Information (external)</option>
                  <option value="normalized_mutual_info_score">Normalized Mutual Information (external)</option>
                  <option value="completeness_score">Completeness score (external)</option>
                  <option value="fowlkes_mallows_score">Fowlkes-Mallows Index (external)</option>
                  <option value="homogeneity_score">Homogeneity score (external)</option>
                  <option value="v_measure_score">V-measure (external)</option>
                </param>
            </when>
            <when value="No">
                <param type="select" name="eval_metrics" label="Which performance metrics would you like to compute?" help="" display="checkboxes" multiple="true">
                  <option value="silhouette_score">Silhouette score</option>
<!--                  <option value="davies_bouldin_score">Davies-Bouldin score</option>-->
<!--                  <option value="calinski_harabasz_score">Calinski-Harabasz score</option>-->
                </param>
            </when>
        </conditional>

        <param type="integer" name="encoding_k" label="Which k-mer length should be used for encoding the data?" value="3" min="1" help="In this tool, the data encoding is always via k-mer frequencies. For alternative encodings and more flexibility, see Run immuneML with YAML tool."/>

        <param type="select" name="dim_red_method" label="Which dimensionality reduction method would you like to apply for the visualization of results?" help="" display="radio">
          <option value="PCA">Principal component analysis (PCA) with 2 components</option>
          <option value="TSNE">T-distributed Stochastic Neighbor Embedding (T-SNE) with 2 components</option>
          <option value="UMAP">Uniform manifold approximation and projection (UMAP) with 2 components</option>
          <option value="None">No dimensionality reduction</option>
        </param>

        <param type="integer" name="n_clusters" label="Clustering will be performed using k-means clustering. How many clusters to look for?" value="2" min="2" help="If a label is available, it is recommended to choose a number of clusters that matches the number of classes for the given label."/>
        <param type="integer" name="training_percentage" label="Percentage of data that is used for cluster discovery. The remaining data is left out and used for independent validation." value="50" min="50" max="100" help=""/>

    </inputs>
    <outputs>
        <data format="txt" name="specs" label="clustering.yaml"/>
        <data format="zip" name="archive" label="Archive: Clustering"/>
        <data format="html" name="html_outfile" label="Summary: Clustering"/>
    </outputs>


    <help><![CDATA[

	This Clustering tool uses the provided dataset to fit a clustering method and evaluates the clustering to a
	predefined set of metrics. The dataset is split into discovery and validation datasets and the clustering results
	are reported on both. It also provides options to include a visualization of the results.

	The Clustering tool has a fixed clustering algorithm (k-means) and data encoding (k-mer frequencies). For more
	flexibility, please see the documentation for the clustering instruction and use Run immuneML with YAML tool or
	immuneML from the command line.

	This tool runs the immuneML Clustering instruction (see `the documentation <https://docs.immuneml.uio.no/latest/yaml_specs/instructions.html#clustering>`_ for details).
	See also `the immuneML Galaxy documentation <https://docs.immuneml.uio.no/galaxy.html>`_.

    **Tool output**

	This Galaxy tool will produce the following history elements:

	- Summary: immuneML analysis: an HTML page for browsing through all results.

	- immuneML Analysis Archive: a .zip file containing the complete output folder as it was produced by immuneML.

	- clustering.yaml: a full YAML specification of the performed analysis.

    ]]></help>

    <citations>
        <citation type="doi">10.1038/s42256-021-00413-z</citation>
    </citations>

</tool>