napistu 0.2.5.dev7__py3-none-any.whl → 0.3.1.dev1__py3-none-any.whl

napistu/rpy2/__init__.py

@@ -1,127 +1,270 @@
+"""
+napistu.rpy2
+============
+
+This subpackage provides utilities for interacting with R and the rpy2 bridge, including:
+- Checking rpy2 availability
+- Importing and caching core and extended rpy2 modules
+- Handling R session information and error reporting
+- Decorators for requiring rpy2 and reporting R-related exceptions
+
+All rpy2-related imports are performed lazily and cached, so that the package can be imported even if rpy2 is not installed.
+"""
+
 from __future__ import annotations
 
 import functools
 import logging
 import os
 import sys
+from functools import lru_cache
+from typing import Any, Callable, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import rpy2.robjects.conversion
+    import rpy2.robjects
+    import rpy2.robjects.packages
+    import rpy2.robjects.pandas2ri
+    import rpy2.robjects.ListVector
+    import pyarrow
+    import rpy2_arrow.arrow
 
 logger = logging.getLogger(__name__)
 
-try:
-    import rpy2  # noqa
 
-    has_rpy2 = True
+@lru_cache(maxsize=1)
+def get_rpy2_availability() -> bool:
+    """
+    Check if rpy2 is available in the current environment.
+
+    Returns
+    -------
+    bool
+        True if rpy2 is importable, False otherwise.
+    """
+    try:
+        import rpy2  # noqa: F401 - needed for rpy2 availability check
+
+        return True
+    except ImportError:
+        return False
+    except Exception as e:
+        logger.debug(f"rpy2 initialization failed: {e}")
+        return False
+
+
+@lru_cache(maxsize=1)
+def get_rpy2_core_modules() -> tuple[
+    "rpy2.robjects.conversion.Converter",
+    "rpy2.robjects.conversion.Converter",
+    "rpy2.robjects.packages.importr",
+]:
+    """
+    Import and cache core rpy2 modules (conversion, default_converter, importr).
+
+    Returns
+    -------
+    tuple
+        (conversion, default_converter, importr) from rpy2.robjects
+
+    Raises
+    ------
+    ImportError
+        If rpy2 is not available or import fails.
+    """
+    if not get_rpy2_availability():
+        raise ImportError(
+            "This function requires `rpy2`. "
+            "Please install `napistu` with the `rpy2` extra dependencies. "
+            "For example: `pip install napistu[rpy2]`"
+        )
+    try:
+        from rpy2.robjects import conversion, default_converter
+        from rpy2.robjects.packages import importr
+
+        return conversion, default_converter, importr
+    except Exception as e:
+        logger.error(f"Failed to import core rpy2 modules: {e}")
+        raise
+
+
+@lru_cache(maxsize=1)
+def get_rpy2_extended_modules() -> tuple[
+    "rpy2.robjects.pandas2ri",
+    "pyarrow",
+    "rpy2_arrow.arrow",
+    "rpy2.robjects",
+    "rpy2.robjects.ListVector",
+]:
+    """
+    Import and cache extended rpy2 modules (pandas2ri, pyarrow, rpy2_arrow, etc.).
+
+    Returns
+    -------
+    tuple
+        (pandas2ri, pyarrow, rpy2_arrow.arrow, ro, ListVector)
+
+    Raises
+    ------
+    ImportError
+        If rpy2 or dependencies are not available or import fails.
+    """
+    if not get_rpy2_availability():
+        raise ImportError(
+            "This function requires `rpy2`. "
+            "Please install `napistu` with the `rpy2` extra dependencies. "
+            "For example: `pip install napistu[rpy2]`"
+        )
+    try:
+        from rpy2.robjects import pandas2ri
+        import pyarrow
+
+        # loading rpy2_arrow checks whether the R arrow package is found
+        # this is the first time when a non-standard R package is loaded
+        # so a bad R setup can cause issues at this stage
+        try:
+            import rpy2_arrow.arrow as pyra
+        except Exception as e:
+            rsession_info()
+            raise e
+        import rpy2.robjects.conversion  # noqa: F401 - needed for R conversion setup
+        import rpy2.rinterface  # noqa: F401 - needed for R interface initialization
+        import rpy2.robjects as ro
+        from rpy2.robjects import ListVector
+
+        return pandas2ri, pyarrow, pyra, ro, ListVector
+    except Exception as e:
+        logger.error(f"Failed to import extended rpy2 modules: {e}")
+        raise
+
+
+@lru_cache(maxsize=1)
+def get_napistu_r_package() -> Any:
+    """
+    Import and cache the napistu R package using rpy2.
+
+    Returns
+    -------
+    Any
+        The imported napistu.r R package object.
+
+    Raises
+    ------
+    ImportError
+        If rpy2 or the napistu R package is not available.
+    """
+    conversion, default_converter, importr = get_rpy2_core_modules()
+    try:
+        napistu_r = importr("napistu.r")
+        return napistu_r
+    except Exception as e:
+        logger.error(f"Failed to import napistu.r R package: {e}")
+        raise
 
-    from rpy2.robjects import conversion, default_converter  # noqa
-    from rpy2.robjects.packages import importr  # noqa
 
-except ImportError:
-    has_rpy2 = False
-    logger.warning(
-        "rpy2 is not installed. "
-        "Some functions will not work. "
-        "Consider installing `cpr[rpy2]`."
-    )
-except Exception as e:
-    has_rpy2 = False
-    print(e)
-    logger.warning("rpy2 initialization failed with an unrecognized exception.")
+def require_rpy2(func: Callable) -> Callable:
+    """
+    Decorator to ensure rpy2 is available before calling the decorated function.
 
+    Raises
+    ------
+    ImportError
+        If rpy2 is not available.
+    """
 
-def warn_if_no_rpy2(func):
     @functools.wraps(func)
-    def warn_if_no_rpy2_wrapper(*args, **kwargs):
-        if not has_rpy2:
+    def wrapper(*args, **kwargs):
+        if not get_rpy2_availability():
             raise ImportError(
-                "This function requires `rpy2`. \n"
-                "Please install `cpr` with the `rpy2` extra dependencies. \n"
-                "For example: `pip install cpr[rpy2]`\n"
+                f"Function '{func.__name__}' requires `rpy2`. "
+                "Please install `napistu` with the `rpy2` extra dependencies. "
+                "For example: `pip install napistu[rpy2]`"
             )
         return func(*args, **kwargs)
 
-    return warn_if_no_rpy2_wrapper
+    return wrapper
+
+
+def report_r_exceptions(func: Callable) -> Callable:
+    """
+    Decorator to provide helpful error reporting for R-related exceptions.
+
+    If an exception occurs, logs the error and prints R session info.
+    """
+
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        if not get_rpy2_availability():
+            raise ImportError(
+                f"Function '{func.__name__}' requires `rpy2`. "
+                "Please install `napistu` with the `rpy2` extra dependencies. "
+                "For example: `pip install napistu[rpy2]`"
+            )
+        try:
+            return func(*args, **kwargs)
+        except Exception as e:
+            logger.error(f"Exception in {func.__name__}: {e}")
+            rsession_info()
+            raise e
+
+    return wrapper
 
 
 def rsession_info() -> None:
-    # report summaries of the R installation found by rpy2
-    # default converters bundled with rpy2 are used
-    # for this step rather than those bundled with rpy2_arrow
-    # because rpy2_arrow requires the arrow R package so
-    # it can be difficult to import this package without
-    # a valid R setup.
-
-    with conversion.localconverter(default_converter):
-        base = importr("base")
-        utils = importr("utils")
-
-        lib_paths = base._libPaths()
-        session_info = utils.sessionInfo()
-
-        logger.warning(
-            "An exception occurred when running some rpy2-related functionality\n"
-            "Here is a summary of your R session\n"
-            f"Using R version in {base.R_home()[0]}\n"
-            ".libPaths ="
-        )
-        logger.warning("\n".join(lib_paths))
-        logger.warning(f"sessionInfo = {session_info}")
-        # suggest a fix
-        logger.warning(_r_homer_warning())
+    """
+    Report summaries of the R installation found by rpy2.
 
-    return None
+    This function logs the R version, library paths, and session info using rpy2.
+    If R is not available or an error occurs, logs a warning.
+    """
+    try:
+        conversion, default_converter, importr = get_rpy2_core_modules()
+        with conversion.localconverter(default_converter):
+            base = importr("base")
+            utils = importr("utils")
+            lib_paths = base._libPaths()
+            session_info = utils.sessionInfo()
+            logger.warning(
+                "An exception occurred when running some rpy2-related functionality\n"
+                "Here is a summary of your R session\n"
+                f"Using R version in {base.R_home()[0]}\n"
+                ".libPaths ="
+            )
+            logger.warning("\n".join(lib_paths))
+            logger.warning(f"sessionInfo = {session_info}")
+            logger.warning(_r_homer_warning())
+    except Exception as e:
+        logger.warning(f"Could not generate R session info: {e}")
 
 
-def _r_homer_warning() -> None:
-    # utility function to suggest installation directions for R
-    # as part of rsession
+def _r_homer_warning() -> str:
+    """
+    Utility function to suggest installation directions for R based on environment.
 
+    Returns
+    -------
+    str
+        Installation instructions for R in the current environment.
+    """
     is_conda = os.path.exists(os.path.join(sys.prefix, "conda-meta"))
     if is_conda:
         r_lib_path = os.path.join(sys.prefix, "lib", "R")
         if os.path.isdir(r_lib_path):
-            logging.warning(
+            return (
                 "You seem to be working in a conda environment with R installed.\n"
-                "If this version was not located by rpy2 then then try to set R_HOME using:\n"
-                f"os.environ['R_HOME'] = {r_lib_path}"
+                "If this version was not located by rpy2 then try to set R_HOME using:\n"
+                f"os.environ['R_HOME'] = '{r_lib_path}'"
             )
         else:
-            logging.warning(
+            return (
                 "You seem to be working in a conda environment but R is NOT installed.\n"
                 "If this is the case then install R, the CPR R package and the R arrow package into your\n"
                 "conda environment and then set the R_HOME environmental variable using:\n"
-                "os.environ['R_HOME'] = <<PATH_TO_R_lib/R>>"
+                "os.environ['R_HOME'] = '<<PATH_TO_R_lib/R>>'"
             )
     else:
-        logging.warning(
+        return (
             "If you don't have R installed or if your desired R library does not match the\n"
             "one above, then set your R_HOME environmental variable using:\n"
-            "os.environ['R_HOME'] = <<PATH_TO_lib/R>>"
+            "os.environ['R_HOME'] = '<<PATH_TO_lib/R>>'"
         )
-
-    return None
-
-
-def report_r_exceptions(function):
-    @functools.wraps(function)
-    def report_r_exceptions_wrapper(*args, **kwargs):
-        if not has_rpy2:
-            raise ImportError(
-                "This function requires `rpy2`. \n"
-                "Please install `cpr` with the `rpy2` extra dependencies. \n"
-                "For example: `pip install cpr[rpy2]`\n"
-            )
-        try:
-            return function(*args, **kwargs)
-        except Exception as e:
-            # log the exception
-            err = "There was an exception in  "
-            err += function.__name__
-
-            logger.warning(err)
-            # report session info
-            rsession_info()
-
-            # re-raise the exception
-            raise e
-
-    return report_r_exceptions_wrapper

napistu/rpy2/callr.py

@@ -1,115 +1,82 @@
 from __future__ import annotations
 
 import pandas as pd
-from napistu.rpy2 import has_rpy2
-from napistu.rpy2 import report_r_exceptions
-from napistu.rpy2 import rsession_info
-from napistu.rpy2 import warn_if_no_rpy2
-
-if has_rpy2:
-    from rpy2.robjects import pandas2ri
-    from rpy2.robjects.packages import importr
-    from rpy2.robjects.packages import InstalledSTPackage, InstalledPackage
-    import pyarrow
-
-    # loading rpy2_arrow checks whether the R arrow package is found
-    # this is the first time when a non-standard R package is loaded
-    # so a bad R setup can cause issues at this stage
-    # rsession_info() adds some helpful debugging information
-    try:
-        import rpy2_arrow.arrow as pyra
-    except Exception as e:
-        rsession_info()
-        raise e
-    import rpy2.robjects.conversion
-    import rpy2.rinterface
-    import rpy2.robjects as ro
-
-
-@warn_if_no_rpy2
+from napistu.rpy2 import (
+    get_rpy2_core_modules,
+    get_rpy2_extended_modules,
+    get_napistu_r_package,
+    require_rpy2,
+    report_r_exceptions,
+)
+
+
+@require_rpy2
 @report_r_exceptions
-def get_rcpr(
-    r_paths: list[str] | None = None,
-):
+def get_napistu_r(r_paths: list[str] | None = None):
     """
-    Get rcpr
-
-    Gets the rcpr R package
+    Get Napistu R package.
 
     Args:
-        r_paths (list[str]):
-            Paths to add to .libPaths() in R
+        r_paths (list[str], optional): Paths to add to .libPaths() in R
 
     Returns:
-        rcpr R package
+        napistu.r R package
     """
-
     _ = get_rbase(r_paths)
-
-    # connect the cpr R package
-    rcpr = importr("rcpr")
-    return rcpr
+    return get_napistu_r_package()
 
 
-@warn_if_no_rpy2
+@require_rpy2
 @report_r_exceptions
 def bioconductor_org_r_function(
     object_type: str, species: str, r_paths: list[str] | None = None
 ):
     """
-    Bioconuctor Organism R Function
+    Bioconductor Organism R Function
 
     Calls "bioconductor_org_function" from the R cpr package to pull a mapping object
     out of a species specific library.
 
     Parameters:
-    object_type (str):
-        Type of function to call
-    species (str):
-        Species name
-    r_paths: list(str):
-        Paths to add to .libPaths() in R. Alternatively consider setting the R_HOME env variable.
+    object_type (str): Type of function to call
+    species (str): Species name
+    r_paths (list[str], optional): Paths to add to .libPaths() in R.
+        Alternatively consider setting the R_HOME env variable.
 
     Returns:
     pd.DataFrame or a function for non-tabular results
     """
-
     _ = get_rbase(r_paths)
-
-    # connect the cpr R package
-    cpr = importr("rcpr")
-
-    results = cpr.bioconductor_org_function(object_type, species)
-
+    napistu_r = get_napistu_r_package()
+    results = napistu_r.bioconductor_org_function(object_type, species)
     return results
 
 
+@require_rpy2
 @report_r_exceptions
-def get_rbase(
-    r_paths: list[str] | None = None,
-) -> InstalledSTPackage | InstalledPackage:
-    """Get the base R package
+def get_rbase(r_paths: list[str] | None = None):
+    """Get the base R package.
 
     Args:
-        r_paths (list[str], optional): Optional additional
-            r_paths. Defaults to None.
+        r_paths (list[str], optional): Optional additional r_paths. Defaults to None.
 
     Returns:
-        _type_: _description_
+        Base R package
     """
+    conversion, default_converter, importr = get_rpy2_core_modules()
     base = importr("base")
     if r_paths is not None:
         base._libPaths(r_paths)
     return base
 
 
-@warn_if_no_rpy2
+@require_rpy2
 @report_r_exceptions
-def pandas_to_r_dataframe(df: pd.DataFrame) -> rpy2.robjects.DataFrame:
-    """Convert a pandas dataframe to an R dataframe
+def pandas_to_r_dataframe(df: pd.DataFrame):
+    """Convert a pandas dataframe to an R dataframe.
 
-    This uses the rpy2-arrow functionality
-    to increase the performance of conversion orders of magnitude.
+    This uses the rpy2-arrow functionality to increase the performance
+    of conversion by orders of magnitude.
 
     Args:
         df (pd.DataFrame): Pandas dataframe
@@ -117,16 +84,18 @@ def pandas_to_r_dataframe(df: pd.DataFrame) -> rpy2.robjects.DataFrame:
     Returns:
         rpy2.robjects.DataFrame: R dataframe
     """
+    pandas2ri, pyarrow, pyra, ro, ListVector = get_rpy2_extended_modules()
+
     conv = _get_py2rpy_pandas_conv()
     with (ro.default_converter + conv).context():
         r_df = ro.conversion.get_conversion().py2rpy(df)
     return r_df
 
 
-@warn_if_no_rpy2
+@require_rpy2
 @report_r_exceptions
-def r_dataframe_to_pandas(rdf: rpy2.robjects.DataFrame) -> pd.DataFrame:
-    """Convert an R dataframe to a pandas dataframe
+def r_dataframe_to_pandas(rdf):
+    """Convert an R dataframe to a pandas dataframe.
 
     Args:
         rdf (rpy2.robjects.DataFrame): R dataframe
@@ -134,28 +103,29 @@ def r_dataframe_to_pandas(rdf: rpy2.robjects.DataFrame) -> pd.DataFrame:
     Returns:
         pd.DataFrame: Pandas dataframe
     """
+    pandas2ri, pyarrow, pyra, ro, ListVector = get_rpy2_extended_modules()
+
     with (ro.default_converter + pandas2ri.converter).context():
         df = ro.conversion.get_conversion().rpy2py(rdf)
     return df
 
 
-@warn_if_no_rpy2
+@require_rpy2
 @report_r_exceptions
 def _get_py2rpy_pandas_conv():
-    """Get the py2rpy arrow converter for pandas
+    """Get the py2rpy arrow converter for pandas.
 
-    This is a high-performance converter using
-    the rpy2-arrow functionality:
+    This is a high-performance converter using the rpy2-arrow functionality:
     https://rpy2.github.io/rpy2-arrow/version/main/html/index.html
 
     Returns:
         Callable: The converter function
     """
+    pandas2ri, pyarrow, pyra, ro, ListVector = get_rpy2_extended_modules()
+
     base = get_rbase()
     # We use the converter included in rpy2-arrow as template.
-    conv = rpy2.robjects.conversion.Converter(
-        "Pandas to data.frame", template=pyra.converter
-    )
+    conv = ro.conversion.Converter("Pandas to data.frame", template=pyra.converter)
 
     @conv.py2rpy.register(pd.DataFrame)
     def py2rpy_pandas(dataf):

napistu/rpy2/constants.py

@@ -21,29 +21,6 @@ BIOC_VALID_EXPANDED_SPECIES_ONTOLOGIES = {
     ONTOLOGIES.SYMBOL,
 }
 
-# bioc ontologies used for linking systematic identifiers
-# (entrez is not part of this list because it forms the gene index)
-BIOC_DOGMATIC_MAPPING_ONTOLOGIES = {
-    ONTOLOGIES.ENSEMBL_GENE,
-    ONTOLOGIES.ENSEMBL_TRANSCRIPT,
-    ONTOLOGIES.ENSEMBL_PROTEIN,
-    ONTOLOGIES.UNIPROT,
-    ONTOLOGIES.GENE_NAME,
-    ONTOLOGIES.SYMBOL,
-}
-BIOC_PROTEIN_ONTOLOGIES = [ONTOLOGIES.UNIPROT, ONTOLOGIES.ENSEMBL_PROTEIN]
-BIOC_GENE_ONTOLOGIES = [
-    ONTOLOGIES.NCBI_ENTREZ_GENE,
-    ONTOLOGIES.ENSEMBL_GENE,
-    ONTOLOGIES.ENSEMBL_TRANSCRIPT,
-]
-BIOC_NAME_ONTOLOGIES = {
-    ONTOLOGIES.GENE_NAME: 0,
-    ONTOLOGIES.SYMBOL: 1,
-    ONTOLOGIES.UNIPROT: 2,
-    ONTOLOGIES.ENSEMBL_PROTEIN: 3,
-}
-
 # prefixes for bioconductor mapping tables
 BIOC_NOMENCLATURE = SimpleNamespace(
     CHR_TBL="CHR",
@@ -63,6 +40,30 @@ BIOC_NOMENCLATURE = SimpleNamespace(
     SYMBOL="symbol",
 )
 
+# Map ontology to bioconductor table name and column name
+BIOC_ONTOLOGY_MAPPING = {
+    ONTOLOGIES.NCBI_ENTREZ_GENE: (
+        BIOC_NOMENCLATURE.CHR_TBL,
+        BIOC_NOMENCLATURE.NCBI_ENTREZ_GENE,
+    ),
+    ONTOLOGIES.ENSEMBL_GENE: (
+        BIOC_NOMENCLATURE.ENSG_TBL,
+        BIOC_NOMENCLATURE.ENSEMBL_GENE,
+    ),
+    ONTOLOGIES.ENSEMBL_TRANSCRIPT: (
+        BIOC_NOMENCLATURE.ENST_TBL,
+        BIOC_NOMENCLATURE.ENSEMBL_TRANSCRIPT,
+    ),
+    ONTOLOGIES.ENSEMBL_PROTEIN: (
+        BIOC_NOMENCLATURE.ENSP_TBL,
+        BIOC_NOMENCLATURE.ENSEMBL_PROTEIN,
+    ),
+    ONTOLOGIES.UNIPROT: (BIOC_NOMENCLATURE.UNIPROT_TBL, BIOC_NOMENCLATURE.UNIPROT),
+    ONTOLOGIES.GENE_NAME: (BIOC_NOMENCLATURE.NAME_TBL, BIOC_NOMENCLATURE.GENE_NAME),
+    ONTOLOGIES.SYMBOL: (BIOC_NOMENCLATURE.SYMBOL_TBL, BIOC_NOMENCLATURE.SYMBOL),
+}
+
+
 # netcontextr constants
 
 COL_GENE = "gene"