TRANSPIRE API

TRANSPIRE.data

TRANSPIRE.data.import_data.add_markers(df_, markers_)

Append organelle marker localization information to a dataframe.

Parameters:

• df (pd.DataFrame) – Pandas dataframe formatted for TRANSPIRE analysis
• markers (Union(str, pd.DataFrame)) – String referring to an organelle marker set in external data or a custom set of markers loaded as a pd.DataFrame or pd.Series with an “accession” and “localization” column specifying organelle marker Uniprot accession numbers and their corresponding subcellular localization.

Returns:

a copy of the original input dataframe with organelle localizations appended as an additional index level

Return type:

df(pd.DataFrame)

TRANSPIRE.data.import_data.load_CORUM()

Load core CORUM complexes

Parameters:None – Returns:DataFrame representation of CORUM core complexes information prot_to_complex (pd.Series): Series for mapping Uniprot accession numbers to their corresponding CORUM complex IDs complex_to_prot (pd.Series): Series for mapping CORUM complex IDs the corresponding Uniprot accession numbers of their subunits Return type:corum (pd.DataFrame)

TRANSPIRE.data.import_data.load_data(f)

Load a dataset for analysis.

Parameters:f (str) – absolute file path for Excel, .csv, or .txt data file Returns:MultiIndex dataframe (index and columns are both MultiIndexes) Return type:df (pd.DataFrame) Raises:ValueError – Error is raised when the target file formatting does not match what is required by TRANSPIRE for proper analysis.

TRANSPIRE.data.import_data.load_organelle_markers(marker_set_name, df=None)

Load an organelle marker set from TRANSPIRE.data.external.organelle_markers

Parameters:

• marker_set_name (str) – Name of marker set to load
• df (pd.DataFrame, optional) – DataFrame to coerce into proper formatting for TRANSPIRE

Returns:

Marker set loaded as a pd.Series with index and value pairs referring to protein accession number and associated subcellular localization

Return type:

markers (pd.Series)

Raises:

ValueError – If marker_set_name is not a valid marker set in TRANSPIRE.data.external.organelle_markers

TRANSPIRE.data.import_data.load_predictions(f)

Load TRANSPIRE predictions from a filepath

Parameters:f (str) – valid filepath to .csv or .zip file Returns:DataFrame loaded from filepath Return type:df (pd.DataFrame)

TRANSPIRE.data.generate_translocations.make_translocations(df, comparisons, synthetic=True)

Generate synthetic translocations between organelles using pre-defined organelle marker proteins or simply generate concatenated protein profiles across the specified comparisons.

Parameters:

• df (pd.DataFrame) – Pandas dataframe properly formatted for TRANSPIRE analysis
• comparisons (Union(list, np.array)) – Pairwise combinations of conditions to make translocations between (list or array of tuples, e.g. [(‘control’, ‘treatment_1’), (‘control’, ‘treatment_2’), (‘control’, ‘treatment_3’)])
• synthetic (bool) – Whether or not to generate synthetic translocation profiles using organelle marker proteins. If False, this function will just return concatenated profiles for all samples accross the provided comparisons

Returns:

Dataframe with concatenated profiles.

Return type:

df_concatenated (pd.DataFrame)

TRANSPIRE.training

class TRANSPIRE.training.ProgressTracker(m, X, y)

Object to keep track of model fitting progress.

Can optionally be used to create a custom callback object that will plot the progress of model fitting.

m

SVGP model

Type:gpflow.models.SVGP

X

values used to evaluate the model

Type:np.ndarray

y

encoded target class labels of each sample in X

Type:np.ndarray

elbo

list of ELBO values after each ProgressTracker.update call

Type:list

acc

accuracy values after each ProgressTracker.update call

Type:list

update()

Update the tracking object based on the current parameters of m

Parameters:None – Returns:None

TRANSPIRE.training.build_model(X, y, **model_params)

Build a GPFlow SVGP classifier.

Parameters:

• X (np.ndarray) – training data (n x m)
• y (np.ndarray) – encoded training data labels (n x 1)
• model_params (dict) – Key, value pairs of model parameters to be passed to gpflow.models.SVGP. Parameters not specified in the dictionary will be chosen from default settings.

Returns:

GPFlow SVGP model built with the defined model parameters

Return type:

m (gpflow.models.SVGP)

TRANSPIRE.training.compute_inducing(X, n_induce)

Compute inducing points using the K-means approach

Parameters:

• X (Union(pd.DataFrame, np.ndarray)) – input data to be fit by the K-means algorithm
• n_induce (int) – number of inducing points to return (i.e. the number of clusters to be fit by K-means)

Returns:

array of inducing points as determined by K-means clustering of the input data (e.g. the K-means-defined cluster centers)

Return type:

Z_induce (np.ndarray)

TRANSPIRE.performance

TRANSPIRE.performance.compute_cutoff(fprs, level, i)

Compute score cutoff based on desired false-positive rate stringency

Parameters:

• fprs (pd.DataFrame) – calculated false-positive rates (DataFrame columns should correspond to translocation scores)
• level (list) – list of multindex levels to groupby (e.g. conditions, folds, etc.)
• i (float) – fpr cutoff between 0 and 1

Returns:

corresponding score cutoffs for each set of levels as defined by the ‘level’ grouping

Return type:

cutoffs (pd.Series)

TRANSPIRE.performance.compute_fpr(x, n=100)

Compute false-positive rates for translocation score cutoffs

Parameters:

• x (pd.DataFrame) – DataFrame including ‘translocation score’ and ‘true label’ columns (as produced by TRANSPIRE.utils.map_binary)
• n (int, optional) – number of bins to split the translocation scores into

Returns:

false-positive rates for different translocation score cutoffs given the true binary labels

Return type:

fpr (pd.Series)

TRANSPIRE.performance.eval_report(means, mapping, mapping_r)

Compute an array of model performance metrics given mean classifer scores across all possible prediction classes

Computed metrics include binary and multi-class log-loss, macro F1 scores, micro F1 scores, and weighted F1 scores.

Parameters:

• means (pd.DataFrame) – DataFrame of classifer scores across each possible class
• mapping (pd.Series) – Mapping generator used to encode class labels
• mapping_r (pd.Series) – Mapping genrator used to decode class labels

Returns:

DataFrame of computed metrics

Return type:

results (pd.DataFrame)

TRANSPIRE.cotranslocation

class TRANSPIRE.cotranslocation.GetSTRINGInteractions

Retrieve known interactions from the STRING database using their REST API

None

get_interactions(IDs, species)

Query STRING database for known interactions between proteins

Parameters:

• IDs (Union(list, np.ndarray)) – StringIDs for query proteins
• species (str) – Taxonomic identifier for the given protein species (e.g. ‘9606’ for Homo Sapiens)

Returns:

known interactions between proteins as well as their corresponding STRING data (evidence scores, etc.)

Return type:

df (pd.DataFrame)

map_identifiers_string(proteins, species)

Use STRING’s API to retrive the corresponding STRING identifiers for each protein

Parameters:

• proteins (Union(list, np.ndarray)) – Uniprot protein accessions to be mapped to StringIDs
• species (str) – Taxonomic identifier for the given protein species (e.g. ‘9606’ for Homo Sapiens)

Returns:

Uniprot accessions mapped to their corresponding StringIDs

Return type:

df (pd.DataFrame)

query(proteins, species, score_cutoff)

Perform a STRING database query on a given set of protein accession numbers.

This is a simple wrapper combining several GetSTRINGInteractions methods that returns at DataFrame of known interactions between the input proteins.

Parameters:

• proteins (np.ndarray) – Uniprot accession numbers for proteins to query for known interactions
• species (str) – Taxonomic identifier for the given protein species (e.g. ‘9606’ for Homo Sapiens)
• score_cutoff (float) – STRING score cutoff for the returned iteractions

Returns:

Known iteractions bewteen the input proteins

Return type:

interactions (pd.DataFrame)

to_query_string(mylist, sep)

Convert a list to a string that can be used as a query string in an http post request

Parameters:

• mylist (list) – list of values
• sep (str) – separator for concatentating the values

Returns:

items in mylist concatenated into a single string

Return type:

l (str)

TRANSPIRE.cotranslocation.compute_distance(X)

Compute the Mahalanobis distance between pairwise combinations of all samples in X.

Parameters:X (pd.DataFrame) – DataFrame with spatial profile data Returns:All pairwise distances between samples. The index from X will become the index and columns for this DataFrame. Return type:dists (pd.DataFrame)

Note that this function will calculate pairwise distances for all combinations of samples in the index (e.g. it returns an n x n DataFrame, which can become quite large depending on the input data)

TRANSPIRE.cotranslocation.compute_fpr(x, y)

Compute false positive rates using x (true positive) and y (true negative) for values ranging between min(x.min(), y.min()) and max(x.max(), y.max())

Parameters:

• x (pd.Series) – True postive pairwise distances
• y (pd.Series) – True negative pariwise distances

Returns:

false positive rates for an array of distances ranging from min(x.min(), y.min()) to max(x.max(), y.max())

Return type:

fpr (pd.Series)

TRANSPIRE.cotranslocation.extract_true_neg(dists, df)

Extract pairwise distances between markers for distinct subcellular organelles as a true negative metric for determining cotranslocation

Parameters:

• dists (pd.Series) – Pairwise distances between proteins; must have ‘accession_A’ and ‘accession_B’ index levels
• df (pd.DataFrame) – Protein profiles DataFrame formatted for TRANSPIRE (e.g. with ‘accession’, ‘gene name’ and ‘localization’ index levels)

Returns:

subset of dists corresponding to distances between markers of distinct subcellular organelles

Return type:

dists (pd.Series)

Raises:

• AssertionError – If dists is not a pd.Series
• AssertionError – If ‘accession_A’ or ‘accession_B’ are not levels in the index

TRANSPIRE.cotranslocation.extract_true_pos(dists, complex_to_prot, prot_to_complex)

Extract pairwise distances between CORUM complex proteins as a true positive metric for determining cotranslocation

Parameters:

• dists (pd.Series) – Pairwise distances between proteins; must have ‘accession_A’ and ‘accession_B’ index levels
• prot_to_complex (pd.Series) – Series for mapping Uniprot accession numbers to their corresponding CORUM complex IDs (as returned by TRANSPIRE.data.import_data.load_CORUM)
• complex_to_prot (pd.Series) – Series for mapping CORUM complex IDs the corresponding Uniprot accession numbers of their subunits (as returned by TRANSPIRE.data.import_data.load_CORUM)

Returns:

subset of dists corresponding to distances between members of CORUM complex members

Return type:

corum_dists (pd.Series)

Raises:

• AssertionError – If dists is not a pd.Series
• AssertionError – If ‘accession_A’ or ‘accession_B’ are not levels in the index

TRANSPIRE.go_enrichment

class TRANSPIRE.go_enrichment.GOAnalyzer(background_proteins, species='9606', alpha=0.05, method='fdr_bh')

Wrapper to make analysis with GOATOOLS less complex

The GOAnalyzer class creates a GOEnrichmentStudyNS object that can be used to run consecutive enrichment studies using the same background gene list.

IDs

ncbi_geneIDs for the input background proteins

Type:pd.DataFrame

alpha

significance cutoff for enrichment analyses

Type:float

obodag

GO Dag stored as a dict

Type:dict

species

species ID for the given analysis (e.g. ‘9606’ for homo sapiens)

Type:str

study

GOEnrichmentStudyNS object used for running enrichment studies

Type:goatools.goea.go_enrichment_ns.GOEnrichmentStudyNS

get_enrichment(query_proteins, return_all=False)

Perform an enrichment analysis on the query_proteins

Parameters:

• query_proteins (Union(list, np.ndarray)) – List of protein accession numbers assess for functional enrichment
• return_all (bool, optional) – If False (default), return only significantly-enriched GO terms (e.g. adj p-value <= GOAnalyzer.alpha). Otherwise, if True, return all associated GO terms (including those that are not significant)

Returns:

Results from GO enrichment analysis.

Return type:

results (pd.DataFrame)

slim(GO_terms, return_all=False)

Leverages GOATOOLS map_to_slim function to map GO terms to their GO-slim counterparts

Parameters:

• GO_terms (Union(list, np.ndarray)) – GO accession numbers to be mapped to slim terms
• return_all (bool, optional) – Whether to return all, recusively-associated GO-slim terms for each given GO term (True) or only return direct descendents (False)

Returns:

Dict pairs of GO accession (key) and its associated list of GO-slim terms (value)

Return type:

result (dict)

TRANSPIRE.visualization

TRANSPIRE.utils

TRANSPIRE.utils.get_mapping(df)

Get label encodings for translocation classes based on the “localization” level of the dataframe

Parameters:df (pd.DataFrame) – dataframe with a “localization” index level Returns:Translocation labels mapped to integers mapping_r(pd.Series): Integers mapped back to translocation labels Return type:mapping (pd.Series)

TRANSPIRE.utils.group_organelles(df_, mapping)

Group together organelles based on a defined mapping pattern.

Parameters:

• df (pd.DataFrame) – Pandas dataframe properly formatted for TRANSPIRE analysis. Must contain a “localization” index level.
• mapping (dict) – dict of values defining how to combine organelles.

Returns:

Copy of the inuput dataframe with the “localization” index level mapped according to mapping

Return type:

df

Note that organelles not found in mapping, but defined in the “localization” index level will retain their original value.

TRANSPIRE.utils.lookup(string, df, level)

Find rows in dataframe that correspond to a search term.

Parameters:

• string (str) – String to search for
• df (pd.DataFrame) – Dataframe to search within
• level (str) – level of index to search for string (e.g. ‘accession’, ‘gene name’, etc)

Returns:

rows of the dataframe containing the given search term in their index

Return type:

df (pd.DataFrame)

TRANSPIRE.utils.map_binary(x, mapping)

Map scores to their binary translocation score representation

Parameters:

• x (pd.DataFrame) – scores to be mapped via mapping
• mapping (pd.Series) – mapping that defines how to map encoded columns in x back to their translocation labels as strings

Returns:

Dataframe with the same index as x, with the mapped translocation scores. If the input dataframe also has a “label” index level, the returned dataframe will also have a “true label” column corresponding to the label mapped to its binary representation.

Return type:

df (pd.DataFrame)

TRANSPIRE.utils.sample_balanced(X, n_limit, n_folds, random_state=17)

Take class-balanced subsets of data from an input dataframe (based on the “label” index level)

Parameters:

• X (pd.DataFrame) – Pandas dataframe properly formatted for TRANSPIRE analysis. Must contain a “label” index level. Most commonly, this would be a dataframe containing synthetic translocations generated by TRANSPIRE
• n_limit (int) – The maximum number of samples to take from any one class
• n_folds (int) – The number of different balanced folds to generate
• random_state (int, optional) – random state to be passed to sklearn.model_selection.StratifiedKFold and pd.DataFrame.sample

Returns:

Dataframe with an additional “fold” level appended to the index. This dataframe consists of n_folds of the input data, stratified such that any one fold does not have more than n_limit members of a given “label”.

Return type:

X_train_dfs (pd.DataFrame)

Note that the returned folds of data will overlap for any classes (ie. labels) where the number of members is < n_folds*n_limit.

TRANSPIRE.utils.train_test_validate_split(X, groupby_levels, f_train=0.5, f_validate=0.25, f_test=0.25, random_state=17)

Split input dataframe into training, validation, and testing partitions, stratified by a set of index levels.

Parameters:

• X (pd.DataFrame) – data to be split into partitions as defined by f_train, f_validate, and f_test
• groupby_levels (list) – which levels to groupby when taking stratified samples
• f_train (float, optional) – fraction of the data to be used for training
• f_validate (float, optional) – fraction of the data to be used for validation
• f_test (float, optional) – fraction of the data to be used for testing (i.e. to evaluate predictive performance)
• random_state (int, optional) – random state to be passed pd.DataFrame.sample

Returns:

stratified data to be used for model training X_validate_df (pd.DataFrame): stratified data to be used for validation X_test_df (pd.DataFrame): stratified data for testing

Return type:

X_train_df (pd.DataFrame)

Raises:

ValueError – If the sum of f_train, f_validate, and f_test does not equal 1

TRANSPIRE.utils.uniprot_mapping_service(proteins, to)

Use the Uniprot REST ID mapping service.

Parameters:

• proteins (Union[list, np.array]) – values to be mapped (e.g. Uniprot accession numbers)
• to (str) – type of mapping to be accomplished as defined by Uniprot standards

Returns:

Dataframe with accession numbers (as index) mapped to their corresponding values

Return type:

df (pd.DataFrame)