SOMADataFrame is a multi-column table that must contain a column
called soma_joinid of type int64, which contains a unique value for each
row and is intended to act as a join key for other objects, such as
SOMASparseNDArray. (lifecycle: maturing)
Super classes
tiledbsoma::TileDBObject -> tiledbsoma::TileDBArray -> tiledbsoma::SOMAArrayBase -> SOMADataFrame
Methods
Inherited methods
tiledbsoma::TileDBObject$class()tiledbsoma::TileDBObject$exists()tiledbsoma::TileDBObject$initialize()tiledbsoma::TileDBObject$is_open()tiledbsoma::TileDBObject$mode()tiledbsoma::TileDBObject$reopen()tiledbsoma::TileDBArray$attributes()tiledbsoma::TileDBArray$attrnames()tiledbsoma::TileDBArray$close()tiledbsoma::TileDBArray$colnames()tiledbsoma::TileDBArray$dimensions()tiledbsoma::TileDBArray$dimnames()tiledbsoma::TileDBArray$get_metadata()tiledbsoma::TileDBArray$index_column_names()tiledbsoma::TileDBArray$ndim()tiledbsoma::TileDBArray$non_empty_domain()tiledbsoma::TileDBArray$open()tiledbsoma::TileDBArray$print()tiledbsoma::TileDBArray$schema()tiledbsoma::TileDBArray$set_metadata()tiledbsoma::TileDBArray$tiledb_array()tiledbsoma::TileDBArray$tiledb_schema()tiledbsoma::TileDBArray$used_shape()
Method create()
Create (lifecycle: maturing)
Usage
SOMADataFrame$create(
schema,
index_column_names = c("soma_joinid"),
domain = NULL,
platform_config = NULL,
internal_use_only = NULL
)Arguments
schemaan
arrow::schema.index_column_namesA vector of column names to use as user-defined index columns. All named columns must exist in the schema, and at least one index column name is required.
domainAn optional list of 2-element vectors specifying the domain of each index column. Each vector should be a pair consisting of the minimum and maximum values storable in the index column. For example, if there is a single int64-valued index column, then
domainmight bec(100, 200)to indicate that values between 100 and 200, inclusive, can be stored in that column. If provided, this list must have the same length asindex_column_names, and the index-column domain will be as specified. If omitted entirely, or ifNULLin a given dimension, the corresponding index-column domain will use the minimum and maximum possible values for the column's datatype. This makes aDataFramegrowable.platform_configA platform configuration object
internal_use_onlyCharacter value to signal this is a 'permitted' call, as
create()is considered internal and should not be called directly.
Method write()
Write (lifecycle: maturing)
Arguments
valuesAn
arrow::Tableorarrow::RecordBatchcontaining all columns, including any index columns. The schema forvaluesmust match the schema for theSOMADataFrame.
Method read()
Read (lifecycle: maturing) Read a user-defined subset of data, addressed by the dataframe indexing column, and optionally filtered.
Usage
SOMADataFrame$read(
coords = NULL,
column_names = NULL,
value_filter = NULL,
result_order = "auto",
iterated = FALSE,
log_level = "auto"
)Arguments
coordsOptional named list of indices specifying the rows to read; each (named) list element corresponds to a dimension of the same name.
column_namesOptional character vector of column names to return.
value_filterOptional string containing a logical expression that is used to filter the returned values. See
tiledb::parse_query_conditionfor more information.result_orderOptional order of read results. This can be one of either
"ROW_MAJOR,"COL_MAJOR", or"auto"` (default).iteratedOption boolean indicated whether data is read in call (when
FALSE, the default value) or in several iterated steps.log_levelOptional logging level with default value of
"warn".
Returns
arrow::Table or TableReadIter
Method update()
Update (lifecycle: maturing)
Arguments
valuesA
data.frame,arrow::Table, orarrow::RecordBatch.row_index_nameAn optional scalar character. If provided, and if the
valuesargument is adata.framewith row names, then the row names will be extracted and added as a new column to thedata.frameprior to performing the update. The name of this new column will be set to the value specified byrow_index_name.
Details
Update the existing SOMADataFrame to add or remove columns based on the
input:
columns present in the current the
SOMADataFramebut absent from the newvalueswill be droppedcolumns absent in current
SOMADataFramebut present in the newvalueswill be addedany columns present in both will be left alone, with the exception that if
valueshas a different type for the column, the entire update will fail because attribute types cannot be changed.
Furthermore, values must contain the same number of rows as the current
SOMADataFrame.
Method shape()
Retrieve the shape; as SOMADataFrames are shapeless,
simply raises an error
Returns
None, instead a .NotYetImplemented() error is raised
Method maxshape()
Retrieve the maxshape; as SOMADataFrames are shapeless,
simply raises an error
Returns
None, instead a .NotYetImplemented() error is raised
Method domain()
Returns a named list of minimum/maximum pairs, one per index
column, currently storable on each index column of the dataframe. These
can be resized up to maxdomain.
(lifecycle: maturing)
Method maxdomain()
Returns a named list of minimum/maximum pairs, one per index column, which are the limits up to which the dataframe can have its domain resized. (lifecycle: maturing)
Method tiledbsoma_has_upgraded_domain()
Returns TRUE if the array has the upgraded resizeable domain
feature from TileDB-SOMA 1.15: the array was created with this support,
or it has had upgrade_domain applied to it.
(lifecycle: maturing)
Method resize_soma_joinid_shape()
Increases the shape of the dataframe on the soma_joinid
index column, if it indeed is an index column, leaving all other index
columns as-is. If the soma_joinid is not an index column, no change is
made. This is a special case of upgrade_domain (WIP for 1.15), but
simpler to keystroke, and handles the most common case for dataframe
domain expansion. Raises an error if the dataframe doesn't already have a
domain: in that case please call tiledbsoma_upgrade_domain (WIP for
1.15).