API reference¶

class vsparse.VCSCArray(shape, major_ptr, values, value_ptr, indices)[source]¶

Bases: _VCSBase

Value-Compressed Sparse Column array. Values are deduplicated per column.

Parameters:

shape (tuple[int, int])
major_ptr (np.ndarray)
values (np.ndarray)
value_ptr (np.ndarray)
indices (np.ndarray)

property T: _VCSBase¶

shares buffers and swaps the VCSC/VCSR dual class.

Type:: Transpose. Free

astype(dtype, copy=True)¶

Cast the stored values to dtype. Structural zeros stay zero implicitly.

Return type:

_VCSBase

Parameters:

dtype (Any)
copy (bool)

copy()¶

count_nonzero()¶

Count of stored elements that are actually nonzero (unlike nnz/getnnz).

Return type:: int

property dtype: dtype¶

classmethod from_scipy(mat)¶

Build from any scipy sparse array/matrix (converted internally).

Return type:: _VCSBase

getnnz(axis=None)¶

Count of stored elements along axis, or overall if None.

Return type:: ndarray | int
Parameters:: axis (int | None)

indices¶

log1p()¶

Elementwise log1p. Structural zeros stay zero implicitly.

Return type:: _VCSBase

major_ptr¶

max(axis=None)¶

Maximum value (including implicit zeros) along axis, or overall if None.

Return type:: ndarray | Any
Parameters:: axis (int | None)

mean(axis=None)¶

Mean of (structural + implicit-zero) values along axis, or overall if None.

Return type:: ndarray | float
Parameters:: axis (int | None)

min(axis=None)¶

Minimum value (including implicit zeros) along axis, or overall if None.

Return type:: ndarray | Any
Parameters:: axis (int | None)

multiply(other)¶

Elementwise multiplication (matches scipy’s sparse-array .multiply).

Return type:: _VCSBase | ndarray

property n_major: int¶

property n_minor: int¶

property n_unique: int¶: Number of stored (major-slice, unique-value) entries.

property nnz: int¶

normalized()¶

A read-depth-normalized, log-transformed, mean-centered view – see vsparse._vcs_norm.

Return type:: Any

shape¶

sum(axis=None)¶

Sum of (structural) values along axis (0=rows, 1=columns), or overall if None.

Return type:: ndarray | float
Parameters:: axis (int | None)

to_csc()¶

Return type:: csc_array

to_csr()¶

Return type:: csr_array

to_scipy()¶: Decompress to the equivalent scipy csc_array/csr_array.

toarray()¶

Return type:: ndarray

transpose()¶

Return type:: _VCSBase

value_ptr¶

values¶

class vsparse.VCSRArray(shape, major_ptr, values, value_ptr, indices)[source]¶

Bases: _VCSBase

Value-Compressed Sparse Row array. Values are deduplicated per row.

Parameters:

shape (tuple[int, int])
major_ptr (np.ndarray)
values (np.ndarray)
value_ptr (np.ndarray)
indices (np.ndarray)

property T: _VCSBase¶

shares buffers and swaps the VCSC/VCSR dual class.

Type:: Transpose. Free

astype(dtype, copy=True)¶

Cast the stored values to dtype. Structural zeros stay zero implicitly.

Return type:

_VCSBase

Parameters:

dtype (Any)
copy (bool)

copy()¶

count_nonzero()¶

Count of stored elements that are actually nonzero (unlike nnz/getnnz).

Return type:: int

property dtype: dtype¶

classmethod from_scipy(mat)¶

Build from any scipy sparse array/matrix (converted internally).

Return type:: _VCSBase

getnnz(axis=None)¶

Count of stored elements along axis, or overall if None.

Return type:: ndarray | int
Parameters:: axis (int | None)

indices¶

log1p()¶

Elementwise log1p. Structural zeros stay zero implicitly.

Return type:: _VCSBase

major_ptr¶

max(axis=None)¶

Maximum value (including implicit zeros) along axis, or overall if None.

Return type:: ndarray | Any
Parameters:: axis (int | None)

mean(axis=None)¶

Mean of (structural + implicit-zero) values along axis, or overall if None.

Return type:: ndarray | float
Parameters:: axis (int | None)

min(axis=None)¶

Minimum value (including implicit zeros) along axis, or overall if None.

Return type:: ndarray | Any
Parameters:: axis (int | None)

multiply(other)¶

Elementwise multiplication (matches scipy’s sparse-array .multiply).

Return type:: _VCSBase | ndarray

property n_major: int¶

property n_minor: int¶

property n_unique: int¶: Number of stored (major-slice, unique-value) entries.

property nnz: int¶

normalized()¶

A read-depth-normalized, log-transformed, mean-centered view – see vsparse._vcs_norm.

Return type:: Any

shape¶

sum(axis=None)¶

Sum of (structural) values along axis (0=rows, 1=columns), or overall if None.

Return type:: ndarray | float
Parameters:: axis (int | None)

to_csc()¶

Return type:: csc_array

to_csr()¶

Return type:: csr_array

to_scipy()¶: Decompress to the equivalent scipy csc_array/csr_array.

toarray()¶

Return type:: ndarray

transpose()¶

Return type:: _VCSBase

value_ptr¶

values¶

vsparse.from_anndata(adata, layer=None, use_raw=False, format='csc')[source]¶

Convert adata.X (or a layer / raw.X) into a VCSC/VCSR array.

Parameters:

adata (AnnData) – Source anndata.AnnData object.
layer (str | None) – If given, read adata.layers[layer] instead of adata.X.
use_raw (bool) – If True, read adata.raw.X instead of adata.X.
format (str) – Either "csc" (default) or "csr", selecting the returned type.

Return type:

_VCSBase

Returns:

A VCSCArray or VCSRArray. The source
matrix may already be CSC, CSR, or dense; it is converted as needed.

vsparse.to_layer(adata, arr, key)[source]¶

Decompress arr and store it as adata.layers[key].

AnnData does not natively understand the VCSC/VCSR layout, so this stores the equivalent scipy sparse array.

Return type:

None

Parameters:

adata (AnnData)
arr (_VCSBase)
key (str)

vsparse.load_and_normalize(path, *, min_cell_counts=10.0, gene_threshold=0.0, min_cells=None, obs_filter=None, x_key='X')[source]¶

Load, filter, and depth-normalize a VCSR/IVCSR-backed .h5ad file.

Reproduces parafac2.normalize.prepare_dataset: cells with total counts <= min_cell_counts and genes with total counts <= gene_threshold * n_cells are dropped. When min_cells is given, genes expressed in fewer than min_cells cells are also dropped. Gene filters are measured on the raw counts after any obs_filter. The remaining matrix is row-normalized to the median per-cell depth, then column-normalized by gene sum, then transformed as log10(1000x + 1). Surrounding metadata (obs, var, obsm, etc.) is sliced to match the retained cells and genes.

Parameters:

path (str | PathLike[str]) – Path to an .h5ad file whose X (or layers[x_key]) was written with format="ivcsc"/"ivcsr" (see write_h5ad()).
min_cell_counts (float) – Cells with total raw counts <= this are dropped.
gene_threshold (float) – Minimum threshold fraction for gene inclusion, as in parafac2.normalize.prepare_dataset: genes with total raw counts <= gene_threshold * n_cells are dropped.
min_cells (int | None) – Optional gene filter. Genes expressed in fewer than this many cells are dropped. Expression is defined as a raw count > 0.
obs_filter (Callable[[DataFrame], object] | None) – Optional callable receiving obs and returning a one-dimensional boolean mask. When provided, rows are subset before cell filtering, gene filtering, and normalization, so gene totals and gene_threshold are computed using only the selected cells. The packed IVCSR stream is still read in full, but indices and values are materialized only for selected rows.
x_key (str) – Top-level h5ad group holding the IVCSR array ("X" by default).

Returns:

Filtered, depth-normalized AnnData object with X as a CSR array and sliced metadata.

Return type:

AnnData

Examples

Select cells using multiple obs columns and multiple accepted values:

load_and_normalize(
    path,
    obs_filter=lambda obs: (
        obs["condition"].isin(["control", "vehicle"])
        & (obs["timepoint"] == "T3")
    ),
)

class vsparse.VCSCAnnData(X=None, *, raw_X=None, **kwargs)[source]¶

Bases: AnnData

An AnnData whose X is a VCSCArray/VCSRArray.

Standard AnnData validates every array assigned to X/layers/etc. against a fixed allowlist of types (dense/sparse/ dask), so a plain AnnData cannot hold a VCSCArray directly. This subclass overrides the X property to store one without going through that validation. A “raw” VCSC/VCSR matrix, if any, is kept as .raw_X – a plain attribute, not wired into anndata’s own .raw/Raw machinery, which has the same restriction.

Because of this, most operations that need anndata’s normal per-element type dispatch on X – concatenation, most of scanpy/anndata’s ecosystem – are not supported while X is VCSC/VCSR-backed. Call to_anndata() first to get a fully-featured, ordinary AnnData. Indexing (adata[obs_idx, var_idx]) is supported (see __getitem__()), but always as an eager copy, not a lazy view – anndata’s view machinery bypasses the X/raw_X overrides here.

Persist with write_h5ad()/write_zarr() and read_h5ad()/read_zarr() (not the top-level anndata.read_h5ad/read_zarr, which always reconstruct a plain AnnData and would fail validating a VCSC-typed X).

Parameters:

X (_AnyVCS | None)
raw_X (_AnyVCS | None)
kwargs (Any)

property X: _VCSBase | None¶: Data matrix of shape n_obs × n_vars.

property raw_X: _VCSBase | None¶: The raw/X matrix, as a VCSCArray/VCSRArray (see class docstring).

classmethod from_anndata(adata, format='csc', raw_format=None, *, include_raw=True)[source]¶

Build from a regular AnnData, compressing X (and raw.X).

Return type:

VCSCAnnData

Parameters:

adata (AnnData)
format (str)
raw_format (str | None)
include_raw (bool)

to_anndata()[source]¶

Decompress to a regular, fully-featured AnnData.

Return type:: AnnData

write_h5ad(filename, *, format='vcsc', convert_strings_to_categoricals=True, dataset_kwargs=None, **_kwargs)[source]¶

Write to .h5ad. Read back with read_h5ad().

Parameters:

format (str) – "vcsc" (default) stores X/raw_X with plain int arrays for the minor-axis indices. "ivcsc" (IVCSC/IVCSR) instead byte-packs them (delta + varint encoding) for a smaller file, at the cost of extra work on write/read. Either way, X/raw_X come back from read_h5ad() as ordinary VCSCArray/VCSRArray objects – "ivcsc" is purely an on-disk storage format.
convert_strings_to_categoricals (bool) – Convert obs/var string columns to categorical in place before writing, as anndata’s own writers do. Only columns with fewer categories than rows are converted.
dataset_kwargs (Mapping[str, Any] | None) – Passed to h5py.Group.create_dataset for every array written. Defaults to Blosc2+LZ4 compression; pass {} to store uncompressed. Either way, compression is only ever applied to numeric arrays – see vsparse._compression.numeric_only_compression().
filename (str | PathLike[str])
_kwargs (Any)

Return type:

None

classmethod read_h5ad(filename)[source]¶

Read a file written by write_h5ad().

Return type:: VCSCAnnData
Parameters:: filename (str | PathLike[str])

write_zarr(store, *, format='vcsc', convert_strings_to_categoricals=True, dataset_kwargs=None, **_kwargs)[source]¶

Write to a zarr store. Read back with read_zarr().

See write_h5ad() for format/convert_strings_to_categoricals/ dataset_kwargs (including the numeric-only compression behavior); the default compression here is Blosc+LZ4 via numcodecs.

Return type:

None

Parameters:

store (Any)
format (str)
convert_strings_to_categoricals (bool)
dataset_kwargs (Mapping[str, Any] | None)
_kwargs (Any)

classmethod read_zarr(store)[source]¶

Read a store written by write_zarr().

Return type:: VCSCAnnData
Parameters:: store (Any)