pertpy.tools.Scgen

pertpy.tools.Scgen#

class Scgen(adata, n_hidden=800, n_latent=100, n_layers=2, dropout_rate=0.2, **model_kwargs)[source]#

JAX implementation of scGen for batch removal and perturbation prediction.

The latent space supports vector arithmetic: the difference between the latent means of a stimulated and a control population, added to unperturbed cells of another cell type, predicts that cell type’s response.

Attributes table#

batch_key

adata.obs column holding the condition or batch.

is_trained

Whether train() has been run.

labels_key

adata.obs column holding the cell type.

Methods table#

batch_removal([adata])

Removes batch effects.

get_decoded_expression([adata, indices, ...])

Get decoded expression.

get_latent_representation([adata, indices, ...])

Return the latent representation for each cell.

load(dir_path[, adata])

Load a model saved with save().

plot_binary_classifier(scgen, adata, delta, ...)

Plots the dot product between delta and latent representation of a linear classifier.

plot_reg_mean_plot(adata, condition_key, ...)

Plots mean matching for a set of specified genes.

plot_reg_var_plot(adata, condition_key, ...)

Plots variance matching for a set of specified genes.

predict([ctrl_key, stim_key, ...])

Predicts the cell type provided by the user in stimulated condition.

save(dir_path, *[, overwrite, save_anndata])

Save the trained model to a directory.

setup_anndata(adata[, batch_key, ...])

Register the fields that scGen reads from adata.

train(*[, max_epochs, batch_size, ...])

Train the model.

Attributes#

Scgen.batch_key#

adata.obs column holding the condition or batch.

Scgen.is_trained#

Whether train() has been run.

Scgen.labels_key#

adata.obs column holding the cell type.

Methods#

Scgen.batch_removal(adata=None)[source]#

Removes batch effects.

Parameters:

adata (AnnData | None, default: None) – AnnData object with equivalent structure to initial AnnData. If None, defaults to the AnnData object used to initialize the model. Must have been setup with batch_key and labels_key, corresponding to batch and cell type metadata, respectively.

Return type:

AnnData

Returns:

A corrected ~anndata.AnnData object. AnnData of corrected gene expression in adata.X and corrected latent space in adata.obsm[“latent”]. A reference to the original AnnData is in corrected.raw if the input adata had no raw attribute.

Examples

>>> import pertpy as pt
>>> data = pt.dt.kang_2018()
>>> pt.tl.Scgen.setup_anndata(data, batch_key="label", labels_key="cell_type")
>>> model = pt.tl.Scgen(data)
>>> model.train(max_epochs=10, batch_size=64, early_stopping=True, early_stopping_patience=5)
>>> corrected_adata = model.batch_removal()
Scgen.get_decoded_expression(adata=None, indices=None, batch_size=1024, *, seed=0)[source]#

Get decoded expression.

Parameters:

  • adata (AnnData | None, default: None) – AnnData with the same variables as the AnnData the model was initialized with. If None, that AnnData is used.

  • indices (Sequence[int] | None, default: None) – Indices of cells to use. If None, all cells are used.

  • batch_size (int, default: 1024) – Minibatch size used while decoding.

  • seed (int, default: 0) – Seed for the latent sampling.

Return type:

ndarray

Returns:

Decoded expression for each cell.

Examples

>>> import pertpy as pt
>>> data = pt.dt.kang_2018()
>>> pt.tl.Scgen.setup_anndata(data, batch_key="label", labels_key="cell_type")
>>> model = pt.tl.Scgen(data)
>>> model.train(max_epochs=10, batch_size=64, early_stopping=True, early_stopping_patience=5)
>>> decoded_X = model.get_decoded_expression()
Scgen.get_latent_representation(adata=None, indices=None, give_mean=True, n_samples=1, batch_size=1024, *, seed=0)[source]#

Return the latent representation for each cell.

Parameters:

  • adata (AnnData | ndarray | None, default: None) – AnnData with the same variables as the AnnData the model was initialized with. If None, that AnnData is used. A dense expression matrix is also accepted.

  • indices (Sequence[int] | None, default: None) – Indices of cells to use. If None, all cells are used.

  • give_mean (bool, default: True) – Whether to return the mean of the latent distribution rather than a sample.

  • n_samples (int, default: 1) – Number of latent samples to draw when give_mean is False.

  • batch_size (int, default: 1024) – Minibatch size used while encoding.

  • seed (int, default: 0) – Seed for the latent sampling.

Return type:

ndarray

Returns:

Low-dimensional representation for each cell.

Examples

>>> import pertpy as pt
>>> data = pt.dt.kang_2018()
>>> pt.tl.Scgen.setup_anndata(data, batch_key="label", labels_key="cell_type")
>>> model = pt.tl.Scgen(data)
>>> model.train(max_epochs=10, batch_size=64, early_stopping=True, early_stopping_patience=5)
>>> latent_X = model.get_latent_representation()
classmethod Scgen.load(dir_path, adata=None)[source]#

Load a model saved with save().

Parameters:

  • dir_path (str | Path) – Directory written by save().

  • adata (AnnData | None, default: None) – AnnData to attach to the model. Required unless the model was saved with save_anndata=True.

Return type:

Scgen

Returns:

The loaded model.

Examples

>>> import pertpy as pt
>>> model = pt.tl.Scgen.load("scgen_model")
Scgen.plot_binary_classifier(scgen, adata, delta, ctrl_key, stim_key, *, fontsize=14, return_fig=False)[source]#

Plots the dot product between delta and latent representation of a linear classifier.

Builds a linear classifier based on the dot product between the difference vector and the latent representation of each cell and plots the dot product results between delta and latent representation.

Parameters:

  • scgen (Scgen) – ScGen object that was trained.

  • adata (AnnData | None) – AnnData object with equivalent structure to initial AnnData. If None, defaults to the AnnData object used to initialize the model. Must have been set up with batch_key and labels_key, corresponding to batch and cell type metadata, respectively.

  • delta (ndarray) – Difference between stimulated and control cells in latent space

  • ctrl_key (str) – Key for control part of the data found in condition_key.

  • stim_key (str) – Key for stimulated part of the data found in condition_key.

  • fontsize (float, default: 14) – Set the font size of the plot.

  • 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.

Scgen.plot_reg_mean_plot(adata, condition_key, axis_keys, labels, *, gene_list=None, top_100_genes=None, verbose=False, legend=True, title=None, x_coeff=0.3, y_coeff=0.8, fontsize=14, show=False, save=None, **kwargs)[source]#

Plots mean matching for a set of specified genes.

Parameters:

  • adata – AnnData object with equivalent structure to initial AnnData. If None, defaults to the AnnData object used to initialize the model. Must have been setup with batch_key and labels_key, corresponding to batch and cell type metadata, respectively.

  • condition_key (str) – The key for the condition

  • axis_keys (dict[str, str]) – Dictionary of adata.obs keys that are used by the axes of the plot. Has to be in the following form: {x: Key for x-axis, y: Key for y-axis}.

  • labels (dict[str, str]) – Dictionary of axes labels of the form {x: x-axis-name, y: y-axis name}.

  • gene_list (list[str] | None, default: None) – list of gene names to be plotted.

  • top_100_genes (list[str] | None, default: None) – List of the top 100 differentially expressed genes. Specify if you want the top 100 DEGs to be assessed extra.

  • verbose (bool, default: False) – Specify if you want information to be printed while creating the plot.

  • legend (bool, default: True) – Whether to plot a legend.

  • title (str | None, default: None) – Set if you want the plot to display a title.

  • x_coeff (float, default: 0.3) – Offset to print the R^2 value in x-direction.

  • y_coeff (float, default: 0.8) – Offset to print the R^2 value in y-direction.

  • fontsize (float, default: 14) – Fontsize used for text in the plot.

  • show (bool, default: False) – if True, will show to the plot after saving it.

  • save (str | bool | None, default: None) – Specify if the plot should be saved or not.

  • **kwargs

Return type:

tuple[float, float] | float

Returns:

Returns R^2 value for all genes and R^2 value for top 100 DEGs if top_100_genes is not None.

Examples

>>> import pertpy as pt
>>> data = pt.dt.kang_2018()
>>> pt.tl.Scgen.setup_anndata(data, batch_key="label", labels_key="cell_type")
>>> scg = pt.tl.Scgen(data)
>>> scg.train(max_epochs=10, batch_size=64, early_stopping=True, early_stopping_patience=5)
>>> pred, delta = scg.predict(ctrl_key='ctrl', stim_key='stim', celltype_to_predict='CD4 T cells')
>>> pred.obs['label'] = 'pred'
>>> eval_adata = data[data.obs['cell_type'] == 'CD4 T cells'].copy().concatenate(pred)
>>> r2_value = scg.plot_reg_mean_plot(eval_adata, condition_key='label', axis_keys={"x": "pred", "y": "stim"},                 labels={"x": "predicted", "y": "ground truth"}, save=False, show=True)
Preview:
../../_images/scgen_reg_mean.png
Scgen.plot_reg_var_plot(adata, condition_key, axis_keys, labels, *, gene_list=None, top_100_genes=None, legend=True, title=None, verbose=False, x_coeff=0.3, y_coeff=0.8, fontsize=14, show=True, save=None, **kwargs)[source]#

Plots variance matching for a set of specified genes.

Parameters:

  • adata – AnnData object with equivalent structure to initial AnnData. If None, defaults to the AnnData object used to initialize the model. Must have been setup with batch_key and labels_key, corresponding to batch and cell type metadata, respectively.

  • condition_key (str) – Key of the condition.

  • axis_keys (dict[str, str]) – Dictionary of adata.obs keys that are used by the axes of the plot. Has to be in the following form: {“x”: “Key for x-axis”, “y”: “Key for y-axis”}.

  • labels (dict[str, str]) – Dictionary of axes labels of the form {“x”: “x-axis-name”, “y”: “y-axis name”}.

  • gene_list (list[str] | None, default: None) – list of gene names to be plotted.

  • top_100_genes (list[str] | None, default: None) – List of the top 100 differentially expressed genes. Specify if you want the top 100 DEGs to be assessed extra.

  • legend (bool, default: True) – Whether to plot a legend.

  • title (str | None, default: None) – Set if you want the plot to display a title.

  • verbose (bool, default: False) – Specify if you want information to be printed while creating the plot.

  • x_coeff (float, default: 0.3) – Offset to print the R^2 value in x-direction.

  • y_coeff (float, default: 0.8) – Offset to print the R^2 value in y-direction.

  • fontsize (float, default: 14) – Fontsize used for text in the plot.

  • show (bool, default: True) – if True, will show to the plot after saving it.

  • save (str | bool | None, default: None) – Specify if the plot should be saved or not.

Return type:

tuple[float, float] | float

Scgen.predict(ctrl_key=None, stim_key=None, adata_to_predict=None, celltype_to_predict=None, restrict_arithmetic_to='all')[source]#

Predicts the cell type provided by the user in stimulated condition.

Parameters:

  • ctrl_key (default: None) – Key for control part of the data found in condition_key.

  • stim_key (default: None) – Key for stimulated part of the data found in condition_key.

  • adata_to_predict (default: None) – Adata for unperturbed cells you want to be predicted.

  • celltype_to_predict (default: None) – The cell type you want to be predicted.

  • restrict_arithmetic_to (default: 'all') – Dictionary of celltypes you want to be observed for prediction.

Return type:

tuple[AnnData, Any]

Returns:

numpy.ndarray of predicted cells in primary space.

delta: float

Difference between stimulated and control cells in latent space

Examples

>>> import pertpy as pt
>>> data = pt.dt.kang_2018()
>>> pt.tl.Scgen.setup_anndata(data, batch_key="label", labels_key="cell_type")
>>> model = pt.tl.Scgen(data)
>>> model.train(max_epochs=10, batch_size=64, early_stopping=True, early_stopping_patience=5)
>>> pred, delta = model.predict(ctrl_key="ctrl", stim_key="stim", celltype_to_predict="CD4 T cells")
Scgen.save(dir_path, *, overwrite=False, save_anndata=False)[source]#

Save the trained model to a directory.

Parameters:

  • dir_path (str | Path) – Directory to write to.

  • overwrite (bool, default: False) – Whether to overwrite an existing directory.

  • save_anndata (bool, default: False) – Whether to also write the AnnData the model was trained on.

Return type:

None

Examples

>>> import pertpy as pt
>>> data = pt.dt.kang_2018()
>>> pt.tl.Scgen.setup_anndata(data, batch_key="label", labels_key="cell_type")
>>> model = pt.tl.Scgen(data)
>>> model.train(max_epochs=10)
>>> model.save("scgen_model")
classmethod Scgen.setup_anndata(adata, batch_key=None, labels_key=None, layer=None)[source]#

Register the fields that scGen reads from adata.

scGen expects log-normalized expression in adata.X or in layer.

Parameters:

  • adata (AnnData) – AnnData to register. Modified in place.

  • batch_key (str | None, default: None) – adata.obs column holding the condition or batch. If None, a constant column is added, which leaves nothing for batch_removal() to correct.

  • labels_key (str | None, default: None) – adata.obs column holding the cell type. If None, a constant column is added.

  • layer (str | None, default: None) – adata.layers key holding the expression to model. If None, adata.X is used.

Return type:

None

Examples

>>> import pertpy as pt
>>> data = pt.dt.kang_2018()
>>> pt.tl.Scgen.setup_anndata(data, batch_key="label", labels_key="cell_type")
Scgen.train(*, max_epochs=None, batch_size=128, train_size=0.9, validation_size=None, shuffle_set_split=True, early_stopping=False, early_stopping_patience=45, early_stopping_min_delta=0.0, lr=0.001, weight_decay=1e-06, eps=0.01, max_norm=None, seed=0)[source]#

Train the model.

Parameters:

  • max_epochs (int | None, default: None) – Passes over the training set. Defaults to min(round((20000 / n_cells) * 400), 400).

  • batch_size (int, default: 128) – Minibatch size.

  • train_size (float, default: 0.9) – Fraction of cells used for training.

  • validation_size (float | None, default: None) – Fraction of cells used for validation. Defaults to everything not used for training.

  • shuffle_set_split (bool, default: True) – Whether to shuffle before splitting rather than splitting sequentially.

  • early_stopping (bool, default: False) – Whether to stop once the validation loss stops improving.

  • early_stopping_patience (int, default: 45) – Epochs without improvement before stopping.

  • early_stopping_min_delta (float, default: 0.0) – Minimum improvement that counts as progress.

  • lr (float, default: 0.001) – Adam learning rate.

  • weight_decay (float, default: 1e-06) – Decoupled weight decay.

  • eps (float, default: 0.01) – Adam epsilon.

  • max_norm (float | None, default: None) – Global gradient norm to clip to.

  • seed (int, default: 0) – Seed for the split, the minibatch shuffling and the model initialization.

Return type:

None

Examples

>>> import pertpy as pt
>>> data = pt.dt.kang_2018()
>>> pt.tl.Scgen.setup_anndata(data, batch_key="label", labels_key="cell_type")
>>> model = pt.tl.Scgen(data)
>>> model.train(max_epochs=10, batch_size=64, early_stopping=True, early_stopping_patience=5)