Merge pull request #27 from sbslee/0.6.0-dev

0.6.0 dev

Author: sbslee

CHANGELOG.rst

@@ -1,6 +1,28 @@
 Changelog
 *********
 
+0.6.0 (2021-10-09)
+------------------
+
+* :issue:`25`: Add new extension ``sphinx-issues`` to Read the Docs.
+* :issue:`26`: Add new extension ``sphinx.ext.linkcode`` to Read the Docs.
+* Add ``by`` argument to :meth:`api.utils.sort_alleles` method. When ``by='name'`` it will sort star alleles by allele number.
+* Update :command:`call-genotypes` command to output genotypes with number-sorted alleles (e.g. '\*4/\*10' instead of '\*10/\*4').
+* Add new semantic type ``SampleTable[Phenotypes]``.
+* Add new method :meth:`api.utils.call_phenotypes`.
+* Add new command :command:`call-phenotypes`.
+* Add ``--phenotypes`` argument  to :command:`combine-results` command.
+* Deprecate :meth:`api.utils.load_control_table` method.
+* Split ``api.utils`` submodule into two submodules ``api.utils`` and ``api.core``.
+* Update :command:`run-ngs-pipeline` command to include phenotype calling step.
+* Update :command:`plot-bam-copy-number` command to run faster when ``--samples`` argument is used.
+* Change 'Unassigned' genotype to 'Indeterminate' genotype.
+* Add new method :meth:`api.core.get_variant_synonyms`.
+* Update :meth:`api.core.list_variants` method to accept multiple star alleles.
+* Update :command:`predict-alleles` command to support multiallelic variants.
+* Update :meth:`api.utils.sort_alleles` method to give priority to non-reference or non-default alleles when breaking ties (i.e. alleles have the same functional status and same number of variants).
+* Update variant information for following alleles: CYP2D6\*122, CYP2D6\*127, CYP2D6\*139.
+
 0.5.0 (2021-10-02)
 ------------------
 
@@ -23,7 +45,7 @@ Changelog
 * Update :command:`create-consolidated-vcf` command to implement phase-extension algorithm.
 * Remove ``SO`` and ``Type`` columns from the variant table.
 * Update :class:`api.genotype.GSTM1Genotyper` class.
-* Update variant information for following alleles: CYP1A2*1C, CYP1A2*1F, CYP1A2*1K, CYP1A2*1L, CYP2B6*17, CYP2D6*15, CYP2D6*21, SLCO1B1*S1, SLCO1B1*S2.
+* Update variant information for following alleles: CYP1A2\*1C, CYP1A2\*1F, CYP1A2\*1K, CYP1A2\*1L, CYP2B6\*17, CYP2D6\*15, CYP2D6\*21, SLCO1B1\*S1, SLCO1B1\*S2.
 * Add ``NotTargetGeneError`` error.
 * Add new method ``api.utils.is_target_gene``.
 * Update :command:`run-ngs-pipeline` command to check whether input gene is one of the target genes before attempting to run the pipeline.

README.rst

@@ -136,6 +136,9 @@ Notably, all archive files have defined semantic types, which allows us to ensur
 - ``SampleTable[Genotypes]``
     * TSV file for storing target gene's genotype call for each sample.
     * Requires following metadata: ``Gene``, ``Assembly``, ``SemanticType``.
+- ``SampleTable[Phenotypes]``
+    * TSV file for storing target gene's phenotype call for each sample.
+    * Requires following metadata: ``Gene``, ``SemanticType``.
 - ``SampleTable[Results]``
     * TSV file for storing various results for each sample.
     * Requires following metadata: ``Gene``, ``Assembly``, ``SemanticType``.
@@ -167,6 +170,7 @@ For getting help on the CLI:
    positional arguments:
      COMMAND
        call-genotypes      Call genotypes for target gene.
+       call-phenotypes     Call phenotypes for the target gene.
        combine-results     Combine various results for the target gene.
        compute-control-statistics
                            Compute various statistics for control gene with BAM data.
@@ -211,10 +215,11 @@ For getting help on a specific command (e.g. call-genotypes):
 
 Below is the list of submodules available in the API:
 
+- **core** : The core submodule is the main suite of tools for PGx research.
 - **genotype** : The genotype submodule is a suite of tools for accurately predicting genotype calls.
 - **pipeline** : The pipeline submodule is used to provide convenient methods that combine multiple PyPGx actions and automatically handle semantic types.
 - **plot** : The plot submodule is used to plot various kinds of profiles such as read depth, copy number, and allele fraction.
-- **utils** : The utils submodule is the main suite of tools for PGx research.
+- **utils** : The utils submodule contains main actions of PyPGx.
 
 
 For getting help on a specific submodule (e.g. utils):

docs/api.rst

@@ -11,10 +11,11 @@ This section describes the application programming interface (API) for PyPGx.
 
 Below is the list of submodules available in the API:
 
+- **core** : The core submodule is the main suite of tools for PGx research.
 - **genotype** : The genotype submodule is a suite of tools for accurately predicting genotype calls.
 - **pipeline** : The pipeline submodule is used to provide convenient methods that combine multiple PyPGx actions and automatically handle semantic types.
 - **plot** : The plot submodule is used to plot various kinds of profiles such as read depth, copy number, and allele fraction.
-- **utils** : The utils submodule is the main suite of tools for PGx research.
+- **utils** : The utils submodule contains main actions of PyPGx.
 
 
 For getting help on a specific submodule (e.g. utils):
@@ -24,6 +25,12 @@ For getting help on a specific submodule (e.g. utils):
    from pypgx.api import utils
    help(utils)
 
+core
+====
+
+.. automodule:: pypgx.api.core
+   :members:
+
 genotype
 ========
 

docs/cli.rst

@@ -21,6 +21,7 @@ For getting help on the CLI:
    positional arguments:
      COMMAND
        call-genotypes      Call genotypes for target gene.
+       call-phenotypes     Call phenotypes for the target gene.
        combine-results     Combine various results for the target gene.
        compute-control-statistics
                            Compute various statistics for control gene with BAM data.
@@ -86,31 +87,54 @@ call-genotypes
      --alleles PATH    Archive file with the semantic type SampleTable[Alleles].
      --cnv-calls PATH  Archive file with the semantic type SampleTable[CNVCalls].
 
+call-phenotypes
+===============
+
+.. code-block:: text
+
+   $ pypgx call-phenotypes -h
+   usage: pypgx call-phenotypes [-h] genotypes phenotypes
+   
+   ########################################
+   # Call phenotypes for the target gene. #
+   ########################################
+   
+   Usage examples:
+     $ pypgx call-phenotypes CYP2D6-genotypes.zip CYP2D6-phenotypes.zip
+   
+   Positional arguments:
+     genotypes   Archive file with the semantic type SampleTable[Genotypes].
+     phenotypes  Archive file with the semantic type SampleTable[Phenotypes].
+   
+   Optional arguments:
+     -h, --help  Show this help message and exit.
+
 combine-results
 ===============
 
 .. code-block:: text
 
    $ pypgx combine-results -h
-   usage: pypgx combine-results [-h] [--genotypes PATH] [--alleles PATH]
-                                [--cnv-calls PATH]
+   usage: pypgx combine-results [-h] [--genotypes PATH] [--phenotypes PATH]
+                                [--alleles PATH] [--cnv-calls PATH]
                                 results
    
    ################################################
    # Combine various results for the target gene. #
    ################################################
    
    Usage examples:
-     $ pypgx combine-results CYP2D6-results.zip --genotypes CYP2D6-genotypes.zip --alleles CYP2D6-alleles.zip --cnv-calls CYP2D6-cnv-calls.zip
+     $ pypgx combine-results CYP2D6-results.zip --genotypes CYP2D6-genotypes.zip --phenotypes CYP2D6-phenotypes.zip --alleles CYP2D6-alleles.zip --cnv-calls CYP2D6-cnv-calls.zip
    
    Positional arguments:
-     results           Archive file with the semantic type SampleTable[Results].
+     results            Archive file with the semantic type SampleTable[Results].
    
    Optional arguments:
-     -h, --help        Show this help message and exit.
-     --genotypes PATH  Archive file with the semantic type SampleTable[Genotypes].
-     --alleles PATH    Archive file with the semantic type SampleTable[Alleles].
-     --cnv-calls PATH  Archive file with the semantic type SampleTable[CNVCalls].
+     -h, --help         Show this help message and exit.
+     --genotypes PATH   Archive file with the semantic type SampleTable[Genotypes].
+     --phenotypes PATH  Archive file with the semantic type SampleTable[Phenotypes].
+     --alleles PATH     Archive file with the semantic type SampleTable[Alleles].
+     --cnv-calls PATH   Archive file with the semantic type SampleTable[CNVCalls].
 
 compute-control-statistics
 ==========================

docs/conf.py

@@ -31,13 +31,17 @@
     'sphinx.ext.autodoc',
     'sphinx.ext.napoleon',
     'sphinx_rtd_theme',
+    'sphinx.ext.linkcode',
     'autodocsumm',
+    'sphinx_issues',
 ]
 
 autodoc_default_options = {
     'autosummary': True,
 }
 
+issues_github_path = 'sbslee/pypgx'
+
 napoleon_use_param = False
 
 # Add any paths that contain templates here, relative to this directory.
@@ -60,3 +64,52 @@
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = []
+
+# -- Add external links to source code with sphinx.ext.linkcode --------------
+
+import inspect
+import pypgx
+
+def linkcode_resolve(domain, info):
+    if domain != 'py':
+        return None
+
+    modname = info['module']
+
+    if not modname:
+        return None
+
+    submod = sys.modules.get(modname)
+
+    if submod is None:
+        return None
+
+    fullname = info['fullname']
+    obj = submod
+
+    for part in fullname.split('.'):
+        try:
+            obj = getattr(obj, part)
+        except AttributeError:
+            return None
+
+    try:
+        fn = inspect.getsourcefile(inspect.unwrap(obj))
+    except TypeError:
+        fn = None
+    if not fn:
+        return None
+
+    try:
+        source, lineno = inspect.getsourcelines(obj)
+    except OSError:
+        lineno = None
+
+    if lineno:
+        linespec = f'#L{lineno}-L{lineno + len(source) - 1}'
+    else:
+        linespec = ''
+
+    fn = os.path.relpath(fn, start=os.path.dirname(pypgx.__file__))
+
+    return f'https://github.com/sbslee/pypgx/tree/master/pypgx/{fn}/{linespec}'

docs/create.py

@@ -3,10 +3,10 @@
 
 import pypgx
 import pypgx.api
-from pypgx.api import utils
+from pypgx.api import core
 from pypgx.cli import commands
 
-submodules = ['genotype', 'pipeline', 'plot', 'utils']
+submodules = ['core', 'genotype', 'pipeline', 'plot', 'utils']
 
 credit = """
 ..
@@ -163,6 +163,9 @@
 - ``SampleTable[Genotypes]``
     * TSV file for storing target gene's genotype call for each sample.
     * Requires following metadata: ``Gene``, ``Assembly``, ``SemanticType``.
+- ``SampleTable[Phenotypes]``
+    * TSV file for storing target gene's phenotype call for each sample.
+    * Requires following metadata: ``Gene``, ``SemanticType``.
 - ``SampleTable[Results]``
     * TSV file for storing various results for each sample.
     * Requires following metadata: ``Gene``, ``Assembly``, ``SemanticType``.
@@ -285,7 +288,7 @@
     'Ultrarapid Metabolizer'
 """.format(**d)
 
-readme_file = f'{utils.PROGRAM_PATH}/README.rst'
+readme_file = f'{core.PROGRAM_PATH}/README.rst'
 
 with open(readme_file, 'w') as f:
     f.write(readme.lstrip())
@@ -332,7 +335,7 @@
     s += '\n'
     cli += s
 
-cli_file = f'{utils.PROGRAM_PATH}/docs/cli.rst'
+cli_file = f'{core.PROGRAM_PATH}/docs/cli.rst'
 
 with open(cli_file, 'w') as f:
     f.write(cli.lstrip())
@@ -371,7 +374,7 @@
     s += '\n'
     api += s
 
-with open(f'{utils.PROGRAM_PATH}/docs/api.rst', 'w') as f:
+with open(f'{core.PROGRAM_PATH}/docs/api.rst', 'w') as f:
     f.write(api.lstrip())
 
 # -- sdk.rst -----------------------------------------------------------------
@@ -394,5 +397,5 @@
 
 """.format(**d)
 
-with open(f'{utils.PROGRAM_PATH}/docs/sdk.rst', 'w') as f:
+with open(f'{core.PROGRAM_PATH}/docs/sdk.rst', 'w') as f:
     f.write(sdk.lstrip())

docs/genes.rst

@@ -0,0 +1,28 @@
+Genes
+*****
+
+CYP2D6
+======
+
+Some alleles in PharmVar will not be called by PyPGx because one or more of their variants have a high false positive rate, likely due to read misalignment to the *CYP2D7* pseudogene. Those alleles are listed in below table. If problematic variants are present in gnomAD, their links are provided so that you can look at filtering status, allele imbalance for heterozygotes, etc.
+
+.. list-table::
+   :widths: 25 25 25 25
+   :header-rows: 1
+
+   * - Problematic Variant
+     - Star Alleles
+     - GRCh37
+     - GRCh38
+   * - rs61745683 (V370I)
+     - \*122
+     - `22-42523514-C-T <https://gnomad.broadinstitute.org/variant/22-42523514-C-T?dataset=gnomad_r2_1>`__
+     - `22-42127512-C-T <https://gnomad.broadinstitute.org/variant/22-42127512-C-T?dataset=gnomad_r3>`__
+   * - rs1058172 (R365H)
+     - \*139
+     - `22-42523528-C-T <https://gnomad.broadinstitute.org/variant/22-42523528-C-T?dataset=gnomad_r2_1>`__
+     - `22-42127526-C-T <https://gnomad.broadinstitute.org/variant/22-42127526-C-T?dataset=gnomad_r3>`__
+   * - rs202102799 (Y355C)
+     - \*127
+     - `22-42523558-T-C <https://gnomad.broadinstitute.org/variant/22-42523558-T-C?dataset=gnomad_r2_1>`__
+     - `22-42127556-T-C <https://gnomad.broadinstitute.org/variant/22-42127556-T-C?dataset=gnomad_r3>`__

docs/index.rst

@@ -6,6 +6,7 @@ Welcome to PyPGx's documentation!
    :caption: Contents:
 
    readme
+   genes
    tutorials
    dpsv
    cli