pertpy.tools.MLPClassifierSpace#

class MLPClassifierSpace[source]#

Fits an ANN classifier to the data and takes the feature space (weights in the last layer) as embedding.

We train the ANN to classify the different perturbations. After training, the penultimate layer is used as the feature space, resulting in one embedding per cell. Consider employing the PseudoBulk or another PerturbationSpace to obtain one embedding per perturbation.

See here https://www.ncbi.nlm.nih.gov/pmc/articles/PMC7289078/ (Dose-response analysis) and Sup 17-19.

Methods table#

add(adata, *, perturbations[, ...])

Add perturbations linearly.

compute(adata, *[, target_col, layer_key, ...])

Creates a perturbation embedding by training a MLP classifier model to distinguish between perturbations.

compute_control_diff(adata, *[, target_col, ...])

Subtract mean of the control from the perturbation.

dose_response(adata, *[, target_col, ...])

Quantify the effect size of each perturbation as a function of dose.

evaluate_combinations(adata, *[, ...])

Score how well an additive model predicts combination perturbations.

fit_dose_response(adata[, response, ...])

Fit a four-parameter Hill curve for each perturbation.

label_transfer(adata, *[, target_column, ...])

Impute missing values in the specified column using KNN imputation in the space defined by use_rep.

nearest_perturbations(adata, perturbation, *)

Rank perturbations by their proximity to a query perturbation in a perturbation space.

plot_dose_response(adata[, response, ...])

Plot the measured responses and fitted Hill curves of each perturbation.

plot_similarity(adata, *[, target_col, ...])

Plot a clustered heatmap of pairwise distances between perturbations.

subtract(adata, *, perturbations[, ...])

Subtract perturbations linearly.

Methods#

add(adata, *, perturbations, reference_key='control', ensure_consistency=True, target_col='perturbation')#

Add perturbations linearly. Assumes input of size n_perts x dimensionality.

Parameters:
adata AnnData

Anndata object of size n_perts x dim.

perturbations Iterable[str]

Perturbations to add.

reference_key str, default: 'control'

perturbation source from which the perturbation summation starts.

ensure_consistency bool, default: True

If True, differentiate against control via compute_control_diff before combining so that “perturbation - perturbation == control” holds in the resulting space. Set False only if the input has already been differenced.

target_col str, default: 'perturbation'

.obs column name that stores the label of the perturbation applied to each cell.

Return type:

tuple[AnnData, AnnData] | AnnData

Returns:

Anndata object of size (n_perts+1) x dim, where the last row is the addition of the specified perturbations. If ensure_consistency is True, returns a tuple of (new_perturbation, adata) where adata is the AnnData object provided as input but updated using compute_control_diff.

Examples

Example usage with PseudobulkSpace:

>>> import pertpy as pt
>>> mdata = pt.ds.papalexi_2021()
>>> ps = pt.tl.PseudobulkSpace()
>>> ps_adata = ps.compute(mdata["rna"], target_col="gene_target", groups_col="gene_target")
>>> new_perturbation = ps.add(ps_adata, perturbations=["ATF2", "CD86"], reference_key="NT")
compute(adata, *, target_col='perturbation', layer_key=None, embedding_key=None, hidden_dim=None, dropout=0.0, batch_norm=True, batch_size=128, test_split_size=0.2, validation_split_size=0.25, max_epochs=20, val_epochs_check=2, patience=2, lr=0.0001, seed=42, balance_classes=False)[source]#

Creates a perturbation embedding by training a MLP classifier model to distinguish between perturbations.

A model is created using the specified parameters (hidden_dim, dropout, batch_norm). Further parameters such as the number of classes to predict (number of perturbations) are obtained from the provided AnnData object directly. Training batches are drawn uniformly, or inversely to perturbation frequency with balance_classes. Next, the model is trained and tested, using the GPU if available. The penultimate-layer activations are extracted for every cell and averaged per perturbation, yielding one embedding per perturbation.

Parameters:
adata AnnData

AnnData object of size cells x genes

target_col str, default: 'perturbation'

.obs column that stores the label of the perturbation applied to each cell.

layer_key str | None, default: None

Layer in adata to use.

embedding_key str | None, default: None

.obsm embedding to train the classifier on. Mutually exclusive with layer_key.

hidden_dim list[int] | None, default: None

List of number of neurons in each hidden layers of the neural network. For instance, [512, 256] will create a neural network with two hidden layers, the first with 512 neurons and the second with 256 neurons.

dropout float, default: 0.0

Amount of dropout applied, constant for all layers.

batch_norm bool, default: True

Whether to apply batch normalization.

batch_size int, default: 128

The batch size, i.e. the number of datapoints to use in one forward/backward pass.

test_split_size float, default: 0.2

Fraction of data to put in the test set. Default to 0.2.

validation_split_size float, default: 0.25

Fraction of data to put in the validation set of the resultant train set. E.g. a test_split_size of 0.2 and a validation_split_size of 0.25 means that 25% of 80% of the data will be used for validation.

max_epochs int, default: 20

Maximum number of epochs for training.

val_epochs_check int, default: 2

Test performance on validation dataset after every val_epochs_check training epochs. Note that this affects early stopping, as the model will be stopped if the validation performance does not improve for patience epochs.

patience int, default: 2

Number of validation performance checks without improvement, after which the early stopping flag is activated and training is therefore stopped.

lr float, default: 0.0001

Learning rate for training.

seed int, default: 42

Random seed for reproducibility.

balance_classes bool, default: False

Whether to sample training cells inversely to the size of their perturbation, so that every perturbation is seen equally often.

Return type:

AnnData

Returns:

AnnData with one observation per perturbation, the averaged penultimate-layer embedding in .X and the perturbation labels in .obs[target_col].

Examples

>>> import pertpy as pt
>>> adata = pt.ds.norman_2019()
>>> dcs = pt.tl.MLPClassifierSpace()
>>> pert_embeddings = dcs.compute(adata, target_col="perturbation_name")
compute_control_diff(adata, *, target_col='perturbation', group_col=None, reference_key='control', layer_key=None, new_layer_key='control_diff', embedding_key=None, new_embedding_key='control_diff', all_data=False, copy=True)#

Subtract mean of the control from the perturbation.

Parameters:
adata AnnData

Anndata object of size cells x genes.

target_col str, default: 'perturbation'

.obs column name that stores the label of the perturbation applied to each cell.

group_col str | None, default: None

.obs column name that stores the label of the group of each cell. If None, ignore groups.

reference_key str, default: 'control'

The key of the control values.

layer_key str | None, default: None

Key of the AnnData layer to use for computation.

new_layer_key str, default: 'control_diff'

the results are stored in the given layer.

embedding_key str | None, default: None

obsm key of the AnnData embedding to use for computation.

new_embedding_key str, default: 'control_diff'

Results are stored in a new embedding in obsm with this key.

all_data bool, default: False

if True, do the computation in all data representations (X, all layers and all embeddings)

copy bool, default: True

If True returns a new AnnData; otherwise updates the input AnnData in place.

Return type:

AnnData

Returns:

Updated AnnData object.

Examples

Example usage with PseudobulkSpace:

>>> import pertpy as pt
>>> mdata = pt.ds.papalexi_2021()
>>> ps = pt.tl.PseudobulkSpace()
>>> diff_adata = ps.compute_control_diff(mdata["rna"], target_col="gene_target", reference_key="NT")
dose_response(adata, *, target_col='perturbation', dose_col='dose', reference_key='control', metric='edistance', layer_key=None, embedding_key=None, **kwargs)#

Quantify the effect size of each perturbation as a function of dose.

For every (perturbation, dose) group the statistical distance to reference_key is computed in the chosen representation using Distance. Operates on cell-level data, since distances are defined between groups of cells.

Parameters:
adata AnnData

Cell-level AnnData.

target_col str, default: 'perturbation'

.obs column with the perturbation label.

dose_col str, default: 'dose'

.obs column with the (numeric) dose.

reference_key str, default: 'control'

Control perturbation all doses are compared against.

metric Literal['edistance', 'euclidean', 'root_mean_squared_error', 'mse', 'mean_absolute_error', 'pearson_distance', 'spearman_distance', 'kendalltau_distance', 'cosine_distance', 'r2_distance', 'mean_pairwise', 'mmd', 'wasserstein', 'sym_kldiv', 't_test', 'ks_test', 'nb_ll', 'classifier_proba', 'classifier_cp', 'mean_var_distribution', 'mahalanobis'], default: 'edistance'

Distance metric passed to Distance.

layer_key str | None, default: None

Layer to compute distances and mean expression from.

embedding_key str | None, default: None

.obsm embedding to compute distances from.

kwargs

Passed to onesided_distances().

Return type:

AnnData

Returns:

AnnData with one observation per non-reference (perturbation, dose) group, holding the mean expression in X and the distance in .obs.

Examples

>>> import pertpy as pt
>>> adata = pt.ds.srivatsan_2020_sciplex2()
>>> ps = pt.tl.PseudobulkSpace()
>>> dose_adata = ps.dose_response(adata, dose_col="dose_value", embedding_key="X_pca")
evaluate_combinations(adata, *, combinations=None, target_col='perturbation', reference_key='control', metric='pearson', sep='+')#

Score how well an additive model predicts combination perturbations.

For every combination "A+B" whose components A and B are each present as single perturbations, the additive prediction effect(A) + effect(B) is compared against the measured combination effect, where effects are taken relative to reference_key. A small distance indicates additive, non-interacting perturbations, whereas a large deviation flags a genetic or pharmacological interaction.

Parameters:
adata AnnData

Perturbation-level AnnData indexed by perturbation (one observation per perturbation).

combinations Iterable[str] | None, default: None

Combination names to evaluate. If None, every obs_name containing sep whose components are all present as singles is used.

target_col str, default: 'perturbation'

.obs column identifying each perturbation.

reference_key str, default: 'control'

Control perturbation subtracted to obtain effects. If absent, values are used as-is.

metric Literal['pearson', 'cosine', 'euclidean'], default: 'pearson'

Distance between predicted and measured combination effects.

sep str, default: '+'

Separator between components in combination names.

Return type:

DataFrame

Returns:

DataFrame indexed by combination with distance, predicted_magnitude and measured_magnitude columns, sorted by ascending distance.

Examples

>>> import pertpy as pt
>>> adata = pt.ds.norman_2019()
>>> ps = pt.tl.PseudobulkSpace()
>>> ps_adata = ps.compute(adata, target_col="perturbation_name")
>>> scores = ps.evaluate_combinations(ps_adata, target_col="perturbation_name", reference_key="control")
fit_dose_response(adata, response='distance', *, target_col='perturbation', dose_col='dose', key_added=None, n_jobs=None)#

Fit a four-parameter Hill curve for each perturbation.

Perturbations whose curve cannot be fit get a warning and NaN parameters.

Parameters:
adata AnnData

AnnData with one observation per dose or replicate, such as the output of dose_response().

response str, default: 'distance'

.obs column or gene in var_names to fit.

target_col str, default: 'perturbation'

.obs column identifying the perturbation.

dose_col str, default: 'dose'

.obs column containing non-negative numeric doses.

key_added str | None, default: None

Prefix of the .obs columns the results are written to. Defaults to response.

n_jobs int | None, default: None

Number of jobs to distribute the perturbations over, passed to joblib.Parallel. None means one job, -1 all available cores.

Return type:

None

Returns:

Adds the fitted response and the per-perturbation e0, emax, slope, ec50, ec50_se, r_squared and ec50_in_range to .obs, prefixed with key_added.

Examples

>>> import pertpy as pt
>>> adata = pt.ds.srivatsan_2020_sciplex2()
>>> ps = pt.tl.PseudobulkSpace()
>>> dose_adata = ps.dose_response(adata, dose_col="dose_value", embedding_key="X_pca")
>>> ps.fit_dose_response(dose_adata, dose_col="dose_value")
>>> ps.fit_dose_response(dose_adata, "CDKN1A", dose_col="dose_value")
label_transfer(adata, *, target_column='perturbation', column_uncertainty_score_key='perturbation_transfer_uncertainty', target_val='unknown', neighbors_key='neighbors')#

Impute missing values in the specified column using KNN imputation in the space defined by use_rep.

Uncertainty is calculated as the entropy of the label distribution in the neighborhood of the target cell. In other words, a cell where all neighbors have the same set of labels will have an uncertainty of 0, whereas a cell where all neighbors have many different labels will have high uncertainty.

Parameters:
adata AnnData

The AnnData object containing single-cell data.

target_column str, default: 'perturbation'

The column name in adata.obs to perform imputation on.

column_uncertainty_score_key str, default: 'perturbation_transfer_uncertainty'

The column name in adata.obs to store the uncertainty score of the label transfer.

target_val str, default: 'unknown'

The target value to impute.

neighbors_key str, default: 'neighbors'

The key in adata.uns where the neighbors are stored.

Return type:

None

Examples

>>> import pertpy as pt
>>> import scanpy as sc
>>> import numpy as np
>>> adata = sc.datasets.pbmc68k_reduced()
>>> # randomly dropout 10% of the data annotations
>>> adata.obs["perturbation"] = adata.obs["louvain"].astype(str).copy()
>>> random_cells = np.random.choice(adata.obs.index, int(adata.obs.shape[0] * 0.1), replace=False)
>>> adata.obs.loc[random_cells, "perturbation"] = "unknown"
>>> sc.pp.neighbors(adata)
>>> sc.tl.umap(adata)
>>> ps = pt.tl.PseudobulkSpace()
>>> ps.label_transfer(adata)
nearest_perturbations(adata, perturbation, *, target_col='perturbation', n_neighbors=10, layer_key=None, embedding_key=None, metric='euclidean')#

Rank perturbations by their proximity to a query perturbation in a perturbation space.

Operates on a perturbation-level AnnData (one observation per perturbation), i.e. the output of any compute. Useful for discovering perturbations with a similar mechanism of action. If adata.obsp["distances"] is present (as produced by DistanceSpace) and no representation is requested explicitly, those precomputed distances are used directly.

Parameters:
adata AnnData

Perturbation-level AnnData indexed by perturbation.

perturbation str

The query perturbation to find neighbors for.

target_col str, default: 'perturbation'

.obs column identifying each perturbation.

n_neighbors int, default: 10

Number of nearest perturbations to return.

layer_key str | None, default: None

Layer to compute distances from.

embedding_key str | None, default: None

.obsm embedding to compute distances from.

metric str, default: 'euclidean'

Distance metric passed to sklearn.metrics.pairwise_distances().

Return type:

DataFrame

Returns:

DataFrame indexed by perturbation with a distance column, sorted ascending and excluding the query.

Examples

>>> import pertpy as pt
>>> adata = pt.ds.norman_2019()
>>> ps = pt.tl.PseudobulkSpace()
>>> ps_adata = ps.compute(adata, target_col="perturbation_name")
>>> neighbors = ps.nearest_perturbations(ps_adata, "CBL+CNN1", target_col="perturbation_name")
plot_dose_response(adata, response='distance', *, target_col='perturbation', dose_col='dose', key_added=None, perturbations=None, ncols=4, return_fig=False)#

Plot the measured responses and fitted Hill curves of each perturbation.

Parameters:
adata AnnData

AnnData with one observation per dose or replicate, such as the output of dose_response().

response str, default: 'distance'

.obs column or gene in var_names to plot.

target_col str, default: 'perturbation'

.obs column identifying the perturbation.

dose_col str, default: 'dose'

.obs column containing the doses.

key_added str | None, default: None

Prefix passed to fit_dose_response(). Defaults to response.

perturbations Sequence[str] | None, default: None

Perturbations to plot. Defaults to all.

ncols int, default: 4

Number of panels per row.

return_fig bool, default: False

if True, returns figure of the plot, that can be used for saving.

Return type:

Figure | None

Returns:

If return_fig is True, returns the figure, otherwise None.

Examples

>>> import pertpy as pt
>>> adata = pt.ds.srivatsan_2020_sciplex2()
>>> ps = pt.tl.PseudobulkSpace()
>>> dose_adata = ps.dose_response(adata, dose_col="dose_value", embedding_key="X_pca")
>>> ps.fit_dose_response(dose_adata, dose_col="dose_value")
>>> ps.plot_dose_response(dose_adata, dose_col="dose_value")
Preview:
../../_images/dose_response.png
plot_similarity(adata, *, target_col='perturbation', layer_key=None, embedding_key=None, metric='euclidean', cmap='viridis', **kwargs)#

Plot a clustered heatmap of pairwise distances between perturbations.

Uses adata.obsp["distances"] when present (e.g. from DistanceSpace) and otherwise computes pairwise distances in the chosen representation.

Parameters:
adata AnnData

Perturbation-level AnnData indexed by perturbation.

target_col str, default: 'perturbation'

.obs column identifying each perturbation.

layer_key str | None, default: None

Layer to compute distances from.

embedding_key str | None, default: None

.obsm embedding to compute distances from.

metric str, default: 'euclidean'

Distance metric passed to sklearn.metrics.pairwise_distances().

cmap str, default: 'viridis'

Matplotlib colormap.

kwargs

Passed to seaborn.clustermap().

Returns:

The grid returned by seaborn.clustermap().

Examples

>>> import pertpy as pt
>>> adata = pt.ds.norman_2019()
>>> ds = pt.tl.DistanceSpace()
>>> ds_adata = ds.compute(adata, target_col="perturbation_name", metric="edistance")
>>> ds.plot_similarity(ds_adata, target_col="perturbation_name")
subtract(adata, *, perturbations, reference_key='control', ensure_consistency=True, target_col='perturbation')#

Subtract perturbations linearly. Assumes input of size n_perts x dimensionality.

Parameters:
adata AnnData

Anndata object of size n_perts x dim.

perturbations Iterable[str]

Perturbations to subtract.

reference_key str, default: 'control'

Perturbation source from which the perturbation subtraction starts.

ensure_consistency bool, default: True

If True, differentiate against control via compute_control_diff before combining so that “perturbation - perturbation == control” holds in the resulting space. Set False only if the input has already been differenced.

target_col str, default: 'perturbation'

.obs column name that stores the label of the perturbation applied to each cell.

Return type:

tuple[AnnData, AnnData] | AnnData

Returns:

Anndata object of size (n_perts+1) x dim, where the last row is the subtraction of the specified perturbations. If ensure_consistency is True, returns a tuple of (new_perturbation, adata) where adata is the AnnData object provided as input but updated using compute_control_diff.

Examples

Example usage with PseudobulkSpace:

>>> import pertpy as pt
>>> mdata = pt.ds.papalexi_2021()
>>> ps = pt.tl.PseudobulkSpace()
>>> ps_adata = ps.compute(mdata["rna"], target_col="gene_target", groups_col="gene_target")
>>> new_perturbation = ps.subtract(ps_adata, reference_key="ATF2", perturbations=["BRD4", "CUL3"])