tiledbsoma.io.resize_experiment

tiledbsoma.io.resize_experiment(uri: str, *, nobs: int, nvars: dict[str, int], 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

Resize the elements in the SOMA Experiment to fit the requested number of observations and variables.

A dataframe will be resized if the soma_joinid column is an index column and the current domain of the soma_joinid column is smaller than requested size. If the new domain of the soma_joinid column does not fit inside the maxshape, the resize fails.

An N-D array will be resized if either dimension of the new shape is larger than the current shape. If either dimension of the new shape is larger than maxshape, the resize fails.

The following base elements are resized:

  • obs dataframe: soma_joinid resized to fit nobs.

For each measurement_name in the experiment the elements are resized as follows where nvar[measurement_name] is the current size if measurement_name or no value is provided by the user:

  • var dataframe: soma_joinid resized to fit nvar[measurement_name].

  • X arrays: shape at least (nobs, nvar[measurement_name]).

  • obsm arrays: shape at least (nobs, current soma_dim_1).

  • varm arrays: shape at least (nvar, current soma_dim_1).

  • obsp arrays: shape at least (nobs, nobs).

  • varm arrays: shape at least (nvar, existing soma_dim_1).

  • varp arrays: shape at least ( nvar, nvar).

Example:

>>> tiledbsoma.io.resize_experiment(
    'pbmc3k_unprocessed',
    nobs=5600,
    nvars={"data":3204, "raw": 13714},
    check_only=True,
)
[DataFrame] obs
  URI file:///data/pbmc3k_unprocessed/obs
  Dry run for: tiledbsoma_resize_soma_joinid_shape(5600)
  OK
[DataFrame] ms/RNA/var
  URI file:///data/pbmc3k_unprocessed/ms/RNA/var
  Dry run for: tiledbsoma_resize_soma_joinid_shape(13714)
  OK
[SparseNDArray] ms/RNA/X/data
  URI file:///data/pbmc3k_unprocessed/ms/RNA/X/data
  Dry run for: resize((5600, 13714))
  OK
Parameters:

  • uri – The URI of a SOMA Experiment.

  • nobs – The desired new shape of the experiment’s obs dataframe.

  • nvars – The desired new shapes of the experiment’s var dataframes. This should be a dict from measurement name to shape, e.g. {"RNA": 10000, "raw": 20000}.

  • 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 resize operations succeed. False if any resize operation fails.