Merge pull request #28 from anergictcell/feature/non-transitive-genes

Make Gene-HPOTerm associations non-transitive

Author: anergictcell

.github/workflows/test_python_versions.yaml

@@ -10,10 +10,10 @@ on:
 
 jobs:
   test_all_python_versions:
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: [3.7, 3.8, 3.9, "3.10", "3.11", "3.12", "3.13"]
+        python-version: [3.8, 3.9, "3.10", "3.11", "3.12", "3.13"]
     steps:
     - uses: actions/checkout@v2
     - name: Set up Python ${{ matrix.python-version }}

CHANGELOG.rst

@@ -1,11 +1,19 @@
 Changelog
 =========
 
+4.0.0
+-----
+Removed Ontology export to dataframe and pandas dependencies
+Change logic of gene-HPO association parsing to be non-transitive by default
+Add method to convert genes or diseases to HPOSet
+Update documentation
+Update minimum Python requirement to 3.8
+Remove dependencies for backporting logic to Python 3.7
+
 3.3.2
 -----
 Data update to 2025-01-16
 
-
 3.3.1
 -----
 Data update to 2024-04-26

MANIFEST.in

@@ -3,4 +3,4 @@ include CHANGELOG.rst
 include pyhpo/data/phenotype_to_genes.txt
 include pyhpo/data/hp.obo
 include pyhpo/data/phenotype.hpoa
-
+include pyhpo/data/genes_to_phenotype.txt

README.rst

@@ -57,9 +57,7 @@ This will install a base version of **PyHPO** that offers most functionality.
 
 .. note::
 
-    Some features of PyHPO require ``pandas`` and ``scipy``. The standard installation via pip will not include pandas or scipy and PyHPO will work just fine. (You will get a warning on the initial import though).
-
-    Without installing ``pandas``, you won't be able to export the Ontology as a ``Dataframe``, everything else will work fine.
+    Some features of PyHPO require  ``scipy``. The standard installation via pip will not include scipy and PyHPO will work just fine. (You will get a warning on the initial import though).
 
     Without installing ``scipy``, you won't be able to use the ``stats`` module, especially the enrichment calculations.
 
@@ -70,13 +68,7 @@ If you want to do enrichment analysis, you must also install ``scipy``.
 
     pip install 'pyhpo[scipy]'
 
-If you want to work with **PyHPO** using ``pandas`` dataframes, you can install the ``pandas`` dependency
-
-.. code:: bash
-
-    pip install 'pyhpo[pandas]'
-
-Or simply install both together:
+Or simply install all optional dependencies:
 
 .. code:: bash
 

docs/annotations.rst

@@ -1,50 +1,205 @@
 Annotations
 ===========
 
-The ``Annotations`` section contains various metadata annotations for HPO terms.
+The ``Annotations`` module contains the gene and disease associations of HPOTerms.
 
-``GeneSingleton`` class
-***********************
-.. autoclass:: pyhpo.annotations.GeneSingleton
-   :no-private-members:
-   :no-special-members:
+.. code::
 
-toJSON
-------
-.. automethod:: pyhpo.annotations.GeneSingleton.toJSON
+    from pyhpo import Ontology
+    from pyhpo.annotations import Omim, Orpha
 
+    Ontology()
 
-``GeneDict`` class
-******************
-.. autoclass:: pyhpo.annotations.GeneDict
-   :no-private-members:
-   :no-special-members:
+    # All genes and diseases can be accessed through the Ontology
 
+    for gene in Ontology.genes:
+        print(gene.name)
+        # >> "EZH2"
+        # ...
 
-``DiseaseSingleton`` class
-**************************
-.. autoclass:: pyhpo.annotations.DiseaseSingleton
-   :no-private-members:
-   :no-special-members:
+    for orpha in Ontology.orpha_diseases:
+        print(orpha.id)
+        # >> 231401
+        # ...
 
-toJSON
-------
-.. automethod:: pyhpo.annotations.DiseaseSingleton.toJSON
 
-``DiseaseDict`` class
-*********************
-.. autoclass:: pyhpo.annotations.DiseaseDict
-   :no-private-members:
-   :no-special-members:
+    # or accessed directly from the `Orpha`, `Omim`, `Gene` class
 
-Omim
-****
-Instance of :class:`pyhpo.annotations.DiseaseDict` to handle Omim diseases. Ensures that diseases are not duplicated through use of Singletons.
+    orpha_disease = Orpha.get(77260)
+    omim_disease = Omim.get(230900)
 
-Orpha
-*****
-Instance of :class:`pyhpo.annotations.DiseaseDict` to handle Orphanet diseases. Ensures that diseases are not duplicated through use of Singletons.
 
-Decipher
-********
-Instance of :class:`pyhpo.annotations.DiseaseDict` to handle Decipher diseases. Ensures that diseases are not duplicated through use of Singletons.
+    # Annotations can be converted to `HPOSet`
+
+    orpha_set = orpha_disease.hpo_set()
+    omim_set = omim_disease.hpo_set()
+
+    similarity = orpha_set.similarity(omim_set)
+    print(similarity)
+    # >> 0.6620065792484546
+
+
+.. class:: GeneSingleton
+
+    An instance of a gene, associated to several :class:`pyhpo.term.HPOTern`.
+
+    .. note::
+
+        Since version 4.0 genes do not contain references to HPOTerms transitively, i.e. only directly
+        associated HPOTerms are linked to the gene.
+
+    .. attribute:: id
+
+        :Return Type: ``int``
+
+        :Returns: The HGNC ID of the gene
+
+    .. attribute:: name
+
+        :Return Type: ``str``
+
+        :Returns: The HUGO gene synbol of the gene
+
+    .. attribute:: symbol
+
+        :Return Type: ``str``
+
+        :Returns: The HUGO gene synbol of the gene (alias of :attr:`GeneSingleton.name`)
+
+    .. attribute:: hpo
+
+        :Return Type: ``set(int)``
+
+        :Returns: The HPO-IDs of all associated :class:`pyhpo.term.HPOTerm` s
+
+    .. autofunction:: pyhpo.annotations.Annotation.toJSON
+
+    .. autofunction:: pyhpo.annotations.Annotation.hpo_set
+
+
+.. class:: Gene
+
+    ``Gene`` holds all :class:`GeneSingleton` instances and ensures they are not duplicated.
+    It does not need to be instantiated, as it is already created as a singleton during the
+    setup of the Ontology.
+
+    .. autofunction:: pyhpo.annotations.Gene.get
+    .. autofunction:: pyhpo.annotations.Gene.__call__
+
+
+.. class:: OmimDisease
+
+    An instance of an Omim disease, associated to several :class:`pyhpo.term.HPOTerm`.
+
+    .. attribute:: id
+
+        :Return Type: ``int``
+
+        :Returns: The Omim ID
+
+    .. attribute:: name
+
+        :Return Type: ``str``
+
+        :Returns: The Omim disease name
+
+    .. attribute:: hpo
+
+        :Return Type: ``set(int)``
+
+        :Returns: The HPO-ID of all associated :class:`HPOTerm` s
+
+    .. autofunction:: pyhpo.annotations.Annotation.toJSON
+
+    .. autofunction:: pyhpo.annotations.Annotation.hpo_set
+
+
+.. class:: Omim
+
+    ``Omim`` holds all :class:`OmimDisease` instances and ensures they are not duplicated.
+    It does not need to be instantiated, as it is already created as a singleton during the
+    setup of the Ontology.
+
+   .. autofunction:: pyhpo.annotations.DiseaseDict.get
+
+        :Return type: :class:`OmimDisease`
+
+   .. autofunction:: pyhpo.annotations.DiseaseDict.__call__
+
+
+.. class:: OrphaDisease
+
+    An instance of an Orpha disease, associated to several :class:`pyhpo.term.HPOTerm`.
+
+    .. attribute:: id
+
+        :Return Type: ``int``
+
+        :Returns: The Orpha ID
+
+    .. attribute:: name
+
+        :Return Type: ``str``
+
+        :Returns: The Orpha disease name
+
+    .. attribute:: hpo
+
+        :Return Type: ``set(int)``
+
+        :Returns: The HPO-ID of all associated :class:`HPOTerm` s
+
+    .. autofunction:: pyhpo.annotations.Annotation.toJSON
+
+    .. autofunction:: pyhpo.annotations.Annotation.hpo_set
+
+
+.. class:: Orpha
+
+    ``Orpha`` holds all :class:`OrphaDisease` instances and ensures they are not duplicated.
+    It does not need to be instantiated, as it is already created as a singleton during the
+    setup of the Ontology.
+
+    .. autofunction:: pyhpo.annotations.DiseaseDict.get
+
+        :Return type: :class:`OrphaDisease`
+
+   .. autofunction:: pyhpo.annotations.DiseaseDict.__call__
+
+
+.. class:: DecipherDisease
+
+    An instance of an Decipher disease, associated to several :class:`pyhpo.term.HPOTerm`.
+
+   .. attribute:: id
+
+        :Return Type: ``int``
+
+      :Returns: The Decipher ID
+
+    .. attribute:: name
+
+        :Return Type: ``str``
+
+        :Returns: The Decipher disease name
+
+    .. attribute:: hpo
+
+        :Return Type: ``set(int)``
+
+        :Returns: The HPO-ID of all associated :class:`HPOTerm` s
+
+    .. autofunction:: pyhpo.annotations.Annotation.toJSON
+
+    .. autofunction:: pyhpo.annotations.Annotation.hpo_set
+
+
+.. class:: Decipher
+
+    ``Decipher`` holds all :class:`DecipherDisease` instances and ensures they are not duplicated.
+
+    .. autofunction:: pyhpo.annotations.DiseaseDict.get
+
+        :Return type: :class:`DecipherDisease`
+
+   .. autofunction:: pyhpo.annotations.DiseaseDict.__call__

docs/conf.py

@@ -39,6 +39,7 @@
     "sphinx.ext.viewcode",
     "sphinx.ext.napoleon",
     "sphinx_autodoc_typehints",
+    "sphinx_rtd_theme",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -57,7 +58,7 @@
 
 # General information about the project.
 project = "PyHPO"
-copyright = "2023, Jonas Marcello"
+copyright = "2025, Jonas Marcello"
 author = pyhpo.__author__
 
 # The version info for the project you're documenting, acts as replacement for

docs/ontology.rst

@@ -3,6 +3,14 @@ Ontology
 
 The ``Ontology`` contains all ``HPOTerm`` s and thus reflects the full ontology including links and information about inheritance
 
+    .. note::
+
+        Starting with `pyhpo 4.0`, the Ontology will link genes non-transitive to HPO terms.
+        This means it will be the same behavior as the `hpo3` library.
+        See https://github.com/anergictcell/hpo/issues/44 and
+        https://github.com/anergictcell/pyhpo/issues/26 for details about this.
+
+
 ``Ontology`` class
 ********************
 .. autoclass:: pyhpo.ontology.OntologyClass

docs/tutorial/basics.rst

@@ -43,6 +43,7 @@ It can now be used across all modules. Imagine the following source code:
     def get_term_name(term_id: int) -> str:
         try:
             term = Ontology[term_id]
+            return term.name
         except KeyError:
             print("Term not present in Ontology")
             return ""

docs/tutorial/data.rst

@@ -3,11 +3,12 @@ Masterdata
 
 **PyHPO** ships with a full version of the HP ontology, including gene and disease associations. I try to keep this data up to date, but will frequently fall behind on the release schedule.
 
-To build the ontology, the following 3 files are needed from the HPO masterdata:
+To build the ontology, the following 4 files are needed from the HPO masterdata:
 
 * ``http://purl.obolibrary.org/obo/hp.obo``
-* ``http://purl.obolibrary.org/obo/hp/hpoa/phenotype_to_genes.txt``
+* ``http://purl.obolibrary.org/obo/hp/hpoa/genes_to_phenotype.txt``
 * ``http://purl.obolibrary.org/obo/hp/hpoa/phenotype.hpoa``
+* ``http://purl.obolibrary.org/obo/hp/hpoa/phenotype_to_genes.txt`` (optional)
 
 
 Updating to the most recent version

pyhpo/__init__.py

@@ -11,7 +11,7 @@
 
 # The following info will be used by setup.py and sphinx documentation
 __author__ = "Jonas Marcello"
-__version__ = "3.3.2"
+__version__ = "4.0.0"
 
 __all__ = (
     "Annotation",