lamindb 0.77.2__py3-none-any.whl → 1.0rc1__py3-none-any.whl

lamindb/{_curate.py → curators/__init__.py}

@@ -2,31 +2,40 @@ from __future__ import annotations
 
 import copy
 import warnings
+from itertools import chain
 from typing import TYPE_CHECKING
 
 import anndata as ad
 import lamindb_setup as ln_setup
 import pandas as pd
+import pyarrow as pa
 from lamin_utils import colors, logger
 from lamindb_setup.core._docs import doc_args
-from lnschema_core import (
+from lamindb_setup.core.upath import UPath
+
+from lamindb.models import (
     Artifact,
     Feature,
     Record,
     Run,
+    Schema,
     ULabel,
 )
 
-from ._from_values import _print_values
-from .core.exceptions import ValidationError
+from .._from_values import _format_values
+from ..core.exceptions import ValidationError
 
 if TYPE_CHECKING:
     from collections.abc import Iterable
     from typing import Any
 
     from lamindb_setup.core.types import UPathStr
-    from lnschema_core.types import FieldAttr
     from mudata import MuData
+    from spatialdata import SpatialData
+
+    from lamindb.base.types import FieldAttr
+
+    from ._spatial import SpatialDataCurator
 
 
 class CurateLookup:
@@ -40,8 +49,8 @@ class CurateLookup:
         public: Whether to lookup from the public instance. Defaults to False.
 
     Example:
-        >>> validator = ln.Validator()
-        >>> validator.lookup()["cell_type"].alveolar_type_1_fibroblast_cell
+        >>> curator = ln.Curator.from_df(...)
+        >>> curator.lookup()["cell_type"].alveolar_type_1_fibroblast_cell
         <Category: alveolar_type_1_fibroblast_cell>
 
     """
@@ -96,7 +105,7 @@ class CurateLookup:
                 f"Lookup objects from the {colors.italic(ref)}:\n "
                 f"{colors.green(getattr_keys)}\n "
                 f"{colors.green(getitem_keys)}\n"
-                'Example:\n    → categories = validator.lookup()["cell_type"]\n'
+                'Example:\n    → categories = curator.lookup()["cell_type"]\n'
                 "    → categories.alveolar_type_1_fibroblast_cell\n\n"
                 "To look up public ontologies, use .lookup(public=True)"
             )
@@ -107,6 +116,15 @@ class CurateLookup:
 class BaseCurator:
     """Curate a dataset."""
 
+    def __init_subclass__(cls, **kwargs):
+        super().__init_subclass__(**kwargs)
+        import sys
+
+        # Deprecated methods
+        if "sphinx" not in sys.modules:
+            if hasattr(cls, "_add_new_from_columns"):
+                cls.add_new_from_columns = cls._add_new_from_columns
+
     def validate(self) -> bool:
         """Validate dataset.
 
@@ -164,14 +182,16 @@ class DataFrameCurator(BaseCurator):
         verbosity: The verbosity level.
         organism: The organism name.
         sources: A dictionary mapping column names to Source records.
-        exclude: A dictionary mapping column names to values to exclude.
+        exclude: A dictionary mapping column names to values to exclude from validation.
+            When specific :class:`~bionty.Source` instances are pinned and may lack default values (e.g., "unknown" or "na"),
+            using the exclude parameter ensures they are not validated.
 
     Returns:
         A curator object.
 
     Examples:
         >>> import bionty as bt
-        >>> curate = ln.Curator.from_df(
+        >>> curator = ln.Curator.from_df(
         ...     df,
         ...     categoricals={
         ...         "cell_type_ontology_id": bt.CellType.ontology_id,
@@ -194,6 +214,9 @@ class DataFrameCurator(BaseCurator):
     ) -> None:
         from lamindb.core._settings import settings
 
+        if organism is not None and not isinstance(organism, str):
+            raise ValueError("organism must be a string such as 'human' or 'mouse'!")
+
         self._df = df
         self._fields = categoricals or {}
         self._columns_field = columns
@@ -255,7 +278,7 @@ class DataFrameCurator(BaseCurator):
             are = "are" if n > 1 else "is"
             if len(nonval_keys) > 0:
                 raise ValidationError(
-                    f"the following {n} key{s} passed to {name} {are} not allowed: {colors.yellow(_print_values(nonval_keys))}"
+                    f"key{s} passed to {name} {are} not present in columns: {colors.yellow(_format_values(nonval_keys))}"
                 )
 
     def _save_columns(self, validated_only: bool = True) -> None:
@@ -300,7 +323,7 @@ class DataFrameCurator(BaseCurator):
         self._kwargs.update({"organism": organism} if organism else {})
         self._update_registry(key, validated_only=False, **self._kwargs, **kwargs)
 
-    def add_new_from_columns(self, organism: str | None = None, **kwargs):
+    def _add_new_from_columns(self, organism: str | None = None, **kwargs):
         """Deprecated to run by default during init."""
         warnings.warn(
             "`.add_new_from_columns()` is deprecated and will be removed in a future version. It's run by default during initialization.",
@@ -323,7 +346,7 @@ class DataFrameCurator(BaseCurator):
         # logging
         n = len(syn_mapper)
         if n > 0:
-            syn_mapper_print = _print_values(
+            syn_mapper_print = _format_values(
                 [f'"{k}" → "{v}"' for k, v in syn_mapper.items()], sep=""
             )
             s = "s" if n > 1 else ""
@@ -332,13 +355,13 @@ class DataFrameCurator(BaseCurator):
             )
         return std_values
 
-    def standardize(self, key: str):
+    def standardize(self, key: str) -> None:
         """Replace synonyms with standardized values.
 
-        Args:
-            key: The key referencing the slot in the DataFrame from which to draw terms.
-
         Modifies the input dataset inplace.
+
+        Args:
+            key: The key referencing the column in the DataFrame to standardize.
         """
         # list is needed to avoid RuntimeError: dictionary changed size during iteration
         avail_keys = list(self.non_validated.keys())
@@ -359,9 +382,12 @@ class DataFrameCurator(BaseCurator):
                     self._df[k] = self._replace_synonyms(k, syn_mapper, self._df[k])
         else:
             if key not in avail_keys:
-                raise KeyError(
-                    f'"{key}" is not a valid key, available keys are: {_print_values(avail_keys)}!'
-                )
+                if key in self._fields:
+                    logger.info(f"No unstandardized values found for {key!r}")
+                else:
+                    raise KeyError(
+                        f"{key!r} is not a valid key, available keys are: {_format_values(avail_keys)}!"
+                    )
             else:
                 if key in self._fields:  # needed to exclude var_index
                     syn_mapper = standardize_categories(
@@ -375,7 +401,9 @@ class DataFrameCurator(BaseCurator):
                         key, syn_mapper, self._df[key]
                     )
 
-    def _update_registry(self, categorical: str, validated_only: bool = True, **kwargs):
+    def _update_registry(
+        self, categorical: str, validated_only: bool = True, **kwargs
+    ) -> None:
         if categorical == "all":
             self._update_registry_all(validated_only=validated_only, **kwargs)
         else:
@@ -441,7 +469,8 @@ class DataFrameCurator(BaseCurator):
 
         Args:
             description: Description of the DataFrame object.
-            key: A path-like key to reference artifact in default storage, e.g., `"myfolder/myfile.fcs"`. Artifacts with the same key form a revision family.
+            key: A path-like key to reference artifact in default storage, e.g., `"myfolder/myfile.fcs"`.
+                Artifacts with the same key form a revision family.
             revises: Previous version of the artifact. Triggers a revision.
             run: The run that creates the artifact.
 
@@ -502,11 +531,13 @@ class AnnDataCurator(DataFrameCurator):
         verbosity: The verbosity level.
         organism: The organism name.
         sources: A dictionary mapping ``.obs.columns`` to Source records.
-        exclude: A dictionary mapping column names to values to exclude.
+        exclude: A dictionary mapping column names to values to exclude from validation.
+            When specific :class:`~bionty.Source` instances are pinned and may lack default values (e.g., "unknown" or "na"),
+            using the exclude parameter ensures they are not validated.
 
     Examples:
         >>> import bionty as bt
-        >>> curate = ln.Curator.from_anndata(
+        >>> curator = ln.Curator.from_anndata(
         ...     adata,
         ...     var_index=bt.Gene.ensembl_gene_id,
         ...     categoricals={
@@ -534,7 +565,7 @@ class AnnDataCurator(DataFrameCurator):
         if isinstance(var_index, str):
             raise TypeError("var_index parameter has to be a bionty field")
 
-        from ._artifact import data_is_anndata
+        from .._artifact import data_is_anndata
 
         if sources is None:
             sources = {}
@@ -710,7 +741,8 @@ class AnnDataCurator(DataFrameCurator):
 
         Args:
             description: A description of the ``AnnData`` object.
-            key: A path-like key to reference artifact in default storage, e.g., `"myfolder/myfile.fcs"`. Artifacts with the same key form a revision family.
+            key: A path-like key to reference artifact in default storage, e.g., `"myfolder/myfile.fcs"`.
+                Artifacts with the same key form a revision family.
             revises: Previous version of the artifact. Triggers a revision.
             run: The run that creates the artifact.
 
@@ -761,11 +793,13 @@ class MuDataCurator:
         verbosity: The verbosity level.
         organism: The organism name.
         sources: A dictionary mapping ``.obs.columns`` to Source records.
-        exclude: A dictionary mapping column names to values to exclude.
+        exclude: A dictionary mapping column names to values to exclude from validation.
+            When specific :class:`~bionty.Source` instances are pinned and may lack default values (e.g., "unknown" or "na"),
+            using the exclude parameter ensures they are not validated.
 
     Examples:
         >>> import bionty as bt
-        >>> curate = ln.Curator.from_mudata(
+        >>> curator = ln.Curator.from_mudata(
         ...     mdata,
         ...     var_index={
         ...         "rna": bt.Gene.ensembl_gene_id,
@@ -1058,6 +1092,514 @@ class MuDataCurator:
         return self._artifact
 
 
+def _maybe_curation_keys_not_present(nonval_keys: list[str], name: str):
+    if (n := len(nonval_keys)) > 0:
+        s = "s" if n > 1 else ""
+        are = "are" if n > 1 else "is"
+        raise ValidationError(
+            f"key{s} passed to {name} {are} not present: {colors.yellow(_format_values(nonval_keys))}"
+        )
+
+
+class SOMACurator(BaseCurator):
+    """Curation flow for ``tiledbsoma``.
+
+    See also :class:`~lamindb.Curator`.
+
+    Args:
+        experiment_uri: A local or cloud path to a `tiledbsoma.Experiment`.
+        var_index: The registry fields for mapping the `.var` indices for measurements.
+            Should be in the form `{"measurement name": ("var column", field)}`.
+            These keys should be used in the flattened form (`'{measurement name}__{column name in .var}'`)
+            in `.standardize` or `.add_new_from`, see the output of `.var_index`.
+        categoricals: A dictionary mapping categorical `.obs` columns to a registry field.
+        obs_columns: The registry field for mapping the names of the `.obs` columns.
+        organism: The organism name.
+        sources: A dictionary mapping `.obs` columns to Source records.
+        exclude: A dictionary mapping column names to values to exclude from validation.
+            When specific :class:`~bionty.Source` instances are pinned and may lack default values (e.g., "unknown" or "na"),
+            using the exclude parameter ensures they are not validated.
+
+    Examples:
+        >>> import bionty as bt
+        >>> curator = ln.Curator.from_tiledbsoma(
+        ...     "./my_array_store.tiledbsoma",
+        ...     var_index={"RNA": ("var_id", bt.Gene.symbol)},
+        ...     categoricals={
+        ...         "cell_type_ontology_id": bt.CellType.ontology_id,
+        ...         "donor_id": ln.ULabel.name
+        ...     },
+        ...     organism="human",
+        ... )
+    """
+
+    def __init__(
+        self,
+        experiment_uri: UPathStr | Artifact,
+        var_index: dict[str, tuple[str, FieldAttr]],
+        categoricals: dict[str, FieldAttr] | None = None,
+        obs_columns: FieldAttr = Feature.name,
+        organism: str | None = None,
+        sources: dict[str, Record] | None = None,
+        exclude: dict[str, str | list[str]] | None = None,
+        using_key: str | None = None,
+    ):
+        self._obs_fields = categoricals or {}
+        self._var_fields = var_index
+        self._columns_field = obs_columns
+        if isinstance(experiment_uri, Artifact):
+            self._experiment_uri = experiment_uri.path
+            self._artifact = experiment_uri
+        else:
+            self._experiment_uri = UPath(experiment_uri)
+            self._artifact = None
+        self._organism = organism
+        self._using_key = using_key
+        self._sources = sources or {}
+        self._exclude = exclude or {}
+
+        self._validated: bool | None = False
+        self._non_validated_values: dict[str, list] | None = None
+        self._validated_values: dict[str, list] = {}
+        # filled by _check_save_keys
+        self._n_obs: int | None = None
+        self._valid_obs_keys: list[str] | None = None
+        self._obs_pa_schema: pa.lib.Schema | None = (
+            None  # this is needed to create the obs feature set
+        )
+        self._valid_var_keys: list[str] | None = None
+        self._var_fields_flat: dict[str, FieldAttr] | None = None
+        self._check_save_keys()
+
+    # check that the provided keys in var_index and categoricals are available in the store
+    # and save features
+    def _check_save_keys(self):
+        from lamindb.core.storage._tiledbsoma import _open_tiledbsoma
+
+        with _open_tiledbsoma(self._experiment_uri, mode="r") as experiment:
+            experiment_obs = experiment.obs
+            self._n_obs = len(experiment_obs)
+            self._obs_pa_schema = experiment_obs.schema
+            valid_obs_keys = [
+                k for k in self._obs_pa_schema.names if k != "soma_joinid"
+            ]
+            self._valid_obs_keys = valid_obs_keys
+
+            valid_var_keys = []
+            ms_list = []
+            for ms in experiment.ms.keys():
+                ms_list.append(ms)
+                var_ms = experiment.ms[ms].var
+                valid_var_keys += [
+                    f"{ms}__{k}" for k in var_ms.keys() if k != "soma_joinid"
+                ]
+            self._valid_var_keys = valid_var_keys
+
+        # check validity of keys in categoricals
+        nonval_keys = []
+        for obs_key in self._obs_fields.keys():
+            if obs_key not in valid_obs_keys:
+                nonval_keys.append(obs_key)
+        _maybe_curation_keys_not_present(nonval_keys, "categoricals")
+
+        # check validity of keys in var_index
+        self._var_fields_flat = {}
+        nonval_keys = []
+        for ms_key in self._var_fields.keys():
+            var_key, var_field = self._var_fields[ms_key]
+            var_key_flat = f"{ms_key}__{var_key}"
+            if var_key_flat not in valid_var_keys:
+                nonval_keys.append(f"({ms_key}, {var_key})")
+            else:
+                self._var_fields_flat[var_key_flat] = var_field
+        _maybe_curation_keys_not_present(nonval_keys, "var_index")
+
+        # check validity of keys in sources and exclude
+        valid_arg_keys = valid_obs_keys + valid_var_keys + ["columns"]
+        for name, dct in (("sources", self._sources), ("exclude", self._exclude)):
+            nonval_keys = []
+            for arg_key in dct.keys():
+                if arg_key not in valid_arg_keys:
+                    nonval_keys.append(arg_key)
+            _maybe_curation_keys_not_present(nonval_keys, name)
+
+        # register obs columns' names
+        register_columns = list(self._obs_fields.keys())
+        organism = check_registry_organism(
+            self._columns_field.field.model, self._organism
+        ).get("organism")
+        update_registry(
+            values=register_columns,
+            field=self._columns_field,
+            key="columns",
+            using_key=self._using_key,
+            validated_only=False,
+            organism=organism,
+            source=self._sources.get("columns"),
+            exclude=self._exclude.get("columns"),
+        )
+        additional_columns = [k for k in valid_obs_keys if k not in register_columns]
+        # no need to register with validated_only=True if columns are features
+        if (
+            len(additional_columns) > 0
+            and self._columns_field.field.model is not Feature
+        ):
+            update_registry(
+                values=additional_columns,
+                field=self._columns_field,
+                key="columns",
+                using_key=self._using_key,
+                validated_only=True,
+                organism=organism,
+                source=self._sources.get("columns"),
+                exclude=self._exclude.get("columns"),
+            )
+
+    def validate(self):
+        """Validate categories."""
+        from lamindb.core.storage._tiledbsoma import _open_tiledbsoma
+
+        validated = True
+        self._non_validated_values = {}
+        with _open_tiledbsoma(self._experiment_uri, mode="r") as experiment:
+            for ms, (key, field) in self._var_fields.items():
+                var_ms = experiment.ms[ms].var
+                var_ms_key = f"{ms}__{key}"
+                # it was already validated and cached
+                if var_ms_key in self._validated_values:
+                    continue
+                var_ms_values = (
+                    var_ms.read(column_names=[key]).concat()[key].to_pylist()
+                )
+                organism = check_registry_organism(
+                    field.field.model, self._organism
+                ).get("organism")
+                update_registry(
+                    values=var_ms_values,
+                    field=field,
+                    key=var_ms_key,
+                    using_key=self._using_key,
+                    validated_only=True,
+                    organism=organism,
+                    source=self._sources.get(var_ms_key),
+                    exclude=self._exclude.get(var_ms_key),
+                )
+                _, non_val = validate_categories(
+                    values=var_ms_values,
+                    field=field,
+                    key=var_ms_key,
+                    using_key=self._using_key,
+                    organism=organism,
+                    source=self._sources.get(var_ms_key),
+                    exclude=self._exclude.get(var_ms_key),
+                )
+                if len(non_val) > 0:
+                    validated = False
+                    self._non_validated_values[var_ms_key] = non_val
+                else:
+                    self._validated_values[var_ms_key] = var_ms_values
+
+            obs = experiment.obs
+            for key, field in self._obs_fields.items():
+                # already validated and cached
+                if key in self._validated_values:
+                    continue
+                values = pa.compute.unique(
+                    obs.read(column_names=[key]).concat()[key]
+                ).to_pylist()
+                organism = check_registry_organism(
+                    field.field.model, self._organism
+                ).get("organism")
+                update_registry(
+                    values=values,
+                    field=field,
+                    key=key,
+                    using_key=self._using_key,
+                    validated_only=True,
+                    organism=organism,
+                    source=self._sources.get(key),
+                    exclude=self._exclude.get(key),
+                )
+                _, non_val = validate_categories(
+                    values=values,
+                    field=field,
+                    key=key,
+                    using_key=self._using_key,
+                    organism=organism,
+                    source=self._sources.get(key),
+                    exclude=self._exclude.get(key),
+                )
+                if len(non_val) > 0:
+                    validated = False
+                    self._non_validated_values[key] = non_val
+                else:
+                    self._validated_values[key] = values
+        self._validated = validated
+        return self._validated
+
+    def _non_validated_values_field(self, key: str) -> tuple[list, FieldAttr]:
+        assert self._non_validated_values is not None  # noqa: S101
+
+        if key in self._valid_obs_keys:
+            field = self._obs_fields[key]
+        elif key in self._valid_var_keys:
+            ms = key.partition("__")[0]
+            field = self._var_fields[ms][1]
+        else:
+            raise KeyError(f"key {key} is invalid!")
+        values = self._non_validated_values.get(key, [])
+        return values, field
+
+    def add_new_from(self, key: str) -> None:
+        """Add validated & new categories.
+
+        Args:
+            key: The key referencing the slot in the `tiledbsoma` store.
+                It should be `'{measurement name}__{column name in .var}'` for columns in `.var`
+                or a column name in `.obs`.
+        """
+        if self._non_validated_values is None:
+            raise ValidationError("Run .validate() first.")
+        if key == "all":
+            keys = list(self._non_validated_values.keys())
+        else:
+            avail_keys = list(
+                chain(self._non_validated_values.keys(), self._validated_values.keys())
+            )
+            if key not in avail_keys:
+                raise KeyError(
+                    f"'{key!r}' is not a valid key, available keys are: {_format_values(avail_keys + ['all'])}!"
+                )
+            keys = [key]
+        for k in keys:
+            values, field = self._non_validated_values_field(k)
+            if len(values) == 0:
+                continue
+            organism = check_registry_organism(field.field.model, self._organism).get(
+                "organism"
+            )
+            update_registry(
+                values=values,
+                field=field,
+                key=k,
+                using_key=self._using_key,
+                validated_only=False,
+                organism=organism,
+                source=self._sources.get(k),
+                exclude=self._exclude.get(k),
+            )
+            # update non-validated values list but keep the key there
+            # it will be removed by .validate()
+            if k in self._non_validated_values:
+                self._non_validated_values[k] = []
+
+    @property
+    def non_validated(self) -> dict[str, list]:
+        """Return the non-validated features and labels."""
+        non_val = {k: v for k, v in self._non_validated_values.items() if v != []}
+        return non_val
+
+    @property
+    def var_index(self) -> dict[str, FieldAttr]:
+        """Return the registry fields with flattened keys to validate variables indices against."""
+        return self._var_fields_flat
+
+    @property
+    def categoricals(self) -> dict[str, FieldAttr]:
+        """Return the obs fields to validate against."""
+        return self._obs_fields
+
+    def lookup(
+        self, using_key: str | None = None, public: bool = False
+    ) -> CurateLookup:
+        """Lookup categories.
+
+        Args:
+            using_key: The instance where the lookup is performed.
+                if "public", the lookup is performed on the public reference.
+        """
+        return CurateLookup(
+            categoricals=self._obs_fields,
+            slots={"columns": self._columns_field, **self._var_fields_flat},
+            using_key=using_key or self._using_key,
+            public=public,
+        )
+
+    def standardize(self, key: str):
+        """Replace synonyms with standardized values.
+
+        Modifies the dataset inplace.
+
+        Args:
+            key: The key referencing the slot in the `tiledbsoma` store.
+                It should be `'{measurement name}__{column name in .var}'` for columns in `.var`
+                or a column name in `.obs`.
+        """
+        if len(self.non_validated) == 0:
+            logger.warning("values are already standardized")
+            return
+        avail_keys = list(self._non_validated_values.keys())
+        if key == "all":
+            keys = avail_keys
+        else:
+            if key not in avail_keys:
+                raise KeyError(
+                    f"'{key!r}' is not a valid key, available keys are: {_format_values(avail_keys + ['all'])}!"
+                )
+            keys = [key]
+
+        for k in keys:
+            values, field = self._non_validated_values_field(k)
+            if len(values) == 0:
+                continue
+            if k in self._valid_var_keys:
+                ms, _, slot_key = k.partition("__")
+                slot = lambda experiment: experiment.ms[ms].var  # noqa: B023
+            else:
+                slot = lambda experiment: experiment.obs
+                slot_key = k
+            # errors if public ontology and the model has no organism
+            # has to be fixed in bionty
+            organism = check_registry_organism(field.field.model, self._organism).get(
+                "organism"
+            )
+            syn_mapper = standardize_categories(
+                values=values,
+                field=field,
+                using_key=self._using_key,
+                source=self._sources.get(k),
+                organism=organism,
+            )
+            if (n_syn_mapper := len(syn_mapper)) == 0:
+                continue
+
+            from lamindb.core.storage._tiledbsoma import _open_tiledbsoma
+
+            with _open_tiledbsoma(self._experiment_uri, mode="r") as experiment:
+                value_filter = f"{slot_key} in {list(syn_mapper.keys())}"
+                table = slot(experiment).read(value_filter=value_filter).concat()
+
+            if len(table) == 0:
+                continue
+
+            df = table.to_pandas()
+            # map values
+            df[slot_key] = df[slot_key].map(
+                lambda val: syn_mapper.get(val, val)  # noqa
+            )
+            # write the mapped values
+            with _open_tiledbsoma(self._experiment_uri, mode="w") as experiment:
+                slot(experiment).write(pa.Table.from_pandas(df, schema=table.schema))
+            # update non_validated dict
+            non_val_k = [
+                nv for nv in self._non_validated_values[k] if nv not in syn_mapper
+            ]
+            self._non_validated_values[k] = non_val_k
+
+            syn_mapper_print = _format_values(
+                [f'"{m_k}" → "{m_v}"' for m_k, m_v in syn_mapper.items()], sep=""
+            )
+            s = "s" if n_syn_mapper > 1 else ""
+            logger.success(
+                f'standardized {n_syn_mapper} synonym{s} in "{k}": {colors.green(syn_mapper_print)}'
+            )
+
+    def save_artifact(
+        self,
+        description: str | None = None,
+        key: str | None = None,
+        revises: Artifact | None = None,
+        run: Run | None = None,
+    ) -> Artifact:
+        """Save the validated `tiledbsoma` store and metadata.
+
+        Args:
+            description: A description of the ``tiledbsoma`` store.
+            key: A path-like key to reference artifact in default storage,
+                e.g., `"myfolder/mystore.tiledbsoma"`. Artifacts with the same key form a revision family.
+            revises: Previous version of the artifact. Triggers a revision.
+            run: The run that creates the artifact.
+
+        Returns:
+            A saved artifact record.
+        """
+        from lamindb.core._data import add_labels
+
+        if not self._validated:
+            self.validate()
+            if not self._validated:
+                raise ValidationError("Dataset does not validate. Please curate.")
+
+        if self._artifact is None:
+            artifact = Artifact(
+                self._experiment_uri,
+                description=description,
+                key=key,
+                revises=revises,
+                run=run,
+            )
+            artifact.n_observations = self._n_obs
+            artifact.otype = "tiledbsoma"
+            artifact.save()
+        else:
+            artifact = self._artifact
+
+        _schemas_m2m = {}
+        if len(self._obs_fields) > 0:
+            organism = check_registry_organism(
+                self._columns_field.field.model, self._organism
+            ).get("organism")
+            empty_dict = {field.name: [] for field in self._obs_pa_schema}  # type: ignore
+            mock_df = pa.Table.from_pydict(
+                empty_dict, schema=self._obs_pa_schema
+            ).to_pandas()
+            # in parallel to https://github.com/laminlabs/lamindb/blob/2a1709990b5736b480c6de49c0ada47fafc8b18d/lamindb/core/_feature_manager.py#L549-L554
+            _schemas_m2m["obs"] = Schema.from_df(
+                df=mock_df,
+                field=self._columns_field,
+                mute=True,
+                organism=organism,
+            )
+        for ms in self._var_fields:
+            var_key, var_field = self._var_fields[ms]
+            organism = check_registry_organism(
+                var_field.field.model, self._organism
+            ).get("organism")
+            _schemas_m2m[f"{ms}__var"] = Schema.from_values(
+                values=self._validated_values[f"{ms}__{var_key}"],
+                field=var_field,
+                organism=organism,
+                raise_validation_error=False,
+            )
+        artifact._staged__schemas_m2m = _schemas_m2m
+
+        feature_ref_is_name = _ref_is_name(self._columns_field)
+        features = Feature.lookup().dict()
+        for key, field in self._obs_fields.items():
+            feature = features.get(key)
+            registry = field.field.model
+            organism = check_registry_organism(field.field.model, self._organism).get(
+                "organism"
+            )
+            labels = registry.from_values(
+                values=self._validated_values[key], field=field, organism=organism
+            )
+            if len(labels) == 0:
+                continue
+            if hasattr(registry, "_name_field"):
+                label_ref_is_name = field.field.name == registry._name_field
+                add_labels(
+                    artifact,
+                    records=labels,
+                    feature=feature,
+                    feature_ref_is_name=feature_ref_is_name,
+                    label_ref_is_name=label_ref_is_name,
+                    from_curator=True,
+                )
+
+        return artifact.save()
+
+
 class Curator(BaseCurator):
     """Dataset curator.
 
@@ -1072,7 +1614,7 @@ class Curator(BaseCurator):
     >>>     categoricals={"perturbation": ln.ULabel.name},  # map categories
     >>> )
     >>> curator.validate()  # validate the data in df
-    >>> artifact = curate.save_artifact(description="my RNA-seq")
+    >>> artifact = curator.save_artifact(description="my RNA-seq")
     >>> artifact.describe()  # see annotations
 
     `curator.validate()` maps values within `df` according to the mapping criteria and logs validated & problematic values.
@@ -1150,6 +1692,105 @@ class Curator(BaseCurator):
             organism=organism,
         )
 
+    @classmethod
+    @doc_args(SOMACurator.__doc__)
+    def from_tiledbsoma(
+        cls,
+        experiment_uri: UPathStr,
+        var_index: dict[str, tuple[str, FieldAttr]],
+        categoricals: dict[str, FieldAttr] | None = None,
+        obs_columns: FieldAttr = Feature.name,
+        using_key: str | None = None,
+        organism: str | None = None,
+        sources: dict[str, Record] | None = None,
+        exclude: dict[str, str | list[str]] | None = None,
+    ) -> SOMACurator:
+        """{}"""  # noqa: D415
+        return SOMACurator(
+            experiment_uri=experiment_uri,
+            var_index=var_index,
+            categoricals=categoricals,
+            obs_columns=obs_columns,
+            using_key=using_key,
+            organism=organism,
+            sources=sources,
+            exclude=exclude,
+        )
+
+    @classmethod
+    def from_spatialdata(
+        cls,
+        sdata: SpatialData,
+        var_index: dict[str, FieldAttr],
+        categoricals: dict[str, dict[str, FieldAttr]] | None = None,
+        using_key: str | None = None,
+        organism: str | None = None,
+        sources: dict[str, dict[str, Record]] | None = None,
+        exclude: dict[str, dict] | None = None,
+        verbosity: str = "hint",
+        *,
+        sample_metadata_key: str = "sample",
+    ) -> SpatialDataCurator:
+        """Curation flow for a ``Spatialdata`` object.
+
+        See also :class:`~lamindb.Curator`.
+
+        Note that if genes or other measurements are removed from the SpatialData object,
+        the object should be recreated.
+
+        In the following docstring, an accessor refers to either a ``.table`` key or the ``sample_metadata_key``.
+
+        Args:
+            sdata: The SpatialData object to curate.
+            var_index: A dictionary mapping table keys to the ``.var`` indices.
+            categoricals: A nested dictionary mapping an accessor to dictionaries that map columns to a registry field.
+            using_key: A reference LaminDB instance.
+            organism: The organism name.
+            sources: A dictionary mapping an accessor to dictionaries that map columns to Source records.
+            exclude: A dictionary mapping an accessor to dictionaries of column names to values to exclude from validation.
+                When specific :class:`~bionty.Source` instances are pinned and may lack default values (e.g., "unknown" or "na"),
+                using the exclude parameter ensures they are not validated.
+            verbosity: The verbosity level of the logger.
+            sample_metadata_key: The key in ``.attrs`` that stores the sample level metadata.
+
+        Examples:
+            >>> import lamindb as ln
+            >>> import bionty as bt
+            >>> curator = ln.Curator.from_spatialdata(
+            ...     sdata,
+            ...     var_index={
+            ...         "table_1": bt.Gene.ensembl_gene_id,
+            ...     },
+            ...     categoricals={
+            ...         "table1":
+            ...             {"cell_type_ontology_id": bt.CellType.ontology_id, "donor_id": ln.ULabel.name},
+            ...         "sample":
+            ...             {"experimental_factor": bt.ExperimentalFactor.name},
+            ...     },
+            ...     organism="human",
+            ... )
+        """
+        try:
+            import spatialdata
+        except ImportError as e:
+            raise ImportError(
+                "Please install spatialdata: pip install spatialdata"
+            ) from e
+
+        from ._spatial import SpatialDataCurator
+
+        return SpatialDataCurator(
+            sdata=sdata,
+            var_index=var_index,
+            categoricals=categoricals,
+            using_key=using_key,
+            verbosity=verbosity,
+            organism=organism,
+            sources=sources,
+            exclude=exclude,
+            sample_metadata_key=sample_metadata_key,
+        )
+
 
 def get_registry_instance(registry: Record, using_key: str | None = None) -> Record:
     """Get a registry instance using a specific instance."""
@@ -1253,7 +1894,7 @@ def validate_categories(
         standardize: Whether to standardize the values.
         hint_print: The hint to print that suggests fixing non-validated values.
     """
-    from lamindb._from_values import _print_values
+    from lamindb._from_values import _format_values
     from lamindb.core._settings import settings
 
     model_field = f"{field.field.model.__name__}.{field.field.name}"
@@ -1315,22 +1956,17 @@ def validate_categories(
     non_validated = [i for i in non_validated if i not in values_validated]
     n_non_validated = len(non_validated)
     if n_non_validated == 0:
-        if len(values_validated) == 0:
-            # nothing to validate
-            logger.indent = ""
-            logger.success(f'"{key}" is validated against {colors.italic(model_field)}')
-            return True, []
-        else:
-            # validated values still need to be saved to the current instance
-            return False, []
+        logger.indent = ""
+        logger.success(f'"{key}" is validated against {colors.italic(model_field)}')
+        return True, []
     else:
         are = "is" if n_non_validated == 1 else "are"
         s = "" if n_non_validated == 1 else "s"
-        print_values = _print_values(non_validated)
+        print_values = _format_values(non_validated)
         warning_message = f"{colors.red(f'{n_non_validated} term{s}')} {are} not validated: {colors.red(print_values)}\n"
         if syn_mapper:
             s = "" if len(syn_mapper) == 1 else "s"
-            syn_mapper_print = _print_values(
+            syn_mapper_print = _format_values(
                 [f'"{k}" → "{v}"' for k, v in syn_mapper.items()], sep=""
             )
             hint_msg = f'.standardize("{key}")'
@@ -1445,8 +2081,8 @@ def save_artifact(
     Returns:
         The saved Artifact.
     """
-    from ._artifact import data_is_anndata
-    from .core._data import add_labels
+    from .._artifact import data_is_anndata
+    from ..core._data import add_labels
 
     artifact = None
     if data_is_anndata(data):
@@ -1489,13 +2125,13 @@ def save_artifact(
         organism,
     )
 
-    if artifact._accessor == "DataFrame":
+    if artifact.otype == "DataFrame":
         artifact.features._add_set_from_df(field=columns_field, **feature_kwargs)
-    elif artifact._accessor == "AnnData":
+    elif artifact.otype == "AnnData":
         artifact.features._add_set_from_anndata(
             var_field=columns_field, **feature_kwargs
         )
-    elif artifact._accessor == "MuData":
+    elif artifact.otype == "MuData":
         artifact.features._add_set_from_mudata(
             var_fields=columns_field, **feature_kwargs
         )
@@ -1515,25 +2151,31 @@ def save_artifact(
             filter_kwargs = check_registry_organism(registry, organism)
             filter_kwargs_current = get_current_filter_kwargs(registry, filter_kwargs)
             df = data if isinstance(data, pd.DataFrame) else data.obs
+            # multi-value columns are separated by "|"
+            if df[key].str.contains("|").any():
+                values = df[key].str.split("|").explode().unique()
+            else:
+                values = df[key].unique()
             labels = registry.from_values(
-                df[key],
+                values,
                 field=field,
                 **filter_kwargs_current,
             )
             if len(labels) == 0:
                 continue
+            label_ref_is_name = None
             if hasattr(registry, "_name_field"):
                 label_ref_is_name = field.field.name == registry._name_field
-                add_labels(
-                    artifact,
-                    records=labels,
-                    feature=feature,
-                    feature_ref_is_name=feature_ref_is_name,
-                    label_ref_is_name=label_ref_is_name,
-                    from_curator=True,
-                )
+            add_labels(
+                artifact,
+                records=labels,
+                feature=feature,
+                feature_ref_is_name=feature_ref_is_name,
+                label_ref_is_name=label_ref_is_name,
+                from_curator=True,
+            )
 
-    if artifact._accessor == "MuData":
+    if artifact.otype == "MuData":
         for modality, modality_fields in fields.items():
             column_field_modality = columns_field.get(modality)
             if modality == "obs":
@@ -1616,6 +2258,7 @@ def update_registry(
     registry = field.field.model
     filter_kwargs = check_registry_organism(registry, organism)
     filter_kwargs.update({"source": source} if source else {})
+    values = [i for i in values if isinstance(i, str) and i]
     if not values:
         return
 
@@ -1710,7 +2353,7 @@ def log_saved_labels(
     validated_only: bool = True,
 ) -> None:
     """Log the saved labels."""
-    from ._from_values import _print_values
+    from .._from_values import _format_values
 
     model_field = colors.italic(model_field)
     for k, labels in labels_saved.items():
@@ -1724,7 +2367,7 @@ def log_saved_labels(
             # labels from a public ontology or a different instance to the present instance
             s = "s" if len(labels) > 1 else ""
             logger.success(
-                f'added {len(labels)} record{s} {k}with {model_field} for "{key}": {_print_values(labels)}'
+                f'added {len(labels)} record{s} {k}with {model_field} for "{key}": {_format_values(labels)}'
             )
 
 
@@ -1800,7 +2443,7 @@ def _save_organism(name: str):
 
 def _ref_is_name(field: FieldAttr) -> bool | None:
     """Check if the reference field is a name field."""
-    from ._can_curate import get_name_field
+    from .._can_curate import get_name_field
 
     name_field = get_name_field(field.field.model)
     return field.field.name == name_field