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 specifying the domain of each index column. Each slot in the list must have its name being the name of an index column, and its value being be a length-two vector consisting of the minimum and maximum values storable in the index column. For example, if there is a single int64-valued index column
soma_joinid, thendomainmight belist(soma_joinid=c(100, 200))to indicate that values between 100 and 200, inclusive, can be stored in that column. If provided, this sequence 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 an empty range, and data writes after that will fail with "A range was set outside of the current domain". Unless you have a particular reason not to, you should always provide the desireddomainat create time: this is an optional but strongly recommended parameter. See alsochange_domainwhich allows you to expand the domain after create.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 tiledbsoma_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).
Method tiledbsoma_upgrade_domain()
Allows you to set the domain of a SOMADataFrame, when the
SOMADataFrame does not have a domain set yet. The argument must be a
tuple of pairs of low/high values for the desired domain, one pair per
index column. For string index columns, you must offer the low/high pair
as ("", ""), or as NULL. If check_only is True, returns
whether the operation would succeed if attempted, and a reason why it
would not. The domain being requested must be contained within what
maxdomain returns.
Method change_domain()
Allows you to set the domain of a SOMADataFrame, when the
SOMADataFrame already has a domain set yet. The argument must be a
tuple of pairs of low/high values for the desired domain, one pair per
index column. For string index columns, you must offer the low/high pair
as ("", ""), or as NULL. If check_only is True, returns
whether the operation would succeed if attempted, and a reason why it
would not. The return value from domain must be contained within
the requested new_domain, and the requested new_domain must be
contained within the return value from maxdomain. (lifecycle: maturing)