napistu 0.1.0__py3-none-any.whl

napistu/ingestion/string.py

@@ -0,0 +1,356 @@
+from __future__ import annotations
+
+import logging
+
+import pandas as pd
+from napistu import identifiers
+from napistu import sbml_dfs_core
+from napistu import source
+from napistu import utils
+from napistu.constants import BQB
+from napistu.constants import COMPARTMENTS
+from napistu.constants import MINI_SBO_FROM_NAME
+from napistu.ingestion import cpr_edgelist
+from napistu.ingestion.constants import SBML_SPECIES_DICT_IDENTIFIERS
+from napistu.ingestion.constants import SBML_SPECIES_DICT_NAME
+from napistu.ingestion.constants import SMBL_REACTION_DICT_IDENTIFIERS
+from napistu.ingestion.constants import SMBL_REACTION_DICT_IS_REVERSIBLE
+from napistu.ingestion.constants import SMBL_REACTION_DICT_NAME
+from napistu.ingestion.constants import SMBL_REACTION_SPEC_SBO_TERM
+from napistu.ingestion.constants import STRING_DOWNSTREAM_COMPARTMENT
+from napistu.ingestion.constants import STRING_DOWNSTREAM_NAME
+from napistu.ingestion.constants import STRING_PROTEIN_ID
+from napistu.ingestion.constants import STRING_PROTEIN_ID_RAW
+from napistu.ingestion.constants import STRING_SOURCE
+from napistu.ingestion.constants import STRING_TARGET
+from napistu.ingestion.constants import STRING_TAX_IDS
+from napistu.ingestion.constants import STRING_UPSTREAM_COMPARTMENT
+from napistu.ingestion.constants import STRING_UPSTREAM_NAME
+from napistu.ingestion.constants import STRING_URL_EXPRESSIONS
+from napistu.ingestion.constants import STRING_VERSION
+from fs import open_fs
+
+logger = logging.getLogger(__name__)
+
+
+def get_string_species_url(
+    species: str, asset: str, version: float = STRING_VERSION
+) -> str:
+    """
+    STRING Species URL
+    Construct urls for downloading specific STRING tables
+    Args:
+        species (str): A species name: e.g., Homo sapiens.
+        asset (str): The type of table to be downloaded. Currently "interactions" or "aliases".
+        version (float): The version of STRING to work with.
+    Returns:
+        str: The download url
+    """
+    if species not in STRING_TAX_IDS.keys():
+        raise ValueError(
+            f"{species} is not a valid value for species ids, valid ids are: {', '.join(STRING_TAX_IDS.keys())}"
+        )
+
+    if asset not in STRING_URL_EXPRESSIONS.keys():
+        raise ValueError(
+            f"{asset} is not a valid value for a STRING asset, valid assets are: "
+            f"{', '.join(STRING_URL_EXPRESSIONS.keys())}"
+        )
+
+    url_fstring = STRING_URL_EXPRESSIONS[asset]
+
+    return eval(
+        f'f"{url_fstring}"', {"taxid": STRING_TAX_IDS[species], "version": version}
+    )
+
+
+def download_string(target_uri: str, species: str) -> None:
+    """Downloads string to the target uri
+
+    Args:
+        target_uri (str): target url
+        species (str): A species name: e.g., Homo sapiens
+
+    Returns:
+        None
+    """
+    string_url = get_string_species_url(
+        species, asset="interactions", version=STRING_VERSION
+    )
+    logger.info("Start downloading string db %s to %s", string_url, target_uri)
+
+    utils.download_wget(string_url, target_uri)
+
+    return None
+
+
+def download_string_aliases(target_uri: str, species: str) -> None:
+    """Downloads string aliases to the target uri
+
+    Args:
+        target_uri (str): target url
+        species (str): A species name: e.g., Homo sapiens
+
+    Returns:
+        None
+    """
+    string_aliases_url = get_string_species_url(
+        species, asset="aliases", version=STRING_VERSION
+    )
+    logger.info(
+        "Start downloading string aliases %s to %s", string_aliases_url, target_uri
+    )
+    utils.download_wget(string_aliases_url, target_uri)
+
+    return None
+
+
+def convert_string_to_sbml_dfs(
+    string_uri: str,
+    string_aliases_uri: str,
+) -> sbml_dfs_core.SBML_dfs:
+    """Ingests string to sbml dfs
+
+    Args:
+        string_uri (str): string uri
+        string_aliases_uri (str): string aliases uri
+
+    Returns:
+        sbml_dfs_core.SBML_dfs: sbml dfs
+    """
+    # Read string raw data
+    string_edgelist = _read_string(string_uri)
+    string_aliases = _read_string_aliases(string_aliases_uri)
+
+    # Start building new sbml dfs
+
+    # remove one edge since reciprocal edges are present; i.e., A-B and B-A
+    # and attributes (e.g., combined_score are the same across both reciprocal
+    # interactions
+    uq_string_edgelist = cpr_edgelist.remove_reciprocal_interactions(
+        string_edgelist, extra_defining_vars=["combined_score"]
+    )
+
+    # Per convention unaggregated models receive an empty source
+    interaction_source = source.Source(init=True)
+
+    # define identifier mapping from aliases to use:
+    alias_to_identifier = {
+        "Ensembl_gene": ("ensembl_gene", BQB.IS_ENCODED_BY),
+        "Ensembl_transcript": ("ensembl_transcript", BQB.IS_ENCODED_BY),
+        "Ensembl_translation": ("ensembl_protein", BQB.IS),
+        "Ensembl_UniProt_AC": ("uniprot", BQB.IS),
+    }
+
+    # filter aliases to only keep required ones
+    string_aliases_fil = string_aliases.query(
+        "source in @alias_to_identifier.keys()"
+    ).set_index(STRING_PROTEIN_ID)
+
+    # to save on memory
+    del string_aliases
+
+    # define species
+    species_df = _build_species_df(
+        uq_string_edgelist, string_aliases_fil, alias_to_identifier
+    )
+
+    # Define compartments
+    # Currently we are mapping everything to the `CELLULAR_COMPONENT`
+    # which is a catch-all go: for unknown localisation
+    compartments_df = sbml_dfs_core._stub_compartments()
+
+    # define interactions
+    interaction_edgelist = _build_interactor_edgelist(uq_string_edgelist)
+
+    # build the final object
+    sbml_dfs = sbml_dfs_core.sbml_dfs_from_edgelist(
+        interaction_edgelist=interaction_edgelist,
+        species_df=species_df,
+        compartments_df=compartments_df,
+        interaction_source=interaction_source,
+        upstream_stoichiometry=0,
+        downstream_stoichiometry=0,
+        downstream_sbo_name="interactor",
+        keep_reactions_data="string",
+    )
+    return sbml_dfs
+
+
+def _read_string(string_uri: str) -> pd.DataFrame:
+    """Reads string from uri
+
+    Args:
+        string_uri (str): string uri
+
+    Returns:
+        pd.DataFrame: string edgelist
+    """
+    base_path, file_name = utils.get_source_base_and_path(string_uri)
+    # TODO: test on gz versus txt
+    with open_fs(base_path) as base_fs:
+        with base_fs.open(file_name, "rb") as f:
+            string_edges = pd.read_csv(f, sep=" ")
+    return string_edges
+
+
+def _read_string_aliases(string_aliases_uri: str) -> pd.DataFrame:
+    """Reads string from uri
+
+    Args:
+        string_aliases_uri (str): string aliases uri
+
+    Returns:
+        pd.DataFrame: string aliases
+    """
+    base_path, file_name = utils.get_source_base_and_path(string_aliases_uri)
+    # TODO: test on gz versus txt
+    with open_fs(base_path) as base_fs:
+        with base_fs.open(file_name, "rb") as f:
+            string_aliases = (
+                pd.read_csv(f, sep="\t")
+                # Rename column with #
+                .rename(columns={STRING_PROTEIN_ID_RAW: STRING_PROTEIN_ID})
+            )
+    return string_aliases
+
+
+def _get_identifiers(
+    row: pd.DataFrame,
+    alias_to_identifier: dict[str, tuple[str, str]],
+    dat_alias: pd.DataFrame,
+) -> identifiers.Identifiers:
+    """Helper function to get identifiers from a row of the string alias file
+
+    Args:
+        row (pd.DataFrame): grouped dataframe
+        alias_to_identifier (dict[str, tuple[str, str]]):
+            map from an alias source to an ontology and a qualifier
+        dat_alias (pd.DataFrame): Helper dataframe with index=string_protein_id
+            and columns=source (the source name), alias (the identifier)
+
+    Returns:
+        identifiers.Identifiers: An Identifiers object containing all identifiers
+    """
+    if row.shape[0] == 0:
+        return identifiers.Identifiers([])
+    d = dat_alias.loc[row.s_name]
+    ids = []
+    for source_name, (ontology, qualifier) in alias_to_identifier.items():
+        for identifier in d.query(f"source == '{source_name}'")["alias"]:
+            # Here we creating an uri
+            uri = identifiers.create_uri_url(ontology=ontology, identifier=identifier)
+            # This is exactly the output format from: identifiers.format_uri
+            # We are doing it manually here to avoid the overhead of parsing
+            # the uri again
+            id_dict = {
+                "ontology": ontology,
+                "identifier": identifier,
+                "bqb": qualifier,
+                "url": uri,
+            }
+            ids.append(id_dict)
+    identifier = identifiers.Identifiers(ids)
+    return identifier
+
+
+def _build_species_df(
+    edgelist: pd.DataFrame,
+    aliases: pd.DataFrame,
+    alias_to_identifier: dict,
+    source_col: str = STRING_SOURCE,
+    target_col: str = STRING_TARGET,
+) -> pd.DataFrame:
+    """Builds the species dataframe from the edgelist and aliases
+
+    Args:
+        edgelist (pd.DataFrame): edgelist
+        aliases (pd.DataFrame): aliases
+        alias_to_identifier (dict[str, tuple[str, str]]):
+            map from an alias source to an ontology and a qualifier
+
+    Returns:
+        pd.DataFrame: species dataframe
+    """
+    species_df = (
+        pd.Series(
+            list(set(edgelist[source_col]).union(edgelist[target_col])),
+            name=SBML_SPECIES_DICT_NAME,
+        )
+        .to_frame()
+        .set_index(SBML_SPECIES_DICT_NAME, drop=False)
+        .apply(
+            _get_identifiers,
+            alias_to_identifier=alias_to_identifier,
+            dat_alias=aliases,
+            axis=1,
+        )
+        .rename(SBML_SPECIES_DICT_IDENTIFIERS)
+        .reset_index()
+    )
+    return species_df
+
+
+def _build_interactor_edgelist(
+    edgelist: pd.DataFrame,
+    upstream_col_name: str = STRING_SOURCE,
+    downstream_col_name: str = STRING_TARGET,
+    add_reverse_interactions: bool = False,
+    sbo_term: str = "interactor",
+    compartment: str = COMPARTMENTS["CELLULAR_COMPONENT"],
+) -> pd.DataFrame:
+    """Format STRING interactions as reactions."""
+
+    sbo_interactor = MINI_SBO_FROM_NAME[sbo_term]
+    dat = edgelist.rename(
+        columns={
+            upstream_col_name: STRING_UPSTREAM_NAME,
+            downstream_col_name: STRING_DOWNSTREAM_NAME,
+        }
+    ).assign(
+        **{
+            STRING_UPSTREAM_COMPARTMENT: compartment,
+            STRING_DOWNSTREAM_COMPARTMENT: compartment,
+            SMBL_REACTION_SPEC_SBO_TERM: sbo_interactor,
+            SMBL_REACTION_DICT_IDENTIFIERS: lambda x: identifiers.Identifiers([]),
+        }
+    )
+    if add_reverse_interactions:
+        dat = (
+            dat
+            # Add the reverse interactions
+            .pipe(
+                lambda d: pd.concat(
+                    [
+                        d,
+                        d.rename(
+                            columns={
+                                STRING_UPSTREAM_NAME: STRING_DOWNSTREAM_NAME,
+                                STRING_DOWNSTREAM_NAME: STRING_UPSTREAM_NAME,
+                            }
+                        ),
+                    ]
+                )
+            )
+        )
+
+    interaction_edgelist = dat
+    interaction_edgelist[SMBL_REACTION_DICT_NAME] = _build_string_reaction_name(
+        dat[STRING_UPSTREAM_NAME], dat[STRING_DOWNSTREAM_NAME]
+    )
+    interaction_edgelist[SMBL_REACTION_DICT_IS_REVERSIBLE] = True
+
+    return interaction_edgelist
+
+
+def _build_string_reaction_name(from_col: pd.Series, to_col: pd.Series) -> pd.Series:
+    """Helper to build the reaction name for string reactions
+
+    Args:
+        from_col (pd.Series): from species
+        to_col (pd.Series): to species
+
+    Returns:
+        pd.Series: new name column
+    """
+    return from_col + " - " + to_col

napistu/ingestion/trrust.py

@@ -0,0 +1,285 @@
+from __future__ import annotations
+
+import os
+from itertools import chain
+
+import pandas as pd
+from napistu import identifiers
+from napistu import sbml_dfs_core
+from napistu import source
+from napistu import utils
+from napistu.constants import MINI_SBO_FROM_NAME
+from napistu.constants import SBOTERM_NAMES
+from napistu.ingestion.constants import SBML_COMPARTMENT_DICT_IDENTIFIERS
+from napistu.ingestion.constants import SBML_COMPARTMENT_DICT_NAME
+from napistu.ingestion.constants import SBML_SPECIES_DICT_IDENTIFIERS
+from napistu.ingestion.constants import SBML_SPECIES_DICT_NAME
+from napistu.ingestion.constants import SMBL_REACTION_DICT_IDENTIFIERS
+from napistu.ingestion.constants import SMBL_REACTION_DICT_IS_REVERSIBLE
+from napistu.ingestion.constants import SMBL_REACTION_DICT_NAME
+from napistu.ingestion.constants import SMBL_REACTION_SPEC_SBO_TERM
+from napistu.ingestion.constants import SPECIES_FULL_NAME_HUMAN
+from napistu.ingestion.constants import STRING_DOWNSTREAM_COMPARTMENT
+from napistu.ingestion.constants import STRING_DOWNSTREAM_NAME
+from napistu.ingestion.constants import STRING_UPSTREAM_COMPARTMENT
+from napistu.ingestion.constants import STRING_UPSTREAM_NAME
+from napistu.ingestion.constants import TRRUST_COMPARTMENT_NUCLEOPLASM
+from napistu.ingestion.constants import TRRUST_COMPARTMENT_NUCLEOPLASM_GO_ID
+from napistu.ingestion.constants import TRRUST_SYMBOL
+from napistu.ingestion.constants import TRRUST_UNIPROT
+from napistu.ingestion.constants import TRRUST_UNIPROT_ID
+from napistu.ingestion.constants import TTRUST_URL_RAW_DATA_HUMAN
+from napistu.ingestion.constants import TRRUST_SIGNS
+from napistu.rpy2 import callr
+from fs import open_fs
+
+
+def download_trrust(target_uri: str) -> None:
+    """Downloads trrust to the target uri
+
+    Args:
+        target_uri (str): target url
+
+    Returns:
+        None
+    """
+    utils.download_wget(TTRUST_URL_RAW_DATA_HUMAN, target_uri)
+
+    return None
+
+
+def convert_trrust_to_sbml_dfs(
+    trrust_uri: str,
+) -> sbml_dfs_core.SBML_dfs:
+    """Ingests trrust to sbml dfs
+
+    Args:
+        trrust_uri (str): trrust uri
+
+    Returns:
+        sbml_dfs
+    """
+    # Read trrust raw data
+    trrust_edgelist = _read_trrust(trrust_uri)
+
+    # Get uniprot to symbol mapping
+    uniprot_2_symbol = _get_uniprot_2_symbol_mapping()
+
+    # Start building new sbml dfs
+    # Per convention unaggregated models receive an empty source
+    interaction_source = source.Source(init=True)
+
+    # Summarize edges
+
+    edge_summaries_df = (
+        trrust_edgelist.groupby(["from", "to"], as_index=True)
+        .apply(_summarize_trrust_pairs)
+        .reset_index(drop=False)
+    )
+
+    # define distinct species
+    species_df = (
+        pd.DataFrame(
+            {
+                SBML_SPECIES_DICT_NAME: list(
+                    {*edge_summaries_df["from"], *edge_summaries_df["to"]}
+                )
+            }
+        )
+        .merge(
+            uniprot_2_symbol.rename({TRRUST_SYMBOL: SBML_SPECIES_DICT_NAME}, axis=1),
+            how="left",
+        )
+        .set_index(SBML_SPECIES_DICT_NAME)
+    )
+
+    # create Identifiers objects for all species with uniprot IDs
+    species_w_ids = species_df[~species_df[TRRUST_UNIPROT_ID].isnull()].sort_index()
+    species_w_ids["url"] = [
+        identifiers.create_uri_url(ontology=TRRUST_UNIPROT, identifier=x)
+        for x in species_w_ids[TRRUST_UNIPROT_ID]
+    ]
+
+    # create a series where each row is a gene with 1+ uniprot ids and the value is an
+    # identifiers objects with all uniprot ids
+    species_w_ids_series = pd.Series(
+        [
+            identifiers.Identifiers(
+                [
+                    identifiers.format_uri(uri=x, biological_qualifier_type="BQB_IS")
+                    for x in species_w_ids.loc[[ind]]["url"].tolist()
+                ]
+            )
+            for ind in species_w_ids.index.unique()
+        ],
+        index=species_w_ids.index.unique(),
+    ).rename(SBML_SPECIES_DICT_IDENTIFIERS)
+
+    # just retain s_name and s_Identifiers
+    # this just needs a source object which will be added later
+    species_df = (
+        species_df.reset_index()
+        .drop(TRRUST_UNIPROT_ID, axis=1)
+        .drop_duplicates()
+        .merge(
+            species_w_ids_series,
+            how="left",
+            left_on=SBML_SPECIES_DICT_NAME,
+            right_index=True,
+        )
+        .reset_index(drop=True)
+    )
+    # stub genes with missing IDs
+    species_df[SBML_SPECIES_DICT_IDENTIFIERS] = species_df[SBML_SPECIES_DICT_IDENTIFIERS].fillna(  # type: ignore
+        value=identifiers.Identifiers([])
+    )
+
+    # define distinct compartments
+    compartments_df = pd.DataFrame(
+        {
+            SBML_COMPARTMENT_DICT_NAME: TRRUST_COMPARTMENT_NUCLEOPLASM,
+            SBML_COMPARTMENT_DICT_IDENTIFIERS: identifiers.Identifiers(
+                [
+                    identifiers.format_uri(
+                        uri=identifiers.create_uri_url(
+                            ontology="go",
+                            identifier=TRRUST_COMPARTMENT_NUCLEOPLASM_GO_ID,
+                        ),
+                        biological_qualifier_type="BQB_IS",
+                    )
+                ]
+            ),
+        },
+        index=[0],
+    )
+
+    gene_gene_identifier_edgelist = edge_summaries_df.rename(
+        {"from": STRING_UPSTREAM_NAME, "to": STRING_DOWNSTREAM_NAME}, axis=1
+    ).assign(
+        upstream_compartment=TRRUST_COMPARTMENT_NUCLEOPLASM,
+        downstream_compartment=TRRUST_COMPARTMENT_NUCLEOPLASM,
+    )
+    gene_gene_identifier_edgelist[SMBL_REACTION_DICT_NAME] = [
+        f"{x} {y} of {z}"
+        for x, y, z in zip(
+            gene_gene_identifier_edgelist[STRING_UPSTREAM_NAME],
+            gene_gene_identifier_edgelist["sign"],
+            gene_gene_identifier_edgelist[STRING_DOWNSTREAM_NAME],
+        )
+    ]
+
+    # convert relationships to SBO terms
+    interaction_edgelist = gene_gene_identifier_edgelist.replace(
+        {"sign": MINI_SBO_FROM_NAME}
+    ).rename({"sign": SMBL_REACTION_SPEC_SBO_TERM}, axis=1)
+
+    # format pubmed identifiers of interactions
+    interaction_edgelist[SMBL_REACTION_DICT_IDENTIFIERS] = [
+        _format_pubmed_for_interactions(x) for x in interaction_edgelist["reference"]
+    ]
+
+    # directionality: by default, set r_isreversible to False for TRRUST data
+    interaction_edgelist[SMBL_REACTION_DICT_IS_REVERSIBLE] = False
+
+    # reduce to essential variables
+    interaction_edgelist = interaction_edgelist[
+        [
+            STRING_UPSTREAM_NAME,
+            STRING_DOWNSTREAM_NAME,
+            STRING_UPSTREAM_COMPARTMENT,
+            STRING_DOWNSTREAM_COMPARTMENT,
+            SMBL_REACTION_DICT_NAME,
+            SMBL_REACTION_SPEC_SBO_TERM,
+            SMBL_REACTION_DICT_IDENTIFIERS,
+            SMBL_REACTION_DICT_IS_REVERSIBLE,
+        ]
+    ]
+
+    # Build sbml dfs
+    sbml_dfs = sbml_dfs_core.sbml_dfs_from_edgelist(
+        interaction_edgelist=interaction_edgelist,
+        species_df=species_df,
+        compartments_df=compartments_df,
+        interaction_source=interaction_source,
+    )
+    sbml_dfs.validate()
+    return sbml_dfs
+
+
+def _read_trrust(trrust_uri: str) -> pd.DataFrame:
+    """Read trrust csv
+
+    Args:
+        trrust_uri (str): uri to the trrust csv
+
+    Returns:
+        pd.DataFrame: Data Frame
+    """
+    base_path = os.path.dirname(trrust_uri)
+    file_name = os.path.basename(trrust_uri)
+    with open_fs(base_path) as base_fs:
+        with base_fs.open(file_name) as f:
+            trrust_edgelist = pd.read_csv(
+                f, sep="\t", names=["from", "to", "sign", "reference"]
+            ).drop_duplicates()
+    return trrust_edgelist
+
+
+def _summarize_trrust_pairs(pair_data: pd.DataFrame) -> pd.Series:
+    """Summarize a TF->target relationship based on the sign and source of the interaction."""
+
+    signs = set(pair_data["sign"].tolist())
+    if (TRRUST_SIGNS.ACTIVATION in signs) and (TRRUST_SIGNS.REPRESSION in signs):
+        sign = SBOTERM_NAMES.MODIFIER
+    elif TRRUST_SIGNS.ACTIVATION in signs:
+        sign = SBOTERM_NAMES.STIMULATOR
+    elif TRRUST_SIGNS.REPRESSION in signs:
+        sign = SBOTERM_NAMES.INHIBITOR
+    else:
+        sign = SBOTERM_NAMES.MODIFIER
+
+    refs = set(chain(*[x.split(";") for x in pair_data["reference"]]))
+    return pd.Series({"sign": sign, "reference": refs})
+
+
+def _get_uniprot_2_symbol_mapping() -> pd.DataFrame:
+    """Create a mapping from Uniprot IDs to human gene symbols."""
+
+    entrez_2_symbol = callr.r_dataframe_to_pandas(
+        callr.bioconductor_org_r_function(
+            TRRUST_SYMBOL.upper(), species=SPECIES_FULL_NAME_HUMAN
+        )
+    )
+    # only look at symbol which uniquely map to a single gene
+    symbol_counts = entrez_2_symbol.value_counts(TRRUST_SYMBOL)
+    unique_symbols = symbol_counts[symbol_counts == 1].index.tolist()
+    entrez_2_symbol = entrez_2_symbol[
+        entrez_2_symbol[TRRUST_SYMBOL].isin(unique_symbols)
+    ]
+
+    # one entrez -> multiple uniprot IDs is okay
+    entrez_2_uniprot = callr.r_dataframe_to_pandas(
+        callr.bioconductor_org_r_function(
+            TRRUST_UNIPROT.upper(), species=SPECIES_FULL_NAME_HUMAN
+        )
+    )
+
+    uniprot_2_symbol = entrez_2_symbol.merge(entrez_2_uniprot).drop("gene_id", axis=1)
+    return uniprot_2_symbol
+
+
+def _format_pubmed_for_interactions(pubmed_set):
+    """Format a set of pubmed ids as an Identifiers object."""
+
+    ids = list()
+    for p in pubmed_set:
+        # some pubmed IDs are bogus
+        url = identifiers.create_uri_url(ontology="pubmed", identifier=p, strict=False)
+        if url is not None:
+            valid_url = identifiers.format_uri(
+                uri=url, biological_qualifier_type="BQB_IS_DESCRIBED_BY"
+            )
+
+            ids.append(valid_url)
+
+    return identifiers.Identifiers(ids)