graphein.ppi¶
Config¶
- class graphein.ppi.config.BioGridConfig(*, searchNames: bool | None = True, max: int | None = 10000, interSpeciesExcluded: bool | None = True, selfInteractionsExcluded: bool | None = False, evidenceList: str | None = '', includeEvidence: bool | None = False, searchIds: bool | None = True, searchSynonyms: bool | None = True, searchBiogridIds: bool | None = True, additionalIdentifierTypes: str | None = '', excludeGenes: bool | None = False, includeInteractors: bool | None = True, includeInteractorInteractions: bool | None = False, pubmedList: str | None = '', excludePubmeds: bool | None = False, htpThreshold: int | None = 20, throughputTag: str | None = 'any')[source]¶
Config for specifying parameters for API calls to BIOGRID. A full description of the parameters can be found at : https://wiki.thebiogrid.org/doku.php/biogridrest
- Parameters:
searchNames (bool, optional) – If ‘true’, the interactor OFFICIAL_SYMBOL will be examined for a match with the geneList.
max (int, optional) – Number of results to fetch, defaults to 10,000
interSpeciesExcluded (bool, optional) – If ‘true’, interactions with interactors from different species will be excluded, defaults to True
selfInteractionsExcluded (bool, optional.) – If ‘true’, interactions with one interactor will be excluded, defaults to False
evidenceList (str, optional) – Any interaction evidence with its Experimental System in the list will be excluded from the results unless includeEvidence is set to true., defaults to “” (empty string)
includeEvidence (bool, optional) – If set to true, any interaction evidence with its Experimental System in the evidenceList will be included in the result, defaults to False
searchIDs (bool, optional) – If ‘true’, the interactor ENTREZ_GENE, ORDERED LOCUS and SYSTEMATIC_NAME (orf) will be examined for a match with the geneList. Defaults to True
searchNames – # If ‘true’, the interactor OFFICIAL_SYMBOL will be examined for a match with the geneList. Defaults to True.
searchSynonyms (bool, optional) – If ‘true’, the interactor SYNONYMS will be examined for a match with the geneList. Defaults to True.
searchBiogridIds – If ‘true’, the entries in ‘GENELIST’ will be compared to BIOGRID internal IDS which are provided in all Tab2 formatted files. Defaults to True
additionalIdentifierTypes (str, optional) – Identifier types on this list are examined for a match with the geneList. Defaults to “”
excludeGenes (bool, optional) – If ‘true’, interactions containing genes in the geneList will be excluded from the results. Defaults to False
includeInteractors (bool, optional) – If ‘true’, in addition to interactions between genes on the geneList, interactions will also be fetched which have only one interactor on the geneList. Defaults to True
includeInteractorInteractions (bool, optional) – # If ‘true’ interactions between the geneList’s first order interactors will be included. Defaults to False
pubmedList (str, optional) – Interactions will be fetched whose Pubmed Id is/ is not in this list, depending on the value of excludePubmeds. Defaults to “”
excludePubmeds (bool, optional) – If ‘false’, interactions with Pubmed ID in pubmedList will be included in the results; if ‘true’ they will be excluded. Defaults to False
htpThreshold (int, optional) – Interactions whose Pubmed ID has more than this number of interactions will be excluded from the results. Ignored if excludePubmeds is ‘false’. Defaults to 20.
throughputTag (str, optional) – If set to ‘low or ‘high’, only interactions with ‘Low throughput’ or ‘High throughput’ in the ‘throughput’ field will be returned. Defaults to “any”
- model_config = {}¶
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class graphein.ppi.config.PPIGraphConfig(*, paginate: bool = True, ncbi_taxon_id: int = 9606, kwargs: dict[str, str | int | float] | None = {'BIOGRID_throughputTag': 'high', 'STRING_escore': 0.2}, string_config: STRINGConfig | None = None, biogrid_config: BioGridConfig | None = None)[source]¶
Config for specifying parameters for PPI Graph Construction
- Parameters:
paginate (bool) – Controls whether or not to paginate API calls. Useful for large queries. Defaults to True
ncbi_taxon_id (int) – Defaults to 9606 (human)
string_config (graphein.ppi.config.STRINGConfig) – Config Object holding parameters for STRINGdb API calls. Defaults to None
biogrid_config (graphein.ppi.config.BioGridConfig, optional) – Config Object holding parameters for BioGrid API calls. Defaults to None
- model_config = {'arbitrary_types_allowed': True}¶
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class graphein.ppi.config.STRINGConfig(*, species: int | None = 9606, required_score: int | None = 50, network_type: str | None = 'functional', add_nodes: int | None = 0, show_query_node_labels: bool | None = 0)[source]¶
Config for specifying parameters for API calls to STRINGdb. Full documentation can be found: https://string-db.org/help/api/
- Parameters:
species (int, optional) – NCBI taxon identifiers, defaults to 9606 (human)
required_score (int, optional) – Threshold of significance to include a interaction, a number between 0 and 1000 (default depends on the network)
network_type (str, optional) – Network type: “functional” (default), “physical”
add_nodes (int, optional) – Adds a number of proteins to the network based on their confidence score, e.g., extends the interaction neighborhood of selected proteins to desired value, defaults to 50
show_query_node_labels (bool, optional) – When available use submitted names in the preferredName column when (0 or 1) (default:0)
- model_config = {}¶
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
Graph Construction¶
Graphs¶
Functions for constructing a PPI PPIGraphConfig from STRINGdb and BIOGRID.
- graphein.ppi.graphs.compute_ppi_graph(protein_list: list[str], edge_construction_funcs: list[Callable], graph_annotation_funcs: list[Callable] | None = None, node_annotation_funcs: list[Callable] | None = None, edge_annotation_funcs: list[Callable] | None = None, config: PPIGraphConfig | None = None) Graph[source]¶
- Computes a PPI Graph from a list of protein IDs. This is the core function
for PPI graph construction.
- Parameters:
protein_list (List[str]) – List of protein identifiers
edge_construction_funcs (List[Callable], optional) – List of functions to construct edges with
graph_annotation_funcs (List[Callable], optional) – List of functions to annotate graph metadata
node_annotation_funcs (List[Callable], optional) – List of functions to annotate node metadata
edge_annotation_funcs (List[Callable], optional) – List of function to annotate edge metadata
config (PPIGraphConfig, optional) – Config object specifying additional parameters for STRING and BIOGRID API calls
- Returns:
nx.Graphof PPI network- Return type:
nx.Graph
- graphein.ppi.graphs.parse_kwargs_from_config(config: PPIGraphConfig) PPIGraphConfig[source]¶
- If configs for STRING and BIOGRID are provided in the Global
~graphein.ppi.config.PPIGraphConfig, we update the kwargs
- Parameters:
config (PPIGraphConfig) – PPI graph configuration object.
- Returns:
config with updated config.kwargs
- Return type:
Edges¶
Functions for adding edges to a PPI Graph from parsed STRING & BIOGRID API call outputs.
- graphein.ppi.edges.add_biogrid_edges(G: Graph, **kwargs) Graph[source]¶
Adds edges from the BIOGRID database (https://thebiogrid.org/) to PPI Graph.
- Parameters:
G (nx.Graph) – Graph to edges to (populated with
protein_idnodes).kwargs – Additional parameters to pass to BIOGRID API calls.
- Returns:
nx.Graph PPIGraph with BIOGRID interactions added as edges.
- Return type:
nx.Graph
- graphein.ppi.edges.add_interacting_proteins(G: Graph, df: DataFrame, kind: str) Graph[source]¶
Generic function for adding interaction edges to PPI Graph. You can use this function to additional interactions using a DataFrame with columns
"p1"and"p2".- Parameters:
G (nx.Graph) – PPI Graph to populate with edges.
df (pd.DataFrame) – DataFrame containing edge list.
kind (str) – name of interaction type.
- Returns:
PPI Graph with pre-computed edges added.
- Return type:
nx.Graph
- graphein.ppi.edges.add_string_edges(G: Graph, **kwargs) Graph[source]¶
Adds edges from STRING PPI database (https://string-db.org/) to a PPI Graph.
- Parameters:
G (nx.Graph) – Graph to edges to (populated with
protein_idnodes).kwargs – Additional parameters to pass to STRING API calls.
- Returns:
PPI Graph with STRING interactions added as edges.
- Return type:
nx.Graph
Graph Features¶
Functions for adding metadata to PPI Graphs from STRING and BIOGRID.
- graphein.ppi.graph_metadata.add_biogrid_metadata(G: Graph, kwargs: dict[str, str | int]) Graph[source]¶
Adds interaction dataframe from BIOGRID to graph.
- graphein.ppi.graph_metadata.add_string_biogrid_metadata(G: Graph, kwargs: dict[str, str | int]) Graph[source]¶
Adds interaction dataframe from STRING and BIOGRID to graph.
Node Features¶
Functions for adding nodes features to a PPI Graph.
Visualisation¶
Contains utilities for plotting PPI NetworkX graphs.
- graphein.ppi.visualisation.get_edge_trace(g: Graph, edge_colours: list[str] | None = None) list[Scatter][source]¶
Gets edge traces from PPI graph. Returns a list of traces enabling edge colours to be set individually.
- Parameters:
g (nx.Graph) – _description_
- Returns:
_description_
- Return type:
List[go.Scatter]
- graphein.ppi.visualisation.get_node_trace(g: Graph, node_size_multiplier: float, node_colourscale: str = 'Viridis') Scatter[source]¶
Produces the node trace for the plotly plot.
- Parameters:
- Returns:
Node trace for plotly plot
- Return type:
go.Scatter
- graphein.ppi.visualisation.plot_ppi_graph(g: Graph, colour_edges_by: str = 'kind', with_labels: bool = True, **kwargs)[source]¶
Plots a Protein-Protein Interaction Graph. Colours edges by kind.
- Parameters:
g (nx.Graph) – NetworkX graph of PPI network.
colour_edges_by – Colour edges by this attribute. Currently, only supports ‘kind’, which colours edges by the source database, by default “kind”
with_labels (bool, optional) – Whether to show labels on nodes. Defaults to True.
- graphein.ppi.visualisation.plotly_ppi_graph(g: Graph, layout: <module 'networkx.drawing.layout' from '/home/runner/work/graphein/graphein/.venv/lib/python3.12/site-packages/networkx/drawing/layout.py'> = <function circular_layout>, title: str | None = None, show_labels: bool = False, node_size_multiplier: float = 5.0, node_colourscale: str = 'Viridis', edge_colours: list[str] | None = None, edge_opacity: float = 0.5, height: int = 500, width: int = 500)[source]¶
Plots a PPI graph.
- Parameters:
g (nx.Graph) – PPI graph
layout (nx.layout) – Layout algorithm to use. Default is circular_layout.
title (str, optional) – Title of the graph. Default is None.
show_labels (bool) – If True, shows labels on nodes. Default is False.
node_size_multiplier (float) – Multiplier for node size. Default is 5.0.
node_colourscale (str) – Colour scale to use for node colours. Default is “Viridis”. Options: ‘Greys’ | ‘YlGnBu’ | ‘Greens’ | ‘YlOrRd’ | ‘Bluered’ | ‘RdBu’ | ‘Reds’ | ‘Blues’ | ‘Picnic’ | ‘Rainbow’ | ‘Portland’ | ‘Jet’ | ‘Hot’ | ‘Blackbody’ | ‘Earth’ | ‘Electric’ | ‘Viridis’ |
edge_colours (List[str], optional) – List of colours (hexcode) to use for edges. Default is None (px.colours.qualitative.T10).
edge_opacity (float) – Opacity of edges. Default is 0.5.
height (int) – Height of the plot. Default is 500.
width (int) – Width of the plot. Default is 500.
- Returns:
Plotly figure of PPI Network
- Return type:
go.Figure
Database Parsers¶
BioGrid¶
Functions for making and parsing API calls to BIOGRID.
- graphein.ppi.parse_biogrid.BIOGRID_df(protein_list: list[str], ncbi_taxon_id: int | str | list[int] | list[str], **kwargs) DataFrame[source]¶
Generates standardised DataFrame with BIOGRID protein-protein interactions, filtered according to user’s input.
- Parameters:
protein_list (List[str]) – List of proteins (official symbol) that will be included in the PPI graph.
ncbi_taxon_id (int) – NCBI taxonomy identifiers for the organism.
9606corresponds to Homo Sapiens.kwargs (Union[int, str, List[int], List[str]]) – Additional parameters to pass to BIOGRID API calls.
- Returns:
Standardised DataFrame with BIOGRID interactions.
- Return type:
pd.DataFrame
- graphein.ppi.parse_biogrid.filter_BIOGRID(df: DataFrame, **kwargs) DataFrame[source]¶
Filters results of the BIOGRID API call according to user kwargs.
- Parameters:
df (pd.DataFrame) – Source specific Pandas DataFrame (BIOGRID) with results of the API call.
kwargs (Dict[str, Union[str, int, List[str], List[int]]]) – User thresholds used to filter the results. The parameter names are of the form
"BIOGRID_<param>", where<param>is the name of the parameter. All the parameters are numerical values.
- Returns:
Source specific Pandas DataFrame with filtered results.
- Return type:
pd.DataFrame
- graphein.ppi.parse_biogrid.params_BIOGRID(params: dict[str, str | int | list[str] | list[int]], **kwargs) dict[str, str | int][source]¶
Updates default parameters with user parameters for the method “interactions” of the BIOGRID API REST.
See also https://wiki.thebiogrid.org/doku.php/biogridrest :param params: Dictionary of default parameters :type params: Dict[str, Union[str, int, List[str], List[int]]] :param kwargs: User parameters for the method “network” of the BIOGRID API
REST. The key must start with “BIOGRID”
- graphein.ppi.parse_biogrid.parse_BIOGRID(protein_list: list[str], ncbi_taxon_id: int | str | list[int] | list[str], paginate: bool = True, **kwargs) DataFrame[source]¶
Makes BIOGRID API call and returns a source specific Pandas dataframe.
See also [1] BIOGRID: https://wiki.thebiogrid.org/doku.php/biogridrest :param protein_list: Proteins to include in the graph :type protein_list: List[str] :param ncbi_taxon_id: NCBI taxonomy identifiers for the organism.
Default is
9606(Homo Sapiens).- Parameters:
paginate (bool) – boolean indicating whether to paginate the calls (for BIOGRID, the maximum number of rows per call is
10000).Defaults toTrue.kwargs (Dict[str, Union[str, int, List[str], List[int]]]) – Parameters of the “interactions” method of the BIOGRID API REST, used to select the results. The parameter names are of the form
"BIOGRID_<param>", where<param>is the name of the parameter. Information about these parameters can be found at [1].
- Returns:
Source specific Pandas dataframe.
- Return type:
pd.DataFrame
STRINGDB¶
Functions for making and parsing API calls to STRINGdb.
- graphein.ppi.parse_stringdb.STRING_df(protein_list: list[str], ncbi_taxon_id: int | str | list[int] | list[str], **kwargs) DataFrame[source]¶
Generates standardised DataFrame with STRING protein-protein interactions, filtered according to user’s input.
- Parameters:
- Returns:
Standardised DataFrame with STRING interactions
- Return type:
pd.DataFrame
- graphein.ppi.parse_stringdb.filter_STRING(df: DataFrame, **kwargs) DataFrame[source]¶
Filters results of the STRING API call according to user kwargs, keeping rows where the input parameters are greater or equal than the input thresholds.
- Parameters:
df (pd.DataFrame) – Source specific Pandas DataFrame (STRING) with results of the API call
kwargs (Dict[str, Union[str, int, List[str], List[int]]]) – User thresholds used to filter the results. The parameter names are of the form
"STRING_<param>", where<param>is the name of the parameter. All the parameters are numerical values.
- Returns:
Source specific Pandas DataFrame with filtered results
- Return type:
pd.DataFrame
- graphein.ppi.parse_stringdb.params_STRING(params: dict[str, str | int | list[str] | list[int]], **kwargs) dict[str, str | int][source]¶
Updates default parameters with user parameters for the method “network” of the STRING API REST. See also https://string-db.org/help/api/
- Parameters:
- Returns:
Dictionary of parameters.
- Return type:
- graphein.ppi.parse_stringdb.parse_STRING(protein_list: list[str], ncbi_taxon_id: int | str | list[int] | list[str], **kwargs) DataFrame[source]¶
Makes STRING API call and returns a source specific Pandas DataFrame. See also [1] STRING: https://string-db.org/help/api/
- Parameters:
protein_list (List[str]) – Proteins to include in the graph
ncbi_taxon_id (int) – NCBI taxonomy identifiers for the organism. Default is
9606(Homo Sapiens).kwargs (Dict[str, Union[str, int, List[str], List[int]]]) – Parameters of the “network” method of the STRING API REST, used to select the results. The parameter names are of the form
"STRING_<param>", where<param>is the name of the parameter. Information about these parameters can be found at [1].
- Returns:
Source specific Pandas DataFrame.
- Return type:
pd.DataFrame