Source code

Download source archive ↓

upstream-extended/iuc/tool_collections/samtools/samtools_reheader/samtools_reheader.xml

1<tool id="samtools_reheader" name="Samtools reheader" version="2.1.0" profile="@PROFILE@">
2    <description>copy SAM/BAM header between datasets or edit read groups</description>
3    <macros>
4        <import>macros.xml</import>
5    </macros>
6    <expand macro="requirements">
7        <requirement type="package" version="5.1.0">gawk</requirement>
8    </expand>
9    <expand macro="stdio"/>
10    <expand macro="version_command"/>
11    <command><![CDATA[
12        samtools reheader
13        #if str($job.job_type) == 'copy_header'
14            '${job.input_header}'
15        #else
16            ## The command handed to -c is built entirely from tool-directory and
17            ## job-directory paths. The user-supplied @RG values live in the
18            ## $rg_edits config file and are read as data by the awk script, so
19            ## they never reach a shell.
20            -c "awk -f '$__tool_directory__/edit_read_groups.awk' '$rg_edits' -"
21        #end if
22            '${input_file}'
23            ${no_pg}
24            > '${output}'
25    ]]></command>
26    <configfiles>
27        <configfile name="rg_edits"><![CDATA[#slurp
28#if str($job.job_type) == 'edit_read_groups'
29#import re
30#for $field in $job.rg_fields
31#if str($field.value_source.value_from) == 'element_identifier'
32#set $rg_value = str($input_file.element_identifier)
33#set $rg_value = re.sub('(?i)[.](bam|sam|cram)$', '', $rg_value)
34#else
35#set $rg_value = str($field.value_source.value)
36#end if
37## The SAM specification restricts @RG field values to printable ASCII
38## ([ -~]+). Anything else -- most importantly tabs and newlines, which would
39## break both the header and this table -- is replaced.
40#set $rg_value = re.sub('[^ -~]', '_', $rg_value)
41${str($field.tag) + "\t" + $rg_value}
42#end for
43#end if
44]]></configfile>
45    </configfiles>
46    <inputs>
47        <param name="input_file" type="data" format="bam" label="Select target dataset" help="The dataset whose header will be replaced or edited. Should be a BAM dataset."/>
48        <conditional name="job">
49            <param name="job_type" type="select" label="What do you want to do?">
50                <option value="copy_header">Copy the header of another dataset</option>
51                <option value="edit_read_groups">Edit read group (@RG) fields in place</option>
52            </param>
53            <when value="copy_header">
54                <param name="input_header" type="data" format="sam,bam" label="Select source dataset" help="Header from this dataset will be used to replace the header in the target dataset. May be either SAM or BAM dataset."/>
55            </when>
56            <when value="edit_read_groups">
57                <repeat name="rg_fields" title="@RG field to set" min="1" default="1">
58                    <param name="tag" type="select" label="Field to set" help="This field will be set on every @RG record of the header. Fields that are not listed here - in particular ID and PU - are left exactly as they are.">
59                        <option value="SM">SM: sample</option>
60                        <option value="LB">LB: library</option>
61                        <option value="PL">PL: platform</option>
62                        <option value="CN">CN: sequencing center</option>
63                        <option value="DS">DS: description</option>
64                    </param>
65                    <conditional name="value_source">
66                        <param name="value_from" type="select" label="Where should the value come from?">
67                            <option value="text">A value I type in</option>
68                            <option value="element_identifier">The name of the target dataset</option>
69                        </param>
70                        <when value="text">
71                            <param name="value" type="text" label="Value" help="The value to set this field to on every @RG record.">
72                                <!-- The default sanitizer would turn characters that are
73                                     perfectly legal in an @RG value into __sq__ and friends.
74                                     Everything the SAM specification allows is kept instead,
75                                     which is safe here because the value is written to a
76                                     config file and read back as data - it never reaches a
77                                     shell. Tabs and newlines are the only real hazard, and
78                                     they are dropped. -->
79                                <sanitizer invalid_char="_">
80                                    <valid initial="string.printable">
81                                        <remove value="&#9;"/>
82                                        <remove value="&#10;"/>
83                                        <remove value="&#13;"/>
84                                    </valid>
85                                </sanitizer>
86                                <validator type="empty_field"/>
87                                <validator type="regex" message="@RG field values must consist of printable ASCII characters (the SAM specification allows [ -~]+)">^[ -~]+\Z</validator>
88                            </param>
89                        </when>
90                        <when value="element_identifier">
91                            <!-- The name of the target dataset is its element identifier when
92                                 the tool is run over a collection, so the value varies per
93                                 element. A typed-in value would be identical for every element. -->
94                        </when>
95                    </conditional>
96                </repeat>
97            </when>
98        </conditional>
99        <param argument="--no-PG" name="no_pg" type="boolean" truevalue="--no-PG" falsevalue=""
100        label="Keep the new header unmodified?"
101        help="By default, samtools reheader will add itself to the chain of tools used to manipulate the target dataset, which will cause one or more @PG records to be inserted into the new header. Activate this option if you want the output to carry the source dataset's header exactly, or - when editing read groups - the edited header and nothing else." />
102    </inputs>
103    <outputs>
104        <data format="bam" name="output" label="${tool.name} on ${on_string}" />
105    </outputs>
106    <tests>
107        <test>
108            <param name="input_file" ftype="bam" value="reheader_input_file.bam"/>
109            <conditional name="job">
110                <param name="job_type" value="copy_header"/>
111                <param name="input_header" ftype="bam" value="reheader_input_header.bam"/>
112            </conditional>
113            <output name="output" ftype="bam" file="reheader_out.bam" lines_diff="1"/><!-- samtools adds reheader line -->
114        </test>
115        <test>
116            <param name="input_file" ftype="bam" value="reheader_input_file.bam"/>
117            <conditional name="job">
118                <param name="job_type" value="copy_header"/>
119                <param name="input_header" ftype="bam" value="reheader_input_header.bam"/>
120            </conditional>
121            <param name="no_pg" value="true"/>
122            <output name="output" ftype="bam" file="reheader_out.bam" />
123        </test>
124        <!-- Editing SM and LB must leave both @RG IDs, both PUs and every read's
125             RG:Z assignment untouched. The expected dataset holds two @RG records,
126             so a wrapper that collapsed the read groups into one would fail here. -->
127        <test>
128            <param name="input_file" ftype="bam" value="reheader_rg_input.bam"/>
129            <conditional name="job">
130                <param name="job_type" value="edit_read_groups"/>
131                <repeat name="rg_fields">
132                    <param name="tag" value="SM"/>
133                    <conditional name="value_source">
134                        <param name="value_from" value="text"/>
135                        <param name="value" value="patient1_tumour"/>
136                    </conditional>
137                </repeat>
138                <repeat name="rg_fields">
139                    <param name="tag" value="LB"/>
140                    <conditional name="value_source">
141                        <param name="value_from" value="text"/>
142                        <param name="value" value="lib1"/>
143                    </conditional>
144                </repeat>
145            </conditional>
146            <param name="no_pg" value="true"/>
147            <output name="output" ftype="bam" file="reheader_rg_out.bam"/>
148        </test>
149        <!-- The next two tests are identical apart from the input dataset. They
150             stand in for two elements of a collection: with SM bound to the dataset
151             name, each one must come out with its own SM, which is what a fixed
152             text value could not do. LB is not listed here, so the second @RG
153             record - which has no LB at all - must still come out without one. -->
154        <test>
155            <param name="input_file" ftype="bam" value="patient1-normal.bam"/>
156            <conditional name="job">
157                <param name="job_type" value="edit_read_groups"/>
158                <repeat name="rg_fields">
159                    <param name="tag" value="SM"/>
160                    <conditional name="value_source">
161                        <param name="value_from" value="element_identifier"/>
162                    </conditional>
163                </repeat>
164            </conditional>
165            <param name="no_pg" value="true"/>
166            <output name="output" ftype="bam" file="patient1-normal_auto_sm.bam"/>
167        </test>
168        <test>
169            <param name="input_file" ftype="bam" value="patient2-tumour.bam"/>
170            <conditional name="job">
171                <param name="job_type" value="edit_read_groups"/>
172                <repeat name="rg_fields">
173                    <param name="tag" value="SM"/>
174                    <conditional name="value_source">
175                        <param name="value_from" value="element_identifier"/>
176                    </conditional>
177                </repeat>
178            </conditional>
179            <param name="no_pg" value="true"/>
180            <output name="output" ftype="bam" file="patient2-tumour_auto_sm.bam"/>
181        </test>
182        <!-- Punctuation that is legal in an @RG value but that Galaxy's default text
183             sanitizer would mangle must survive intact. Nothing here reaches a shell,
184             so the semicolon and parentheses are inert. -->
185        <test>
186            <param name="input_file" ftype="bam" value="reheader_rg_input.bam"/>
187            <conditional name="job">
188                <param name="job_type" value="edit_read_groups"/>
189                <repeat name="rg_fields">
190                    <param name="tag" value="SM"/>
191                    <conditional name="value_source">
192                        <param name="value_from" value="text"/>
193                        <param name="value" value="patient1_tumour"/>
194                    </conditional>
195                </repeat>
196                <repeat name="rg_fields">
197                    <param name="tag" value="DS"/>
198                    <conditional name="value_source">
199                        <param name="value_from" value="text"/>
200                        <param name="value" value="Batch #7, lane 3 (re-run); 50% input"/>
201                    </conditional>
202                </repeat>
203            </conditional>
204            <param name="no_pg" value="true"/>
205            <output name="output" ftype="bam" file="reheader_rg_punctuation.bam"/>
206        </test>
207        <!-- Asking to edit read groups in a header that has none must fail loudly
208             rather than return the input unchanged. -->
209        <test expect_failure="true">
210            <param name="input_file" ftype="bam" value="reheader_input_file.bam"/>
211            <conditional name="job">
212                <param name="job_type" value="edit_read_groups"/>
213                <repeat name="rg_fields">
214                    <param name="tag" value="SM"/>
215                    <conditional name="value_source">
216                        <param name="value_from" value="text"/>
217                        <param name="value" value="patient1_tumour"/>
218                    </conditional>
219                </repeat>
220            </conditional>
221        </test>
222    </tests>
223    <help><![CDATA[
224**What it does**
225
226Rewrites the header of a BAM dataset using the ``samtools reheader`` command. The
227reads themselves are never touched, so read counts and per-read ``RG:Z`` tags are
228always preserved.
229
230Two modes are available.
231
232**Copy the header of another dataset**
233
234Generates a new BAM dataset with the contents of the *target* dataset, but the
235header of the *source* dataset.
236
237**Edit read group (@RG) fields in place**
238
239Sets the selected fields on *every* ``@RG`` record of the target dataset's header,
240adding a field to records that do not have it yet and replacing it on records that
241do. All other fields are left alone.
242
243This is the mode to use after merging per-lane BAM files into one per-sample BAM
244file. Aligners typically derive the whole read group from the name of their input,
245so a merged dataset ends up with one ``@RG`` record per lane whose ``SM`` is a
246per-lane name. Setting ``SM`` here makes every record agree on the sample while
247``ID`` and ``PU`` stay distinct per lane, which is what downstream variant callers
248expect. Note that this is *not* what tools such as *Picard AddOrReplaceReadGroups*
249do: those assign every read to a single new read group, which discards the
250per-lane information.
251
252``ID`` and ``PU`` are deliberately not offered here. They identify individual read
253groups, so setting them to one value across the header would defeat the purpose of
254this mode - and, in the case of ``ID``, produce an invalid header with duplicate
255identifiers.
256
257When this tool is run over a collection, choosing *The name of the target dataset*
258binds the value to each element's identifier, so every element gets its own value.
259A fixed text value would be applied unchanged to every element of the collection.
260A trailing ``.bam``, ``.sam`` or ``.cram`` is removed from the name before it is
261used, since collection elements often carry one.
262
263Listing the same field twice sets it to the value given last. Editing a header that
264contains no ``@RG`` records at all fails, rather than quietly returning the input
265unchanged.
266    ]]></help>
267    <expand macro="citations"/>
268</tool>