genal-python 0.9__tar.gz → 1.1__tar.gz

{genal_python-0.9 → genal_python-1.1}/PKG-INFO

@@ -1,9 +1,9 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.3
 Name: genal-python
-Version: 0.9
+Version: 1.1
 Summary: A python toolkit for polygenic risk scoring and mendelian randomization.
 Author-email: Cyprien Rivier <riviercyprien@gmail.com>
-Requires-Python: >=3.7
+Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
@@ -16,12 +16,16 @@ Requires-Dist: plotnine==0.12.3
 Requires-Dist: psutil==5.9.1
 Requires-Dist: pyliftover==0.4
 Requires-Dist: scikit_learn>=1.3.0
-Requires-Dist: scipy>=1.11.4
+Requires-Dist: scipy>=1.10.1, <1.11
 Requires-Dist: statsmodels==0.14.0
 Requires-Dist: tqdm==4.66.1
 Requires-Dist: wget==3.2
 Project-URL: Home, https://github.com/CypRiv/genal
 
+[![Python 3.8](https://img.shields.io/badge/python-3.8%20%7C%203.9%20%7C%203.10-blue)](https://www.python.org/downloads/release/python-3100/)
+
+<img src="/genal_logo.png" data-canonical-src="/genal_logo.png" height="80" />  
+
 <center><h1> genal: A Python Toolkit for Genetic Risk Scoring and Mendelian Randomization </h1></center>
 
 
@@ -54,12 +58,18 @@ The module prioritizes user-friendliness and intuitive operation, aiming to redu
 
 Genal draws on concepts from well-established R packages such as TwoSampleMR, MR-Presso, MendelianRandomization, and gwasvcf, adapting their proven methodologies to the Python environment. This approach ensures that users have access to tried and tested techniques with the versatility of Python's data science tools. 
 
+<img src="/Genal_flowchart.png" data-canonical-src="/Genal_flowchart.png" style="max-width:100%;" />
+
+Genal flowchart. Created in https://www.BioRender.com
 ## Citation <a name="citation"></a> 
-If you're using genal, please cite the following paper:
-**Genal: A Python Toolkit for Genetic Risk Scoring and Mendelian Randomization.** Cyprien A. Rivier, Santiago Clocchiatti-Tuozzo, Shufan Huo, Victor Torres-Lopez, Daniela Renedo, Kevin N. Sheth, Guido J. Falcone, Julian N. Acosta. medRxiv 2024.05.23.24307776; doi: https://doi.org/10.1101/2024.05.23.24307776
+If you're using genal, please cite the following paper:  
+**Genal: A Python Toolkit for Genetic Risk Scoring and Mendelian Randomization.**  
+Cyprien A. Rivier, Santiago Clocchiatti-Tuozzo, Shufan Huo, Victor Torres-Lopez, Daniela Renedo, Kevin N. Sheth, Guido J. Falcone, Julian N. Acosta.  
+Bioinformatics Advances 2024.  
+doi: https://doi.org/10.1093/bioadv/vbae207
 
 ## Requirements for the genal module <a name="paragraph1"></a> 
-***Python 3.11 or later***. https://www.python.org/ <br> 
+***Python 3.8 or later***. https://www.python.org/ <br> 
 
 
 ## Installation and How to use the genal module <a name="paragraph2"></a>
@@ -70,7 +80,7 @@ If you're using genal, please cite the following paper:
 > 
 > **Optional**: It is recommended to create a new environment to avoid dependencies conflicts. Here, we create a new conda environment called 'genal_env'.
 > ```
-> conda create --name genal_env python=3.11
+> conda create --name genal_env python=3.8
 > conda activate genal_env
 > ```
 
@@ -84,12 +94,19 @@ And import it in a python environment with:
 import genal
 ```
 
-The main genal functionalities require a working installation of PLINK v1.9 that can be downloaded here: https://www.cog-genomics.org/plink/ 
-Once downloaded, the path to the plink executable can be set with:
+The main genal functionalities require a working installation of PLINK v2.0. 
+If you have already installed plink v2.0, you can set the path to its executable with:
 
 ```
 genal.set_plink(path="/path/to/plink/executable/file")
 ```
+
+If plink is not installed, genal can install the correct version for your system with the following line:
+
+```
+genal.install_plink()
+```
+
 ### Documentation <a name="paragraph2.2"></a>
 
 For detailed information on how to use the functionalities of Genal, please refer to the documentation: https://genal.rtfd.io
@@ -124,7 +141,7 @@ For this tutorial, we will obtain genetic instruments for systolic blood pressur
 
 ### Data loading <a name="paragraph3.1"></a>
 
-We start this tutorial with publicly available summary statistics from a large GWAS study of systolic blood pressure. [Link to study](https://www.nature.com/articles/s41588-018-0205-x). After downloading and unzipping the summary statistics, we load them into a pandas DataFrame:
+We start this tutorial with publicly available summary statistics from a large GWAS study of systolic blood pressure. [Link to study](https://www.nature.com/articles/s41588-018-0205-x). [Download link](http://ftp.ebi.ac.uk/pub/databases/gwas/summary_statistics/GCST006001-GCST007000/GCST006624/Evangelou_30224653_SBP.txt.gz). After downloading and unzipping the summary statistics, we load them into a pandas DataFrame:
 
 ```python
 import pandas as pd
@@ -242,7 +259,7 @@ You do not need to obtain the 1000 genome reference panel yourself, genal will d
 SBP_Geno.preprocess_data(preprocessing = 'Fill_delete', reference_panel = "afr")
 ```
 
-You can also use a custom reference panel by specifying to the reference_panel argument a path to bed/bim/fam files (without the extension).
+You can also use a custom reference panel by specifying to the reference_panel argument a path to bed/bim/fam (plink v1.9 format) or pgen/pvar/psam files (plink v2.0 format), without the extension.
 
 ### Clumping <a name="paragraph3.3"></a>
 
@@ -275,7 +292,7 @@ Computing a Polygenic Risk Score (PRS) can be done in one line with the `genal.G
 SBP_clumped.prs(name = "SBP_prs", path = "path/to/genetic/files")
 ```
 
-The genetic files of the target population can be either contained in one triple of bed/bim/fam files with information for all SNPs, or divided by chromosome (one bed/bim/fam triple for chr 1, another for chr 2, etc...). In the latter case, provide the path by replacing the chromosome number by `$` and genal will extract the necessary SNPs from each chromosome and merge them before running the PRS. For instance, if the genetic files are named `Pop_chr1.bed`, `Pop_chr1.bim`, `Pop_chr1.fam`, `Pop_chr2.bed`, ..., you can use:
+The genetic files of the target population can be either contained in one triple of bed/bim/fam or pgen/pvar/psam files with information for all SNPs, or divided by chromosome (one bed/bim/fam or pgen/pvar/psam triple for chr 1, another for chr 2, etc...). In the latter case, provide the path by replacing the chromosome number by `$` and genal will extract the necessary SNPs from each chromosome and merge them before running the PRS. For instance, if the genetic files are named `Pop_chr1.bed`, `Pop_chr1.bim`, `Pop_chr1.fam`, `Pop_chr2.bed`, ..., you can use:
 
 ```python
 SBP_clumped.prs(name = "SBP_prs", path = "Pop_chr$")
@@ -378,7 +395,7 @@ You can customize how the proxies are chosen with the following arguments:
 
 To run MR, we need to load both our exposure and outcome SNP-level data in `genal.Geno` instances. In our case, the genetic instruments of the MR are the SNPs associated with blood pressure at genome-wide significant levels resulting from the clumping of the blood pressure GWAS. They are stored in our `SBP_clumped` `genal.Geno` instance which also include their association with the exposure trait (instrument-SBP estimates in the `BETA` column).
 
-To get their association with the outcome trait (instrument-stroke estimates), we are going to use SNP-level data from a large GWAS of stroke performed by the GIGASTROKE consortium ([https://www.nature.com/articles/s41586-022-05165-3](https://www.nature.com/articles/s41586-022-05165-3)):
+To get their association with the outcome trait (instrument-stroke estimates), we are going to use SNP-level data from a large GWAS of stroke performed by the GIGASTROKE consortium: [Link to study](https://www.nature.com/articles/s41586-022-05165-3). [Link to download](http://ftp.ebi.ac.uk/pub/databases/gwas/summary_statistics/GCST90104001-GCST90105000/GCST90104539/GCST90104539_buildGRCh37.tsv.gz):
 
 ```python
 stroke_gwas = pd.read_csv("GCST90104539_buildGRCh37.tsv",sep="\t")
@@ -506,6 +523,12 @@ And that will give:
 | SBP      | Stroke_eur | Egger Intercept          | 1499 | -0.001381 | 0.000813  | 8.935529e-02  | 2959.965136 | 1497 | 1.253763e-98 |
 | SBP      | Stroke_eur | Inverse-Variance Weighted| 1499 | 0.023049  | 0.001061  | 1.382645e-104 | 2965.678836 | 1498 | 4.280737e-99 |
     
+If you wish to display the coefficients as odds ratios with confidence intervals for a binary outcome trait, you can use the `odds = True` argument:
+
+```python
+SBP_clumped.MR(action = 2, methods = ["Egger","IVW"], exposure_name = "SBP", outcome_name = "Stroke_eur", heterogeneity = True, odds = True)
+```
+
 As expected, many MR methods indicate that SBP is strongly associated with stroke, but there could be concerns for horizontal pleiotropy (instruments influencing the outcome through a different pathway than the one used as exposure) given the almost significant MR-Egger intercept p-value.
 To investigate horizontal pleiotropy in more details, a very useful method is Mendelian Randomization Pleiotropy RESidual Sum and Outlier (MR-PRESSO). MR-PRESSO is a method designed to detect and correct for horizontal pleiotropy. It will identify which instruments are likely to be pleiotropic on their effect on the outcome, and it will rerun an inverse-variance weighted MR after excluding them. It can be run using the `genal.Geno.MRpresso` method:
 
@@ -535,7 +558,7 @@ df_pheno = pd.read_csv("path/to/trait/data")
 
 > **Note:**
 > 
->    One important point is to make sure that the IDs of the participants are identical in the phenotypic data and in the genetic data.
+>    One important point is to make sure that both the Family IDs (FID) and Individual IDs (IID) of the participants are identical in the phenotypic data and in the genetic data. 
 
 Then, it is advised to make a copy of the `genal.Geno` instance containing our instruments as we are going to update their coefficients and to avoid any confusion:
 
@@ -546,7 +569,7 @@ SBP_adjusted = SBP_clumped.copy()
 We can then call the `genal.Geno.set_phenotype` method, specifying which column contains our trait of interest (for the association testing) and which column contains the individual IDs:
 
 ```python
-SBP_adjusted.set_phenotype(df_pheno, PHENO = "htn", IID = "IID")
+SBP_adjusted.set_phenotype(df_pheno, PHENO = "htn", IID = "IID", FID = "FID")
 ```
 
 At this point, genal will identify if the phenotype is binary or quantitative in order to choose the appropriate regression model. If the phenotype is binary, it will assume that the most frequent value is coding for control (and the other value for case), this can be changed with `alternate_control = True`:

{genal_python-0.9 → genal_python-1.1}/README.md

@@ -1,3 +1,7 @@
+[![Python 3.8](https://img.shields.io/badge/python-3.8%20%7C%203.9%20%7C%203.10-blue)](https://www.python.org/downloads/release/python-3100/)
+
+<img src="/genal_logo.png" data-canonical-src="/genal_logo.png" height="80" />  
+
 <center><h1> genal: A Python Toolkit for Genetic Risk Scoring and Mendelian Randomization </h1></center>
 
 
@@ -30,12 +34,18 @@ The module prioritizes user-friendliness and intuitive operation, aiming to redu
 
 Genal draws on concepts from well-established R packages such as TwoSampleMR, MR-Presso, MendelianRandomization, and gwasvcf, adapting their proven methodologies to the Python environment. This approach ensures that users have access to tried and tested techniques with the versatility of Python's data science tools. 
 
+<img src="/Genal_flowchart.png" data-canonical-src="/Genal_flowchart.png" style="max-width:100%;" />
+
+Genal flowchart. Created in https://www.BioRender.com
 ## Citation <a name="citation"></a> 
-If you're using genal, please cite the following paper:
-**Genal: A Python Toolkit for Genetic Risk Scoring and Mendelian Randomization.** Cyprien A. Rivier, Santiago Clocchiatti-Tuozzo, Shufan Huo, Victor Torres-Lopez, Daniela Renedo, Kevin N. Sheth, Guido J. Falcone, Julian N. Acosta. medRxiv 2024.05.23.24307776; doi: https://doi.org/10.1101/2024.05.23.24307776
+If you're using genal, please cite the following paper:  
+**Genal: A Python Toolkit for Genetic Risk Scoring and Mendelian Randomization.**  
+Cyprien A. Rivier, Santiago Clocchiatti-Tuozzo, Shufan Huo, Victor Torres-Lopez, Daniela Renedo, Kevin N. Sheth, Guido J. Falcone, Julian N. Acosta.  
+Bioinformatics Advances 2024.  
+doi: https://doi.org/10.1093/bioadv/vbae207
 
 ## Requirements for the genal module <a name="paragraph1"></a> 
-***Python 3.11 or later***. https://www.python.org/ <br> 
+***Python 3.8 or later***. https://www.python.org/ <br> 
 
 
 ## Installation and How to use the genal module <a name="paragraph2"></a>
@@ -46,7 +56,7 @@ If you're using genal, please cite the following paper:
 > 
 > **Optional**: It is recommended to create a new environment to avoid dependencies conflicts. Here, we create a new conda environment called 'genal_env'.
 > ```
-> conda create --name genal_env python=3.11
+> conda create --name genal_env python=3.8
 > conda activate genal_env
 > ```
 
@@ -60,12 +70,19 @@ And import it in a python environment with:
 import genal
 ```
 
-The main genal functionalities require a working installation of PLINK v1.9 that can be downloaded here: https://www.cog-genomics.org/plink/ 
-Once downloaded, the path to the plink executable can be set with:
+The main genal functionalities require a working installation of PLINK v2.0. 
+If you have already installed plink v2.0, you can set the path to its executable with:
 
 ```
 genal.set_plink(path="/path/to/plink/executable/file")
 ```
+
+If plink is not installed, genal can install the correct version for your system with the following line:
+
+```
+genal.install_plink()
+```
+
 ### Documentation <a name="paragraph2.2"></a>
 
 For detailed information on how to use the functionalities of Genal, please refer to the documentation: https://genal.rtfd.io
@@ -100,7 +117,7 @@ For this tutorial, we will obtain genetic instruments for systolic blood pressur
 
 ### Data loading <a name="paragraph3.1"></a>
 
-We start this tutorial with publicly available summary statistics from a large GWAS study of systolic blood pressure. [Link to study](https://www.nature.com/articles/s41588-018-0205-x). After downloading and unzipping the summary statistics, we load them into a pandas DataFrame:
+We start this tutorial with publicly available summary statistics from a large GWAS study of systolic blood pressure. [Link to study](https://www.nature.com/articles/s41588-018-0205-x). [Download link](http://ftp.ebi.ac.uk/pub/databases/gwas/summary_statistics/GCST006001-GCST007000/GCST006624/Evangelou_30224653_SBP.txt.gz). After downloading and unzipping the summary statistics, we load them into a pandas DataFrame:
 
 ```python
 import pandas as pd
@@ -218,7 +235,7 @@ You do not need to obtain the 1000 genome reference panel yourself, genal will d
 SBP_Geno.preprocess_data(preprocessing = 'Fill_delete', reference_panel = "afr")
 ```
 
-You can also use a custom reference panel by specifying to the reference_panel argument a path to bed/bim/fam files (without the extension).
+You can also use a custom reference panel by specifying to the reference_panel argument a path to bed/bim/fam (plink v1.9 format) or pgen/pvar/psam files (plink v2.0 format), without the extension.
 
 ### Clumping <a name="paragraph3.3"></a>
 
@@ -251,7 +268,7 @@ Computing a Polygenic Risk Score (PRS) can be done in one line with the `genal.G
 SBP_clumped.prs(name = "SBP_prs", path = "path/to/genetic/files")
 ```
 
-The genetic files of the target population can be either contained in one triple of bed/bim/fam files with information for all SNPs, or divided by chromosome (one bed/bim/fam triple for chr 1, another for chr 2, etc...). In the latter case, provide the path by replacing the chromosome number by `$` and genal will extract the necessary SNPs from each chromosome and merge them before running the PRS. For instance, if the genetic files are named `Pop_chr1.bed`, `Pop_chr1.bim`, `Pop_chr1.fam`, `Pop_chr2.bed`, ..., you can use:
+The genetic files of the target population can be either contained in one triple of bed/bim/fam or pgen/pvar/psam files with information for all SNPs, or divided by chromosome (one bed/bim/fam or pgen/pvar/psam triple for chr 1, another for chr 2, etc...). In the latter case, provide the path by replacing the chromosome number by `$` and genal will extract the necessary SNPs from each chromosome and merge them before running the PRS. For instance, if the genetic files are named `Pop_chr1.bed`, `Pop_chr1.bim`, `Pop_chr1.fam`, `Pop_chr2.bed`, ..., you can use:
 
 ```python
 SBP_clumped.prs(name = "SBP_prs", path = "Pop_chr$")
@@ -354,7 +371,7 @@ You can customize how the proxies are chosen with the following arguments:
 
 To run MR, we need to load both our exposure and outcome SNP-level data in `genal.Geno` instances. In our case, the genetic instruments of the MR are the SNPs associated with blood pressure at genome-wide significant levels resulting from the clumping of the blood pressure GWAS. They are stored in our `SBP_clumped` `genal.Geno` instance which also include their association with the exposure trait (instrument-SBP estimates in the `BETA` column).
 
-To get their association with the outcome trait (instrument-stroke estimates), we are going to use SNP-level data from a large GWAS of stroke performed by the GIGASTROKE consortium ([https://www.nature.com/articles/s41586-022-05165-3](https://www.nature.com/articles/s41586-022-05165-3)):
+To get their association with the outcome trait (instrument-stroke estimates), we are going to use SNP-level data from a large GWAS of stroke performed by the GIGASTROKE consortium: [Link to study](https://www.nature.com/articles/s41586-022-05165-3). [Link to download](http://ftp.ebi.ac.uk/pub/databases/gwas/summary_statistics/GCST90104001-GCST90105000/GCST90104539/GCST90104539_buildGRCh37.tsv.gz):
 
 ```python
 stroke_gwas = pd.read_csv("GCST90104539_buildGRCh37.tsv",sep="\t")
@@ -482,6 +499,12 @@ And that will give:
 | SBP      | Stroke_eur | Egger Intercept          | 1499 | -0.001381 | 0.000813  | 8.935529e-02  | 2959.965136 | 1497 | 1.253763e-98 |
 | SBP      | Stroke_eur | Inverse-Variance Weighted| 1499 | 0.023049  | 0.001061  | 1.382645e-104 | 2965.678836 | 1498 | 4.280737e-99 |
     
+If you wish to display the coefficients as odds ratios with confidence intervals for a binary outcome trait, you can use the `odds = True` argument:
+
+```python
+SBP_clumped.MR(action = 2, methods = ["Egger","IVW"], exposure_name = "SBP", outcome_name = "Stroke_eur", heterogeneity = True, odds = True)
+```
+
 As expected, many MR methods indicate that SBP is strongly associated with stroke, but there could be concerns for horizontal pleiotropy (instruments influencing the outcome through a different pathway than the one used as exposure) given the almost significant MR-Egger intercept p-value.
 To investigate horizontal pleiotropy in more details, a very useful method is Mendelian Randomization Pleiotropy RESidual Sum and Outlier (MR-PRESSO). MR-PRESSO is a method designed to detect and correct for horizontal pleiotropy. It will identify which instruments are likely to be pleiotropic on their effect on the outcome, and it will rerun an inverse-variance weighted MR after excluding them. It can be run using the `genal.Geno.MRpresso` method:
 
@@ -511,7 +534,7 @@ df_pheno = pd.read_csv("path/to/trait/data")
 
 > **Note:**
 > 
->    One important point is to make sure that the IDs of the participants are identical in the phenotypic data and in the genetic data.
+>    One important point is to make sure that both the Family IDs (FID) and Individual IDs (IID) of the participants are identical in the phenotypic data and in the genetic data. 
 
 Then, it is advised to make a copy of the `genal.Geno` instance containing our instruments as we are going to update their coefficients and to avoid any confusion:
 
@@ -522,7 +545,7 @@ SBP_adjusted = SBP_clumped.copy()
 We can then call the `genal.Geno.set_phenotype` method, specifying which column contains our trait of interest (for the association testing) and which column contains the individual IDs:
 
 ```python
-SBP_adjusted.set_phenotype(df_pheno, PHENO = "htn", IID = "IID")
+SBP_adjusted.set_phenotype(df_pheno, PHENO = "htn", IID = "IID", FID = "FID")
 ```
 
 At this point, genal will identify if the phenotype is binary or quantitative in order to choose the appropriate regression model. If the phenotype is binary, it will assume that the most frequent value is coding for control (and the other value for case), this can be changed with `alternate_control = True`:

{genal_python-0.9 → genal_python-1.1/docs}/requirements.txt

@@ -1,13 +1,14 @@
+sphinx
+sphinx_rtd_theme
 aiohttp==3.9.5
 nest_asyncio==1.5.5
-numpy>=1.24.4, <2.0
+numpy>=1.24.4,<2.0
 pandas>=2.0.3
 plotnine==0.12.3
 psutil==5.9.1
 pyliftover==0.4
 scikit_learn>=1.3.0
 scipy>=1.11.4
-sphinx_rtd_theme==1.3.0
 statsmodels==0.14.0
 tqdm==4.66.1
-wget==3.2
+wget==3.2

{genal_python-0.9 → genal_python-1.1}/docs/source/conf.py

@@ -13,7 +13,7 @@ sys.path.insert(0, os.path.abspath('../../'))
 project = 'genal'
 copyright = '2023, Cyprien A. Rivier'
 author = 'Cyprien A. Rivier'
-release = 'v0.9'
+release = 'v1.1'
 
 
 # -- General configuration ---------------------------------------------------

{genal_python-0.9 → genal_python-1.1}/docs/source/index.rst

@@ -3,12 +3,16 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
+.. image:: Images/genal_logo.png
+   :alt: genal_logo
+   :width: 400px
+
 genal: A Python Toolkit for Genetic Risk Scoring and Mendelian Randomization
 ============================================================================
 
-:Author: Cyprien Rivier
+:Author: Cyprien A. Rivier
 :Date: |today|
-:Version: "0.8"
+:Version: "1.0"
 
 Genal is a python module designed to make it easy to run genetic risk scores and mendelian randomization analyses. It integrates a collection of tools that facilitate the cleaning of single nucleotide polymorphism data (usually derived from Genome-Wide Association Studies) and enable the execution of key clinical population genetic workflows. The functionalities provided by genal include clumping, lifting, association testing, polygenic risk scoring, and Mendelian randomization analyses, all within a single Python module.
 
@@ -46,8 +50,8 @@ Citation
 If you use genal in your work, please cite the following paper:
 
 .. [Rivier.2024] *Genal: A Python Toolkit for Genetic Risk Scoring and Mendelian Randomization*
-   Cyprien Rivier, Cyprien A. Rivier, Santiago Clocchiatti-Tuozzo, Shufan Huo, Victor Torres-Lopez, Daniela Renedo, Kevin N. Sheth, Guido J. Falcone, Julian N. Acosta. 
-   medRxiv. 2024 May `10.1101/2024.05.23.24307776 <https://doi.org/10.1101/2024.05.23.24307776>`_.
+   Cyprien A. Rivier, Santiago Clocchiatti-Tuozzo, Shufan Huo, Victor Torres-Lopez, Daniela Renedo, Kevin N. Sheth, Guido J. Falcone, Julian N. Acosta. 
+   Bioinformatics Advances. 2024 December; `10.1093/bioadv/vbae207 <https://doi.org/10.1093/bioadv/vbae207>`_.
 
 References
 ----------

{genal_python-0.9 → genal_python-1.1}/docs/source/introduction.rst

@@ -7,10 +7,10 @@ Installation
 
     .. code-block:: bash
 
-        conda create --name genal_env python=3.11
+        conda create --name genal_env python=3.8
         conda activate genal_env
 
-The genal package requires Python 3.11. Download and install it with pip: 
+The genal package requires Python 3.8 or later. Download and install it with pip: 
 
 .. code-block:: bash
 
@@ -22,17 +22,26 @@ And import it in a python environment with:
 
     import genal
 
-The main genal functionalities require a working installation of PLINK v1.9 (and not 2.0 as certain functionalities have not been updated yet) that can be downloaded here: https://www.cog-genomics.org/plink/ 
-Once downloaded, the path to the plink 1.9 executable should be set with:
+The main genal functionalities require a working installation of PLINK v2.0. 
+If you have already installed plink v2.0, you can set the path to its executable with:
 
 .. code-block:: python
 
     genal.set_plink(path="/path/to/plink/executable/file")
 
+If plink is not installed, genal can install the correct version for your system with the :meth:`~genal.tools.install_plink` function:
+
+.. code-block:: python
+
+    genal.install_plink()
+
 ========
 Tutorial
 ========
 
+.. image:: Images/Genal_flowchart.png
+   :alt: Genal_flowchart
+
 For the purpose of this tutorial, we are going to build a PRS of systolic blood pressure (SBP) and investigate the genetically-determined effect of SBP on the risk of stroke. We will use both summary statistics from Genome-Wide Association Studies (GWAS) and individual-level data from the UK Biobank as our test population. We are going to go through the following steps:
 
 Table of contents
@@ -51,7 +60,7 @@ h. `GWAS Catalog`_
 Data loading
 ============
 
-We start this tutorial with publicly available summary statistics data from a large GWAS of systolic blood pressure (https://www.nature.com/articles/s41588-018-0205-x). After downloading and unzipping the summary statistics, we load the data into a pandas dataframe:
+We start this tutorial with publicly available summary statistics data from a large GWAS of systolic blood pressure `Link to study <https://www.nature.com/articles/s41588-018-0205-x>`_. `Download link <http://ftp.ebi.ac.uk/pub/databases/gwas/summary_statistics/GCST006001-GCST007000/GCST006624/Evangelou_30224653_SBP.txt.gz>`_. After downloading and unzipping the summary statistics, we load the data into a pandas dataframe:
 
 .. code-block:: python
 
@@ -179,8 +188,7 @@ By default, the reference panel used is the European (EUR) one. You can specify
 
     SBP_Geno.preprocess_data(preprocessing='Fill_delete', reference_panel="afr")
 
-You can also use a custom reference panel by specifying the path to bed/bim/fam files (without the extension) in the ``reference_panel`` argument.
-
+You can also use a custom reference panel by specifying to the reference_panel argument a path to bed/bim/fam (plink v1.9 format) or pgen/pvar/psam files (plink v2.0 format), without the extension.
 
 Clumping
 --------
@@ -215,7 +223,7 @@ Computing a Polygenic Risk Score (PRS) can be done in one line with the :meth:`~
 
     SBP_clumped.prs(name="SBP_prs", path="path/to/genetic/files")
 
-The genetic files of the target population can be either contained in one triple of bed/bim/fam files with information for all SNPs, or divided by chromosome (one bed/bim/fam triple for chr 1, another for chr 2, etc...). In the latter case, provide the path by replacing the chromosome number by ``$`` and genal will extract the necessary SNPs from each chromosome and merge them before running the PRS. For instance, if the genetic files are named ``Pop_chr1.bed``, ``Pop_chr1.bim``, ``Pop_chr1.fam``, ``Pop_chr2.bed``, ..., you can use:
+The genetic files of the target population can be either contained in one triple of bed/bim/fam or pgen/pvar/psam files with information for all SNPs, or divided by chromosome (one bed/bim/fam or pgen/pvar/psam triple for chr 1, another for chr 2, etc...). In the latter case, provide the path by replacing the chromosome number by `$` and genal will extract the necessary SNPs from each chromosome and merge them before running the PRS. For instance, if the genetic files are named `Pop_chr1.bed`, `Pop_chr1.bim`, `Pop_chr1.fam`, `Pop_chr2.bed`, ..., you can use:
 
 .. code-block:: python
 
@@ -318,7 +326,8 @@ Mendelian Randomization
 
 To run MR, we need to load both our exposure and outcome SNP-level data in :class:`~genal.Geno` instances. In our case, the genetic instruments of the MR are the SNPs associated with blood pressure at genome-wide significant levels resulting from the clumping of the blood pressure GWAS. They are stored in our ``SBP_clumped`` :class:`~genal.Geno` instance which also include their association with the exposure trait (instrument-SBP estimates in the ``BETA`` column).
 
-To get their association with the outcome trait (instrument-stroke estimates), we are going to use SNP-level data from a large GWAS of stroke performed by the GIGASTROKE consortium (`Nature article <https://www.nature.com/articles/s41586-022-05165-3>`_):
+To get their association with the outcome trait (instrument-stroke estimates), we are going to use SNP-level data from a large GWAS of stroke performed by the GIGASTROKE consortium:
+`Link to study <https://www.nature.com/articles/s41586-022-05165-3>`_. `Download link <http://ftp.ebi.ac.uk/pub/databases/gwas/summary_statistics/GCST90104001-GCST90105000/GCST90104539/GCST90104539_buildGRCh37.tsv.gz>`_.
 
 .. code-block:: python
 
@@ -461,8 +470,12 @@ And that will give:
     1      SBP  Stroke_eur            Egger Intercept  1499 -0.001381  0.000813  8.935529e-02  2959.965136  1497  1.253763e-98
     2      SBP  Stroke_eur  Inverse-Variance Weighted  1499  0.023049  0.001061  1.382645e-104 2965.678836  1498  4.280737e-99
 
+If you wish to display the coefficients as odds ratios with confidence intervals for a binary outcome trait, you can use the `odds = True` argument:
+
+.. code-block:: python
+
+    SBP_clumped.MR(action=2, methods=["Egger","IVW"], exposure_name="SBP", outcome_name="Stroke_eur", heterogeneity=True, odds=True)
 
-    
 As expected, many MR methods indicate that SBP is strongly associated with stroke, but there could be concerns for horizontal pleiotropy (instruments influencing the outcome through a different pathway than the one used as exposure) given the almost significant MR-Egger intercept p-value.
 
 To investigate horizontal pleiotropy in more detail, a very useful method is Mendelian Randomization Pleiotropy RESidual Sum and Outlier (MR-PRESSO). 
@@ -499,7 +512,7 @@ Let's start by loading phenotypic data:
     df_pheno = pd.read_csv("path/to/trait/data")
 
 .. note::
-   One important point is to make sure that the IDs of the participants are identical in the phenotypic data and in the genetic data.
+   One important point is to make sure that both the Family IDs (FID) and Individual IDs (IID) of the participants are identical in the phenotypic data and in the genetic data.
 
 Then, it is advised to make a copy of the :class:`~genal.Geno` instance containing our instruments as we are going to update their coefficients and to avoid any confusion:
 
@@ -511,7 +524,7 @@ We can then call the :meth:`~genal.Geno.set_phenotype` method, specifying which
 
 .. code-block:: python
 
-    SBP_adjusted.set_phenotype(df_pheno, PHENO="htn", IID="IID")
+    SBP_adjusted.set_phenotype(df_pheno, PHENO="htn", IID="IID", FID="FID")
 
 At this point, genal will identify if the phenotype is binary or quantitative in order to choose the appropriate regression model. If the phenotype is binary, it will assume that the most frequent value is coding for control (and the other value for case), this can be changed with ``alternate_control=True``::