usage.rst

.. _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
=======  ===========


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


.. _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.


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


.. _distrib-usage:

distrib
-------

Generate a table containing the distribution of markers between two groups of individuals defined in a :ref:`population-map`.

**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
``--disable-correction, -C``   If set, Bonferroni correction will NOT be used when assessing significance of association with phenotypic group
============================   ===========

**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


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


.. _signif-usage:

signif
------

Find markers significantly associated with groups of individuals defined in a :ref:`population-map`.

**Command**

::

    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 ]

**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
``--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


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


.. _map-usage:

map
---

Align markers to a genome and compute bias and probability of association with group for each aligned marker.

**Command**

::

    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 ]


**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)
``--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)
``--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
``--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
============================   ===========

**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


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


.. _freq-usage:

freq
----

Generate a table containing the distribution of markers in the entire dataset.

**Command**

::

    radsex freq --markers-table markers_table_path --output-file output_file_path [ --min-depth min_depth ]

**Options**

============================   ===========
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**

A :ref:`freq-results-file`:

::

    Frequency     Count
            1     10389
            2      3869
            3      2884
            4      1824
            5      1672
            6      1276
            7      1261
            8      1278
            9      1355
            10     1291


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


.. _depth-usage:

depth
-----

Compute the minimum, maximum, median, and average marker depth in each individual from the dataset.

**Command**

::

    radsex depth --markers-table markers_table_path --popmap popmap_file --output-file output_file_path

**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
============================   ===========

**Output**

A :ref:`depth-results-file`:

::

    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