tiledbsoma.Collection

class tiledbsoma.Collection(handle: SOMAGroupWrapper[Any], **kwargs: Any)

Collection is a persistent container of named SOMA objects, stored as a mapping of string keys and SOMA object values. Values may be any persistent tiledbsoma object, including DataFrame, SparseNDArray, DenseNDArray, Experiment, Measurement, or another Collection. A Collection refers to elements by a per-element URI. A Collection may store its reference to an element by absolute URI or relative URI.

Lifecycle

Maturing.

Examples

>>> import tiledbsoma
>>> import pyarrow as pa
>>> import numpy as np
>>> # create a collection and add a (4, 4) dense matrix to it
>>> with tiledbsoma.Collection.create("./test_collection") as my_collection:
...     # collection created. You can now add SOMA objects, e.g., a DenseNDArray.
...     # New objects are returned open for write.
...     my_dense_ndarray = my_collection.add_new_dense_ndarray(
...         "my_dense_ndarray", type=pa.int32(), shape=(4, 4)
...     )
...     data = pa.Tensor.from_numpy(np.eye(4, 4, dtype=np.int32))
...     my_dense_ndarray.write((slice(None), slice(None)), data)
...
... # example of opening collection to read an object back
... with tiledbsoma.open("./test_collection") as my_collection:
...     data = my_collection["my_dense_ndarray"].read()
...
>>> data
<pyarrow.Tensor>
type: int32
shape: (4, 4)
strides: (16, 4)
>>> data.to_numpy()
array([[1, 0, 0, 0],
       [0, 1, 0, 0],
       [0, 0, 1, 0],
       [0, 0, 0, 1]], dtype=int32)

__init__(handle: SOMAGroupWrapper[Any], **kwargs: Any)

Internal-only common initializer steps.

This function is internal; users should open TileDB SOMA objects using the create() and open() factory class methods.

Methods

__init__(handle, **kwargs)	Internal-only common initializer steps.
exists(uri[, context, tiledb_timestamp])	Finds whether an object of this type exists at the given URI.
create(uri, *[, platform_config, context, ...])	Creates and opens a new SOMA collection in storage.
open(uri[, mode, tiledb_timestamp, context, ...])	Opens this specific type of SOMA object.
reopen(mode[, tiledb_timestamp])	Return a new copy of the SOMAObject with the given mode at the current Unix timestamp.
close()	Release any resources held while the object is open.
verify_open_for_writing()	Raises an error if the object is not open for writing.
items()
keys()
values()
members()	Get a mapping of {member_name: (uri, soma_object_type)}
get(k[,d])
set(key, value, *[, use_relative_uri])	Adds an element to the collection.
setdefault(k[,d])
update([E, ]**F)	If E present and has a .keys() method, does: for k in E: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k, v in F.items(): D[k] = v
clear()
pop(k[,d])	If key is not found, d is returned if given, otherwise KeyError is raised.
popitem()	as a 2-tuple; but raise KeyError if D is empty.
add_new_collection(key[, kind, uri, ...])	Adds a new sub-collection to this collection.
add_new_dataframe(key, *[, uri, ...])	Adds a new DataFrame to this collection.
add_new_dense_ndarray(key, *, cls[, uri, ...])	Adds a new DenseNDArray to this Collection.
add_new_sparse_ndarray(key, *, cls[, uri, ...])	Adds a new SparseNDArray to this Collection.

Attributes

uri	Accessor for the object's storage URI.
closed	True if the object has been closed.
context	A value storing implementation-specific configuration information.
metadata	The metadata of this SOMA object.
mode	The mode this object was opened in, either r or w.
soma_type	A string describing the SOMA type of this object.
tiledb_timestamp	The time that this object was opened in UTC.
tiledb_timestamp_ms	The time this object was opened, as millis since the Unix epoch.