usage.rst 16.9 KB
Newer Older
Romain Feron's avatar
Romain Feron committed
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
.. _full-usage:

RADSex usage
============

The RADSex software implements the general command-line interface:

``radsex <command> [options]``

**Available commands**

=======  ===========
Command  Description
=======  ===========
depth    Compute marker depth statistics for each individual
distrib  Compute the distribution of markers between compared groups
freq     Compute the distribution of markers in all individuals
map      Align markers to a genome and compute metrics for each aligned marker
process  Compute a table of marker depths from a set of demultiplexed reads files
signif   Extract markers significantly associated with phenotypic group from a marker depths table
subset   Extract a subset of markers from a marker depths table
=======  ===========


RomainFeron's avatar
RomainFeron committed
25
26
27
------------------------------------------------------------------------------------------------------------


Romain Feron's avatar
Romain Feron committed
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
.. _process-usage:

process
-------

Generate a table containing the depth of each marker in each individual from the dataset.

**Command**

::

    radsex process --input-dir input_dir_path --output-file output_file_path [ --threads n_threads --min-depth min_depth ]


**Options**

=====================   ===========
Option                  Description
=====================   ===========
``--input-dir, -i``     Path to a folder containing demultiplexed reads
``--output-file, -o``   Path to the generated marker depths table
``--threads, -T``       Number of threads to use (default: 1)
``--min-depth, -d``     Minimum depth to consider a marker present in an individual (default: 1)
=====================   ===========

**Output**

A :ref:`markers-depths-table-file`:

::

    #Number of markers : 4
    id   sequence     individual_1    individual_2    individual_3    individual_4    individual_5
     0   TGCA..TATT              0              15              24              17              21
     1   TGCA..GACC             20              18               3              26               4
     2   TGCA..ATCG              2               1               5              16               0
     3   TGCA..CCGA             14              29              23               2              19


.. note:: Input files are automatically dectected from the input directory based on their extensions. Supported extensions are **.fa**, **.fa.gz**, **.fq**, **.fq.gz**, **.fasta**, **.fasta.gz**, **.fastq**, **.fastq.gz**, **.fna**, and **.fna.gz**. Individual IDs in the output table will be inferred from the input files names after removing the extension. For instance, a file named **individual_1.fastq.gz** will be attributed the ID **individual_1**. Make sure to use the same IDs when creating the population map.


RomainFeron's avatar
RomainFeron committed
70
71
72
------------------------------------------------------------------------------------------------------------


Romain Feron's avatar
Romain Feron committed
73
74
75
76
77
.. _distrib-usage:

distrib
-------

RomainFeron's avatar
RomainFeron committed
78
Generate a table containing the distribution of markers between two groups of individuals defined in a :ref:`population-map`.
Romain Feron's avatar
Romain Feron committed
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96

**Command**

::

    radsex distrib --markers-table markers_table_path --output-file output_file_path --popmap popmap_path [ --min-depth min_depth --groups group1,group2 --signif-threshold signif_threshold --disable-correction ]

**Options**

============================   ===========
Option                         Description
============================   ===========
``--markers-table, -t``        Path to a marker depths table generated by "process"
``--popmap, -p``               Path to a tabulated file specifying groups for all individuals
``--output-file, -o``          Path to the output file (distribution of markers between groups)
``--min-depth, -d``            Minimum depth to consider a marker present in an individual
``--groups, -G``               Names of the groups to compare if there are more than two groups in the popmap (--groups group1, group2)
``--signif-threshold, -S``     P-value threshold to consider a marker significantly associated with a phenotypic group
RomainFeron's avatar
RomainFeron committed
97
``--disable-correction, -C``   If set, Bonferroni correction will NOT be used when assessing significance of association with phenotypic group
Romain Feron's avatar
Romain Feron committed
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
============================   ===========

**Output**

A :ref:`sex-distribution-file`:

::

    Males    Females    Markers       P     Signif      Bias
        0          1          7       1     False     -0.333
        0          2          3    0.39     False     -0.666
        0          3          1    0.10     False     -1.000
        1          0          6       1     False      0.333
        1          1          5       1     False      0.000
        1          2          1       1     False     -0.333
        1          3          2    0.39     False     -0.666
        2          0          3    0.39     False      0.666
        2          1          8       1     False      0.333
        2          2          4       1     False      0.000
        2          3          2       1     False     -0.333
        3          0          4    0.10     False      1.000
        3          1          7    0.39     False      0.666
        3          2          6       1     False      0.333
        3          3          9       1     False      0.000


RomainFeron's avatar
RomainFeron committed
124
------------------------------------------------------------------------------------------------------------
Romain Feron's avatar
Romain Feron committed
125

RomainFeron's avatar
RomainFeron committed
126
127
128
129

.. _signif-usage:

signif
Romain Feron's avatar
Romain Feron committed
130
131
------

RomainFeron's avatar
RomainFeron committed
132
Find markers significantly associated with groups of individuals defined in a :ref:`population-map`.
Romain Feron's avatar
Romain Feron committed
133
134
135
136
137

**Command**

::

RomainFeron's avatar
RomainFeron committed
138
    radsex signif --markers-table markers_table_path --output-file output_file_path --popmap popmap_path [ --min-depth min_depth --groups group1,group2 --signif-threshold signif_threshold --disable-correction --output-fasta ]
Romain Feron's avatar
Romain Feron committed
139
140
141
142
143
144
145
146

**Options**

============================   ===========
Option                         Description
============================   ===========
``--markers-table, -t``        Path to a marker depths table generated by "process"
``--popmap, -p``               Path to a tabulated file specifying groups for all individuals
RomainFeron's avatar
RomainFeron committed
147
``--output-file, -o``          Path to the output file (distribution of markers between groups)
Romain Feron's avatar
Romain Feron committed
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
``--min-depth, -d``            Minimum depth to consider a marker present in an individual
``--groups, -G``               Names of the groups to compare if there are more than two groups in the popmap (--groups group1, group2)
``--signif-threshold, -S``     P-value threshold to consider a marker significantly associated with a phenotypic group
``--disable-correction, -C``   If set, Bonferroni correction will NOT be used when assessing significance of association with phenotypic group
``--output-fasta, -a``         If set, markers are saved to a fasta file instead of a markers depth table
============================   ===========

**Output**

:ref:`markers-depths-table-file`:

::

    #Number of markers : 4
    id   sequence     individual_1    individual_2    individual_3    individual_4    individual_5
     0   TGCA..TATT              0              15              24              17              21
     1   TGCA..GACC             20              18               3              26               4
     2   TGCA..ATCG              2               1               5              16               0
     3   TGCA..CCGA             14              29              23               2              19

:ref:`fasta-file`:

::

    >4495827_F:0_M:21_p:1.14577e-07_mindepth:10
    TGCAG.....GGATGTGTATCCATA
    >4609394_F:0_M:23_p:1.08057e-08_mindepth:10
    TGCAG.....GGTTCCATCCCAAAT
    >4661391_F:0_M:26_p:1.92225e-10_mindepth:10
    TGCAG.....GTAGAGTGACCAGTT
    >5182569_F:0_M:22_p:3.62243e-08_mindepth:10
    TGCAG.....ACATGCTGTAAATGC
    >5625957_F:0_M:25_p:7.91633e-10_mindepth:10
    TGCAG.....CTGGAGAAGAGTAGG


RomainFeron's avatar
RomainFeron committed
184
------------------------------------------------------------------------------------------------------------
Romain Feron's avatar
Romain Feron committed
185
186


RomainFeron's avatar
RomainFeron committed
187
188
189
190
191
192
.. _map-usage:

map
---

Align markers to a genome and compute bias and probability of association with group for each aligned marker.
Romain Feron's avatar
Romain Feron committed
193
194
195
196
197

**Command**

::

RomainFeron's avatar
RomainFeron committed
198
199
    radsex map --input-file input_file_path --output-file output_file_path --population-map popmap_file_path --genome-file genome_file_path [ --min-depth min_depth --min-quality min_quality --min-frequency min_frequency ]

Romain Feron's avatar
Romain Feron committed
200
201
202
203
204
205
206
207
208

**Options**

============================   ===========
Option                         Description
============================   ===========
``--markers-table, -t``        Path to a marker depths table generated by "process"
``--popmap, -p``               Path to a tabulated file specifying groups for all individuals
``--output-file, -o``          Path to the output file (distribution of markers between groups)
RomainFeron's avatar
RomainFeron committed
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
``--genome-file, -g``          Path to the genome file
``--min-depth, -d``            Minimum depth to consider a marker present in an individual
``--groups, -G``               Names of the groups to compare if there are more than two groups in the popmap (--groups group1, group2)
``--min-quality, -q``          Minimum mapping quality to retain a marker
``--min-frequency, -Q``        Minimum frequency of individuals in which a marker is present to retain a marker
``--signif-threshold, -S``     P-value threshold to consider a marker significantly associated with a phenotypic group
``--disable-correction, -C``   If set, Bonferroni correction will NOT be used when assessing significance of association with phenotypic group
============================   ===========

**Output**

A :ref:`mapping-results-file`:

::

    Contig    Position       Length     Marker_id       Bias             P      Signif
    LG03      18366992     36623554       4335174     -0.202         0.073      False
    LG05      28289991     33792114       4335919          0             1      False
    LG05      29738230     33792114       4336169      0.149         0.356      False
    LG22         71119     28810691       4336631      0.159         0.162      False
    LG15      20142338     30000224       4336732          0             1      False
    LG02      26668964     31118443       4337320          0             1      False
    LG03       4463700     36623554       4337383     -0.033         0.973      False
    LG13      32240045     33409148       4338936     -0.073         0.704      False
    LG13      19113343     33409148       4340342      0.064         0.479      False
    LG22      22503191     28810691       4341087     -0.080         0.704      False
    LG01      17881236     39973033       8678129     -0.736     3.417e-08      True
    LG01      16475480     39973033       8888270     -0.705     1.462e-07      True
    LG01      15761951     39973033       8954765     -0.769     8.054e-09      True
    LG01      16562550     39973033       8990122     -0.736     3.417e-08      True


------------------------------------------------------------------------------------------------------------


.. _subset-usage:

subset
------

Extract a subset of markers from a markers depth table based on presence in individuals from each compared group.

**Command**

::

    radsex distrib --markers-table markers_table_path --output-file output_file_path --popmap popmap_path [ --min-depth min_depth --groups group1,group2 --signif-threshold signif_threshold --disable-correction --min-group1 min_group1 --min-group2 min_group2 --max-group1 max_group1 --max-group2 max_group2 --min-individuals min_individuals --max-individuals max_individuals --output-fasta ]

**Options**

============================   ===========
Option                         Description
============================   ===========
``--markers-table, -t``        Path to a marker depths table generated by "process"
``--popmap, -p``               Path to a tabulated file specifying groups for all individuals
``--output-file, -o``          Path to the output file (subset of markers)
Romain Feron's avatar
Romain Feron committed
265
266
267
268
269
``--min-depth, -d``            Minimum depth to consider a marker present in an individual
``--groups, -G``               Names of the groups to compare if there are more than two groups in the popmap (--groups group1, group2)
``--signif-threshold, -S``     P-value threshold to consider a marker significantly associated with a phenotypic group
``--disable-correction, -C``   If set, Bonferroni correction will NOT be used when assessing significance of association with phenotypic group
``--output-fasta, -a``         If set, markers are saved to a fasta file instead of a markers depth table
RomainFeron's avatar
RomainFeron committed
270
271
272
273
274
275
``--min-group1, -m``           Minimum number of individuals from the first group to retain a marker in the subset
``--min-group2, -n``           Minimum number of individuals from the second group to retain a marker in the subset
``--max-group1, -M``           Maximum number of individuals from the first group to retain a marker in the subset
``--max-group2, -N``           Maximum number of individuals from the second group to retain a marker in the subset
``--min-individuals, -i``      Minimum number of individuals to retain a marker in the subset
``--max-individuals, -I``      Maximum number of individuals to retain a marker in the subset
Romain Feron's avatar
Romain Feron committed
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
============================   ===========

**Output**

:ref:`markers-depths-table-file`:

::

    #Number of markers : 4
    id   sequence     individual_1    individual_2    individual_3    individual_4    individual_5
     0   TGCA..TATT              0              15              24              17              21
     1   TGCA..GACC             20              18               3              26               4
     2   TGCA..ATCG              2               1               5              16               0
     3   TGCA..CCGA             14              29              23               2              19

:ref:`fasta-file`:

::

    >4495827_F:0_M:21_p:1.14577e-07_mindepth:10
    TGCAG.....GGATGTGTATCCATA
    >4609394_F:0_M:23_p:1.08057e-08_mindepth:10
    TGCAG.....GGTTCCATCCCAAAT
    >4661391_F:0_M:26_p:1.92225e-10_mindepth:10
    TGCAG.....GTAGAGTGACCAGTT
    >5182569_F:0_M:22_p:3.62243e-08_mindepth:10
    TGCAG.....ACATGCTGTAAATGC
    >5625957_F:0_M:25_p:7.91633e-10_mindepth:10
    TGCAG.....CTGGAGAAGAGTAGG


RomainFeron's avatar
RomainFeron committed
307
------------------------------------------------------------------------------------------------------------
Romain Feron's avatar
Romain Feron committed
308
309
310
311
312
313
314


.. _freq-usage:

freq
----

RomainFeron's avatar
RomainFeron committed
315
316
Generate a table containing the distribution of markers in the entire dataset.

Romain Feron's avatar
Romain Feron committed
317
318
319
320
**Command**

::

RomainFeron's avatar
RomainFeron committed
321
    radsex freq --markers-table markers_table_path --output-file output_file_path [ --min-depth min_depth ]
Romain Feron's avatar
Romain Feron committed
322
323
324

**Options**

RomainFeron's avatar
RomainFeron committed
325
326
327
328
329
330
331
332
333
============================   ===========
Option                         Description
============================   ===========
``--markers-table, -t``        Path to a marker depths table generated by "process"
``--output-file, -o``          Path to the output file (distribution of markers between groups)
``--min-depth, -d``            Minimum depth to consider a marker present in an individual
============================   ===========

**Output**
Romain Feron's avatar
Romain Feron committed
334

RomainFeron's avatar
RomainFeron committed
335
A :ref:`freq-results-file`:
Romain Feron's avatar
Romain Feron committed
336
337
338

::

RomainFeron's avatar
RomainFeron committed
339
340
341
342
343
344
345
346
347
348
349
350
351
352
    Frequency     Count
            1     10389
            2      3869
            3      2884
            4      1824
            5      1672
            6      1276
            7      1261
            8      1278
            9      1355
            10     1291


------------------------------------------------------------------------------------------------------------
Romain Feron's avatar
Romain Feron committed
353
354
355
356
357
358
359


.. _depth-usage:

depth
-----

RomainFeron's avatar
RomainFeron committed
360
361
Compute the minimum, maximum, median, and average marker depth in each individual from the dataset.

Romain Feron's avatar
Romain Feron committed
362
363
364
365
**Command**

::

RomainFeron's avatar
RomainFeron committed
366
    radsex depth --markers-table markers_table_path --popmap popmap_file --output-file output_file_path
Romain Feron's avatar
Romain Feron committed
367
368
369

**Options**

RomainFeron's avatar
RomainFeron committed
370
371
372
373
374
375
376
377
378
379
============================   ===========
Option                         Description
============================   ===========
``--markers-table, -t``        Path to a marker depths table generated by "process"
``--popmap, -p``               Path to a tabulated file specifying groups for all individuals
``--output-file, -o``          Path to the output file (distribution of markers between groups)
``--min-depth, -d``            Minimum depth to consider a marker present in an individual
============================   ===========

**Output**
Romain Feron's avatar
Romain Feron committed
380

RomainFeron's avatar
RomainFeron committed
381
A :ref:`depth-results-file`:
Romain Feron's avatar
Romain Feron committed
382
383
384

::

RomainFeron's avatar
RomainFeron committed
385
386
387
388
389
390
391
392
393
394
395
    Individual    Group    Markers    Retained    Min_depth    Max_depth    Median_depth    Average_depth
    SRR1519834    M        1084439       72938            0        60604              60               71
    SRR1519837    M         914664       72938            0        48628              44               53
    SRR1519830    F        1165312       72938            0        35358              54               72
    SRR1519853    M         500353       72938            0        27276              28               33
    SRR1519824    F         498666       72938            0        23912              21               27
    SRR1519819    F         552423       72938            0        36001              24               32
    SRR1519846    M         522372       72938            0        30307              31               36
    SRR1519829    F         944099       72938            0        64723              45               61
    SRR1519812    F         781177       72938            0        44358              36               46
    SRR1519862    M        1313850       72938            0        64356              69               81
Romain Feron's avatar
Romain Feron committed
396