singlecellexperiment package

Subpackages

Submodules

singlecellexperiment.SingleCellExperiment module

class singlecellexperiment.SingleCellExperiment.SingleCellExperiment(assays=None, row_ranges=None, row_data=None, column_data=None, row_names=None, column_names=None, metadata=None, reduced_dimensions=None, reduced_dims=None, main_experiment_name=None, alternative_experiments=None, row_pairs=None, column_pairs=None, alternative_experiment_check_dim_names=True, validate=True, **kwargs)[source]

Bases: RangedSummarizedExperiment

Container class for single-cell experiments, extending RangedSummarizedExperiment to provide slots for embeddings and alternative experiments that share the same cells.

In contrast to R, ndarray or scipy matrices are unnamed and do not contain rownames and colnames. Hence, these matrices cannot be directly used as values in assays or alternative experiments. We strictly enforce type checks in these cases.

To relax these restrictions for alternative experiments, set type_check_alternative_experiments to False.

If you are using the alternative experiment slot, the number of cells must match the parent experiment. Otherwise, these cells do not share the same sample or annotations and cannot be set in alternative experiments!

Note: Validation checks do not apply to row_pairs or column_pairs.

__copy__()[source]
Returns:

A shallow copy of the current SingleCellExperiment.

__deepcopy__(memo=None, _nil=[])[source]
Returns:

A deep copy of the current SingleCellExperiment.

__init__(assays=None, row_ranges=None, row_data=None, column_data=None, row_names=None, column_names=None, metadata=None, reduced_dimensions=None, reduced_dims=None, main_experiment_name=None, alternative_experiments=None, row_pairs=None, column_pairs=None, alternative_experiment_check_dim_names=True, validate=True, **kwargs)[source]

Initialize a single-cell experiment.

Parameters:

  • assays (Dict[str, Any]) –

    A dictionary containing matrices, with assay names as keys and 2-dimensional matrices represented as either ndarray or spmatrix.

    Alternatively, you may use any 2-dimensional matrix that has the shape property and implements the slice operation using the __getitem__ dunder method.

    All matrices in assays must be 2-dimensional and have the same shape (number of rows, number of columns).

  • row_ranges (Union[GenomicRanges, GenomicRangesList, None]) – Genomic features, must be the same length as the number of rows of the matrices in assays.

  • row_data (Optional[BiocFrame]) –

    Features, must be the same length as the number of rows of the matrices in assays.

    Feature information is coerced to a BiocFrame. Defaults to None.

  • column_data (Optional[BiocFrame]) –

    Sample data, must be the same length as the number of columns of the matrices in assays.

    Sample information is coerced to a BiocFrame. Defaults to None.

  • row_names (Optional[List[str]]) – A list of strings, same as the number of rows.Defaults to None.

  • column_names (Optional[List[str]]) – A list of string, same as the number of columns. Defaults to None.

  • metadata (Optional[dict]) – Additional experimental metadata describing the methods. Defaults to None.

  • reduced_dimensions (Optional[Dict[str, Any]]) –

    Slot for low-dimensionality embeddings.

    Usually a dictionary with the embedding method as keys (e.g., t-SNE, UMAP) and the dimensions as values.

    Embeddings may be represented as a matrix or a data frame, must contain a shape.

  • reduced_dims (Optional[Dict[str, Any]]) – Will be deprecated in the future versions. Use py:attr:~reduced_dimensions instead.

  • main_experiment_name (Optional[str]) – A string, specifying the main experiment name.

  • alternative_experiments (Optional[Dict[str, Any]]) –

    Used to manage multi-modal experiments performed on the same sample/cells.

    Alternative experiments must contain the same cells (rows) as the primary experiment. It’s a dictionary with keys as the names of the alternative experiments (e.g., sc-atac, crispr) and values as subclasses of SummarizedExperiment.

  • alternative_experiment_check_dim_names (bool) –

    Whether to check if the column names of the alternative experiment match the column names of the main experiment. This is the equivalent to the withDimnames parameter in the R implementation.

    Defaults to True.

  • row_pairs (Optional[Any]) –

    Row pairings/relationships between features.

    Defaults to None.

  • column_pairs (Optional[Any]) –

    Column pairings/relationships between cells.

    Defaults to None.

  • validate (bool) – Internal use only.

  • kwargs – Additional arguments.

__repr__()[source]
Return type:

str

Returns:

A string representation.

alternative_experiment(name)[source]

Alias for get_alternative_experiment(), for back-compatibility.

Return type:

Any

property alternative_experiment_names: List[str]

Alias for get_alternative_experiment_names().

property alternative_experiments: Dict[str, Any]

Alias for get_alternative_experiments().

property column_pair_names: List[str]

Alias for get_column_pair_names().

property column_pairs: Dict[str, Any]

Alias for get_column_pairs().

combine_columns(*other)[source]

Wrapper around combine_columns().

Return type:

SingleCellExperiment

combine_rows(*other)[source]

Wrapper around combine_rows().

Return type:

SingleCellExperiment

copy()[source]

Alias for __copy__().

classmethod from_anndata(input)[source]

Create a SingleCellExperiment from AnnData.

Args:
input:

Input data.

Return type:

SingleCellExperiment

Returns:

A SingleCellExperiment object. If the input contains any data in the uns attribute, the metadata slot of the SingleCellExperiment will contain a key uns.

get_alternative_experiment(name, with_dim_names=True)[source]

Access alternative experiment by name.

Parameters:

  • name (Union[str, int]) – Name or index position of the alternative experiment.

  • with_dim_names (bool) –

    Whether to replace the column names of the alternative experiment with the column names of the main experiment. This is the equivalent to the withDimnames parameter in the R implementation.

    Defaults to True.

Raises:

  • AttributeError – If the dimension name does not exist.

  • IndexError – If index is greater than the number of reduced dimensions.

Return type:

Any

Returns:

The alternative experiment.

get_alternative_experiment_names()[source]

Access alternative experiment names.

Return type:

List[str]

Returns:

List of alternative experiment names.

get_alternative_experiments(with_dim_names=True)[source]

Access alternative experiments.

Parameters:

with_dim_names (bool) –

Whether to replace the column names of the alternative experiment with the column names of the main experiment. This is the equivalent to the withDimnames parameter in the R implementation.

Defaults to True.

Return type:

Dict[str, Any]

Returns:

A dictionary with experiment names as keys and value the alternative experiment.

get_column_pair_names()[source]

Access column pair names.

Return type:

List[str]

Returns:

List of column pair names.

get_column_pairs()[source]

Access column pairings/relationships between cells.

Return type:

Dict[str, Any]

Returns:

Access column pairs.

get_main_experiment_name()[source]

Access main experiment name.

Return type:

Optional[str]

Returns:

Name if available, otherwise None.

get_reduced_dim_names()[source]

Alias for get_reduced_dimension_names(), for back-compatibility.

Return type:

Dict[str, Any]

get_reduced_dimension(name)[source]

Access an embedding by name.

Parameters:

name (Union[str, int]) – Name or index position of the reduced dimension.

Raises:

  • AttributeError – If the dimension name does not exist.

  • IndexError – If index is greater than the number of reduced dimensions.

Return type:

Any

Returns:

The embedding.

get_reduced_dimension_names()[source]

Access reduced dimension names.

Return type:

List[str]

Returns:

List of reduced dimensionality names.

get_reduced_dimensions()[source]

Access dimensionality embeddings.

Return type:

Dict[str, Any]

Returns:

A dictionary with keys as names of embedding method and value the embedding.

get_reduced_dims()[source]

Alias for get_reduced_dimensions(), for back-compatibility.

Return type:

Dict[str, Any]

get_row_pair_names()[source]

Access row pair names.

Return type:

List[str]

Returns:

List of row pair names.

get_row_pairs()[source]

Access row pairings/relationships between features.

Return type:

Dict[str, Any]

Returns:

Access row pairs.

get_slice(rows, columns)[source]

Alias for __getitem__.

Return type:

SingleCellExperiment

property main_experiment_name: str | None

Alias for get_main_experiment_name().

reduced_dim(name)[source]

Alias for get_reduced_dimension(), for back-compatibility.

Return type:

Any

property reduced_dim_names: List[str]

Alias for get_reduced_dimension_names().

reduced_dimension(name)[source]

Alias for get_reduced_dimension(), for back-compatibility.

Return type:

Any

property reduced_dimension_names: List[str]

Alias for get_reduced_dimension_names().

property reduced_dimensions: Dict[str, Any]

Alias for get_reduced_dimensions().

property reduced_dims: Dict[str, Any]

Alias for get_reduced_dimensions().

relaxed_combine_columns(*other)[source]

Wrapper around relaxed_combine_columns().

Return type:

SingleCellExperiment

relaxed_combine_rows(*other)[source]

Wrapper around relaxed_combine_rows().

Return type:

SingleCellExperiment

property row_pair_names: List[str]

Alias for get_row_pair_names().

property row_pairs: Dict[str, Any]

Alias for get_row_pairs().

set_alternative_experiment(name, alternative_experiment, with_dim_names=True, in_place=False)[source]

Add or replace alternative_experiment’s.

Parameters:

  • name (str) – New or existing alternative experiment name.

  • alternative_experiment (Any) – Alternative experiments must contain the same cells (rows) as the primary experiment. Is a subclasses of SummarizedExperiment.

  • with_dim_names (bool) –

    Whether to check if the column names of the alternative experiment match the column names of the main experiment. This is the equivalent to the withDimnames parameter in the R implementation.

    Defaults to True.

  • in_place (bool) – Whether to modify the SingleCellExperiment in place.

Return type:

SingleCellExperiment

Returns:

A modified BasSingleCellExperimenteSE object, either as a copy of the original or as a reference to the (in-place-modified) original.

set_alternative_experiment_names(names, in_place=False)[source]

Replace alternative_experiment’s names.

Parameters:

  • names (List[str]) – New alternative experiment names.

  • in_place (bool) – Whether to modify the SingleCellExperiment in place.

Return type:

SingleCellExperiment

Returns:

A modified SingleCellExperiment object, either as a copy of the original or as a reference to the (in-place-modified) original.

set_alternative_experiments(alternative_experiments, with_dim_names=True, in_place=False)[source]

Set new alternative experiments.

Parameters:

  • alternative_experiments (Dict[str, Any]) – New alternative experiments.

  • with_dim_names (bool) –

    Whether to check if the column names of the alternative experiment match the column names of the main experiment. This is the equivalent to the withDimnames parameter in the R implementation.

    Defaults to True.

  • in_place (bool) – Whether to modify the SingleCellExperiment in place.

Return type:

SingleCellExperiment

Returns:

A modified SingleCellExperiment object, either as a copy of the original or as a reference to the (in-place-modified) original.

set_column_pair_names(names, in_place=False)[source]

Replace column_pair’s names.

Parameters:

  • names (List[str]) – New names.

  • in_place (bool) – Whether to modify the SingleCellExperiment in place.

Return type:

SingleCellExperiment

Returns:

A modified SingleCellExperiment object, either as a copy of the original or as a reference to the (in-place-modified) original.

set_column_pairs(pairs, in_place=False)[source]

Replace column_pairs’s names.

Parameters:

  • names – New column pairs.

  • in_place (bool) – Whether to modify the SingleCellExperiment in place.

Return type:

SingleCellExperiment

Returns:

A modified SingleCellExperiment object, either as a copy of the original or as a reference to the (in-place-modified) original.

set_main_experiment_name(name, in_place=False)[source]

Set new experiment data (assays).

Parameters:

  • name (Optional[str]) – New main experiment name.

  • in_place (bool) – Whether to modify the SingleCellExperiment in place.

Return type:

SingleCellExperiment

Returns:

A modified SingleCellExperiment object, either as a copy of the original or as a reference to the (in-place-modified) original.

set_reduced_dim_names(names, in_place=False)[source]

Alias for set_reduced_dimension_names(), for back-compatibility.

Return type:

SingleCellExperiment

set_reduced_dimension(name, embedding, in_place=False)[source]

Add or replace reduced_dimension’s.

Parameters:

  • name (str) – New or existing embedding or dimension name.

  • embedding (Any) – Embeddings may be represented as a matrix or a data frame, must contain a shape.

  • in_place (bool) – Whether to modify the SingleCellExperiment in place.

Return type:

SingleCellExperiment

Returns:

A modified SingleCellExperiment object, either as a copy of the original or as a reference to the (in-place-modified) original.

set_reduced_dimension_names(names, in_place=False)[source]

Replace reduced_dims’s names.

Parameters:

  • names (List[str]) – New dimensionality names.

  • in_place (bool) – Whether to modify the SingleCellExperiment in place.

Return type:

SingleCellExperiment

Returns:

A modified SingleCellExperiment object, either as a copy of the original or as a reference to the (in-place-modified) original.

set_reduced_dimensions(reduced_dims, in_place=False)[source]

Set new reduced dimensions.

Parameters:

  • reduced_dims (Dict[str, Any]) – New embeddings.

  • in_place (bool) – Whether to modify the SingleCellExperiment in place.

Return type:

SingleCellExperiment

Returns:

A modified SingleCellExperiment object, either as a copy of the original or as a reference to the (in-place-modified) original.

set_reduced_dims(reduced_dims, in_place=False)[source]

Alias for set_reduced_dimensions(), for back-compatibility.

Return type:

SingleCellExperiment

set_row_pair_names(names, in_place=False)[source]

Replace row_pair’s names.

Parameters:

  • names (List[str]) – New names.

  • in_place (bool) – Whether to modify the SingleCellExperiment in place.

Return type:

SingleCellExperiment

Returns:

A modified SingleCellExperiment object, either as a copy of the original or as a reference to the (in-place-modified) original.

set_row_pairs(pairs, in_place=False)[source]

Replace row_pairs’s names.

Parameters:

  • names – New row pairs.

  • in_place (bool) – Whether to modify the SingleCellExperiment in place.

Return type:

SingleCellExperiment

Returns:

A modified SingleCellExperiment object, either as a copy of the original or as a reference to the (in-place-modified) original.

to_anndata(include_alternative_experiments=False)[source]

Transform SingleCellExperiment-like into a AnnData representation.

Parameters:

include_alternative_experiments (bool) – Whether to transform alternative experiments.

Returns:

A tuple with AnnData main experiment and a list of alternative experiments.

to_mudata()[source]

Transform SingleCellExperiment object into MuData representation.

If main_experiment_name is None, this experiment is called Unknown Modality in the MuData object.

Returns:

A MuData object.

singlecellexperiment.SingleCellExperiment.combine_columns(*x)[source]

Combine multiple SingleCellExperiment objects by column.

All assays must contain the same assay names. If you need a flexible combine operation, checkout relaxed_combine_columns().

Return type:

SingleCellExperiment

Returns:

A combined SingleCellExperiment.

singlecellexperiment.SingleCellExperiment.combine_rows(*x)[source]

Combine multiple SingleCellExperiment objects by row.

All assays must contain the same assay names. If you need a flexible combine operation, checkout relaxed_combine_rows().

Return type:

SingleCellExperiment

Returns:

A combined SingleCellExperiment.

singlecellexperiment.SingleCellExperiment.relaxed_combine_columns(*x)[source]

A relaxed version of the combine_columns() method for SingleCellExperiment objects. Whereas combine_columns expects that all objects have the same rows, relaxed_combine_columns allows for different rows. Absent columns in any object are filled in with appropriate placeholder values before combining.

Parameters:

x (SingleCellExperiment) – One or more SingleCellExperiment objects, possibly with differences in the number and identity of their rows.

Return type:

SingleCellExperiment

Returns:

A SingleCellExperiment that combines all experiments along their columns and contains the union of all rows. Rows absent in any x are filled in with placeholders consisting of Nones or masked NumPy values.

singlecellexperiment.SingleCellExperiment.relaxed_combine_rows(*x)[source]

A relaxed version of the combine_rows() method for SingleCellExperiment objects. Whereas combine_rows expects that all objects have the same columns, relaxed_combine_rows allows for different columns. Absent columns in any object are filled in with appropriate placeholder values before combining.

Parameters:

x (SingleCellExperiment) – One or more SingleCellExperiment objects, possibly with differences in the number and identity of their columns.

Return type:

SingleCellExperiment

Returns:

A SingleCellExperiment that combines all experiments along their rows and contains the union of all columns. Columns absent in any x are filled in with placeholders consisting of Nones or masked NumPy values.

Module contents