anndata.experimental.backed.Dataset2D

class anndata.experimental.backed.Dataset2D(ds)

Bases: Mapping[Hashable, XDataArray | Dataset2D]

A wrapper class meant to enable working with lazy dataframe data according to AnnData’s internal API. This class ensures that “dataframe-invariants” are respected, namely that there is only one 1d dim and coord with the same name i.e., like a pandas.DataFrame.

You should not have to initiate this class yourself. Setting an xarray.Dataset into a relevant part of the AnnData object will attempt to wrap that object in this object, trying to enforce the “dataframe-invariants.”

Because xarray requires xarray.Dataset.coords to be in-memory, this class provides handling for an out-of-memory index via true_index. This feature is helpful for loading remote data faster where the index itself may not be initially useful for constructing the object e.g., cell ids.

Attributes

columns

AnnData internally looks for columns so this ensures usability

Returns:

pandas.Index that represents the “columns.”

ds

The underlying xarray.Dataset.

dtypes

Return a Mapping with the dtypes of the variables in the Dataset2D.

iloc

AnnData internally looks for iloc so this ensures usability.

Returns:

Handler class for doing the iloc-style indexing using isel().

index

A pandas.Index object corresponding to anndata.experimental.backed.Dataset2D.index_dim.

AnnData internally looks for index so this ensures usability.

Returns:

The index of the of the dataframe as resolved from coords.

index_dim

The underlying computational index i.e., the lone coordinate dimension.

is_backed

Check whether or not the object is backed, used to indicate if there are any in-memory objects. Must be externally set, defaults false.

shape

AnnData internally looks for shape so this ensures usability.

Returns:

The (2D) shape of the dataframe resolved from sizes.

true_index

true_xr_index as a pandas.Index.

true_index_dim

Key of the “true” index.

Because xarray loads its coordinates/indexes in memory, we allow for signaling that a given variable, which is not a coordinate, is the “true” index.

For example, the true index may be cell names but loading these over an internet connection may not be desirable or necessary for most use cases such as getting a quick preview of the columns or loading only one column that isn’t the index.

This property is the key of said variable. The default is index_dim if this variable has not been set.

true_xr_index

The index AnnData is actually interested in e.g., cell names, for verification.

xr_index

The coordinate of anndata.experimental.backed.Dataset2D.index_dim

Methods

__getitem__(key)

Get a column or a subset of columns.

Overloads:

• key (Hashable) → DataArray

• key (Collection[Hashable]) → Dataset2D

Parameters:

key Mapping[Any, Any] | Hashable | Iterable[Hashable]

A column name returns that column as an xarray.DataArray, a collection of column names returns a Dataset2D with those columns. See xarray.Dataset.__getitem__() for all supported keys.

__setitem__(key, value)

Setting can only be performed when the incoming value is “standalone” like numpy.ndarray to mimic pandas. One can also use the tuple setting style like ds["foo"] = (ds.index_dim, value) to set the value, although the index name must match. Similarly, one can use the xarray.DataArray but it must have the same (one and only one) dim name/coord name as index_dim.

For supported setter values see xarray.Dataset.__setitem__().

Parameters:

key Hashable | Iterable[Hashable] | Mapping

Name of the column to set.

value object

The column’s data, as described above.

Return type:

None

copy(data=None, *, deep=False)

Return a copy of the Dataset2D object. See xarray.Dataset.copy() for more information.

Return type:

Dataset2D

equals(b)

Thin wrapper around xarray.Dataset.equals()

Return type:

bool

keys()

Return type:

KeysView[Hashable]

reindex(index=None, axis=0, fill_value=nan)

Reindex the current object against a new index.

Parameters:

index Index | None

The new index for reindexing, by default None

axis Literal[0]

Provided for API consistency, should not be called over axis!=0, by default 0

fill_value Scalar | None

The value with which to fill in via pandas.Series.reindex(), by default np.nan

Return type:

Dataset2D

Returns:

Reindexed dataset.

to_memory(*, copy=False)

Converts to pandas.DataFrame. The index of the dataframe comes from true_index_dim if it differs from index_dim.

Parameters:

copy bool

Unused argument

Return type:

DataFrame

Returns:

pandas.DataFrame with index set accordingly.