diff --git a/doc/build/html/_static/manhattan.png b/doc/build/html/_static/manhattan.png new file mode 100755 index 0000000000000000000000000000000000000000..af738508cf5b9ff5e56552b1e2db81e550a1876a Binary files /dev/null and b/doc/build/html/_static/manhattan.png differ diff --git a/doc/source/about.rst b/doc/source/about.rst index 9eaef614aad3f2f3d7090bfb58eaa24858348b18..c6aa632940deb4c64831fb469441ca5a16fd91ab 100644 --- a/doc/source/about.rst +++ b/doc/source/about.rst @@ -1,25 +1,23 @@ -What is JASS? -============= +What is JASS: A python package to perform Multi-trait GWAS +========================================================== -JASS is a python package that handles the computation of joint statistics over sets of selected GWAS results, and the interactive exploration of the results through a web interface or static graph (https://jass.pasteur.fr/index.html). JASS is a highly versatile tool that can be used either as : +JASS is a Python package that handles the computation of joint statistics over sets of selected GWAS results through a command-line tool. -* (i) an online web service, or +More precisely, users can perform multi-trait GWAS and display static plots of the results on their own data through the command-line interface. The functionality of this package can be explored on a web server, https://jass.pasteur.fr/, which allows users to perform multi-trait GWAS on a database of 184 summary statistics. -* (ii) a command line tool that one can use independently for development purposes. +In this documentation, we cover the steps required for installing the software and illustrate its usage through examples. -More precisely, The generation of joint statistics over a set of selected studies, and the generation of static plots to display the results, is easily performed using the command line interface. These functionalities can also be accessed through a web application embedded in the python package, which also enables the exploration of the results through a dynamic JavaScript interface.The JASS analysis module handles the data processing, going from the import of the data up to the computation of the joint statistics and the generation of the various static plots to illustrate the results. +We also briefly describe in the next section the pre-processing of raw GWAS data, which can be performed through a companion `Nextflow pipeline provided <https://gitlab.pasteur.fr/statistical-genetics/jass_suite_pipeline>`_ alongside the JASS package. -In this documentation, we cover first the steps required for installing the software, and illustrate its usage through a reproducible example to guide the users. +For method details and applications, check out our publications related to JASS or its accompanying packages (RAISS). -We also briefly describe in the next section the pre-processing of raw GWAS data which can be performed through a companion script provided on behalf of the JASS package. - -For method details and application inspiration check out our publications with JASS or its accompanying packages (RAISS): JASS application paper :cite:`julienne2021multitrait` +Study on the statistical power of JASS :cite:`suzuki2024trait` + JASS computational architecture :cite:`julienne2020jass` RAISS :cite:`10.1093/bioinformatics/btz466` -.. bibliography:: reference.bib diff --git a/doc/source/bibliography.rst b/doc/source/bibliography.rst new file mode 100644 index 0000000000000000000000000000000000000000..8f5fcf360f397363749f81f7c3956606e77a957d --- /dev/null +++ b/doc/source/bibliography.rst @@ -0,0 +1,4 @@ +References +========== + +.. bibliography:: reference.bib diff --git a/doc/source/command_line_usage.rst b/doc/source/command_line_usage.rst index e6a7f27b73ecc0e2961938384152de0f888b719b..3de239916d4f6e04d65c335f4e6f9d585808d4e7 100644 --- a/doc/source/command_line_usage.rst +++ b/doc/source/command_line_usage.rst @@ -6,10 +6,3 @@ This section contains the exhaustive list of the sub-commands and options availa .. argparse:: :ref: jass.__main__.get_parser :prog: jass - -Utilities -~~~~~~~~~~~~~~~~~~~ - -.. argparse:: - :ref: scripts.hdf5_add_attributes.get_parser - :prog: scripts/hdf5_add_attributes diff --git a/doc/source/data_import.rst b/doc/source/data_import.rst index c8630ef69d787f7905102fa0c8401dc2443c23a1..cb4bf63261ff24c1356ab215b2b4426d5bddb045 100644 --- a/doc/source/data_import.rst +++ b/doc/source/data_import.rst @@ -1,14 +1,32 @@ Data preparation ================ -The **first paragraph of this section describes the input data** that have to be provided in order to run JASS, as well as their format. -To generate these data, **you can use the procedure described in the second paragraph.** -The final paragraph describes an imputation tool compatible with JASS input format (optional preparation step). + +JASS requires GWAS summary statistics to be harmonized and formatted (see **JASS input data** section below) . + We advice the user to follow the methods provided in the **first section** of this page to harmonize their data. + The **second section** describes the different input data required by JASS. +The **third section** describes an imputation tool compatible with JASS input format (optional preparation step). +Finally, we provided a command line example to assemble input data into the JASS inittable (the database of curated summary statistics used to perform the multi-trait GWAS) + + +How to generate input data for JASS +----------------------------------- + +Option 1 Nextflow pipeline: +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Preprocessing steps for JASS (data harmonisation and imputation)have been gathered into a Nextflow pipeline : `JASS pipeline Suite <https://gitlab.pasteur.fr/statistical-genetics/jass_suite_pipeline>`_. +While this option might have stronger installation requirements, it ensure reproducibility by leveraging docker containers (fixed version of JASS and accompanying packages). +It will also be much more efficient is you a large number of heterogeneous data to handle and a computing cluster available. + + +Option 2 Prepare input data using the JASS pre-processing Python package: +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +To standardize the format of the input GWAS datasets, you can use the `JASS Pre-processing package <https://gitlab.pasteur.fr/statistical-genetics/JASS_Pre-processing>`_. The `JASS Pre-processing documentation <http://statistical-genetics.pages.pasteur.fr/JASS_Pre-processing/>`_ details the use of this tool. JASS input data --------------- -JASS data, from which all statistics can be computed, are stored in an HDF5 file. +JASS data, from Multi-trait GWAS can be computed, are stored in an HDF5 file. This file can be created with the procedure `create-inittable`. This procedure needs the following input files to complete: GWAS description @@ -22,7 +40,7 @@ This file that must contain the following columns and tab-separated: | GIANT | HIP | Hip Circumference | Anthropometry| 142762 | | | Shungin et al. 2015| url to reference| url to data | local path to data | +-------------+----------+-------------------+--------------+--------------------+--------------------+--------------------+--------------------+-----------------+-------------+--------------------+ -The Consortium and outcome names must correspond to the name of the summary statistic files and covariance columns. Nsample, Ncase and Ncontrol can be left blank. The last four columns +The Consortium and outcome names must correspond to the name of the summary statistic files and covariance columns as describe in the following section. Nsample, Ncase and Ncontrol can be left blank. The last four columns can also be left blank if the user doesn't want to run JASS on a server. GWAS results files @@ -36,6 +54,7 @@ GWAS results files in the tabular format by chromosome (tab separated) *all in t | rs6548219| 30762 | A | G | -1.133 | +----------+-------+------+-----+--------+ +**A0** is the effect allele. The name of file *MUST* follow this pattern : "z_{CONSORTIUM}_{TRAIT}_chr{chromosome number}.txt". The consortium and the trait must be capitalized and must *NOT* contain _ . @@ -43,8 +62,8 @@ Covariance file (OPTIONAL) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ A covariance file that corresponds to the covariance between traits under H0. This file is a tab-separated tabular file. -We recommend that this covariance file to be computed using the `LDScore regression <https://github.com/bulik/ldsc/wiki/Heritability-and-Genetic-Correlation>`_ -However, this step can be fastidious and if not provided by the user, a matrix will be inferred from low signal zscore. +We recommend that this covariance file to be computed using the `LDScore regression <https://gitlab.pasteur.fr/statistical-genetics/jass_suite_pipeline#running-the-ldsc-regression-covariance-step>`_ +However, this step can be fastidious and if not provided by the user, a matrix will be inferred from low signal zscore. The traits names (columns and row names of the matrix) must correspond to the summary statistic file names: ``z_{CONSORTIUM}_{TRAIT}``. You can see below an example subset that illustrates this format:: @@ -55,8 +74,9 @@ The traits names (columns and row names of the matrix) must correspond to the su GABRIEL_ASTHMA 0.085 0.025 0.0382 1.0134 -0.0104 GEFOS_BMD-FOREARM -0.0061 -0.0002 0.0048 -0.0104 1.0123 + Region file -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~ Region file of approximately independant LD regions to the BED file. For european ancestry and grch37/hg19, we suggest to use the regions as defined by :cite:`Berisa2015`, which is already available in `the data folder of the package <https://gitlab.pasteur.fr/statistical-genetics/jass/blob/master/data/fourier_ls-all.bed>`_. @@ -71,60 +91,6 @@ Region file of approximately independant LD regions to the BED file. For europea For inferring approximately independant LD regions from your own panel we recommend using https://privefl.github.io/bigsnpr/ . See :cite:`10.1093/bioinformatics/btab519` on the matter. - -Init table generation ---------------------- - -The init table generation is performed using JASS with the previously-mentionned input files. Below is a command line example that illustrates the syntax to generate this init table. - -.. code-block:: shell - - # configure - export JASS_DATA_DIR=/tmp/JASSDATA - # import GWAS data into JASS - jass create-inittable --input-data-path "GWAS/*.txt" --init-covariance-path "COV.txt" --regions-map-path "regions.txt" --description-file-path "description.txt" --init-table-path "inittable.hdf5" - -.. _Create initTable: - -How to generate input data for JASS ------------------------------------ - -Option 1 nextflow pipeline : -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Preprocessing steps for JASS (data harmonisation and imputation)have been gathered in one nextflow pipeline : `JASS pipeline Suite <https://gitlab.pasteur.fr/statistical-genetics/jass_suite_pipeline>`_. -While this option might have stronger installation requirements, it ensure reproducibility by leveraging docker containers (fixed version of JASS and accompanying packages). -It will also be much more efficient is you a large number of heterogeneous data to handle and a computing cluster available. - - -Option 2 manually prepare input data: -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To standardize the format of the input GWAS datasets, you can use the `JASS Pre-processing package <https://gitlab.pasteur.fr/statistical-genetics/JASS_Pre-processing>`_. The `JASS Pre-processing documentation <http://statistical-genetics.pages.pasteur.fr/JASS_Pre-processing/>`_ details the use of this tool. - -We think that the best way to compute such covariance from summary statistics is to use the LD-score regression (https://github.com/bulik/ldsc/wiki/Heritability-and-Genetic-Correlation). In the output of the LD-score genetic correlation use the intercept (intercept heritability of trait i for variance of trait i and intercept of the genetic covariance for the covariance between the two traits):: - - - Heritability of phenotype 1 - --------------------------- - Total Observed scale h2: 0.0674 (0.0091) - Lambda GC: 1.105 - Mean Chi^2: 1.147 - Intercept: 1.0234 (0.0098) - Ratio: 0.159 (0.067) - - Heritability of phenotype 2/2 - ----------------------------- - Total Observed scale h2: 0.1412 (0.0083) - Lambda GC: 1.0466 - Mean Chi^2: 1.1987 - Intercept: 0.7664 (0.0107) - Ratio < 0 (usually indicates GC correction). - - Genetic Covariance - ------------------ - Total Observed scale gencov: 0.0089 (0.0044) - Mean z1*z2: 0.003 - Intercept: -0.0151 (0.0062) - Data imputation (optional) -------------------------- @@ -135,10 +101,8 @@ Creation of the JASS inittable ------------------------------ Once, GWAS summary statistics are harmonized, they are integrated into -one file by the using jass command line (see detail in command line usage) +one file by the using jass command line (see detail in command line usage). Note that GWAS results must be provided through name pattern (ruled used by Unix Shell) corresponding to the file to be included. .. code-block:: console jass create-inittable --input-data-path "harmonized_GWAS_files/*.txt" --init-covariance-path $path1/Covariance_matrix_H0.csv --regions-map-path $path2/Region_file.bed --description-file-path $path3/Data_summary.csv --init-table-path $path4/init_table_EUR_not_imputed.hdf5 - -.. bibliography:: reference.bib diff --git a/doc/source/generating_joint_analysis.rst b/doc/source/generating_joint_analysis.rst index d6b38869af551286df81ed17f0c16eade101e2ff..517c617821204daeb4a4f19bcfe9ce191ad1e14c 100644 --- a/doc/source/generating_joint_analysis.rst +++ b/doc/source/generating_joint_analysis.rst @@ -1,41 +1,75 @@ Compute Multi-trait GWAS with JASS ================================== -Once the GWAS summary statistics are integrated in the inittable, -you can generate analysis for any combination -and several joint tests with the command jass create-project-data -(see command line usage for the detail of arguments). +Once the GWAS summary statistics are integrated in the inittable (see Data preparation), +you can generate multi-trait GWAS for any set of traits +and for several joint tests with the command jass create-project-data +(see command line reference for the detail of arguments). -Whatever the test used, the command will generate three output: -* A **HDFStore containing several tables** (Each table can be read from the HDFStore with the pandas.read_hdf function): - - 'SumStatTab' : The results of the joint analysis by SNPs - - 'PhenoList' : the meta data of analysed GWAS - - 'COV' : The H0 covariance used to perform joint analysis - - 'GENCOV' (If present in the initTable): The genetic covariance as computed by the LDscore. - - 'Regions' : Results of the joint analysis summarised by LD regions (Notably Lead SNPs by regions) - - 'summaryTable': a double entry table summarizing the number of significant regions by test (univariate vs joint test) +Command Line example +-------------------- +Here is a mock up example of a command line to generate a multi-trait GWAS on 4 traits using the *Omnibus* test. +See command line usage for more details + +.. code-block:: console + + jass create-project-data --init-table-path init_table/init_table.hdf5 --phenotype z_MAGIC_GLUCOSE-TOLERANCE z_MAGIC_FAST-GLUCOSE z_MAGIC_FAST-INSULIN z_MAGIC_HBA1C --worktable-path ./work_glycemic.hdf5 --manhattan-plot-path ./manhattan_glycemic.png --quadrant-plot-path ./quadrant_glycemic.png + + +Generated Results +----------------- +Whatever the test used, the command will generate three outputs: + +* A **HDFStore containing several tables** (Each table can be extracted using the can extracted to a tsv using the `jass extract-tsv <https://statistical-genetics.pages.pasteur.fr/jass/command_line_usage.html#extract-tsv>`_ be read from the HDFStore with the pandas.read_hdf function): + + * 'SumStatTab' : The results of the joint analysis by SNPs + + * 'PhenoList' : the meta data of GWAS included in the multi-trait GWAS + + * 'COV' : The H0 covariance used to perform joint analysis + + * 'GENCOV' (If present in the initTable): The genetic covariance as computed by the LDscore. + + * 'Regions' : Results of the joint analysis summarised by LD-independent regions (notably Lead SNPs by regions) + + * 'summaryTable': a double entry table summarizing the number of significant regions by test (univariate vs joint test) * A **.png Manhattan plot** of the joint test p-values: -.. image:: ./_static/manhattan_glycemic_blood_asthma.png +.. image:: ./_static/manhattan.png * A **.png Quadrant plot** which is a scatter plot of the minimum p-value by region of the joint test with respect to the minimum p-value by region of the univariate tests. This plot provides an easy way to see if your joint analysis detected association not previously reported in the litterature. .. image:: ./_static/quadrant_glycemic_blood_asthma.png +Available multi-trait tests: +---------------------------- + +Several multi-trait tests are available through the *jass create-project-data* command. +The *Omnibus* test can be interpreted as a multivariate analysis of variance using alternative allele counts as a grouping variable. The *SumZ* test perform a linear combination of traits Z-scores and test this combination for association. +Please refer to +:cite:`julienne2021multitrait` +for the full description and derivation of those test + The Omnibus tests ------------------ +^^^^^^^^^^^^^^^^^ + +If no option is provided to specify the test, a Omnibus test analysis will be performed. For instance: + +.. code-block:: shell + + jass create-project-data --init-table-path inittable_name.hdf5 --phenotypes z_CONSORTIUM1_TRAIT1 z_CONSORTIUM1_TRAIT2 z_CONSORTIUM2_TRAIT1 --worktable-path worktable_name.hdf5 --manhattan-plot-path manhattan_name.png --quadrant-plot-path /quadrant_name.png --qq-plot-path QQplots_name.png -If no method option, a Omnibus test analysis will be performed. The SumZ test -------------- +^^^^^^^^^^^^^ + If the flag --sumz is passed to the jass create-project-data a SumZ test will be performed. -By default, all the traits will have the same weight. +By default, all the traits will have the same weight in the linear combination. -If the user wishes to, she/he can specify a vector of weight by using the --custom-loadings option. +If the user wishes to, they can specify a vector of weight by using the --custom-loadings option. .. code-block:: shell @@ -52,7 +86,6 @@ the test_loadings.csv is comma separated file with the following structure: +-----------------------------+-------+ - Access HDFStore components -------------------------- @@ -71,13 +104,4 @@ For instance if you want to access the Regions table : pd.read_hdf("WK_test.hdf5", "Regions") Note that is you wish that the SumStatTab table to be saved as a csv file you can provide the command lines -with the --csv-file-path option and a csv will be generated as well. Outputting a csv while lengthen execution -and require the appropriate storage space. - -Command Line example --------------------- - -See command line usage for details -.. code-block:: shell - - jass create-project-data --init-table-path init_table/init_table_EUR_not_imputed.hdf5 --phenotype z_MAGIC_GLUCOSE-TOLERANCE z_MAGIC_FAST-GLUCOSE z_MAGIC_FAST-INSULIN z_MAGIC_HBA1C --worktable-path ./work_glycemic.hdf5 --manhattan-plot-path ./manhattan_glycemic.png --quadrant-plot-path ./quadrant_glycemic.png +with the --csv-file-path option and a csv will be generated as well. Outputting a csv will lengthen the execution and require the appropriate storage space (several 10Gb depending of the number of traits). diff --git a/doc/source/get_predicted_gain.rst b/doc/source/get_predicted_gain.rst index 9dea792471e07a2846adb7a73d92f8f0c14ea103..ffff58305137edfb7d5652850a4c006e703cbc88 100644 --- a/doc/source/get_predicted_gain.rst +++ b/doc/source/get_predicted_gain.rst @@ -1,7 +1,7 @@ Compute JASS power gain from the genetic architecture of traits =============================================================== -In a recent study :cite:`suzuki2023trait`, we explore how the genetic architecture of the set of traits (heritability, genetic covariance, heritability undetected by the univariate test, ...) can be predictive of statistical power gain of the multi-trait test. +In a recent study :cite:`suzuki2024trait`, we explore how the genetic architecture of the set of traits (heritability, genetic covariance, heritability undetected by the univariate test, ...) can be predictive of statistical power gain of the multi-trait test. @@ -34,6 +34,5 @@ When executed the command will created a report at --gain-path ['z_SPIRO-UKB_FVC'; 'z_SPIRO-UKB_FEV1'; 'z_TAGC_ASTHMA'],0.1,0.1731946683845993,0.0637,0.3843393026739591,0.2785193310634847,0.7976315890930669,0.8139196701681637,0.8013809378674498,0.06428524764535551 ['z_GIANT_HIP'; 'z_GLG_HDL'; 'z_GLG_LDL'; 'z_MAGIC_2HGLU-ADJBMI'],0.2,0.14899001074867035,0.01535,0.12076877719858631,0.22628198390356655,0.9055326131023057,0.6573854616675169,0.7879956172999502,-0.010766494024690904 -The last column provide the predicted gain ("the higher the more promising"). Note that extrapoling on new data might give lesser performances than reported in :cite:`suzuki2023trait`. +The last column provide the predicted gain ("the higher the more promising"). Note that extrapoling on new data might give lesser performances than reported in :cite:`suzuki2024trait`. -.. bibliography:: reference.bib \ No newline at end of file diff --git a/doc/source/index.rst b/doc/source/index.rst index 87967f4a2da31ea34bc97b1035c41e2f138b0896..1cbd3ad3ce91d1fe583b1a88c6c810480f70fb8e 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -14,10 +14,8 @@ JASS documentation install data_import generating_joint_analysis - get_predicted_gain + bibliography command_line_usage - web_usage - web_admin develop Indices and tables diff --git a/doc/source/install.rst b/doc/source/install.rst index 71cbafaadfe8c533636a93e5014f7c9f8eeb4e4d..0d26d35e88c83a7ed3fa291e3ea3444a418cdc8f 100644 --- a/doc/source/install.rst +++ b/doc/source/install.rst @@ -1,9 +1,8 @@ Installation ============ -You can use JASS locally either using the command line interface in a terminal, or by running a web server. Deployment in a public server is also later discussed in this document. - -You need **python3** to install and use JASS. As of April 2022, JASS runs on python from 3.8 to 3.10. +You can use JASS locally through the command line interface in a terminal. +You need **python3** to install and use JASS. As of May 2025, JASS runs on python from 3.8 to 3.12. Installation with pip (recommended) ----------------------------------- @@ -16,66 +15,6 @@ We advise users to install jass in a virtual environment pip3 install git+https://gitlab.pasteur.fr/statistical-genetics/jass.git pip3 install -r https://gitlab.pasteur.fr/statistical-genetics/jass/-/raw/master/requirements.txt - -Installation with conda ------------------------ - -A procedure for the correct installation of JASS in Anaconda environment for development purpose is developed in detail below. - -**1. Create a specific directory and load the code on your laptop (only the first time)** - -For example, the directory $HOME/DEVELOP_JASS has been created. -In a TERMINAL window, type the following instructions: - -.. code-block:: shell - - cd $HOME/DEVELOP_JASS - git clone https://gitlab.pasteur.fr/statistical-genetics/jass - -**2. Change directory to the JASS main directory** - -.. code-block:: shell - - cd $HOME/DEVELOP_JASS/jass - -**3. Create a specific virtual ANACONDA environment for JASS:** - -.. note:: - - You have to check that you are in the **base** environment of Anaconda before creating the new virtual environment: - -.. code-block:: shell - - conda create --name Dev_Jass_Python python=3.10 - -**4. Activation of the new environment** - -.. code-block:: shell - - conda activate Dev_Jass_Python - -**5. Installing JASS dependencies** - -.. code-block:: shell - - pip install -r requirements.txt - -**6. Installing JASS for development purpose** - -.. code-block:: shell - - pip install -e . - -**7. Installation verification** - -.. code-block:: shell - - pip freeze - -Installing it this way will automatically import and setup all of the dependencies required to run JASS. - -This is pretty much all you need to do to use JASS on the command line, or to run a local personal web server. To deploy JASS on a public web server, please refer to the "Public server deployment" section. - Additional software installation on Linux ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -85,92 +24,5 @@ Some python packages require additional non-python software that you might need sudo apt install libfreetype6-dev #(required by matplotlib) sudo apt install libhdf5-dev #(required by tables) - sudo apt install rabbitmq-server #(required by celery) - -Additional software installation on Windows -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. tip:: For Windows, an easy option is to install the free software package manager called chocolatey. - -In order to have a correct installation of RabbitMQ on windows, we recommend to install chocolatey by running the following command as Administrator in a powershell: - -.. code-block:: shell - - Set-ExecutionPolicy Bypass -Scope Process -Force; iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1')) - -Then, you can install RabbitMQ with the "choco install" command: - -.. code-block:: shell - - Choco install rabbitmq - -Run JASS as a web application (optional) ----------------------------------------- - -To run locally JASS as a web application, it is recommended to use docker compose as it handles all dependencies in one command. -If using docker compose is not an option, you need to launch two servers in two different processes, the `celery` task management server and the web server. The web server handles the HTTP requests, and sends all computation requests to the task management server. - -Launching with docker compose (recommended) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Once docker is installed, copy the :ref:`initTable.hdf5 you created <Create initTable>` in data/ folder and then run - -.. code-block:: shell - - # build the application - docker compose build - # launch the whole application - docker compose up - # then visit http://0.0.0.0:3000/ - -If you just want to try jass with test data (i.e without creating an initTable), run: - -.. code-block:: shell - - # build the application - docker compose build - # launch the whole application with - docker compose -f docker-compose.yaml -f docker-compose.test.yaml up - # then visit http://0.0.0.0:3000/ - -launching the two servers on Linux -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The command lines below show how to launch the two servers. Please note that you should of course not use this for any use beyond tests and personnal use, we provide further instructions below to deploy JASS on shared/public servers. - -.. code-block:: shell - - # launch celery to process tasks - celery -A jass worker - ## and in ANOTHER TERMINAL - # launch the web server - jass serve - -By default, the Jass server will listen to requests on the port 8080 of your machine. You can control the host and port that the JASS standalone webserver listens to through two environment variables, ``JASS_HOST`` and ``JASS_PORT``, that you just have to set before to launch the web server. - -Launching the celery server on Windows -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -In order to launch the celery server on windows, it is necessary to use the following command in a terminal: - -.. code-block:: shell - - celery -A jass worker --pool=solo - -.. warning:: - The command recommended for Linux crashes when it is used on windows due to incorrect recognition of the prefork option on windows by the billiard library. - The part “--pool=solo†is necessary on windows because this is the only option of celery that works on windows. - -Launching the web server on Windows -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The web server is launched in another terminal (the same as on Linux): - -.. code-block:: shell - - jass serve - -Public server deployment (optional) ------------------------------------ -Helm charts are available in the `chart folder of the source repository <https://gitlab.pasteur.fr/statistical-genetics/jass/tree/master/chart>`_. These charts automate the installation and update of the application in a kubernetes cluster. -In this specific deployment, the JASS web application is hosted by an NGINX server, served by the uvicorn library. It communicates with a celery container that handles the user-launched tasks. Many other deployment options are of course possible, use whichever suits your infrastructure! diff --git a/doc/source/reference.bib b/doc/source/reference.bib index 901b14a9691c75bac3e660837b9f99777a24a58a..0d010f9cd3cd9606122e16ca00cb56f5c59a8b64 100644 --- a/doc/source/reference.bib +++ b/doc/source/reference.bib @@ -20,12 +20,14 @@ publisher={Oxford University Press} } -@article{suzuki2023trait, - title={Trait selection strategy in multi-trait GWAS: Boosting SNPs discoverability}, +@article{suzuki2024trait, + title={Trait selection strategy in multi-trait GWAS: Boosting SNP discoverability}, author={Suzuki, Yuka and M{\'e}nager, Herv{\'e} and Brancotte, Bryan and Vernet, Rapha{\"e}l and Nerin, Cyril and Boetto, Christophe and Auvergne, Antoine and Linhard, Christophe and Torchet, Rachel and Lechat, Pierre and others}, - journal={bioRxiv}, - year={2023}, - publisher={Cold Spring Harbor Laboratory Preprints} + journal={Human Genetics and Genomics Advances}, + volume={5}, + number={3}, + year={2024}, + publisher={Elsevier} } diff --git a/doc/source/web_admin.rst b/doc/source/web_admin.rst deleted file mode 100644 index f2acb5df80c57487be9bb87b00fc1d40efee8221..0000000000000000000000000000000000000000 --- a/doc/source/web_admin.rst +++ /dev/null @@ -1,86 +0,0 @@ -Web admin -=============================================================================== - -Updating data -------------------------------------------------------------------------------- - -You can update data using kubectl, to do so see this `"How To" <https://gitlab.pasteur.fr/statistical-genetics/jass/-/blob/master/chart/HOWTO.md?ref_type=heads#updating-data-including-inittablehdf5>`_. - -An alternative using fex.pasteur.fr is also proposed, with no binary to install locally. - -Upload to fex -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Go to https://fex.pasteur.fr/fup, click on "fex yourself" and choose the file you want to send. -In our example it is initTableTest.hdf5 - -.. image:: _static/fex-upload.png - :width: 100% - -Get the fex link -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -You then receive an email containing the url where the initTable is available, copy it. -In our example it is https://dl.pasteur.fr/fop/6atgurR3/initTableTest.hdf5 - -.. image:: _static/fex-email.png - :width: 100% - -Go to gitlab pipelines -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Go to https://gitlab.pasteur.fr/statistical-genetics/jass/-/pipelines - -Click on the last grey/green circle on the right (indicated 1 in the following image). -Then on the task ``upload-from-fex-to-dev`` (indicated 2) if you want to send the file in dev. -A job is also proposed related to master pipelines. - -.. image:: _static/gitlab-pipelines.png - :width: 100% - -Trigger while providing the URL -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Provide in an variable name ``FEX_URL`` the url. -In our example ``FEX_URL=https://dl.pasteur.fr/fop/6atgurR3/initTableTest.hdf5`` - -.. image:: _static/trigger-job-with-url.png - :width: 100% - -After some time the job is completed, you see with the ls that the file is now there. - -After the job is completed, in the right part you see "Job artifact", when browsing them you have the -file you have added, and the previous one that was replaced. -Artefact are keep 1 month as of March 2024. - -.. image:: _static/job-done-with-url.png - :width: 100% - -Deleting data -------------------------------------------------------------------------------- - -You can also simply delete hdf5 file (and only them). - -Go to https://gitlab.pasteur.fr/statistical-genetics/jass/-/pipelines - -Click on the last grey/green circle on the right (indicated 1 in the following image). -Then on the task ``delete-data-from-dev`` (indicated 2). - -.. image:: _static/gitlab-pipelines-delete-file.png - :width: 100% - -Trigger while providing the filename -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Provide in an variable name ``HDF5_FILENAME`` the hdf5 filename (no relative path allowed). -In our example ``HDF5_FILENAME=initTableTest.hdf5`` - -.. image:: _static/trigger-job-with-filename.png - :width: 100% - -Also in the right part you see "Job artifact", when browsing them you have the -file you just removed. -Artefact are keep 1 month as of March 2024. - -.. image:: _static/job-done-with-filename.png - :width: 100% \ No newline at end of file diff --git a/doc/source/web_usage.rst b/doc/source/web_usage.rst deleted file mode 100644 index b5c59e20a425f276c94357f37fe51441b32c0315..0000000000000000000000000000000000000000 --- a/doc/source/web_usage.rst +++ /dev/null @@ -1,14 +0,0 @@ -Web usage -========= - -The web interface of JASS allows you to launch joint analyses over different datasets, and explore their results. - -.. image:: _static/jass_welcome_page.png - :width: 100% - :alt: JASS welcome page - -The next screen lets you choose the datasets that you wish to analyse - -.. image:: _static/jass_select_phenotypes.png - :width: 100% - :alt: JASS phenotype selection page diff --git a/jass/__init__.py b/jass/__init__.py index 1f1936152ef05f96cc5a43fe50a4c93359902bd4..989eb0d44f40125065ecb821b40a24cbc6759589 100644 --- a/jass/__init__.py +++ b/jass/__init__.py @@ -9,9 +9,5 @@ Submodules config models - server - tasks util """ - -#from jass.tasks import celery