tiledbsoma.DataFrame.change_domain

DataFrame.change_domain(newdomain: Sequence[None | tuple[Any, Any] | list[Any]], check_only: bool = False) → tuple[bool, str]

Allows you to enlarge the domain of a SOMA DataFrame, when the DataFrame already has a domain.

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 None. If check_only is True, returns whether the operation would succeed if attempted, and a reason why it would not.

For example, suppose the dataframe’s sole index-column name is "soma_joinid" (which is the default at create). If the dataframe’s .maxdomain is ((0, 999999),) and its .domain is ((0, 2899),), this means that soma_joinid values between 0 and 2899 can be read or written; any attempt to read or write soma_joinid values outside this range will result in an error. If you then apply .change_domain([(0, 5700)]), then .domain will report ((0, 5699),), and now soma_joinid values in the range 0 to 5699 can now be written to the dataframe.

If you use non-default index_column_names in the dataframe’s create then you need to specify the (low, high) pairs for each index column. For example, if the dataframe’s index_column_names is ["soma_joinid", "cell_type"], then you can upgrade domain using [(0, 5699), ("", "")].

Lastly, it is an error to try to set the domain to be smaller than maxdomain along any index column. The maxdomain of a dataframe is set at creation time, and cannot be extended afterward.

Lifecycle

Maturing.