tiledbsoma.Collection¶

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)

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, , uri, context, *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`
`metadata`
`mode`	The mode this object was opened in, either `r`, `w`, or `d`.
`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.