tiledbsoma.io.upgrade_experiment_shapes

tiledbsoma.io.upgrade_experiment_shapes(uri: str, *, verbose: bool = False, check_only: bool = False, context: ~tiledbsoma.options._soma_tiledb_context.SOMATileDBContext | None = None, output_handle: ~_io.TextIOWrapper | ~_io.StringIO = <_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>) → bool

Upgrade the elements inside a SOMA Experiment to use the shape feature introduced in TileDB-SOMA 1.15.

A new shape feature was introduced in TileDB-SOMA in release 1.15. This updates the elements in TileDB-SOMA to use the new feature. It makes an experiment created before TileDB-SOMA 1.15 look like an experiment created by TileDB-SOMA 1.15 or later. You can use tiledbsoma.io.show_experiment_shapes before and after to see the difference.

For each dataframe and N-D array that is being upgraded, if the dataframe does not currently support the new shape feature, upgrades to add the feature and sets the domain to the dataframe’s current non_empty_domain. If the new shape feature is already enable, nothing is changed.

The following elements are updated:

  • the obs dataframe in the experiment,

for each measurement:

  • the var dataframe,

  • all X arrays,

  • all obsm arrays,

  • all varm arrays,

  • all obsp arrays,

  • all varm arrays,

  • all varp arrays.

Example:

>>> tiledbsoma.io.upgrade_experiment_shapes('pbmc3k_unprocessed_old', check_only=True)
[DataFrame] obs
  URI file:///data/pbmc3k_unprocessed_old/obs
  Dry run for: tiledbsoma_upgrade_soma_joinid_shape(2700)
  OK
[DataFrame] ms/RNA/var
  URI file:///data/pbmc3k_unprocessed_old/ms/RNA/var
  Dry run for: tiledbsoma_upgrade_soma_joinid_shape(13714)
  OK
[SparseNDArray] ms/RNA/X/data
  URI file:///data/pbmc3k_unprocessed_old/ms/RNA/X/data
  Dry run for: tiledbsoma_upgrade_shape((2700, 13714))
  OK
Parameters:

  • uri – The URI of a SOMA Experiment.

  • verbose – If True, produce per-array output as the upgrade runs.

  • check_only – If True, don’t apply the upgrades, but show what would be attempted, and show why each one would fail.

  • context – Optional SOMATileDBContext.

Returns:

True if all upgrade operations succeed. False if any upgrade operation fails.