tiledbsoma.io.update_obs

tiledbsoma.io.update_obs(exp: Experiment, new_data: DataFrame, *, context: SOMATileDBContext | None = None, platform_config: Dict[str, Mapping[str, Any]] | object | None = None, default_index_name: str = 'obs_id') → None

Replaces the entire obs DataFrame with the contents of a new pandas DataFrame.

This function is designed to perform a full replacement of the obs DataFrame. It assumes the input new_data DataFrame represents the desired final state for the obs SOMA DataFrame. The operation implicitly relies on row order for alignment.

Details: * Schema Changes: Columns present in new_data but not in the existing obs will be added. Columns present

in the existing obs but absent from new_data will be dropped.

  • Row Alignment: The function requires that the input `new_data DataFrame has the exact same number of rows

    and order as the existing obs DataFrame. It does not perform a join based on user-defined cell IDs or other index columns.

To avoid data misalignment, the following workflow is recommended:

  1. Read the entire existing obs DataFrame into memory.

  2. Perform all desired modifications (updating values, adding/dropping columns) on this DataFrame, preserving the original row order.

  3. Pass the fully modified DataFrame to update_obs’s new_data argument.

Parameters:

  • exp – The SOMAExperiment whose obs is to be updated. Must be opened for write.

  • new_data – A pandas DataFrame containing the final desired data for the obs SOMA DataFrame.

  • context – Optional SOMATileDBContext containing storage parameters, etc.

  • platform_config – Platform-specific options used to update this array, provided in the form {"tiledb": {"create": {"dataframe_dim_zstd_level": 7}}}

  • default_index_name – What to call the new_data index column if it is nameless in Pandas, or has name "index".

Returns:

None

Lifecycle

Maturing.