scvi.data.fields.BaseAnnDataField

class scvi.data.fields.BaseAnnDataField

Abstract class for a single AnnData/MuData field.

A Field class defines how scvi-tools will map a data field used by a model to an attribute in an AnnData/MuData object.

Attributes table

attr_key	The key of the data field within the relevant AnnData attribute.
attr_name	The name of the AnnData attribute where the data is stored.
is_empty	Returns True if the field is empty as a function of its kwargs.
mod_key	The modality key of the data field within the MuData (if applicable).
registry_key	The key that is referenced by models via a data loader.

Methods table

get_data_registry()	Returns a nested dictionary which describes the mapping to the data field.
get_field_data(adata)	Returns the requested data as determined by the field.
get_summary_stats(state_registry)	Returns a dictionary comprising of summary statistics relevant to the field.
register_field(adata)	Sets up the AnnData/MuData object and creates a mapping for scvi-tools models to use.
transfer_field(state_registry, adata_target, ...)	Takes an existing setup dictionary and transfers the same setup to the target AnnData.
validate_field(adata)	Validates whether an AnnData/MuData object is compatible with this field definition.
view_state_registry(state_registry)	Returns a rich.table.Table summarizing a state registry produced by this field.

Attributes

BaseAnnDataField.attr_key

The key of the data field within the relevant AnnData attribute.

BaseAnnDataField.attr_name

The name of the AnnData attribute where the data is stored.

BaseAnnDataField.is_empty

Returns True if the field is empty as a function of its kwargs.

A field can be empty if it is composed of a collection of variables, and for a given instance of a model, the collection is empty. If empty, the field will be omitted from the registry, but included in the summary stats dictionary.

BaseAnnDataField.mod_key

The modality key of the data field within the MuData (if applicable).

BaseAnnDataField.registry_key

The key that is referenced by models via a data loader.

Methods

BaseAnnDataField.get_data_registry()

Returns a nested dictionary which describes the mapping to the data field.

The dictionary is of the form {“mod_key”: mod_key, “attr_name”: attr_name, “attr_key”: attr_key}. This mapping is then combined with the mappings of other fields to make up the data registry.

Return type:

dict

BaseAnnDataField.get_field_data(adata)

Returns the requested data as determined by the field.

Return type:

ndarray | DataFrame

abstractmethod BaseAnnDataField.get_summary_stats(state_registry)

Returns a dictionary comprising of summary statistics relevant to the field.

Parameters:

state_registry (dict) – Dictionary returned by register_field(). Summary stats should always be a function of information stored in this dictionary.

Return type:

dict

Returns:

summary_stats_dict The dictionary is of the form {summary_stat_name: summary_stat_value}. This mapping is then combined with the mappings of other fields to make up the summary stats mapping.

abstractmethod BaseAnnDataField.register_field(adata)

Sets up the AnnData/MuData object and creates a mapping for scvi-tools models to use.

Return type:

dict

Returns:

dict A dictionary containing any additional state required for scvi-tools models not stored directly on the AnnData/MuData object.

abstractmethod BaseAnnDataField.transfer_field(state_registry, adata_target, **kwargs)

Takes an existing setup dictionary and transfers the same setup to the target AnnData.

Used when one is running a pretrained model on a new AnnData object, which requires the mapping from the original data to be applied to the new AnnData object.

Parameters:

• state_registry (dict) – state_registry dictionary created after registering an AnnData using an AnnDataManager object.

• adata_target (AnnData | MuData) – AnnData/MuData object that is being registered.

• **kwargs – Keyword arguments to modify transfer behavior.

Return type:

dict

Returns:

dict A dictionary containing any additional state required for scvi-tools models not stored directly on the AnnData object.

abstractmethod BaseAnnDataField.validate_field(adata)

Validates whether an AnnData/MuData object is compatible with this field definition.

Return type:

None

abstractmethod BaseAnnDataField.view_state_registry(state_registry)

Returns a rich.table.Table summarizing a state registry produced by this field.

Parameters:

state_registry (dict) – Dictionary returned by register_field(). Printed summary should always be a function of information stored in this dictionary.

Return type:

Table | None

Returns:

state_registry_summary Optional rich.table.Table summarizing the state_registry.