Merge pull request #607 from TheJacksonLaboratory/release_v2.0.0-RC2

Release v2.0.0-RC2

.github/workflows/pages-latest.yml

@@ -0,0 +1,71 @@
+# Simple workflow for deploying static content to GitHub Pages
+name: Deploy the latest documentation to GitHub pages
+
+on:
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+  # Runs on pushes targeting the main branch
+  push:
+    branches: [ develop ]
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v3
+      with:
+        fetch-depth: 0 # otherwise, you will fail to push refs to dest repo
+        ref: develop
+
+    - name: Set up Python 3
+      uses: actions/setup-python@v4
+      with:
+        python-version: 3.9
+
+    - name: Install Python dependencies
+      run: |
+        pip install sphinx
+        pip install sphinx-rtd-theme
+
+    - name: Set up JDK 17
+      uses: actions/setup-java@v3
+      with:
+        java-version: '17'
+        distribution: 'adopt'
+
+    - name: Build LIRICAL
+      run: ./mvnw -Prelease -DskipTests package # We test elsewhere
+
+    - name: Build documentation
+      run: |
+        ## Init the target folder. 
+        # We will put all site documentation there.
+        DOCS_VERSION=latest
+        mkdir -p gh-pages/${DOCS_VERSION}
+        touch gh-pages/.nojekyll
+        
+        ## Copy Javadoc
+        # Copy aggregated Javadoc into `apidocs` folder. 
+        # The aggregated docs are built by Maven in `package` phase.
+        
+        APIDOCS=$(pwd)/gh-pages/${DOCS_VERSION}/apidocs
+        printf "Copying Javadocs from %s to %s\n" $(pwd)/target/site/apidocs ${APIDOCS}
+        cp -r target/site/apidocs ${APIDOCS}
+        
+        ## Build the docs
+        # Generate the HTML pages and move the generated content into the target folder.
+        printf "Building the ${DOCS_VERSION} documentation\n"
+        cd docs/ 
+        make html
+        cd ..
+        mv docs/_build/html/* gh-pages/${DOCS_VERSION}/
+
+
+    - name: Deploy documentation
+      if: ${{ github.event_name == 'push' }}
+      uses: JamesIves/github-pages-deploy-action@v4.4.1
+      with:
+        folder: gh-pages
+        force: false

.github/workflows/pages-stable.yml

@@ -0,0 +1,71 @@
+# Simple workflow for deploying static content to GitHub Pages
+name: Deploy the stable documentation to GitHub pages
+
+on:
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+  # Runs on pushes targeting the main branch
+  push:
+    branches: [ main ]
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v3
+      with:
+        fetch-depth: 0 # otherwise, you will fail to push refs to dest repo
+        ref: master
+
+    - name: Set up Python 3
+      uses: actions/setup-python@v4
+      with:
+        python-version: 3.9
+
+    - name: Install Python dependencies
+      run: |
+        pip install sphinx
+        pip install sphinx-rtd-theme
+
+    - name: Set up JDK 17
+      uses: actions/setup-java@v3
+      with:
+        java-version: '17'
+        distribution: 'adopt'
+
+    - name: Build LIRICAL
+      run: ./mvnw -Prelease -DskipTests package # We test elsewhere
+
+    - name: Build documentation
+      run: |
+        ## Init the target folder. 
+        # We will put all site documentation there.
+        DOCS_VERSION=stable
+        mkdir -p gh-pages/${DOCS_VERSION}
+        touch gh-pages/.nojekyll
+        
+        ## Copy Javadoc
+        # Copy aggregated Javadoc into `apidocs` folder. 
+        # The aggregated docs are built by Maven in `package` phase.
+
+        APIDOCS=$(pwd)/gh-pages/${DOCS_VERSION}/apidocs
+        printf "Copying Javadocs from %s to %s\n" $(pwd)/target/site/apidocs ${APIDOCS} 
+        cp -r target/site/apidocs ${APIDOCS}
+        
+        ## Build the docs
+        # Generate the HTML pages and move the generated content into the target folder.
+        printf "Building the ${DOCS_VERSION} documentation\n"
+        cd docs/ 
+        make html
+        cd ..
+        mv docs/_build/html/* gh-pages/${DOCS_VERSION}/
+
+
+    - name: Deploy documentation
+      if: ${{ github.event_name == 'push' }}
+      uses: JamesIves/github-pages-deploy-action@v4.4.1
+      with:
+        folder: gh-pages
+        force: false

CHANGELOG.rst

@@ -7,9 +7,11 @@ v2.0.0 (TBD)
 -------------------
 - Require Java 17
 - Prune and split codebase into several Maven modules
-- Enhance HTML report
+- Enhance HTML report, add `JSON` output format
 - Add ``prioritize`` command for running LIRICAL entirely from CLI
+- Change the YAML input format
 - Add support for phenopacket schema ``v2``
+- Host documentation and API docs on github.io
 
 -------------------
 v1.3.3 (2021-05-14)

README.md

@@ -1,23 +1,29 @@
-# LIRICAL
-
-[![Documentation Status](https://readthedocs.org/projects/lirical/badge/?version=master)](https://lirical.readthedocs.io/en/latest/?badge=master)
 [![GitHub release](https://img.shields.io/github/release/TheJacksonLaboratory/LIRICAL.svg)](https://github.com/TheJacksonLaboratory/LIRICAL/releases)
 [![Java CI with Maven](https://github.com/TheJacksonLaboratory/LIRICAL/workflows/Java%20CI%20with%20Maven/badge.svg)](https://github.com/TheJacksonLaboratory/LIRICAL/actions/workflows/maven.yml)
 
-
-## LIkelihood Ratio Interpretation of Clinical AbnormaLities
-
-LIRICAL is designed to provide clincially interpretable computational analysis of phenotypic
-abnormalities (encoded using the [Human Phenotype Ontology](http://www.human-phenotyope-ontology.org)),
+# LIRICAL
+LIRICAL (LIkelihood Ratio Interpretation of Clinical AbnormaLities) 
+is designed to provide clinically interpretable computational analysis of phenotypic
+abnormalities (encoded using the [Human Phenotype Ontology](http://www.human-phenotype-ontology.org)),
 optionally combined with an analysis of variants and genotypes if a VCF file is provided with the
 results of diagnostic gene panel, exome, or genome sequencing.
 
 A manuscript describing LIRICAL is available at the 
 [American Journal of Human Genetics](https://pubmed.ncbi.nlm.nih.gov/32755546/).
 
 
-Please consult the Read the docs site for [Detailed documentation](https://lirical.readthedocs.io/en/master/).
-
-Most users should download the latest `LIRICAL.jar` file from 
+## Availability
+Most users should download the latest distribution ZIP file from
 the [Releases page](https://github.com/TheJacksonLaboratory/LIRICAL/releases).
 
+
+## Documentation
+Please consult the documentation for installation instructions and a tutorial:
+- [reference documentation](https://thejacksonlaboratory.github.io/LIRICAL/stable)
+- [edge release documentation](https://thejacksonlaboratory.github.io/LIRICAL/latest)
+
+
+## API docs
+Developers can access Javadoc at:
+- [reference](https://thejacksonlaboratory.github.io/LIRICAL/stable/apidocs)
+- [edge release](https://thejacksonlaboratory.github.io/LIRICAL/latest/apidocs)

docs/conf.py

@@ -46,24 +46,24 @@
 
 # General information about the project.
 project = u'LIRICAL'
-copyright = u'2019'
+copyright = u'2023, Peter Robinson'
 author = u'Peter Robinson'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = u'0.9'
+version = u'2.0'
 # The full version, including alpha/beta/rc tags.
-release = u'0.9'
+release = u'2.0.0-RC2'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.

docs/explanations.rst

@@ -11,7 +11,7 @@ one of the standard methods for diagnostics. Current algorithms such as
 and statistical approaches to prioritize the typically long lists of genes with candidate pathogenic variants, but do not
 provide robust estimates of the strength of the predictions beyond the placement in a ranked list, nor do they provide
 measures of how much any individual phenotypic observation has contributed to the prioritization result.
-LIRICAL exploits the clinical likelihood ratio framework to provide an estimate of the posttest probability of candidate
+LIRICAL exploits the clinical likelihood ratio framework to provide an estimate of the post-test probability of candidate
 diagnoses, the likelihood ratio for each observed HPO phenotype, and the predicted pathogenicity of observed variants.
 
 LIRICAL makes use of the clinical likelihood ratio (LR) framework to perform phenotype-driven genomic diagnostics that addresses

docs/genotype-score.rst

@@ -4,17 +4,52 @@ LIRICAL's Genotype Score
 ========================
 
 We can estimate the pathogenicity of a variant on the basis of a
-computational pathogenicity score that ranges from 0 (predicted benign) to 1 (maximum pathogenicity prediction). LIRICAL
-uses the pathogenicity score prediction of
-`Exomiser <https://www.ncbi.nlm.nih.gov/pubmed/26562621>`_.  Our model depends on the assumed mode of inheritance of the
-disease, and provides an estimate likelihood ratio for the observed genotype. For example, we expect two
-pathogenic alleles in an autosomal recessive disease and one in an autosomal dominant disease. Our model takes
-into account the expected frequency of seeing predicted pathogenic variants in the population. Genes known to carry few
-common functional variants in healthy individuals may be judged more likely to cause certain kinds of disease than genes
-known to carry many such variants (`Petrovski et al., 2013 <https://www.ncbi.nlm.nih.gov/pmc/articles/PMC3749936/>`_).
+computational pathogenicity score that ranges from 0 (predicted benign) to 1 (maximum pathogenicity prediction).
+LIRICAL uses the pathogenicity score prediction of `Exomiser <https://www.ncbi.nlm.nih.gov/pubmed/26562621>`_.
+Our model depends on the assumed mode of inheritance of the disease,
+and provides an estimate likelihood ratio for the observed genotype.
+For example, we expect two pathogenic alleles in an autosomal recessive disease and one in an autosomal dominant disease.
+Our model takes into account the expected frequency of seeing predicted pathogenic variants in the population.
+Genes known to carry few common functional variants in healthy individuals may be judged more likely
+to cause certain kinds of disease than genes known to carry many such variants
+(`Petrovski et al., 2013 <https://www.ncbi.nlm.nih.gov/pmc/articles/PMC3749936/>`_).
 
 LIRICAL's model provides an integrated score for each gene that assesses the observed genotype, comparing its probability
 given that a disease associated with the gene is present in the proband vs. the probability that the genotype is unrelated
 to the clinical manifestations observed in the proband. See the manuscript for algorithmic details.
 
 
+Related analysis options
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following genotype configuration options can be set on top of the phenotype-only analysis.
+
+.. _rsttx-dbs:
+
+Transcript databases
+~~~~~~~~~~~~~~~~~~~~
+
+LIRICAL can use transcript data from UCSC or RefSeq.
+The default is `RefSeq <https://www.ncbi.nlm.nih.gov/refseq/>`_,
+but transcript definitions from `UCSC <http://genome.ucsc.edu/>`_ can also be used.
+
+
+.. _rstbg-var-freqs:
+
+Background variant frequencies
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+LIRICAL uses a background frequency file that records the freqeuncy of predicted pathogenic variants
+in protein-coding genes (as estimated from gnomAD data). By default, LIRICAL will use pre-fabricated
+files for this (that are included in the ``src/main/resources/background`` directory). This is recommended
+for most users. If you create your own background file, then you can use it with the ``-b`` option, that should
+then indicate the path to a non-default background frequency file.
+
+.. _rstglobal-mode:
+
+Global mode
+~~~~~~~~~~~
+
+By default, LIRICAL ranks candidate genes for which at least one pathogenic allele is present in the VCF file.
+However, LIRICAL can also be run in a ``--global`` mode in which diseases are ranked irrespective of
+whether a disease gene is known for a disease or whether the gene is found to have a pathogenic allele or not.

docs/index.rst

@@ -16,11 +16,9 @@ as `Human Phenotype Ontology (HPO) <http://www.human-phenotype-ontology.org>`_ t
    :caption: Contents:
 
    setup
+   tutorial
    running
-   LIRICAL output files <output>
+   output
    explanations
-   options
    advanced
-   tutorial
-
 

docs/lirical-json.rst

@@ -0,0 +1,83 @@
+.. _rstlirical-json:
+
+LIRICAL JSON Output
+===================
+
+Lirical outputs results in a JSON format if ``--output-format json`` option is included in the command-line::
+
+  lirical phenopacket -p LDS2.v2.json \
+    --output-format json
+
+The JSON document contains three sections, the sections are described in the following text along with examples.
+
+Examples of each section are provided below:
+
+Analysis data
+^^^^^^^^^^^^^
+
+``analysisData`` contains the analysis inputs (e.g. sample ID, age, present/excluded phenotypic features):
+
+.. code-block:: json
+
+  "analysisData" : {
+    "sampleId" : "EXAMPLE",
+    "age" : "P1Y2M3D",
+    "sex" : "MALE",
+    "observedPhenotypicFeatures" : [ "HP:0000001", "HP:0000002" ],
+    "excludedPhenotypicFeatures" : [ "HP:0000003" ]
+  }
+
+Analysis metadata
+^^^^^^^^^^^^^^^^^
+
+``analysisMetadata`` includes user-provided options, analysis date, resource versions, etc.
+
+.. code-block:: json
+
+  "analysisMetadata" : {
+    "liricalVersion" : "liricalVersion",
+    "hpoVersion" : "hpoVersion",
+    "transcriptDatabase" : "transcriptDatabase",
+    "analysisDate" : "2022-12-29T14:02:58.653929682",
+    "sampleName" : "sampleId",
+    "isGlobalAnalysisMode" : true
+  }
+
+Analysis results
+^^^^^^^^^^^^^^^^
+
+``analysisResults`` has a list of `TestResult`\ s for each of the tested diseases.
+
+Here we show an example for a made-up disease `OMIM:1234567`.
+
+.. code-block:: json
+
+  "analysisResults" : [ {
+    "diseaseId" : "OMIM:1234567",
+    "pretestProbability" : 1.2,
+    "observedPhenotypicFeatures" : [ {
+      "query" : "HP:0000001",
+      "match" : "HP:0000002",
+      "matchType" : "EXACT_MATCH",
+      "lr" : 1.34,
+      "explanation" : "EXPLANATION"
+    } ],
+    "excludedPhenotypicFeatures" : [ {
+      "query" : "HP:0000001",
+      "match" : "HP:0000003",
+      "matchType" : "EXCLUDED_QUERY_TERM_NOT_PRESENT_IN_DISEASE",
+      "lr" : 1.23,
+      "explanation" : "EXCLUDED_EXPLANATION"
+    } ],
+    "genotypeLR" : {
+      "geneId" : {
+        "id" : "NCBIGene:1234",
+        "symbol" : "GENE_SYMBOL"
+      },
+      "lr" : 1.23,
+      "explanation" : "GENE_EXPLANATION"
+    },
+    "compositeLR" : 2.027286,
+    "posttestProbability" : 1.0895759082370065
+  } ]
+