cellarr-array

This package provided high-level wrappers for TileDB arrays, for handling genomic data matrices.

Install

To get started, install the package from PyPI

pip install cellarr-array

Quick Start

Creating Arrays

importnumpyasnpfromscipyimportsparsefromcellarr_arrayimportcreate_cellarray, CellArrConfig# Create a dense 2D arraydense_array=create_cellarray(
uri="dense_matrix.tdb",
shape=(10000, 5000),
attr_dtype=np.float32,
sparse=False,
dim_names=["cells", "genes"]
)
# Create a sparse 2D array with custom compressionconfig=CellArrConfig(
tile_capacity=1000,
attrs_filters={"data": [{"name": "zstd", "level": 7}]}
)
sparse_array=create_cellarray(
uri="sparse_matrix.tdb",
shape=(10000, 5000),
attr_dtype=np.float32,
sparse=True,
config=config,
dim_names=["cells", "genes"]
)
# Create a 1D arrayarray_1d=create_cellarray(
uri="vector.tdb",
shape=(1000,),
attr_dtype=np.float32,
sparse=False
)

Writing Data

# Writing to dense arraysdata=np.random.random((1000, 5000)).astype(np.float32)
dense_array.write_batch(data, start_row=0)
# Writing to sparse arrayssparse_data=sparse.random(1000, 5000, density=0.1, format="csr", dtype=np.float32)
sparse_array.write_batch(sparse_data, start_row=0)
# Writing to 1D arraysdata_1d=np.random.random(100).astype(np.float32)
array_1d.write_batch(data_1d, start_row=0)

Reading Data

# Slicing operations (similar to NumPy)# Full slicefull_data=dense_array[:]
# Partial slicesubset=dense_array[100:200, 1000:2000]
# Using lists of indicescells= [10, 20, 30]
genes= [5, 15, 25]
subset=dense_array[cells, genes]
# Mixed slicingsubset=dense_array[100:200, genes]

Working with Sparse Arrays

fromcellarr_arrayimportSparseCellArray# Create a sparse array with CSR output formatcsr_array=SparseCellArray(
uri="sparse_matrix.tdb",
return_sparse=True
)
# Get result as CSR matrixresult=csr_array[100:200, 500:1000]
# Result is scipy.sparse.coo_matrixassertsparse.isspmatrix_csr(result)
# Perform sparse operationsnnz=result.nnzdensity=result.nnz/ (result.shape[0] *result.shape[1])
# Convert to other sparse formats if neededresult_csc=result.tocsc()

Likewise create a CSC output format

fromscipyimportsparse# Create a sparse array with CSC output formatcsc_array=SparseCellArray(
uri="sparse_matrix.tdb",
return_sparse=True,
sparse_coerce=sparse.csc_matrix
)
# Get result as CSR matrixresult=csc_array[100:200, 500:1000]
print(result)

Array Maintenance

# Consolidate fragmentsarray.consolidate()
# Custom consolidationconfig=ConsolidationConfig(
steps=2,
vacuum_after=True
)
array.consolidate(config)
# Vacuumarray.vacuum()

Note

This project has been set up using BiocSetup and PyScaffold.