anndict.adata_dict.write_adata_dict

anndict.adata_dict.write_adata_dict(adata_dict, directory, *, file_prefix='')

Save each AnnData object from an AdataDict into a separate .h5ad file, creating a directory structure that reflects the hierarchy of the AdataDict using key values as directory names. The hierarchy and structure are saved in files called adata_dict.hierarchy.json and adata_dict.db.json, which are used internally by AnnDictionary.

Parameters:

adata_dict AdataDict

An AdataDict.

directory str

Base directory where .h5ad files will be saved.

file_prefix str (default: '')

Optional prefix for the filenames.

Return type:

None

Notes

Each element in the key tuple becomes a subdirectory, ensuring the directory hierarchy matches the AdataDict’s hierarchy precisely. The filename itself is <file_prefix> + key_elements_joined_by_underscores.h5ad.

Examples

Case 1: Flat hierarchy

adata_dict.set_hierarchy(["Donor", "Tissue"])
print(adata_dict)
> {
>     ("Donor1", "Tissue1"): adata_d1_t1,
>     ("Donor1", "Tissue2"): adata_d1_t2,
>     ("Donor2", "Tissue1"): adata_d2_t1,
> }

The files will be saved as:

directory/
├── adata_dict.hierarchy.json
├── adata_dict.db.json
├── <file_prefix>Donor1_Tissue1.h5ad
├── <file_prefix>Donor1_Tissue2.h5ad
└── <file_prefix>Donor2_Tissue1.h5ad

Case 2: Nested hierarchy

adata_dict.set_hierarchy(["Donor", ["Tissue"]])
print(adata_dict)
> {
>     ("Donor1",): {
>         ("Tissue1",): adata_d1_t1,
>         ("Tissue2",): adata_d1_t2,
>     },
>     ("Donor2",): {
>         ("Tissue1",): adata_d2_t1,
>     },
> }

The files will be saved as:

directory/
├── adata_dict.hierarchy.json
├── adata_dict.db.json
├── Donor1/
│   ├── <file_prefix>Tissue1.h5ad
│   └── <file_prefix>Tissue2.h5ad
└── Donor2/
    └── <file_prefix>Tissue1.h5ad

Case 3: Nested hierarchy with multiple indices at the deepest level

adata_dict.set_hierarchy(["Donor", ["Tissue", "Cell Type"]])
print(adata_dict)
> {
>     ("Donor1",): {
>         ("Tissue1", "CellType1"): adata_d1_t1_c1,
>         ("Tissue1", "CellType2"): adata_d1_t1_c2,
>         ("Tissue2", "CellType3"): adata_d1_t2_c3,
>     },
>     ("Donor2",): {
>         ("Tissue1", "CellType1"): adata_d2_t1_c1,
>     },
> }

The files will be saved as:

directory/
├── adata_dict.hierarchy.json
├── adata_dict.db.json
├── Donor1/
│   ├── <file_prefix>Tissue1_CellType1.h5ad
│   ├── <file_prefix>Tissue1_CellType2.h5ad
│   └── <file_prefix>Tissue2_CellType3.h5ad
└── Donor2/
    └── <file_prefix>Tissue1_CellType1.h5ad