anndata - Annotated data#
anndata is a Python package for handling annotated data matrices in memory and on disk, positioned between pandas and xarray. anndata offers a broad range of computationally efficient features including, among others, sparse data support, lazy operations, and a PyTorch interface.
Discuss development on GitHub.
Read the documentation.
Ask questions on the scverse Discourse.
Install via
pip install anndata
orconda install anndata -c conda-forge
.See Scanpy’s documentation for usage related to single cell data. anndata was initially built for Scanpy.
anndata is part of the scverse project (website, governance) and is fiscally sponsored by NumFOCUS. Please consider making a tax-deductible donation to help the project pay for developer time, professional services, travel, workshops, and a variety of other needs.
![](https://raw.githubusercontent.com/numfocus/templates/master/images/numfocus-logo.png)
Citation#
If you use anndata
in your work, please cite the anndata
pre-print as follows:
anndata: Annotated data
Isaac Virshup, Sergei Rybakov, Fabian J. Theis, Philipp Angerer, F. Alexander Wolf
bioRxiv 2021 Dec 19. doi: 10.1101/2021.12.16.473007.
You can cite the scverse publication as follows:
The scverse project provides a computational ecosystem for single-cell omics data analysis
Isaac Virshup, Danila Bredikhin, Lukas Heumos, Giovanni Palla, Gregor Sturm, Adam Gayoso, Ilia Kats, Mikaela Koutrouli, Scverse Community, Bonnie Berger, Dana Pe’er, Aviv Regev, Sarah A. Teichmann, Francesca Finotello, F. Alexander Wolf, Nir Yosef, Oliver Stegle & Fabian J. Theis
Nat Biotechnol. 2023 Apr 10. doi: 10.1038/s41587-023-01733-8.
Latest additions#
Version 0.10#
0.10.7 2024-04-09#
Bugfix
Handle upstream
numcodecs
bug where read-only string arrays cannot be encoded @ivirshup #1421Use in-memory sparse matrix directly to fix compatibility with
scipy
1.13
@ilan-gold #1435
Documentation
Performance
Remove
vindex
for subsettingdask.array.Array
because of its slowness and memory consumption @ilan-gold #1432
0.10.6 2024-03-11#
Bugfix
Defer import of zarr in test helpers, as scanpy CI job relies on them #1343 @ilan-gold
Writing a dataframe with non-unique column names now throws an error, instead of silently overwriting #1335 @ivirshup
Bring optimization from #1233 to indexing on the whole
AnnData
object, not just the sparse dataset itself #1365 @ilan-goldFix mean slice length checking to use improved performance when indexing backed sparse matrices with boolean masks along their major axis #1366 @ilan-gold
Fixed overflow occurring when writing dask arrays with sparse chunks by always writing dask arrays with 64 bit indptr and indices, and adding an overflow check to
.append
method of sparse on disk structures #1348 @ivirshupModified
ValueError
message for invalid.X
during construction to show more helpful list instead of ambiguous__name__
#1395 @eroellPin
array-api-compat!=1.5
to avoid incorrect implementation ofasarray
#1411 @ivirshup
Documentation
Development
0.10.5 2024-01-25#
Bugfix
Fix outer concatenation along variables when only a subset of objects had an entry in layers #1291 @ivirshup
Fix comparison of >2d arrays in
uns
during concatenation #1300 @ivirshupFix bug (introduced in 0.10.4) where indexing an AnnData with
list[bool]
would return the wrong result #1332 @ivirshup
Documentation
Re-add search-as-you-type, this time via
readthedocs-sphinx-search
#1311 @flying-sheep
Performance
BaseCompressedSparseDataset
’sindptr
is cached #1266 @ilan-goldImproved performance when indexing backed sparse matrices with boolean masks along their major axis #1233 @ilan-gold
0.10.4 2024-01-04#
Bugfix
Only try to use
Categorical.map(na_action=…)
in actually supported Pandas ≥2.1 #1226 @flying-sheepAnnData.__sizeof__()
support for backed datasets #1230 @Neah-Koadata[:, []]
now returns anAnnData
object empty on the appropriate dimensions instead of erroring #1243 @ilan-goldadata.X[mask]
works in newernumpy
versions whenX
isbacked
#1255 @ilan-goldadata.X[...]
fixed forX
as aBaseCompressedSparseDataset
withzarr
backend #1265 @ilan-goldImprove read/write error reporting #1273 @flying-sheep
Documentation
Improve aligned mapping error messages #1252 @flying-sheep
0.10.3 2023-10-31#
Bugfix
Prevent pandas from causing infinite recursion when setting a slice of a categorical column #1211 @flying-sheep
Documentation
Stop showing “Support for Awkward Arrays is currently experimental” warnings when reading, concatenating, slicing, or transposing AnnData objects #1182 @flying-sheep
Other updates
Fail canary CI job when tests raise unexpected warnings. #1182 @flying-sheep
0.10.2 2023-10-11#
Bugfix
Added compatibility layer for packages relying on
anndata._core.sparse_dataset.SparseDataset
. Note that this API is deprecated and new code should useCSRDataset
,CSCDataset
, andsparse_dataset()
instead. #1185 @ivirshupHandle deprecation warning from
pd.Categorical.map
thrown duringanndata.concat
#1189 @flying-sheep @ivirshupFixed extra steps being included in IO tracebacks #1193 @flying-sheep
as_dense
argument ofwrite_h5ad
no longer writes an array without encoding metadata #1193 @flying-sheep
Performance
Improved performance of
concat_on_disk
with dense arrays in some cases #1169 @selmanozleyen
0.10.1 2023-10-08#
Bugfix
0.10.0 2023-10-06#
Features
GPU Support
Dense and sparse
CuPy
arrays are now supported #1066 @ivirshupOnce you have
CuPy
arrays in your anndata, use it with:rapids-singlecell
from v0.9+
anndata now has GPU enabled CI. Made possibly by a grant from CZI’s EOSS program and managed via Cirun #1066 #1084 @Zethson @ivirshup
Out of core
Concatenate on-disk anndata objects with
anndata.experimental.concat_on_disk()
#955 @selmanozleyenAnnData can now hold dask arrays with
scipy.sparse.spmatrix
chunks #1114 @ivirshupPublic API for interacting with on disk sparse arrays:
sparse_dataset()
,CSRDataset
, andCSCDataset
#765 @ilan-gold @ivirshupImproved performance for simple slices of OOC sparse arrays #1131 @ivirshup
Improved errors and warnings
Improved error messages when combining dataframes with duplicated column names #1029 @ivirshup
Improved warnings when modifying views of
AlingedMappings
#1016 @flying-sheep @ivirshupAnnDataReadError
s have been removed. The original error is now thrown with additional information in a note #1055 @ivirshup
Documentation
Added zarr examples to file format docs #1162 @ivirshup
Breaking changes
anndata.AnnData.transpose()
no longer copies unnecessarily. If you rely on the copying behavior, call.copy
on the resulting object. #1114 @ivirshup
Other updates
Bump minimum python version to 3.9 #1117 @flying-sheep
Deprecations
Deprecate
anndata.read
, which was just an alias foranndata.read_h5ad()
#1108 @ivirshup.dtype
argument toAnnData
constructor is now deprecated #1153 @ivirshup
Bug fixes
Fix shape inference on initialization when
X=None
is specified #1121 @flying-sheep
See Release notes for more.
News#
Muon paper published 2022-02-02#
Muon has been published in Genome Biology [^cite_bredikhin22].
Muon is a framework for multimodal data built on top of AnnData
.
COVID-19 datasets distributed as h5ad
2020-04-01#
In a joint initiative, the Wellcome Sanger Institute, the Human Cell Atlas, and the CZI distribute datasets related to COVID-19 via anndata’s h5ad
files: covid19cellatlas.org.