anndata 0.12.8__tar.gz → 0.12.10__tar.gz

{anndata-0.12.8 → anndata-0.12.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: anndata
-Version: 0.12.8
+Version: 0.12.10
 Summary: Annotated data.
 Project-URL: Documentation, https://anndata.readthedocs.io/
 Project-URL: Source, https://github.com/scverse/anndata
@@ -32,7 +32,7 @@ Requires-Dist: natsort
 Requires-Dist: numpy>=1.26
 Requires-Dist: packaging>=24.2
 Requires-Dist: pandas!=2.1.2,<3,>=2.1.0
-Requires-Dist: scipy>=1.12
+Requires-Dist: scipy!=1.17.0,>=1.12
 Requires-Dist: zarr!=3.0.*,>=2.18.7
 Provides-Extra: cu11
 Requires-Dist: cupy-cuda11x; extra == 'cu11'

anndata-0.12.10/docs/release-notes/0.12.10.md

@@ -0,0 +1,6 @@
+(v0.12.10)=
+### 0.12.10 {small}`2026-02-06`
+
+#### Miscellaneous changes
+
+- Add {attr}`anndata.settings.copy_on_write_X` to allow for forward-compatibility with future copy-on-write behavior (release `0.13`). Currently, setting {attr}`~anndata.AnnData.X` on a view implicitly updates the object from which the view was created. {user}`ilan-gold` ({pr}`2327`)

anndata-0.12.10/docs/release-notes/0.12.9.md

@@ -0,0 +1,6 @@
+(v0.12.9)=
+### 0.12.9 {small}`2026-01-29`
+
+#### Performance
+
+- Add a `write_csr_csc_indices_with_min_possible_dtype` option to {attr}`anndata.settings` to enable downcasting of the `indices` of csr and csc matrices to a smaller dtype when writing. For example, if your csr matrix only has 30000 columns, then you can write out the `indices` of that matrix as `uint16` instead of `int64`. {user}`ilan-gold` ({pr}`2159`)

{anndata-0.12.8 → anndata-0.12.10}/pyproject.toml

@@ -40,7 +40,7 @@ dependencies = [
     "pandas >=2.1.0, !=2.1.2, <3",
     "numpy>=1.26",
     # https://github.com/scverse/anndata/issues/1434
-    "scipy >=1.12",
+    "scipy >=1.12,!=1.17.0",
     "h5py>=3.8",
     "natsort",
     "packaging>=24.2",
@@ -163,6 +163,8 @@ filterwarnings_when_strict = [
     "default:.*FixedLengthUTF32:zarr.core.dtype.common.UnstableSpecificationWarning",
     "default:Automatic shard shape inference is experimental",
     "default:Writing zarr v2:UserWarning",
+    # TODO: Remove in conjunction with or before https://github.com/scverse/anndata/pull/1707
+    "default:.*will obey copy-on-write semantics:FutureWarning",
 ]
 python_files = [ "test_*.py" ]
 testpaths = [

{anndata-0.12.8 → anndata-0.12.10}/src/anndata/_core/anndata.py

@@ -597,8 +597,38 @@ class AnnData(metaclass=utils.DeprecationMixinMeta):  # noqa: PLW1641
         # else:
         #     return X
 
+    def _handle_view_X_cow(self, value: XDataType | None):
+        if self._is_view:
+            if settings.copy_on_write_X:
+                msg = "Setting element `.X` of view, initializing view as actual."
+                warnings.warn(msg, ImplicitModificationWarning, stacklevel=2)
+                new = self._mutated_copy(X=value)
+                self._init_as_actual(new)
+                return True
+            msg = "Setting element `.X` of view of `AnnData` object will obey copy-on-write semantics in the next minor release. "
+            "In other words, this subset of your original `AnnData` will be copied-in-place and initialized with the value passed into this setter. "
+            "Set `anndata.settings.copy_on_write_X = True` to begin opting in to this behavior."
+            warnings.warn(msg, FutureWarning, stacklevel=2)
+        return False
+
     @X.setter
     def X(self, value: XDataType | None):  # noqa: PLR0912
+        value = (
+            coerce_array(value, name="X", allow_array_like=True)
+            if value is not None
+            else None
+        )
+        can_set_direct_if_not_none = value is None or (
+            np.isscalar(value)
+            or (hasattr(value, "shape") and (self.shape == value.shape))
+            or (self.n_vars == 1 and self.n_obs == len(value))
+            or (self.n_obs == 1 and self.n_vars == len(value))
+        )
+        if not can_set_direct_if_not_none:
+            msg = f"Data matrix has wrong shape {value.shape}, need to be {self.shape}."
+            raise ValueError(msg)
+        if self._handle_view_X_cow(value):
+            return None
         if value is None:
             if self.isbacked:
                 msg = "Cannot currently remove data matrix from backed object."
@@ -607,7 +637,6 @@ class AnnData(metaclass=utils.DeprecationMixinMeta):  # noqa: PLW1641
                 self._init_as_actual(self.copy())
             self._X = None
             return
-        value = coerce_array(value, name="X", allow_array_like=True)
 
         # If indices are both arrays, we need to modify them
         # so we don’t set values like coordinates
@@ -620,67 +649,51 @@ class AnnData(metaclass=utils.DeprecationMixinMeta):  # noqa: PLW1641
             oidx, vidx = np.ix_(self._oidx, self._vidx)
         else:
             oidx, vidx = self._oidx, self._vidx
-        if (
-            np.isscalar(value)
-            or (hasattr(value, "shape") and (self.shape == value.shape))
-            or (self.n_vars == 1 and self.n_obs == len(value))
-            or (self.n_obs == 1 and self.n_vars == len(value))
-        ):
-            if not np.isscalar(value):
-                if self.is_view and any(
-                    isinstance(idx, np.ndarray)
-                    and len(np.unique(idx)) != len(idx.ravel())
-                    for idx in [oidx, vidx]
-                ):
-                    msg = (
-                        "You are attempting to set `X` to a matrix on a view which has non-unique indices. "
-                        "The resulting `adata.X` will likely not equal the value to which you set it. "
-                        "To avoid this potential issue, please make a copy of the data first. "
-                        "In the future, this operation will throw an error."
-                    )
-                    warnings.warn(msg, FutureWarning, stacklevel=1)
-                if self.shape != value.shape:
-                    # For assigning vector of values to 2d array or matrix
-                    # Not necessary for row of 2d array
-                    value = value.reshape(self.shape)
-            if self.isbacked:
-                if self.is_view:
-                    X = self.file["X"]
-                    if isinstance(X, h5py.Group):
-                        X = sparse_dataset(X)
-                    X[oidx, vidx] = value
-                else:
-                    self._set_backed("X", value)
-            elif self.is_view:
-                if sparse.issparse(self._adata_ref._X) and isinstance(
-                    value, np.ndarray
-                ):
-                    if isinstance(self._adata_ref.X, CSArray):
-                        memory_class = sparse.coo_array
-                    else:
-                        memory_class = sparse.coo_matrix
-                    value = memory_class(value)
-                elif sparse.issparse(value) and isinstance(
-                    self._adata_ref._X, np.ndarray
-                ):
-                    warnings.warn(
-                        "Trying to set a dense array with a sparse array on a view."
-                        "Densifying the sparse array."
-                        "This may incur excessive memory usage",
-                        stacklevel=2,
-                    )
-                    value = value.toarray()
-                warnings.warn(
-                    "Modifying `X` on a view results in data being overridden",
-                    ImplicitModificationWarning,
-                    stacklevel=2,
+        if not np.isscalar(value):
+            if self.is_view and any(
+                isinstance(idx, np.ndarray) and len(np.unique(idx)) != len(idx.ravel())
+                for idx in [oidx, vidx]
+            ):
+                msg = (
+                    "You are attempting to set `X` to a matrix on a view which has non-unique indices. "
+                    "The resulting `adata.X` will likely not equal the value to which you set it. "
+                    "To avoid this potential issue, please make a copy of the data first. "
+                    "In the future, this operation will throw an error."
                 )
-                self._adata_ref._X[oidx, vidx] = value
+                warnings.warn(msg, FutureWarning, stacklevel=2)
+            if self.shape != value.shape:
+                # For assigning vector of values to 2d array or matrix
+                # Not necessary for row of 2d array
+                value = value.reshape(self.shape)
+        if self.isbacked:
+            if self.is_view:
+                X = self.file["X"]
+                if isinstance(X, h5py.Group):
+                    msg = "Cannot write to views of sparse backed files"
+                    raise NotImplementedError(msg)
+                X[oidx, vidx] = value
             else:
-                self._X = value
+                self._set_backed("X", value)
+        elif self.is_view:
+            if sparse.issparse(self._adata_ref._X) and isinstance(value, np.ndarray):
+                if isinstance(self._adata_ref.X, CSArray):
+                    memory_class = sparse.coo_array
+                else:
+                    memory_class = sparse.coo_matrix
+                value = memory_class(value)
+            elif sparse.issparse(value) and isinstance(self._adata_ref._X, np.ndarray):
+                msg = (
+                    "Trying to set a dense array with a sparse array on a view. "
+                    "Densifying the sparse array. "
+                    "This may incur excessive memory usage"
+                )
+                warnings.warn(msg, UserWarning, stacklevel=2)
+                value = value.toarray()
+            msg = "Modifying `X` on a view results in data being overridden"
+            warnings.warn(msg, ImplicitModificationWarning, stacklevel=2)
+            self._adata_ref._X[oidx, vidx] = value
         else:
-            msg = f"Data matrix has wrong shape {value.shape}, need to be {self.shape}."
-            raise ValueError(msg)
+            self._X = value
 
     @X.deleter
     def X(self):
@@ -1492,8 +1505,7 @@ class AnnData(metaclass=utils.DeprecationMixinMeta):  # noqa: PLW1641
                 return self._mutated_copy(
                     X=_subset(self._adata_ref.X, (self._oidx, self._vidx)).copy()
                 )
-            else:
-                return self._mutated_copy()
+            return self._mutated_copy()
         else:
             from ..io import read_h5ad, write_h5ad
 

{anndata-0.12.8 → anndata-0.12.10}/src/anndata/_io/specs/methods.py

@@ -738,6 +738,24 @@ def write_sparse_compressed(
     for attr_name in ["data", "indices", "indptr"]:
         attr = getattr(value, attr_name)
         dtype = indptr_dtype if attr_name == "indptr" else attr.dtype
+        if (
+            attr_name == "indices"
+            and settings.write_csr_csc_indices_with_min_possible_dtype
+        ):
+            # np.min_scalar_type can return things like np.ulonglong which zarr doesn't understand
+            # and I find this clearer as to what the result type is i.e., unsigned or signed.
+            # For example `np.iinfo(np.uint16).max + 1` could be either `uint32` or `int32`,
+            # and there's nothing in numpy's docs disallowing this output to change.
+            if (minor_axis_size := value.shape[value.format == "csr"]) <= np.iinfo(
+                np.uint8
+            ).max:
+                dtype = np.dtype("uint8")
+            elif minor_axis_size <= np.iinfo(np.uint16).max:
+                dtype = np.dtype("uint16")
+            elif minor_axis_size <= np.iinfo(np.uint32).max:
+                dtype = np.dtype("uint32")
+            elif minor_axis_size <= np.iinfo(np.uint64).max:
+                dtype = np.dtype("uint64")
         if isinstance(f, H5Group) or is_zarr_v2():
             g.create_dataset(
                 attr_name, data=attr, shape=attr.shape, dtype=dtype, **dataset_kwargs

{anndata-0.12.8 → anndata-0.12.10}/src/anndata/_settings.py

@@ -503,6 +503,14 @@ settings.register(
     get_from_env=check_and_get_bool,
 )
 
+settings.register(
+    "write_csr_csc_indices_with_min_possible_dtype",
+    default_value=False,
+    description="Write a csr or csc matrix with the minimum possible data type for `indices`, always unsigned integer.",
+    validate=validate_bool,
+    get_from_env=check_and_get_bool,
+)
+
 settings.register(
     "auto_shard_zarr_v3",
     default_value=False,
@@ -512,5 +520,18 @@ settings.register(
 )
 
 
+settings.register(
+    "copy_on_write_X",
+    default_value=False,
+    description=(
+        "Whether to copy-on-write X. "
+        "Currently `my_adata_view[subset].X = value` will write back to the original AnnData object at the `subset` location. "
+        "`X` is the only element where this behavior is implemented though."
+    ),
+    validate=validate_bool,
+    get_from_env=check_and_get_bool,
+)
+
+
 ##################################################################################
 ##################################################################################

{anndata-0.12.8 → anndata-0.12.10}/src/anndata/_settings.pyi

@@ -42,10 +42,12 @@ class _AnnDataSettingsManager(SettingsManager):
     remove_unused_categories: bool = True
     check_uniqueness: bool = True
     allow_write_nullable_strings: bool = False
+    copy_on_write_X: bool = False
     zarr_write_format: Literal[2, 3] = 2
     use_sparse_array_on_read: bool = False
     min_rows_for_chunked_h5_copy: int = 1000
     disallow_forward_slash_in_h5ad: bool = False
+    write_csr_csc_indices_with_min_possible_dtype: bool = False
     auto_shard_zarr_v3: bool = False
 
 settings: _AnnDataSettingsManager

{anndata-0.12.8 → anndata-0.12.10}/tests/test_io_elementwise.py

@@ -455,6 +455,113 @@ def test_write_indptr_dtype_override(store, sparse_format):
     np.testing.assert_array_equal(store["X/indptr"][...], X.indptr)
 
 
+@pytest.mark.parametrize(
+    ("num_minor_axis", "expected_dtype"),
+    [
+        pytest.param(1, np.dtype("uint8"), id="one_col-expected_uint8_on_disk"),
+        pytest.param(
+            np.iinfo(np.uint8).max,
+            np.dtype("uint8"),
+            id="max_np.uint8-matching_dtype_on_disk",
+        ),
+        pytest.param(
+            np.iinfo(np.int8).max,
+            np.dtype("uint8"),
+            id="max_np.int8-uint8_on_disk",
+        ),
+        pytest.param(
+            np.iinfo(np.uint16).max,
+            np.dtype("uint16"),
+            id="max_np.uint16-matching_dtype_on_disk",
+        ),
+        pytest.param(
+            np.iinfo(np.int16).max,
+            np.dtype("uint16"),
+            id="max_np.int16-uint16_on_disk",
+        ),
+        pytest.param(
+            np.iinfo(np.uint32).max,
+            np.dtype("uint32"),
+            id="max_np.uint32-matching_dtype_on_disk",
+        ),
+        pytest.param(
+            np.iinfo(np.int32).max,
+            np.dtype("uint32"),
+            id="max_np.int32-uint32_on_disk",
+        ),
+        pytest.param(
+            np.iinfo(np.uint8).max + 1,
+            np.dtype("uint16"),
+            id="max_np.uint8_plus_one_cols-expected_uint16_on_disk",
+        ),
+        pytest.param(
+            np.iinfo(np.uint16).max + 1,
+            np.dtype("uint32"),
+            id="max_np.uint16_plus_one_cols-expected_uint32_on_disk",
+        ),
+        pytest.param(
+            np.iinfo(np.uint32).max + 1,
+            np.dtype("uint64"),
+            id="max_np.uint32_plus_one_cols-expected_uint64_on_disk",
+        ),
+        pytest.param(
+            np.iinfo(np.int64).max + 1,
+            np.dtype("uint64"),
+            id="max_np.int64_plus_one_cols-expected_uint64_on_disk",
+            marks=pytest.mark.xfail(
+                reason="scipy sparse does not support bigger than max(int64) values in indices and there is no uint128."
+            ),
+        ),
+        pytest.param(
+            np.iinfo(np.uint64).max + 1,
+            np.dtype("uint64"),
+            id="max_np.uint64_plus_one_cols-expected_uint64_on_disk",
+            marks=pytest.mark.xfail(
+                reason="scipy sparse does not support bigger than max(int64) values in indices and there is no uint128."
+            ),
+        ),
+    ],
+)
+@pytest.mark.parametrize("format", ["csr", "csc"])
+def test_write_indices_min(
+    store: H5Group | ZarrGroup,
+    num_minor_axis: int,
+    expected_dtype: np.dtype,
+    format: Literal["csr", "csc"],
+):
+    minor_axis_index = np.array([num_minor_axis - 1])
+    major_axis_index = np.array([10])
+    row_cols = (
+        (minor_axis_index, major_axis_index)
+        if format == "csc"
+        else (major_axis_index, minor_axis_index)
+    )
+    shape = (num_minor_axis, 20) if format == "csc" else (20, num_minor_axis)
+    X = getattr(sparse, f"{format}_array")(
+        (np.array([10]), row_cols),
+        shape=shape,
+    )
+    assert X.nnz == 1
+    with ad.settings.override(write_csr_csc_indices_with_min_possible_dtype=True):
+        write_elem(store, "X", X)
+
+    assert store["X/indices"].dtype == expected_dtype
+    with ad.settings.override(use_sparse_array_on_read=True):
+        result = read_elem(store["X"])
+    assert_equal(result.data, X.data)
+    assert_equal(result.indices, X.indices)
+    assert_equal(result.indptr, X.indptr)
+    assert X.format == result.format
+    assert result.shape == X.shape
+    # != comparison converts to csr, which allocates a lot of memory or errors out with:
+    # ValueError: array is too big; `arr.size * arr.dtype.itemsize` is larger than the maximum possible size.
+    # Because the old, very large, minor axis is now the major axis and so either it fails to create or the indptr is very big.
+    # The above tests should be enough to capture the desired equality checks so this is mostly for being extra sure.
+    # See https://github.com/scipy/scipy/issues/23826
+    if not (format == "csc" and num_minor_axis > np.iinfo(np.uint16).max + 1):
+        assert (result != X).nnz == 0
+
+
 def test_io_spec_raw(store):
     adata = gen_adata((3, 2), **GEN_ADATA_NO_XARRAY_ARGS)
     adata.raw = adata.copy()

{anndata-0.12.8 → anndata-0.12.10}/tests/test_x.py

@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+from contextlib import nullcontext
+
 import numpy as np
 import pandas as pd
 import pytest
@@ -50,17 +52,35 @@ def test_repeat_indices_view():
 
 @pytest.mark.parametrize("orig_array_type", UNLABELLED_ARRAY_TYPES)
 @pytest.mark.parametrize("new_array_type", UNLABELLED_ARRAY_TYPES)
-def test_setter_view(orig_array_type, new_array_type):
+@pytest.mark.parametrize("copy_on_write_X", [True, False], ids=["CoW", "update"])
+def test_setter_view(orig_array_type, new_array_type, *, copy_on_write_X: bool):
+    ad.settings.copy_on_write_X = copy_on_write_X
     adata = gen_adata((10, 10), X_type=orig_array_type)
     orig_X = adata.X
+    expected_X = asarray(orig_X.copy())
     to_assign = new_array_type(np.ones((9, 9)))
-    if isinstance(orig_X, np.ndarray) and sparse.issparse(to_assign):
-        # https://github.com/scverse/anndata/issues/500
-        pytest.xfail("Cannot set a dense array with a sparse array")
+    if not copy_on_write_X:
+        expected_X[:9, :9] = asarray(to_assign)
     view = adata[:9, :9]
-    view.X = to_assign
-    np.testing.assert_equal(asarray(view.X), np.ones((9, 9)))
-    assert isinstance(view.X, type(orig_X))
+    with (
+        pytest.warns(
+            ImplicitModificationWarning if copy_on_write_X else FutureWarning,
+            match=r"initializing view as actual"
+            if copy_on_write_X
+            else r"will obey copy-on-write semantics",
+        ),
+        pytest.warns(UserWarning, match=r"Trying to set a dense array")
+        if sparse.issparse(to_assign)
+        and isinstance(orig_X, np.ndarray)
+        and not copy_on_write_X
+        else nullcontext(),
+    ):
+        view.X = to_assign
+    assert_equal(view.X, to_assign)
+    assert isinstance(view.X, type(to_assign) if copy_on_write_X else type(orig_X))
+    assert_equal(adata.X, expected_X)
+    # If cow, then not a view and if not cow, it is a view
+    assert view.is_view != copy_on_write_X
 
 
 ###############################