Merge pull request #60 from monarch-initiative/setup-release-workflow

Setup release workflow

.github/workflows/pages.yml

@@ -1,10 +1,7 @@
-# Simple workflow for deploying static content to GitHub Pages
 name: Deploy 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, develop ]
 
@@ -14,15 +11,14 @@ jobs:
 
     steps:
     - name: Checkout
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
       with:
         fetch-depth: 0 # otherwise, you will fail to push refs to dest repo
-        ref: main
 
-    - name: Set up Python 3
+    - name: Set up Python 3.11
       uses: actions/setup-python@v4
       with:
-        python-version: 3.9
+        python-version: 3.11
 
     - name: Install library with docs dependencies
       run: |
@@ -55,7 +51,6 @@ jobs:
 
           cd docs
           sphinx-apidoc --separate --module-first -d 2 -H "API reference" --follow-links -o apidocs ../src/genophenocorr
-          # TODO - enable doctest when ready
           make html
           
           mv _build/html/* ../gh-pages/${DOCDIR}

.github/workflows/python_ci.yml

@@ -8,25 +8,22 @@ on:
 
 jobs:
     build:
-      runs-on: ${{ matrix.os }}
-
-      strategy:
-        fail-fast: false
-        matrix:
-          os:
-            - ubuntu-latest
-            - windows-latest
-            - macOS-latest
+      runs-on: ubuntu-latest
 
       steps:
-        - uses: actions/checkout@v2
-        - name: Initialize Python ${{ matrix.python }}
+        - uses: actions/checkout@v4
+        - name: Initialize Python 3.11
           uses: actions/[email protected]
           with:
             python-version: "3.11"
         - name: Install package
           run: |
-            python3 -m pip install .[test]
+            python3 -m pip install .[test,docs]
         - name: Run pytest tests
           run: |
             pytest
+        - name: Run documentation tests
+          run: |
+            cd docs
+            sphinx-apidoc --separate --module-first -d 2 -H "API reference" -o apidocs ../src/genophenocorr
+            make doctest

HOW_TO_RELEASE.md

@@ -0,0 +1,71 @@
+# How to release
+
+The document describes how to release `genophenocorr` to *PyPi*.
+
+## Release checklist
+
+- update documentation and notebooks to present the latest features 
+- create and checkout a release branch
+- remove deprecated methods targeted for removal in this version. The `TODO` markers are labeled using 
+  the target version (e.g. `TODO[v0.3.0]`)
+- bump versions to a release:
+  - `src/genophenocorr/__init__.py`
+  - `docs/conf.py`
+- ensure the CI passes
+- deploy to PyPi (described below)
+- merge to `main`
+- create a GitHub release from the latest `main` commit, including a new tag 
+- merge `main` to `develop`
+- bump versions to a `dev` version to begin next development iteration
+
+## Deploy to PyPi
+
+### Virtual environment for deployment
+
+As an optional one-time step, consider creating a dedicated virtual environment with the packages required 
+for testing, building, and deployment:
+
+```shell
+# Create and activate the virtual environment
+python3 -m venv build
+source build/bin/activate
+
+# Install the build packages
+python3 -m pip install build twine
+```
+
+### Setup PyPi credentials
+
+As another one-time action, you must create a profile on PyPi and generate an access token. 
+The token is used to upload the packages.
+
+First, create an account (e.g. associated with your GitHub account), configure 2FA, store recovery codes, etc.
+Then, generate a token to upload the packages. You can generate a token per project or for all projects. 
+Store the token into `$HOME/.pypirc` file with `-rw-------` permissions. The file should look like:
+
+```
+[pypi]
+  username = __token__
+  password = <YOUR-TOKEN-HERE>
+```
+
+Now we're ready to publish packages!
+
+### Deploy
+Run the following to deploy `genophenocorr` to PyPi:  
+
+```bash
+# Ensure you're on the release branch
+cd genophenocorr
+
+# Build the package
+python3 -m build
+
+# Deploy
+python3 -m twine upload dist/*
+
+# Clear the built and deployed files
+rm -rf build dist
+```
+
+The commands will build source distribution and a wheel, and deploy the source distribution and wheel to PyPi.

README.md

@@ -1,57 +1,41 @@
-# Genophenocorr
-# [![CI](https://github.com/monarch-initiative/genophenocorr/workflows/CI/badge.svg)](https://github.com/monarch-initiative/genophenocorr/actions/workflows/python_ci.yml)
+[![Build status](https://github.com/monarch-initiative/genophenocorr/workflows/CI/badge.svg)](https://github.com/monarch-initiative/genophenocorr/actions/workflows/python_ci.yml)
+![PyPi downloads](https://img.shields.io/pypi/dm/genophenocorr.svg?label=Pypi%20downloads)
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/genophenocorr)
 
-A Python library for genotype-phenotype association analysis. 
+Genophenocorr is a Python library for genotype-phenotype association analysis. 
 
+An example of simple genotype-phenotype association analysis
+```python
+# Load HPO
+import hpotk
+hpo = hpotk.load_minimal_ontology('http://purl.obolibrary.org/obo/hp.json')
 
-# Set up
+# Load a cohort of phenopackets 
+from genophenocorr.data import get_toy_cohort
+cohort = get_toy_cohort()
 
-Create a virtual environment. This is an optional step, otherwise the package will be installed into the active 
-Python environment.
+# Analyze genotype-phenotype associations 
+from genophenocorr.analysis import CohortAnalysis
+from genophenocorr.constants import VariantEffect
 
-```shell
-python3 -m venv venv
-source venv/bin/activate
+cohort_analysis = CohortAnalysis(cohort, 'NM_1234.5', hpo)
+frameshift = cohort_analysis.compare_by_variant_type(VariantEffect.FRAMESHIFT_VARIANT)
+print(frameshift)
 ```
 
-Install the package into the environment:
+prints a table with genotype-phenotype correlations:
 
-```shell
-python3 -m pip install genophenocorr
+```text
+                            With frameshift_variant         Without frameshift_variant
+                                              Count Percent                      Count Percent  p-value
+HP:0001166 (Arachnodactyly)                       4  30.77%                         10  76.92%  0.04718
+HP:0001250 (Seizure)                             11  84.62%                          9  69.23%  0.64472
+HP:0001257 (Spasticity)                           8  61.54%                          9  69.23%  1.00000
 ```
 
-# Run tests
+## Documentation
 
-Tests can be run after checking the source code from GitHub and installing the test dependencies:
+Check out the User guide and the API reference for more info:
 
-```shell
-cd genophenocorr
-python3 -m pip install .[test]
-
-pytest
-```
-
-# Build documentation
-
-First, make sure you have the necessary dependencies:
-
-```shell
-cd genophenocorr
-python3 -m pip install .[docs]
-```
-Setting up dependencies is a one-time action for a given Python environment.
-
-Next, we can run the doc tests and build the HTML documentation:
-
-```shell
-cd docs
-
-# Generate the API reference from Python docstrings
-sphinx-apidoc --separate --module-first -d 2 -H "API reference" --follow-links -o apidocs ../src/genophenocorr
-
-# Run the doc tests and build the documentation
-make doctest html
-```
-
-The code above will run the documentation and fail if the docs are out of sync with the code.
-Then, the docs will be built at `docs/build/html`
+- [Stable documentation](https://thejacksonlaboratory.github.io/genophenocorr/stable) (last release on `main` branch)
+- [Latest documentation](https://thejacksonlaboratory.github.io/genophenocorr/latest) (bleeding edge, latest commit on `development` branch)

docs/conf.py

@@ -177,6 +177,9 @@
 
 # Nothing special here
 doctest_global_setup = """
+# For printing data frames "as is".
+import pandas as pd
+pd.set_option('expand_frame_repr', False)
 """
 
 # -- Intersphinx setup --------------------------------------------------------
@@ -192,5 +195,5 @@
 }
 
 # -- Sphinx copybutton setup --------------------------------------------------
-# Exclude `>>>` when copying the cell
-copybutton_exclude = '.linenos, .gp'
+# Exclude `>>>`, the line numbers, and the output when copying the cell.
+copybutton_exclude = '.linenos, .gp, .go'

docs/index.rst

@@ -10,31 +10,26 @@ A key question in biology and human genetics concerns the relationships between
 genetics, the focus is generally placed on the study of whether specific disease-causing alleles are associated with specific phenotypic 
 manifestations of the disease. 
 
-genophenocorr is a Python package designed to support genotype-phenotype correlation analysis. The input to genophenocorr is a collection
-of `Global Alliance for Genomics and Health (GA4GH) Phenopackets <https://pubmed.ncbi.nlm.nih.gov/35705716/>`_. genophenocorr ingests
-data from these phenopackets and performs analysis of the correlation of specific variants, variant types (e.g., missense vs. premature termination codon),
-or variant location in protein motifs or other features. The phenotypic abnormalities are represented by 
-`Human Phenotype Ontology (HPO) <https://hpo.jax.org/app/>`_ terms. Statistical analysis is performed using a 
-`Fisher Exact Test <https://en.wikipedia.org/wiki/Fisher%27s_exact_test>`_, and 
-results are reported for each tested HPO term.
+`genophenocorr` is a Python package designed to support genotype-phenotype correlation analysis.
+The input to `genophenocorr` is a collection of `Global Alliance for Genomics and Health (GA4GH) Phenopackets <https://pubmed.ncbi.nlm.nih.gov/35705716/>`_.
+`genophenocorr` ingests data from these phenopackets and performs analysis of the correlation of specific variants,
+variant types (e.g., missense vs. premature termination codon), or variant location in protein motifs or other features.
+The phenotypic abnormalities are represented by `Human Phenotype Ontology (HPO) <https://hpo.jax.org/app/>`_ terms.
+Statistical analysis is performed using a `Fisher Exact Test <https://en.wikipedia.org/wiki/Fisher%27s_exact_test>`_,
+and results are reported for each tested HPO term.
 
-We recommend that users create a Jupyter notebook for each cohort of patients they would like to test. This documentation provides a detailed tutorial.
-It is also possible to use the Python code as a library (TODO create package in PyPI).
+We recommend that users create a Jupyter notebook for each cohort of patients they would like to test.
+
+This documentation includes installation instructions, a brief tutorial, and a comprehensive user guide.
+The technical information is available in API reference.
 
 
 Literature
 ^^^^^^^^^^
 
 We provide recommended reading for background on the study of genotype-phenotype correlations.
 
-- `Orgogozo V, et al. (2015) <https://pubmed.ncbi.nlm.nih.gov/26042146/>`_ The differential view of genotype-phenotype relationships. 
-
-
-
-Installation
-^^^^^^^^^^^^
-See :ref:`installation` for instructions on how to set up the package. 
-
+- `Orgogozo V, et al. (2015) <https://pubmed.ncbi.nlm.nih.gov/26042146/>`_ The differential view of genotype-phenotype relationships.
 
 --------
 Feedback

docs/installation.rst

@@ -4,9 +4,31 @@
 Installation
 ============
 
-Todo
+The document describes how to install `genophenocorr` into your environment.
 
-Installation of genophenocorr as a Python package
--------------------------------------------------
-	$ pip install genophenocorr
+Stable release
+**************
+
+Installing `genophenocorr` is easy - we publish releases on `Python Package Index (PyPi) <https://pypi.org/project/genophenocorr>`_.
+
+Run the following to install the latest *stable* release::
+
+  python3 -m pip install genophenocorr
+
+
+Latest release
+**************
+
+The *latest* release can be installed by cloning the GitHub repository::
+
+  git clone https://github.com/monarch-initiative/genophenocorr.git
+  cd genophenocorr
+
+  # Switch to `develop` branch to access the latest features
+  git checkout develop
+
+  python3 -m pip install .
+
+The code above will clone the source code from GitHub repository, switch to the `develop` branch with the latest features,
+and install the library into the current Python (virtual) environment.