SOMA Experiment

SOMAExperiment is a specialized SOMACollection, representing one or more modes of measurement across a single collection of cells (aka a “multimodal dataset”) with pre-defined fields: obs and ms (see Active Bindings below for details) (lifecycle: maturing).

Adding new objects to a collection

The SOMAExperiment class provides a number of type-specific methods for adding new a object to the collection, such as add_new_sparse_ndarray() and add_new_dataframe(). These methods will create the new object and add it as member of the SOMAExperiment. The new object will always inherit the parent context (see SOMATileDBContext) and, by default, its platform configuration (see PlatformConfig). However, the user can override the default platform configuration by passing a custom configuration to the platform_config argument.

Super classes

tiledbsoma::SOMAObject -> tiledbsoma::SOMACollectionBase -> SOMAExperiment

Active bindings

obs

A SOMADataFrame containing primary annotations on the observation axis. The contents of the soma_joinid column define the observation index domain, obs_id. All observations for the SOMAExperiment must be defined in this data frame.

ms

A SOMACollection of named SOMAMeasurements.

Methods

Public methods

• SOMAExperiment$axis_query()

• SOMAExperiment$update_obs()

• SOMAExperiment$update_var()

• SOMAExperiment$clone()

Inherited methods

• tiledbsoma::SOMAObject$class()
• tiledbsoma::SOMAObject$exists()
• tiledbsoma::SOMAObject$get_metadata()
• tiledbsoma::SOMAObject$initialize()
• tiledbsoma::SOMAObject$is_open()
• tiledbsoma::SOMAObject$mode()
• tiledbsoma::SOMAObject$reopen()
• tiledbsoma::SOMACollectionBase$add_new_collection()
• tiledbsoma::SOMACollectionBase$add_new_dataframe()
• tiledbsoma::SOMACollectionBase$add_new_dense_ndarray()
• tiledbsoma::SOMACollectionBase$add_new_sparse_ndarray()
• tiledbsoma::SOMACollectionBase$close()
• tiledbsoma::SOMACollectionBase$create()
• tiledbsoma::SOMACollectionBase$get()
• tiledbsoma::SOMACollectionBase$length()
• tiledbsoma::SOMACollectionBase$names()
• tiledbsoma::SOMACollectionBase$open()
• tiledbsoma::SOMACollectionBase$print()
• tiledbsoma::SOMACollectionBase$remove()
• tiledbsoma::SOMACollectionBase$set()
• tiledbsoma::SOMACollectionBase$set_metadata()

---

Method axis_query()

Subset and extract data from a SOMAMeasurement by querying the obs/var axes.

Usage

SOMAExperiment$axis_query(measurement_name, obs_query = NULL, var_query = NULL)

Arguments

measurement_name

The name of the measurement to query.

obs_query, var_query

An SOMAAxisQuery object for the obs/var axis.

Returns

A SOMAExperimentAxisQuery object.

---

Method update_obs()

Update the obs data frame to add or remove columns. See SOMADataFrame$update() for more details.

Usage

SOMAExperiment$update_obs(values, row_index_name = NULL)

Arguments

values

A data frame, Arrow table, or Arrow record batch.

row_index_name

An optional scalar character. If provided, and if the values argument is a data frame with row names, then the row names will be extracted and added as a new column to the data frame prior to performing the update. The name of this new column will be set to the value specified by row_index_name.

---

Method update_var()

Update the var data frame to add or remove columns. See SOMADataFrame$update() for more details.

Usage

SOMAExperiment$update_var(values, measurement_name, row_index_name = NULL)

Arguments

values

A data frame, Arrow table, or Arrow record batch.

measurement_name

The name of the SOMAMeasurement whose var will be updated.

row_index_name

An optional scalar character. If provided, and if the values argument is a data frame with row names, then the row names will be extracted and added as a new column to the data frame prior to performing the update. The name of this new column will be set to the value specified by row_index_name.

---

Method clone()

The objects of this class are cloneable with this method.

Usage

SOMAExperiment$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

Examples

uri <- withr::local_tempfile(pattern = "soma-experiment")
obs <- data.frame(
  soma_joinid = bit64::seq.integer64(0L, 99L),
  obs_id = paste0("cell_", seq_len(100L))
)
sch <- arrow::infer_schema(obs)

(exp <- SOMAExperimentCreate(uri))
#> <SOMAExperiment>
#>   uri: /tmp/RtmpjD0Pq2/soma-experiment27091fd307df
sdf <- exp$add_new_dataframe(
  "obs",
  sch,
  "soma_joinid",
  list(soma_joinid = c(0, 100))
)
sdf$write(arrow::as_arrow_table(obs, schema = sch))
sdf$close()
exp$close()

(exp <- SOMAExperimentOpen(uri))
#> <SOMAExperiment>
#>   uri: /tmp/RtmpjD0Pq2/soma-experiment27091fd307df
exp$obs
#> <SOMADataFrame>
#>   uri: file:///tmp/RtmpjD0Pq2/soma-experiment27091fd307df/obs
#>   dimensions: soma_joinid 
#>   attributes: obs_id