<commit_before>Command-line utilities
=======================

.. grs-compute
.. _grs-compute:

``grs-compute``
^^^^^^^^^^^^^^^

Computes the GRS using a '.grs' file and individual-level genotypes. 

The GRS are computed using the following formula:

.. math::
    GRS_i = \sum_{j=0}^{m} \beta_j \cdot X_{ij} 

Where :math:`GRS_i` is the genetic risk score for the `i`:sup:`th` sample, j
indexes the genetic variants included in the score, :math:`\beta_j` is the
coefficient estimated from the summary statistics and :math:`X_{ij}` is the
number of effect alleles carried by individual `i` at variant `j`.

.. note::
    If the coefficient (:math:`\beta`) is negative, it's additive inverse is
    used instead (:math:`-\beta`) and the effect and reference alleles are
    swapped accordingly. This ensures that contributions to the GRS are always
    positive.

If the IMPUTE2 format is used to hold the genotype information, the variants
are further weighted by the INFO score as a form of genotype confidence
weighting:

.. math::
    GRS_i = \sum_{j=0}^{m} \beta_j \cdot X_{ij}  \cdot info_j

.. todo::
    Eventually, we will weight variant as soon as there is some genotype
    quality metric (e.g. in a VCF file).

.. literalinclude:: includes/grs_compute_help.txt
    :language: none

.. grs-create
.. _grs-create:

``grs-create``
^^^^^^^^^^^^^^^

Creating a GRS consists of selecting variants that will be considered jointly
when the GRS will be computed using genotype data.

This script requires a ``.grs`` file and the selection is based on the p-value
sorting and thresholding algorithm.

This method consists of the following steps:

1. Rank the variants by increasing p-value.
2. Select the top variant, include it in the GRS and exclude all variants in LD
   at a pre-defined threshold (``--ld-threshold``).
3. Repeat 2. until the p-value threshold is reached (``--p-threshold``).

.. note::

    If a ``maf`` column is present in the summary statistics association file,
    all variants that are too rare will be automaticall excluded when reading
    the summary statistics file. If it is not available, the MAF will be
    computed from the genotype data to allow filtering, which is more
    computationally intensive.

For now, a plink binary file is required for the reference. A
population-specific reference panel like the 1000 genomes phase 3 should be
used.

This script generates a 'grs' file that is suitable for computing the GRS using
:ref:`grs-compute`.

.. literalinclude:: includes/grs_create_help.txt
    :language: none

.. grs-mr
.. _grs-mr:

``grs-mr``
^^^^^^^^^^^

Mendelian randomization is a technique where genetic variants (or a genetic
risk score (G)) is used to estimate the effect of an exposure (X) on an outcome
(Y). Here, the estimation is done using the ratio method:

.. math::
    \beta = \frac{\beta_{Y \sim G}}{\beta_{X \sim G}}

In the current implementation, bootstrap resampling is used to estimate the
standard error which can be used for further inference.

.. literalinclude:: includes/grs_mr_help.txt
    :language: none

.. grs-utils
.. _grs-utils:

``grs-utils``
^^^^^^^^^^^^^^

This tool contains multiple features to manipulate GRS after they have been
computed. Most of these tools either generate plots (as png files) or modified
versions of the computed GRS. The latter file format is simply a CSV with a
'sample' and a 'grs' column.

histogram
++++++++++

The histogram sub-command generates a histogram of all the GRS values. Here is
an example:

.. image:: _static/images/histogram.png


quantiles
++++++++++

This function is used to dichotomize the GRS. The parameters are:
- ``-k`` The number of quantiles to take to form a group.
- ``-q`` The total number of quantiles.

Here are various examples of dichotomizations: ::

    # Create two groups with respect to the median.
    grs-utils quantiles my_grs.grs -k 1 -q 2

    # 1st vs 5th quintiles.
    grs-utils quantiles my_grs.grs -k 1 -q 5

    # 1st vs 5th quintiles, but keeping all the samples (will be set to NA).
    grs-utils quantiles my_grs.grs -k 1 -q 5 --keep-unclassified

The output file will contain two columns and a header: ``sample`` and
``group``. The group '0' contains the individuals with lower values of the GRS
and the group '1' contains individuals with high values of the GRS.

standardize
++++++++++++

This function standardizes a GRS:

.. math::
    GRS' = \frac{GRS - \bar{GRS}}{s}

This function is useful when different GRS are to be compared. For example, is
linear regression is used to assess the effect of a GRS on a given trait (Y),
then the coefficient can be interpreted as the number of units increase in Y
for a 1 s.d. increase in the GRS.

correlation
++++++++++++

This utility takes two computed GRS files as input and plots the correlation
between the GRS. This can be useful to test the variability of changing
different hyperparameters (e.g. p-value threshold).

This script opens the plot in the interactive matplotlib viewer. From there, it
can manipulated and saved to a file.

Here is an example:

.. image:: _static/images/correlation.png

On the plot, the linear regression fit is displayed as well as the identity
line to quickly assess the agreement between GRS.

.. literalinclude:: includes/grs_utils_help.txt
    :language: none

beta-plot
++++++++++

This utility takes SNPs from summary statistics (grs format) and computes the
SNPs effect in a given population. The utility plots the correlation between
the expected coefficients (SNPs effect in the summary statistics) and the
observed coefficients (SNPs effect in the given population).

The utility also displays the standard errors on the plot. For the expected
coefficients, the standard errors are derived from the p-values. From the
p-values, the z-scores are retrieved and the standard errors are obtained by
dividing each expected coefficient by it's z-score.

.. math::
    z = \frac{\beta}{s.e.}

Here is an example of the plot:

.. image:: _static/images/beta_plot.png

The execution also produces a text file displaying the SNPs information
(chromosome, position, alleles, coefficients, standard errors, maf in the
given population and n, the number of individuals used to compute each
observed coefficient).

.. literalinclude:: includes/grs_utils_beta_plot_help.txt
    :language: none

.. grs-evaluate
.. _grs-evaluate:<commit_msg>Updated the documentation for beta-plot.<commit_after>Command-line utilities
=======================

.. grs-compute
.. _grs-compute:

``grs-compute``
^^^^^^^^^^^^^^^

Computes the GRS using a '.grs' file and individual-level genotypes. 

The GRS are computed using the following formula:

.. math::
    GRS_i = \sum_{j=0}^{m} \beta_j \cdot X_{ij} 

Where :math:`GRS_i` is the genetic risk score for the `i`:sup:`th` sample, j
indexes the genetic variants included in the score, :math:`\beta_j` is the
coefficient estimated from the summary statistics and :math:`X_{ij}` is the
number of effect alleles carried by individual `i` at variant `j`.

.. note::
    If the coefficient (:math:`\beta`) is negative, it's additive inverse is
    used instead (:math:`-\beta`) and the effect and reference alleles are
    swapped accordingly. This ensures that contributions to the GRS are always
    positive.

If the IMPUTE2 format is used to hold the genotype information, the variants
are further weighted by the INFO score as a form of genotype confidence
weighting:

.. math::
    GRS_i = \sum_{j=0}^{m} \beta_j \cdot X_{ij}  \cdot info_j

.. todo::
    Eventually, we will weight variant as soon as there is some genotype
    quality metric (e.g. in a VCF file).

.. literalinclude:: includes/grs_compute_help.txt
    :language: none

.. grs-create
.. _grs-create:

``grs-create``
^^^^^^^^^^^^^^^

Creating a GRS consists of selecting variants that will be considered jointly
when the GRS will be computed using genotype data.

This script requires a ``.grs`` file and the selection is based on the p-value
sorting and thresholding algorithm.

This method consists of the following steps:

1. Rank the variants by increasing p-value.
2. Select the top variant, include it in the GRS and exclude all variants in LD
   at a pre-defined threshold (``--ld-threshold``).
3. Repeat 2. until the p-value threshold is reached (``--p-threshold``).

.. note::

    If a ``maf`` column is present in the summary statistics association file,
    all variants that are too rare will be automaticall excluded when reading
    the summary statistics file. If it is not available, the MAF will be
    computed from the genotype data to allow filtering, which is more
    computationally intensive.

For now, a plink binary file is required for the reference. A
population-specific reference panel like the 1000 genomes phase 3 should be
used.

This script generates a 'grs' file that is suitable for computing the GRS using
:ref:`grs-compute`.

.. literalinclude:: includes/grs_create_help.txt
    :language: none

.. grs-mr
.. _grs-mr:

``grs-mr``
^^^^^^^^^^^

Mendelian randomization is a technique where genetic variants (or a genetic
risk score (G)) is used to estimate the effect of an exposure (X) on an outcome
(Y). Here, the estimation is done using the ratio method:

.. math::
    \beta = \frac{\beta_{Y \sim G}}{\beta_{X \sim G}}

In the current implementation, bootstrap resampling is used to estimate the
standard error which can be used for further inference.

.. literalinclude:: includes/grs_mr_help.txt
    :language: none

.. grs-utils
.. _grs-utils:

``grs-utils``
^^^^^^^^^^^^^^

This tool contains multiple features to manipulate GRS after they have been
computed. Most of these tools either generate plots (as png files) or modified
versions of the computed GRS. The latter file format is simply a CSV with a
'sample' and a 'grs' column.

histogram
++++++++++

The histogram sub-command generates a histogram of all the GRS values. Here is
an example:

.. image:: _static/images/histogram.png


quantiles
++++++++++

This function is used to dichotomize the GRS. The parameters are:
- ``-k`` The number of quantiles to take to form a group.
- ``-q`` The total number of quantiles.

Here are various examples of dichotomizations: ::

    # Create two groups with respect to the median.
    grs-utils quantiles my_grs.grs -k 1 -q 2

    # 1st vs 5th quintiles.
    grs-utils quantiles my_grs.grs -k 1 -q 5

    # 1st vs 5th quintiles, but keeping all the samples (will be set to NA).
    grs-utils quantiles my_grs.grs -k 1 -q 5 --keep-unclassified

The output file will contain two columns and a header: ``sample`` and
``group``. The group '0' contains the individuals with lower values of the GRS
and the group '1' contains individuals with high values of the GRS.

standardize
++++++++++++

This function standardizes a GRS:

.. math::
    GRS' = \frac{GRS - \bar{GRS}}{s}

This function is useful when different GRS are to be compared. For example, is
linear regression is used to assess the effect of a GRS on a given trait (Y),
then the coefficient can be interpreted as the number of units increase in Y
for a 1 s.d. increase in the GRS.

correlation
++++++++++++

This utility takes two computed GRS files as input and plots the correlation
between the GRS. This can be useful to test the variability of changing
different hyperparameters (e.g. p-value threshold).

This script opens the plot in the interactive matplotlib viewer. From there, it
can manipulated and saved to a file.

Here is an example:

.. image:: _static/images/correlation.png

On the plot, the linear regression fit is displayed as well as the identity
line to quickly assess the agreement between GRS.

.. literalinclude:: includes/grs_utils_help.txt
    :language: none

beta-plot
++++++++++

This utility compares the effect of variants between a summary statistics file
in the GRS format and regression results using the user's data. The goal is
to ensure that the reported effect sizes are compatible and that there are no
large or systematic discrepencies that could indicate a population or strand
mismatch.

The utility also displays the standard errors on the plot. For the error of the
expected coefficients, the standard errors are derived from the p-values and
effect sizes.

.. math::
    z = \frac{\beta}{s.e.}

Here is an example of the plot:

.. image:: _static/images/beta_plot.png

The execution also produces a text file displaying the SNPs information
(chromosome, position, alleles, coefficients, standard errors, maf in the
given population and n, the number of individuals used to compute each
observed coefficient).

.. literalinclude:: includes/grs_utils_beta_plot_help.txt
    :language: none

.. grs-evaluate
.. _grs-evaluate:
{'fraction_non_alphanumeric': 0.09333962412518676, 'fraction_numerical': 0.003931744908390344, 'mean_word_length': 3.844952380952381, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3915475', 'n_tokens_mistral': 3710, 'n_tokens_neox': 3510, 'n_words': 1773}