plexora 0.0.1__py3-none-any.whl

plexora/server/models/adapters/anndata_adapter.py

@@ -0,0 +1,388 @@
+from __future__ import annotations
+
+import numpy as np
+import polars as pl
+
+from .base import MetadataColumn, NormalizedDatasource
+
+# Column name used to hold the resolved observation ID (adata.obs_names, or a
+# custom obs column when `obs_id_field` is set) in the materialized table,
+# when the caller doesn't provide an explicit obs_id_field. data_model.py's
+# gating/query code (e.g. get_channel_cells) treats config['featureData'][0]
+# ['idField'] as a literal column name that must exist in the loaded table --
+# unlike CSV, AnnData has no single "the ID column" without this fallback.
+DEFAULT_ID_COLUMN = "obs_id"
+
+# These three column names are load-bearing: 'id' is the positional row index
+# every downstream gating/query function keys off, 'X'/'Y' are the resolved
+# coordinate columns. If a real obs column (e.g. a literal "id" column, seen
+# in real exemplar data) were used as obs_id_field/celltype without this
+# guard, it would silently overwrite one of these dict keys when the table is
+# built below -- corrupting the positional id or coordinates rather than
+# raising. See _reject_reserved_collisions().
+_RESERVED_COLUMN_NAMES = {"id", "X", "Y"}
+
+# The "does this column identify an image/sample/region" heuristic lives in
+# classify.py, which owns every column-name vocabulary in one place. Re-exported
+# here because this module is where the ambiguity guard below enforces it, and
+# adapters/inspection.py has always imported it from this name.
+from .classify import is_likely_image_identifier_name  # noqa: F401
+from .classify import is_numeric_dtype
+
+
+def describe_obsm(adata) -> list[dict]:
+    """Each obsm array as {"name", "shape"}.
+
+    Lives here rather than in inspection.py because both this adapter and that
+    module need it, and inspection already imports from this direction --
+    the reverse would be a cycle.
+
+    Shape is read off the array's own metadata, never by materializing it: a
+    backed h5ad and a zarr group both report it without a read, and an
+    embedding on a million-cell table is not something to load in order to
+    label a dropdown. An entry whose shape cannot be determined still appears,
+    without one -- leaving it out would hide a candidate, which is the failure
+    this list exists to prevent.
+    """
+    entries = []
+    for name in adata.obsm.keys():
+        if not name:
+            continue
+        entry = {"name": str(name)}
+        shape = getattr(adata.obsm[name], "shape", None)
+        if shape is not None:
+            entry["shape"] = [int(dim) for dim in shape]
+        entries.append(entry)
+    return entries
+
+
+def _likely_image_identifier_columns(adata) -> list[str]:
+    candidates = []
+    for column in adata.obs.columns:
+        if not is_likely_image_identifier_name(column):
+            continue
+        if adata.obs[column].nunique(dropna=True) > 1:
+            candidates.append(column)
+    return candidates
+
+
+def _deduplicate_names(names: list[str]) -> list[str]:
+    """Real multiplexed-imaging panels commonly re-stain/re-image the same
+    marker across cycles (e.g. PTPRC/CD45 twice), producing duplicate
+    adata.var_names -- confirmed against real exemplar data. Auto-suffixing
+    (matching anndata's own var_names_make_unique() convention) is more
+    useful than hard-failing on a very ordinary occurrence.
+    """
+    seen: dict[str, int] = {}
+    result = []
+    for name in names:
+        if name not in seen:
+            seen[name] = 0
+            result.append(name)
+        else:
+            seen[name] += 1
+            result.append(f"{name}_{seen[name]}")
+    return result
+
+
+class AnnDataAdapter:
+    """Adapter for AnnData (.h5ad)-backed datasources.
+
+    Takes the project's DataSpec (server/models/project.py). `coordinates`,
+    `features` and `subset` are the read spec -- how to get from the file to a
+    table -- and are the adapter's own vocabulary; the project record stores
+    them without interpreting them. Roles describe the table that comes out.
+
+    The table this produces always has a positional 'id' column plus 'X'/'Y',
+    which is why those three names are reserved below.
+    """
+
+    def __init__(self, spec):
+        self.spec = spec
+        self.path = spec.src
+        self.coordinates = dict(spec.coordinates or {})
+        self.features = dict(spec.features or {}) or {'source': 'X'}
+        self.subset = dict(spec.subset or {})
+        self.celltype_column = spec.roles.celltype
+        # The obs column the user named as the image identifier, if they did.
+        # An answer beats the name heuristic below: it is the only way to catch
+        # a table keyed on a column called "roi" or "core", which the heuristic
+        # does not recognise and would wave through.
+        self.image_id_column = spec.roles.image_id
+        # Which obs column supplies the identifier, or None for the positional
+        # row index (the default -- see the uint32-packing note in
+        # datasource.py). Deliberately read from the read spec rather than
+        # inferred from the cell_id role: an obs column literally named "id"
+        # exists in real data, and it must hit the reserved-name guard below
+        # rather than being mistaken for "just number the rows".
+        self.obs_id_field = spec.obs_id_field
+        # Explicit opt-in only -- no heuristic guessing at whether the
+        # chosen feature source "looks" already transformed. Same contract and
+        # same transform as CsvAdapter, so a threshold means the same thing
+        # whichever format the project was imported from.
+        self.apply_log_transform = bool(spec.is_transformed)
+
+    def _read_adata(self):
+        """The one format-specific step in load_table() -- everything after
+        this point is plain AnnData manipulation and is shared verbatim by
+        SpatialDataAdapter, which overrides only this method (see
+        adapters/spatialdata_adapter.py)."""
+        import anndata as ad
+
+        return ad.read_h5ad(self.path)
+
+    def _read_obs(self):
+        """adata.obs on its own, as a pandas DataFrame.
+
+        Deliberately not `self._read_adata().obs`: that materializes X, which is
+        the expensive part of the file and the one part a metadata column can
+        never need. Reading the obs element alone turns "colour cells by a
+        phenotype column" from a full re-import into a directory read.
+
+        `anndata.io.read_elem` is the public reader for one element of an
+        on-disk AnnData; the private path is the fallback for older versions,
+        matching what the ROI plugin's exporter does against the same files.
+        """
+        import h5py
+
+        try:
+            from anndata.io import read_elem  # anndata >= 0.10, public API
+        except ImportError:  # pragma: no cover - older anndata
+            from anndata._io.specs import read_elem
+
+        with h5py.File(self.path, "r") as handle:
+            return read_elem(handle["obs"])
+
+    def _subset_mask(self, obs):
+        """The rows load_table() keeps, or None when it keeps every row.
+
+        The single source of truth for the subset, so anything reading obs
+        outside load_table() lands on the same cells. Getting this wrong is not
+        a visible error -- the values simply belong to different cells than the
+        ones on screen, shifted by however many rows the other image contributed.
+        """
+        column = self.subset.get('column')
+        if not column:
+            return None
+        if column not in obs.columns:
+            raise ValueError(f"Subset column {column!r} not found in adata.obs")
+        value = self.subset.get('value')
+        mask = obs[column].astype(str).to_numpy() == str(value)
+        if not mask.any():
+            raise ValueError(f"No observations match {column}={value!r}")
+        return mask
+
+    def read_obs_column(self, name: str) -> MetadataColumn:
+        """One obs column, subset the same way the loaded table was.
+
+        Raises KeyError for a column the file does not have, which is how the
+        caller tells "no such column" from "this format has nothing to add"
+        (CsvAdapter returns None for the latter).
+        """
+        obs = self._read_obs()
+        if name not in obs.columns:
+            raise KeyError(name)
+        column = obs[name]
+        mask = self._subset_mask(obs)
+        if mask is not None:
+            column = column[mask]
+
+        categories = None
+        if hasattr(column, "cat"):
+            # The file's own level order (see MetadataColumn.categories). Taken
+            # before the values are flattened to strings, which is the only
+            # moment it still exists.
+            categories = tuple(str(level) for level in column.cat.categories)
+            column = column.astype(object)
+        values = column.to_numpy()
+        return MetadataColumn(name=name, values=values, categories=categories)
+
+    def load_table(self) -> NormalizedDatasource:
+        adata = self._read_adata()
+
+        subset_column = self.subset.get('column')
+        if subset_column:
+            mask = self._subset_mask(adata.obs)
+            adata = adata[mask].copy()
+        else:
+            named = self.image_id_column
+            if named and named in adata.obs.columns:
+                # The user told us which column identifies the image, so ask
+                # that column rather than guessing which one to ask. This is
+                # the check the name heuristic below cannot make: it only fires
+                # for conventionally-named columns, so a table keyed on "roi"
+                # or "core" loaded whole and drew several images' cells over
+                # one image, with nothing said.
+                images = adata.obs[named].astype(str).nunique(dropna=True)
+                if images > 1:
+                    raise ValueError(
+                        f"Column {named!r} covers {images} images, but no "
+                        "subset was specified -- loading them all would draw "
+                        "several images' cells over one image. Choose which "
+                        "image to load."
+                    )
+            else:
+                ambiguous = _likely_image_identifier_columns(adata)
+                if ambiguous:
+                    raise ValueError(
+                        "AnnData object has candidate image/sample identifier "
+                        f"column(s) {ambiguous} with more than one distinct "
+                        "value, but no subset was specified -- refusing to "
+                        "silently load all observations. Set dataSource.subset "
+                        "(or subset_by/subset_value) to pick one image/sample."
+                    )
+
+        n_obs = adata.n_obs
+        if n_obs == 0:
+            raise ValueError("Resolved AnnData subset has zero observations")
+
+        x_values, y_values = self._resolve_coordinates(adata)
+        if not np.isfinite(x_values).all() or not np.isfinite(y_values).all():
+            raise ValueError("Resolved X/Y coordinates contain non-finite values")
+
+        feature_matrix, feature_names = self._resolve_features(adata)
+
+        if self.obs_id_field:
+            if self.obs_id_field not in adata.obs.columns:
+                raise ValueError(f"obs_id_field {self.obs_id_field!r} not found in adata.obs")
+            if self.obs_id_field in _RESERVED_COLUMN_NAMES:
+                raise ValueError(
+                    f"obs_id_field {self.obs_id_field!r} collides with a reserved "
+                    f"column name ({sorted(_RESERVED_COLUMN_NAMES)}) -- choose a "
+                    "different observation ID column, or leave it unset to use "
+                    "adata.obs_names."
+                )
+            column = adata.obs[self.obs_id_field]
+            # A numeric obs column stays numeric. The usual reason to name one
+            # here is that it holds the segmentation mask's own label values,
+            # and the centroid cache packs the cell id into a uint32 -- a
+            # stringified integer only survives that round trip by being parsed
+            # back out again. adata.obs_names below has no such expectation and
+            # is genuinely text, so it keeps the str cast.
+            id_values = (column.to_numpy() if is_numeric_dtype(column.dtype)
+                         else column.astype(str).to_numpy())
+            id_field_name = self.obs_id_field
+        else:
+            id_values = np.asarray([str(v) for v in adata.obs_names])
+            id_field_name = DEFAULT_ID_COLUMN
+
+        feature_names = _deduplicate_names(feature_names)
+        reserved = _RESERVED_COLUMN_NAMES | {id_field_name}
+        collisions = [name for name in feature_names if name in reserved]
+        if collisions:
+            raise ValueError(f"Feature name(s) collide with reserved columns: {collisions}")
+
+        columns = {
+            "id": np.arange(n_obs, dtype=np.int64),
+            "X": x_values,
+            "Y": y_values,
+            id_field_name: id_values,
+        }
+        for i, feature_name in enumerate(feature_names):
+            values = feature_matrix[:, i].astype(np.float64)
+            values = np.where(np.isneginf(values), 0.0, values)
+            if self.apply_log_transform:
+                values = np.log1p(values)
+            columns[feature_name] = values
+
+        celltype_column = None
+        if self.celltype_column:
+            if self.celltype_column not in adata.obs.columns:
+                raise ValueError(f"celltype column {self.celltype_column!r} not found in adata.obs")
+            if self.celltype_column in reserved:
+                raise ValueError(
+                    f"celltype column {self.celltype_column!r} collides with a "
+                    f"reserved/ID column name -- choose a different column."
+                )
+            columns[self.celltype_column] = adata.obs[self.celltype_column].astype(str).to_numpy()
+            celltype_column = self.celltype_column
+
+        table = pl.DataFrame(columns)
+        source_obs_ids = [str(v) for v in adata.obs_names]
+
+        return NormalizedDatasource(
+            table=table,
+            id_column="id",
+            source_obs_ids=source_obs_ids,
+            x_column="X",
+            y_column="Y",
+            feature_columns=list(feature_names),
+            celltype_column=celltype_column,
+            obs_columns=[str(c) for c in adata.obs.columns],
+            # anndata's Layers mapping can report a spurious `None` key
+            # (observed with anndata 0.13.2) even when no such layer exists --
+            # filtered out here the same way adapters/inspection.py does.
+            layers=[str(k) for k in adata.layers.keys() if k],
+            # Recorded so the coordinate question has candidates to offer
+            # without reopening the file. Same codec as inspection's, so the
+            # import path and the edit page describe an array identically.
+            obsm=describe_obsm(adata),
+        )
+
+    def _resolve_coordinates(self, adata):
+        source = self.coordinates.get('source')
+        if source is None:
+            if 'spatial' not in adata.obsm:
+                raise ValueError(
+                    "No coordinate source specified and adata.obsm['spatial'] "
+                    "is absent -- set dataSource.coordinates (coordinate_source"
+                    "='obsm'/'obs' plus the relevant keys/columns) explicitly."
+                )
+            source, obsm_key = 'obsm', 'spatial'
+        else:
+            obsm_key = self.coordinates.get('obsm_key')
+
+        if source == 'obsm':
+            obsm_key = obsm_key or 'spatial'
+            if obsm_key not in adata.obsm:
+                raise ValueError(f"obsm key {obsm_key!r} not found in adata.obsm")
+            xy = np.asarray(adata.obsm[obsm_key])
+            if xy.ndim != 2 or xy.shape[1] < 2:
+                raise ValueError(f"adata.obsm[{obsm_key!r}] must be 2D with at least 2 columns")
+            return xy[:, 0].astype(np.float64), xy[:, 1].astype(np.float64)
+
+        if source == 'obs':
+            x_col = self.coordinates.get('x_column')
+            y_col = self.coordinates.get('y_column')
+            if not x_col or not y_col:
+                raise ValueError(
+                    "dataSource.coordinates.x_column/y_column are required "
+                    "when coordinates.source='obs'"
+                )
+            if x_col not in adata.obs.columns or y_col not in adata.obs.columns:
+                raise ValueError(f"Coordinate columns {x_col!r}/{y_col!r} not found in adata.obs")
+            x_values = adata.obs[x_col].to_numpy(dtype=np.float64)
+            y_values = adata.obs[y_col].to_numpy(dtype=np.float64)
+            return x_values, y_values
+
+        raise ValueError(f"Unknown coordinates.source: {source!r}")
+
+    def _resolve_features(self, adata):
+        source = self.features.get('source', 'X')
+        if source == 'X':
+            matrix = adata.X
+            names = [str(v) for v in adata.var_names]
+        elif source == 'layer':
+            layer = self.features.get('layer')
+            if not layer:
+                raise ValueError("dataSource.features.layer is required when features.source='layer'")
+            if layer not in adata.layers:
+                raise ValueError(f"Layer {layer!r} not found in adata.layers")
+            matrix = adata.layers[layer]
+            names = [str(v) for v in adata.var_names]
+        elif source == 'obs':
+            obs_columns = self.features.get('obs_columns') or []
+            if not obs_columns:
+                raise ValueError("dataSource.features.obs_columns is required when features.source='obs'")
+            missing = [c for c in obs_columns if c not in adata.obs.columns]
+            if missing:
+                raise ValueError(f"obs feature columns not found in adata.obs: {missing}")
+            matrix = adata.obs[obs_columns].to_numpy(dtype=np.float64)
+            names = list(obs_columns)
+        else:
+            raise ValueError(f"Unknown features.source: {source!r}")
+
+        if hasattr(matrix, 'toarray'):
+            matrix = matrix.toarray()
+        matrix = np.asarray(matrix, dtype=np.float64)
+        return matrix, names

plexora/server/models/adapters/base.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Protocol
+
+import numpy as np
+import polars as pl
+
+
+@dataclass(frozen=True)
+class MetadataColumn:
+    """One annotation column, aligned row-for-row with the loaded table.
+
+    Exists because `NormalizedDatasource.table` is deliberately narrow for the
+    structural formats: AnnDataAdapter materializes id/X/Y/the id field/the
+    markers/the celltype column and nothing else, so an arbitrary `.obs` column
+    is named by `obs_columns` but is not IN the table. A tool that colours cells
+    by an annotation needs the values, and re-reading the whole file to get one
+    column would cost the same as the import did.
+
+    `categories` is the source's own category order when it declares one -- a
+    pandas Categorical in obs. It is carried rather than re-derived because it
+    is the one ordering that cannot be recovered from the values: a legend
+    sorted alphabetically puts "Stage 10" before "Stage 2", and a file that
+    already says what order its levels go in should be believed. None means the
+    source said nothing, and the caller is free to sort.
+    """
+
+    name: str
+    values: np.ndarray
+    categories: tuple[str, ...] | None = None
+
+
+@dataclass(frozen=True)
+class NormalizedDatasource:
+    """Source-agnostic view of an observation/cell table.
+
+    `table` always carries a positional 'id' column plus the resolved
+    x/y/feature/celltype columns under the exact names data_model.py's
+    downstream gating/query code already expects (the same names stored in
+    config[...]['featureData'][0]['xCoordinate']/['yCoordinate']/etc.) --
+    adapters differ only in how they produce this table, never in its shape.
+    """
+
+    table: pl.DataFrame
+    id_column: str
+    source_obs_ids: list[str]
+    x_column: str
+    y_column: str
+    feature_columns: list[str]
+    celltype_column: str | None
+    obs_metadata: pl.DataFrame | None = None
+    # The two below describe what else the SOURCE offers -- not what this table
+    # ended up holding. They exist for adapters that build `table` from a read
+    # spec rather than reading a file verbatim, and they are what a user later
+    # picks from when changing that spec. Both are empty for a CSV, where the
+    # table's columns already are the file's columns and there is one matrix.
+
+    #: The source file's own annotation column names, in its own order. What a
+    #: user chooses between when saying which column holds the cell id or the
+    #: coordinates -- see Project.role_columns.
+    obs_columns: list[str] = field(default_factory=list)
+    #: The names of the extra expression matrices the file carries alongside
+    #: `X`. What a user chooses between when saying which one holds the marker
+    #: intensities -- see Project.feature_source.
+    layers: list[str] = field(default_factory=list)
+    #: The source file's obsm arrays as {"name", "shape"}. What a user chooses
+    #: between when saying where the cell coordinates are -- see
+    #: Project.coordinate_options. The shape is carried because it is the only
+    #: other thing on offer, and even it cannot separate a position from an
+    #: embedding: `spatial` and `X_umap` are routinely both (n, 2) float32.
+    obsm: list[dict] = field(default_factory=list)
+
+
+class DatasourceAdapter(Protocol):
+    """One instance per (config entry, load). Stateless with respect to
+    data_model.py's module globals -- an adapter only knows how to turn a
+    featureData config dict into a NormalizedDatasource. All I/O happens in
+    load_table(), called once per load_datasource().
+    """
+
+    def load_table(self) -> NormalizedDatasource: ...
+
+    def read_obs_column(self, name: str) -> MetadataColumn | None:
+        """One annotation column the loaded table does not carry.
+
+        None means "there is no such thing here" rather than "not found": a CSV
+        adapter's table IS the file, so every column is already in `frame()` and
+        there is nothing this could add. Adapters that build a table from a read
+        spec return the values, subset exactly as `load_table()` subset them, so
+        the result lines up row-for-row with the loaded frame.
+        """
+        ...

plexora/server/models/adapters/classify.py

@@ -0,0 +1,192 @@
+"""Which columns are markers, and which are metadata.
+
+This used to be answered in five places that disagreed: three hardcoded
+denylists (`import_routes.listNotMarkers`, `datasource._default_marker_columns`,
+`channelMatch.js markers_notToTransform`) and two independent "numeric column
+that produced a histogram" derivations (`api/dataset.TableHandle.markers`,
+`datasetContext.js`). Adding a morphology column meant remembering all of them.
+
+It is one question about the imported data, so it gets one answer, computed
+once at import and stored on the project (`DataSpec.columns`). Everything
+downstream reads the stored answer rather than re-deriving it.
+
+The prediction is a starting point, not a verdict -- for CSV the user confirms
+it on the classification screen and drags anything we got wrong. Being roughly
+right matters much more than being subtly clever, so the rules are blunt and
+name-based, and deliberately biased towards calling a column metadata: a
+metadata column wrongly offered as a marker shows up as a nonsense histogram in
+every plugin, while a marker wrongly filed as metadata is one drag away.
+
+Stdlib only, on purpose. `anndata_adapter` imports the name heuristics from
+here rather than the other way round, so nothing that merely wants to classify
+column names pays for numpy/polars/anndata.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Iterable, Mapping
+
+# Conventional names for the column identifying which image/sample/region an
+# observation belongs to. Also used by AnnDataAdapter to decide whether a file
+# might span several images and therefore needs an explicit subset choice --
+# deliberately not "any categorical column", since cell_type/cluster/condition
+# are common in ordinary single-image data and must not trigger that.
+_LIKELY_IMAGE_IDENTIFIER_NAMES = {
+    "imageid", "image", "sample", "sampleid", "region", "regionid",
+    "roi", "fov", "well", "slide", "core",
+}
+
+# Non-marker columns a quantification table conventionally carries. Matched
+# against the normalized name, so "X_centroid", "x centroid" and "XCentroid"
+# are one entry. Grouped by what they are, because that is how they get
+# extended.
+_METADATA_NAMES = {
+    # identity
+    "id", "cellid", "cellindex", "objectid", "object", "label", "index",
+    # position
+    "x", "y", "xcentroid", "ycentroid", "centroidx", "centroidy",
+    "xposition", "yposition", "xcoordinate", "ycoordinate",
+    "columncentroid", "rowcentroid", "column", "row", "globalx", "globaly",
+    # morphology
+    "area", "convexarea", "filledarea", "bboxarea", "perimeter",
+    "majoraxislength", "minoraxislength", "axismajorlength", "axisminorlength",
+    "eccentricity", "solidity", "extent", "orientation", "circularity",
+    "equivalentdiameter", "feretdiametermax", "eulernumber", "formfactor",
+    "elongation", "compactness", "roundness", "aspectratio",
+    # annotation
+    "phenotype", "celltype", "cluster", "leiden", "louvain", "condition",
+    "treatment", "patient", "donor", "batch", "replicate", "timepoint",
+} | _LIKELY_IMAGE_IDENTIFIER_NAMES
+
+# Suffixes that mark a column as a derived measurement of something rather
+# than an intensity: "CD3_area", "DNA1_orientation". Checked after the exact
+# names above so a marker literally called "Area" still resolves.
+_METADATA_SUFFIXES = (
+    "centroid", "area", "perimeter", "eccentricity", "solidity", "extent",
+    "orientation", "axislength", "diameter", "circularity",
+)
+
+#: Role -> ordered patterns, most specific first. The first column matching the
+#: earliest pattern wins, so "X_centroid" beats a bare "X" for the x role but a
+#: table with only "X" still resolves.
+_ROLE_PATTERNS = {
+    "cell_id": (r"^cellid$", r"^cellindex$", r"^objectid$", r"^cell$", r"^label$", r"^id$"),
+    "x": (r"^xcentroid$", r"^centroidx$", r"^xposition$", r"^xcoordinate$",
+          r"^columncentroid$", r"^globalx$", r"^x$"),
+    "y": (r"^ycentroid$", r"^centroidy$", r"^yposition$", r"^ycoordinate$",
+          r"^rowcentroid$", r"^globaly$", r"^y$"),
+    "celltype": (r"^phenotype$", r"^celltype$", r"^cluster$", r"^leiden$"),
+    "image_id": tuple(rf"^{re.escape(name)}$" for name in sorted(_LIKELY_IMAGE_IDENTIFIER_NAMES)),
+}
+
+_NUMERIC_DTYPE = re.compile(r"int|float|double|number", re.IGNORECASE)
+
+
+def normalize_column_name(name: Any) -> str:
+    """Strip separators and case so the name vocabularies above stay short."""
+    return re.sub(r"[\s_\-.]+", "", str(name)).lower()
+
+
+def is_likely_image_identifier_name(column_name: Any) -> bool:
+    """Whether a column name looks like it identifies an image/sample/region."""
+    return normalize_column_name(column_name) in _LIKELY_IMAGE_IDENTIFIER_NAMES
+
+
+def is_numeric_dtype(dtype: Any) -> bool:
+    """Whether a reported dtype string is numeric.
+
+    Takes the string rather than the dtype object so this works for polars,
+    numpy and pandas alike, and so a caller with only a JSON payload (the
+    client sends dtypes as strings) gets the same answer.
+    """
+    return bool(_NUMERIC_DTYPE.search(str(dtype or "")))
+
+
+def looks_like_metadata(name: Any, dtype: Any = None) -> bool:
+    """Whether one column should start life in the metadata box."""
+    normalized = normalize_column_name(name)
+    if not normalized:
+        return True
+    if dtype is not None and not is_numeric_dtype(dtype):
+        # A marker is an intensity. Anything non-numeric is an annotation,
+        # whatever it is called.
+        return True
+    if normalized in _METADATA_NAMES:
+        return True
+    return any(normalized.endswith(suffix) for suffix in _METADATA_SUFFIXES)
+
+
+def guess_roles(columns: Iterable[Any]) -> dict:
+    """Best guess at which column fills each role.
+
+    Returns only the roles it is confident about; an unresolved role is simply
+    absent, which the project record stores as None and something may later ask
+    the user to fill in.
+    """
+    names = [str(c) for c in columns]
+    by_normalized = {}
+    for name in names:
+        by_normalized.setdefault(normalize_column_name(name), name)
+
+    roles = {}
+    taken = set()
+    for role, patterns in _ROLE_PATTERNS.items():
+        for pattern in patterns:
+            match = next(
+                (original for normalized, original in by_normalized.items()
+                 if original not in taken and re.match(pattern, normalized)),
+                None,
+            )
+            if match is not None:
+                roles[role] = match
+                taken.add(match)
+                break
+    return roles
+
+
+def classify_columns(columns: Iterable[Mapping[str, Any] | str]) -> dict:
+    """Split columns into markers and metadata, and guess the column roles.
+
+    `columns` is either bare names or `{"name": ..., "dtype": ...}` mappings;
+    supplying dtypes makes the split markedly better, since every non-numeric
+    column is metadata regardless of its name.
+
+    Returns `{"markers": [...], "metadata": [...], "roles": {...}}` with the
+    input order preserved inside each group -- a table's own column order is
+    usually meaningful to whoever produced it, and reordering makes the
+    classification screen harder to check.
+    """
+    names, dtypes = [], {}
+    for column in columns or ():
+        if isinstance(column, Mapping):
+            name = column.get("name")
+            if name is None:
+                continue
+            names.append(str(name))
+            dtypes[str(name)] = column.get("dtype")
+        else:
+            names.append(str(column))
+            dtypes[str(column)] = None
+
+    metadata = [n for n in names if looks_like_metadata(n, dtypes.get(n))]
+    metadata_set = set(metadata)
+    markers = [n for n in names if n not in metadata_set]
+    return {"markers": markers, "metadata": metadata, "roles": guess_roles(names)}
+
+
+def classify_from_inspection(inspection: Mapping[str, Any]) -> dict:
+    """The split for an AnnData or SpatialData table, taken from its structure.
+
+    `var_names` are markers and `obs` columns are metadata by construction --
+    the file already draws the line this screen exists to draw for CSV, so the
+    user is never asked to confirm it. Roles are still guessed from the obs
+    names, since which obs column holds the cell id is not structural.
+    """
+    obs_columns = inspection.get("obs_columns") or []
+    obs_names = [c.get("name") for c in obs_columns if isinstance(c, Mapping) and c.get("name")]
+    return {
+        "markers": [str(v) for v in (inspection.get("var_names") or ())],
+        "metadata": [str(n) for n in obs_names],
+        "roles": guess_roles(obs_names),
+    }