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

napistu/ontologies/mygene.py

@@ -0,0 +1,369 @@
+import logging
+from typing import Dict, List, Set, Union
+from types import GeneratorType
+import itertools
+
+import mygene
+import pandas as pd
+
+from napistu.constants import ONTOLOGIES
+from napistu.ontologies.constants import (
+    MYGENE_DEFS,
+    NAPISTU_FROM_MYGENE_FIELDS,
+    NAPISTU_TO_MYGENE_FIELDS,
+    INTERCONVERTIBLE_GENIC_ONTOLOGIES,
+    MYGENE_QUERY_DEFS_LIST,
+    MYGENE_DEFAULT_QUERIES,
+    SPECIES_TO_TAXID,
+)
+
+# Configure logging to suppress biothings warnings
+logging.getLogger("biothings.client").setLevel(logging.ERROR)
+logger = logging.getLogger(__name__)
+
+
+def create_python_mapping_tables(
+    mappings: Set[str], species: str = "Homo sapiens", test_mode: bool = False
+) -> Dict[str, pd.DataFrame]:
+    """Create genome-wide mapping tables between Entrez and other gene identifiers.
+
+    Python equivalent of create_bioconductor_mapping_tables using MyGene.info API.
+
+    Parameters
+    ----------
+    mappings : Set[str]
+        Set of ontologies to create mappings for. Must be valid ontologies from
+        INTERCONVERTIBLE_GENIC_ONTOLOGIES.
+    species : str, default "Homo sapiens"
+        Species name (e.g., "Homo sapiens", "Mus musculus"). Must be a key in
+        SPECIES_TO_TAXID or a valid NCBI taxonomy ID.
+    test_mode : bool, default False
+        If True, only fetch the first 1000 genes for testing purposes.
+
+    Returns
+    -------
+    Dict[str, pd.DataFrame]
+        Dictionary with ontology names as keys and DataFrames as values.
+        Each DataFrame has Entrez gene IDs as index and mapped identifiers as values.
+
+    Raises
+    ------
+    ValueError
+        If any requested mappings are invalid or species is not recognized.
+    ImportError
+        If mygene package is not available.
+
+    Notes
+    -----
+    The function uses MyGene.info API to fetch gene annotations and creates mapping
+    tables between different gene identifier systems. It supports various ontologies
+    like Ensembl genes/transcripts/proteins, UniProt, gene symbols, etc.
+
+    Examples
+    --------
+    >>> mappings = {'ensembl_gene', 'symbol', 'uniprot'}
+    >>> tables = create_python_mapping_tables(mappings, 'Homo sapiens')
+    >>> print(tables['symbol'].head())
+    """
+
+    mygene_fields = _format_mygene_fields(mappings)
+
+    # Convert species name to taxonomy ID
+    taxa_id = _format_mygene_species(species)
+
+    # Initialize MyGene client
+    mg = mygene.MyGeneInfo()
+
+    # Fetch comprehensive gene data
+    logger.info("Fetching genome-wide gene data from MyGene...")
+    all_genes_df = _fetch_mygene_data_all_queries(
+        mg=mg, taxa_id=taxa_id, fields=mygene_fields, test_mode=test_mode
+    )
+
+    if all_genes_df.empty:
+        raise ValueError(f"No gene data retrieved for species: {species}")
+
+    logger.info(f"Retrieved {len(all_genes_df)} genes and RNAs")
+    mapping_tables = _create_mygene_mapping_tables(all_genes_df, mygene_fields)
+
+    return mapping_tables
+
+
+def _fetch_mygene_data_all_queries(
+    mg: mygene.MyGeneInfo,
+    taxa_id: int,
+    fields: List[str],
+    query_strategies: List[str] = MYGENE_DEFAULT_QUERIES,
+    test_mode: bool = False,
+) -> pd.DataFrame:
+    """Fetch comprehensive gene data from MyGene using multiple query strategies.
+
+    Parameters
+    ----------
+    mg : mygene.MyGeneInfo
+        Initialized MyGene.info client
+    taxa_id : int
+        NCBI taxonomy ID for the species
+    fields : List[str]
+        List of MyGene.info fields to retrieve
+    query_strategies : List[str], default MYGENE_DEFAULT_QUERIES
+        List of query strategies to use from MYGENE_QUERY_DEFS_LIST
+    test_mode : bool, default False
+        If True, only fetch first 1000 genes
+
+    Returns
+    -------
+    pd.DataFrame
+        Combined DataFrame with gene data from all queries
+
+    Raises
+    ------
+    ValueError
+        If any query strategies are invalid
+    """
+
+    all_results = []
+
+    # Validate queries
+    invalid_queries = set(query_strategies) - set(MYGENE_QUERY_DEFS_LIST)
+    if invalid_queries:
+        raise ValueError(
+            f"Invalid queries: {', '.join(invalid_queries)}. "
+            f"Valid queries are: {', '.join(MYGENE_QUERY_DEFS_LIST)}"
+        )
+
+    for query in query_strategies:
+        results_df = _fetch_mygene_data(
+            mg=mg, query=query, taxa_id=taxa_id, fields=fields, test_mode=test_mode
+        )
+
+        all_results.append(results_df)
+
+    return pd.concat(all_results)
+
+
+def _format_mygene_fields(mappings: Set[str]) -> Set[str]:
+    """Format and validate ontology mappings for MyGene.info queries.
+
+    Parameters
+    ----------
+    mappings : Set[str]
+        Set of ontologies to validate and convert to MyGene.info field names
+
+    Returns
+    -------
+    Set[str]
+        Set of valid MyGene.info field names including NCBI_ENTREZ_GENE
+
+    Raises
+    ------
+    ValueError
+        If any mappings are invalid
+    """
+    # Validate inputs
+    invalid_mappings = mappings - INTERCONVERTIBLE_GENIC_ONTOLOGIES
+    if invalid_mappings:
+        raise ValueError(
+            f"Invalid mappings: {', '.join(invalid_mappings)}. "
+            f"Valid options are: {', '.join(INTERCONVERTIBLE_GENIC_ONTOLOGIES)}"
+        )
+
+    logger.info(
+        f"Creating mapping tables from entrez genes to/from {', '.join(mappings)}"
+    )
+
+    # Convert ontologies to MyGene fields and ensure NCBI_ENTREZ_GENE is included
+    mygene_fields = {NAPISTU_TO_MYGENE_FIELDS[ontology] for ontology in mappings}
+    mygene_fields.add(MYGENE_DEFS.NCBI_ENTREZ_GENE)
+
+    return mygene_fields
+
+
+def _format_mygene_species(species: Union[str, int]) -> int:
+    """Convert species name or taxonomy ID to NCBI taxonomy ID.
+
+    Parameters
+    ----------
+    species : Union[str, int]
+        Species name (e.g. "Homo sapiens") or NCBI taxonomy ID
+
+    Returns
+    -------
+    int
+        NCBI taxonomy ID
+
+    Raises
+    ------
+    ValueError
+        If species name is not recognized
+    """
+    if isinstance(species, int):
+        logger.debug(f"Using taxonomy ID: {species}")
+        return species
+    else:
+        if species not in SPECIES_TO_TAXID:
+            raise ValueError(
+                f"Invalid species: {species}. Please use a species name in "
+                "SPECIES_TO_TAXID or directly pass the NCBI Taxonomy ID."
+            )
+
+        taxid = SPECIES_TO_TAXID[species]
+        logger.debug(f"Using species name: {species}; taxid: {taxid}")
+
+        return taxid
+
+
+def _fetch_mygene_data(
+    mg: mygene.MyGeneInfo,
+    query: str,
+    taxa_id: int,
+    fields: List[str],
+    test_mode: bool = False,
+) -> pd.DataFrame:
+    """Fetch gene data from MyGene.info for a single query.
+
+    Parameters
+    ----------
+    mg : mygene.MyGeneInfo
+        Initialized MyGene.info client
+    query : str
+        Query string to search for genes
+    taxa_id : int
+        NCBI taxonomy ID for the species
+    fields : List[str]
+        List of MyGene.info fields to retrieve
+    test_mode : bool, default False
+        If True, only fetch first 1000 genes
+
+    Returns
+    -------
+    pd.DataFrame
+        DataFrame containing gene data from the query
+
+    Raises
+    ------
+    ValueError
+        If query results are not in expected format
+    """
+    logger.debug(f"Querying: {query}")
+
+    result = mg.query(query, species=taxa_id, fields=",".join(fields), fetch_all=True)
+
+    # Validate result is a generator
+    if isinstance(result, GeneratorType):
+        all_hits = []
+
+        if test_mode:
+            # Only look at first 1000 genes in test mode
+            result = itertools.islice(result, 1000)
+
+        for i, gene in enumerate(result):
+            all_hits.append(gene)
+
+    else:
+        raise ValueError("The query results are not a generator")
+
+    results_df = pd.DataFrame(all_hits).assign(query_type=query)
+
+    if results_df.empty:
+        logger.warning(
+            f"No results found for {query} of species taxa id: {taxa_id} "
+            f"and fields: {', '.join(fields)}"
+        )
+        return pd.DataFrame()
+    else:
+        logger.info(f"Retrieved {results_df.shape[0]} genes from {query}")
+        return results_df
+
+
+def unnest_mygene_ontology(df: pd.DataFrame, field: str) -> pd.DataFrame:
+    """Unnest a column containing list of dicts in MyGene.info results.
+
+    Parameters
+    ----------
+    df : pd.DataFrame
+        DataFrame containing MyGene.info results
+    field : str
+        Field name to unnest, must contain a period to indicate nesting
+
+    Returns
+    -------
+    pd.DataFrame
+        DataFrame with unnested values, containing columns for entrez ID and the
+        unnested field value
+
+    Raises
+    ------
+    ValueError
+        If field format is invalid or data structure is unexpected
+    """
+    if "." in field:
+        # Extract nested ontology field
+        col_name, key_name = field.split(".")
+    else:
+        raise ValueError(
+            f"This function should only be called on a nested mygene ontology "
+            f"field; but you passed: {field} (the period indicates nesting)"
+        )
+
+    valid_df = df.dropna()
+    rows = []
+    for i, row in valid_df.iterrows():
+        entrez = row[MYGENE_DEFS.NCBI_ENTREZ_GENE]
+
+        if isinstance(row[col_name], list):
+            for item in row[col_name]:
+                rows.append([entrez, item[key_name]])
+        elif isinstance(row[col_name], dict):
+            rows.append([entrez, row[col_name][key_name]])
+        else:
+            raise ValueError(f"Unexpected type: {type(row[col_name])} for row {i}")
+
+    return pd.DataFrame(rows, columns=[MYGENE_DEFS.NCBI_ENTREZ_GENE, field])
+
+
+def _create_mygene_mapping_tables(
+    mygene_results_df: pd.DataFrame, mygene_fields: Set[str]
+) -> Dict[str, pd.DataFrame]:
+    """Create mapping tables from MyGene.info query results.
+
+    Parameters
+    ----------
+    mygene_results_df : pd.DataFrame
+        DataFrame containing MyGene.info query results
+    mygene_fields : Set[str]
+        Set of MyGene.info fields that were queried
+
+    Returns
+    -------
+    Dict[str, pd.DataFrame]
+        Dictionary mapping ontology names to DataFrames containing identifier mappings
+    """
+    mapping_tables = {}
+    for field in mygene_fields:
+        logger.info(f"Processing field: {field}")
+
+        # Select entrezgene + query field
+        if field == MYGENE_DEFS.NCBI_ENTREZ_GENE:
+            tbl = mygene_results_df.loc[:, [MYGENE_DEFS.NCBI_ENTREZ_GENE]]
+        elif "." in field:
+            ontology, entity = field.split(".")
+            tbl = unnest_mygene_ontology(
+                mygene_results_df.loc[:, [MYGENE_DEFS.NCBI_ENTREZ_GENE, ontology]],
+                field,
+            )
+        else:
+            tbl = mygene_results_df.loc[:, [MYGENE_DEFS.NCBI_ENTREZ_GENE, field]]
+
+        mapping_tables[NAPISTU_FROM_MYGENE_FIELDS[field]] = (
+            # Rename records
+            tbl.rename(columns={c: NAPISTU_FROM_MYGENE_FIELDS[c] for c in tbl.columns})
+            # Force all records to be strings
+            .astype(str)
+            # Remove duplicates
+            .drop_duplicates()
+            # Set index
+            .set_index(ONTOLOGIES.NCBI_ENTREZ_GENE)
+        )
+
+    return mapping_tables

napistu/ontologies/renaming.py

@@ -0,0 +1,198 @@
+"""Module for handling ontology aliases and validation."""
+
+from __future__ import annotations
+
+from typing import Dict, Set
+import logging
+from pydantic import BaseModel, field_validator
+from napistu.constants import (
+    ONTOLOGY_SPECIES_ALIASES,
+    ONTOLOGIES_LIST,
+    IDENTIFIERS,
+    SBML_DFS,
+)
+import pandas as pd
+from napistu import identifiers, sbml_dfs_core
+
+logger = logging.getLogger(__name__)
+
+
+def rename_species_ontologies(
+    sbml_dfs: sbml_dfs_core.SBML_dfs, aliases=ONTOLOGY_SPECIES_ALIASES
+):
+    """
+    Rename ontologies in the species identifiers table of an SBML_dfs object using provided aliases.
+
+    This function updates the ontology names in the species identifiers of the given SBML_dfs object
+    according to the provided alias mapping. It validates the alias mapping, logs which ontologies will be updated,
+    and replaces any matching aliases in the species identifiers with their canonical ontology names.
+
+    Parameters
+    ----------
+    sbml_dfs : napistu.sbml_dfs_core.SBML_dfs
+        The SBML_dfs object whose species table will be updated in-place.
+    aliases : dict[str, set[str]], optional
+        Dictionary mapping canonical ontology names to sets of their aliases. By default, uses ONTOLOGY_SPECIES_ALIASES.
+        All keys must be valid ontologies from ONTOLOGIES_LIST. Values must not overlap between keys or with keys themselves.
+
+    Returns
+    -------
+    None
+        The function updates sbml_dfs.species in-place and does not return a value.
+
+    Raises
+    ------
+    ValueError
+        If the alias mapping is invalid (e.g., keys not in ONTOLOGIES_LIST, overlapping values, or values used as keys),
+        or if there is no overlap between the provided aliases and the ontologies present in the species identifiers.
+
+    Examples
+    --------
+    >>> from napistu.ontologies.renaming import rename_species_ontologies
+    >>> sbml_dfs = ...  # an SBML_dfs object
+    >>> aliases = {"ncbi_entrez_gene": {"ncbigene", "ncbi_gene"}, "uniprot": {"uniprot_id"}}
+    >>> rename_species_ontologies(sbml_dfs, aliases)
+    """
+
+    species_identifiers = sbml_dfs.get_identifiers(SBML_DFS.SPECIES)
+
+    aliases = OntologySet(ontologies=aliases).ontologies
+    alias_mapping = _create_alias_mapping(aliases)
+
+    _log_ontology_updates(alias_mapping, set(species_identifiers[IDENTIFIERS.ONTOLOGY]))
+
+    species_identifiers[IDENTIFIERS.ONTOLOGY] = species_identifiers[
+        IDENTIFIERS.ONTOLOGY
+    ].map(lambda x: alias_mapping.get(x, x))
+
+    species_identifiers = identifiers.df_to_identifiers(
+        species_identifiers, SBML_DFS.SPECIES
+    )
+
+    updated_species = sbml_dfs.species.drop(SBML_DFS.S_IDENTIFIERS, axis=1).join(
+        pd.DataFrame(species_identifiers)
+    )
+
+    setattr(sbml_dfs, "species", updated_species)
+
+
+class OntologySet(BaseModel):
+    """Validate ontology mappings.
+
+    This model ensures that:
+    1. All keys are valid ontologies from ONTOLOGIES_LIST
+    2. The dict maps strings to sets of strings
+    3. Values in the sets do not overlap between different keys
+    4. Values in the sets are not also used as keys
+
+    Attributes
+    ----------
+    ontologies : Dict[str, Set[str]]
+        Dictionary mapping ontology names to sets of their aliases
+    """
+
+    ontologies: Dict[str, Set[str]]
+
+    @field_validator("ontologies")
+    @classmethod
+    def validate_ontologies(cls, v: Dict[str, Set[str]]) -> Dict[str, Set[str]]:
+        """Validate the ontology mapping structure.
+
+        Parameters
+        ----------
+        v : Dict[str, Set[str]]
+            Dictionary mapping ontology names to sets of their aliases
+
+        Returns
+        -------
+        Dict[str, Set[str]]
+            The validated ontology mapping dictionary
+
+        Raises
+        ------
+        ValueError
+            If any keys are not valid ontologies from ONTOLOGIES_LIST
+            If any values overlap between different ontologies
+            If any values are also used as ontology keys
+        """
+        # Check that all keys are valid ontologies
+        invalid_ontologies = set(v.keys()) - set(ONTOLOGIES_LIST)
+        if invalid_ontologies:
+            raise ValueError(
+                f"Invalid ontologies: {', '.join(invalid_ontologies)}. "
+                f"Must be one of: {', '.join(ONTOLOGIES_LIST)}"
+            )
+
+        # Check that values don't overlap between keys and aren't used as keys
+        all_values = set()
+        keys = set(v.keys())
+        for key, values in v.items():
+            # Check for overlap with other values
+            overlap = values & all_values
+            if overlap:
+                raise ValueError(
+                    f"Found overlapping values {overlap} under multiple ontologies"
+                )
+            # Check for overlap with keys
+            key_overlap = values & keys
+            if key_overlap:
+                raise ValueError(
+                    f"Found values {key_overlap} that are also used as ontology keys"
+                )
+            all_values.update(values)
+
+        return v
+
+
+def _create_alias_mapping(ontology_dict: Dict[str, Set[str]]) -> Dict[str, str]:
+    """Create a mapping from aliases to canonical ontology names.
+
+    Only creates mappings for the aliases specified in the input dictionary.
+    Does not include mappings for canonical names to themselves.
+
+    Parameters
+    ----------
+    ontology_dict : Dict[str, Set[str]]
+        Dictionary mapping ontologies to their aliases
+
+    Returns
+    -------
+    Dict[str, str]
+        Dictionary mapping each alias to its canonical ontology name
+    """
+    mapping = {}
+    for ontology, aliases in ontology_dict.items():
+        # Only map aliases to canonical names
+        for alias in aliases:
+            mapping[alias] = ontology
+    return mapping
+
+
+def _log_ontology_updates(
+    alias_mapping: Dict[str, str], species_ontologies: Set[str]
+) -> None:
+    """Log which ontology aliases will be updated.
+
+    Parameters
+    ----------
+    alias_mapping : Dict[str, str]
+        Dictionary mapping old ontology names to new ones
+    species_ontologies : Set[str]
+        Set of ontology names present in the species identifiers
+
+    Raises
+    ------
+    ValueError
+        If there is no overlap between the aliases and species ontologies
+    """
+    # Find which aliases are present in the species data
+    updatable_aliases = set(alias_mapping.keys()) & species_ontologies
+    if not updatable_aliases:
+        raise ValueError(
+            "The set of ontologies in the species identifiers and aliases do not overlap. "
+            "Please provide an updated aliases dict."
+        )
+
+    # Log which ontologies will be updated
+    updates = [f"{old} -> {alias_mapping[old]}" for old in updatable_aliases]
+    logger.info(f"Updating the following ontologies: {', '.join(updates)}")