alhena 0.1.0__py3-none-any.whl

alhena/__init__.py

@@ -0,0 +1,148 @@
+"""ALHENA, an H&E encoder distilled from transcriptomic foundation models
+for multi-scale slide analysis.
+"""
+
+from __future__ import annotations
+
+# Loaded with the package so the readers are reached as alhena.io; it imports nothing new.
+from alhena import io as io
+from alhena._constants import (
+    BACKBONE_NATIVE_MPP,
+    CLASS_AXES,
+    CLASS_COLORS,
+    COMPARTMENT_V1,
+    DEFAULT_AXIS,
+    DEFAULT_K,
+    DEFAULT_TAU,
+    INPUT_SIZE,
+    LINEAGE_V1,
+    PATCH_SIZE,
+    REFERENCE_MPP,
+    RETRIEVAL_DEPTH,
+    TISSUE_ALIASES,
+    TISSUE_TO_SHARD,
+    label_order,
+)
+from alhena._errors import (
+    AlhenaError,
+    AlhenaValueError,
+    AlhenaWarning,
+    BackboneNotFoundError,
+    BundleError,
+    CellSpaceMismatchError,
+    EnvelopeWarning,
+    GeometryError,
+    GeometryWarning,
+    MembershipError,
+    MissingExtraError,
+    ReferenceCoverageWarning,
+    ReferenceError,
+)
+from alhena._version import __version__ as __version__
+from alhena.annotate import annotate_cells, retrieve, vote
+from alhena.api import CellTyper, load_celltyper, load_encoder
+from alhena.cells import (
+    membership_from_centroids,
+    membership_from_labels,
+    membership_from_polygons,
+    pool_cells,
+    validate_membership,
+)
+from alhena.encoder import AlhenaEncoder, load_bundle
+from alhena.metrics import align_truth, chance_floor, confidence_sweep, score
+from alhena.preprocess import describe_geometry, prepare_tiles
+from alhena.refbuild import (
+    ShardBuildReport,
+    build_reference,
+    is_user_built,
+    read_scconcept_embeddings,
+)
+from alhena.reference import (
+    Reference,
+    available_shards,
+    available_tissues,
+    describe_shard,
+    load_reference,
+    shard_for_tissue,
+)
+from alhena.types import (
+    AnnotationResult,
+    BundleInfo,
+    CellEmbeddings,
+    GeometryReport,
+    ReferenceInfo,
+    ResampleInfo,
+    ScoreReport,
+    SelfCheckReport,
+    TileEmbeddings,
+)
+
+__all__ = [
+    "BACKBONE_NATIVE_MPP",
+    "CLASS_AXES",
+    "CLASS_COLORS",
+    "COMPARTMENT_V1",
+    "DEFAULT_AXIS",
+    "DEFAULT_K",
+    "DEFAULT_TAU",
+    "INPUT_SIZE",
+    "LINEAGE_V1",
+    "PATCH_SIZE",
+    "REFERENCE_MPP",
+    "RETRIEVAL_DEPTH",
+    "TISSUE_ALIASES",
+    "TISSUE_TO_SHARD",
+    "AlhenaEncoder",
+    "AlhenaError",
+    "AlhenaValueError",
+    "AlhenaWarning",
+    "AnnotationResult",
+    "BackboneNotFoundError",
+    "BundleError",
+    "BundleInfo",
+    "CellEmbeddings",
+    "CellSpaceMismatchError",
+    "CellTyper",
+    "EnvelopeWarning",
+    "GeometryError",
+    "GeometryReport",
+    "GeometryWarning",
+    "MembershipError",
+    "MissingExtraError",
+    "Reference",
+    "ReferenceCoverageWarning",
+    "ReferenceError",
+    "ReferenceInfo",
+    "ResampleInfo",
+    "ScoreReport",
+    "SelfCheckReport",
+    "ShardBuildReport",
+    "TileEmbeddings",
+    "__version__",
+    "align_truth",
+    "annotate_cells",
+    "available_shards",
+    "available_tissues",
+    "build_reference",
+    "chance_floor",
+    "confidence_sweep",
+    "describe_geometry",
+    "describe_shard",
+    "is_user_built",
+    "label_order",
+    "load_bundle",
+    "load_celltyper",
+    "load_encoder",
+    "load_reference",
+    "membership_from_centroids",
+    "membership_from_labels",
+    "membership_from_polygons",
+    "pool_cells",
+    "prepare_tiles",
+    "read_scconcept_embeddings",
+    "retrieve",
+    "score",
+    "shard_for_tissue",
+    "validate_membership",
+    "vote",
+]

alhena/_bundle.py

@@ -0,0 +1,121 @@
+"""What a bundle declares about its weights, and the identity computed from them."""
+
+from __future__ import annotations
+
+import hashlib
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any, TypeVar
+
+import torch
+
+from alhena._constants import SCCONCEPT_MODEL, SCCONCEPT_VERSION
+from alhena._errors import BundleError
+
+_CELL_SPACE_TAG = "alhena-cell-space-v1"
+_IDENTITY_DIGITS = 16
+
+# What each object of a bundle configuration holds, as the refusal of a malformed one names it.
+_BUNDLE_SECTIONS: dict[str, str] = {
+    "adapters": "the rank and the scaling of the low-rank adapters",
+    "dims": "the widths of the embedding and of the cell space",
+    "teacher": "the single-cell model the cell space is aligned to",
+    "backbone": "the architecture and the repository of the backbone",
+}
+
+_Declared = TypeVar("_Declared", int, float, str)
+
+
+def _tensor_digest(tensor: torch.Tensor | None) -> str:
+    """Return the digest of a tensor's float32 bytes, or an empty field when it is absent."""
+    if tensor is None:
+        return ""
+    values = tensor.detach().to(dtype=torch.float32).cpu().contiguous().numpy()
+    return hashlib.sha256(values.tobytes()).hexdigest()
+
+
+def bundle_identity(
+    adapter_bytes: bytes,
+    head_tensors: Mapping[str, torch.Tensor],
+    scconcept_model: str = SCCONCEPT_MODEL,
+    scconcept_version: str = SCCONCEPT_VERSION,
+) -> tuple[str, str]:
+    """Return the encoder identity and the cell space identity of a bundle.
+
+    Each is the first sixteen hexadecimal digits of a SHA-256 digest: of the adapter file, and of
+    `alhena-cell-space-v1`, the adapter digest, the digests of the cell and reference head weights,
+    the single-cell model name and its version, joined by `|`.
+
+    Args:
+        adapter_bytes: Contents of the adapter file.
+        head_tensors: Head weights, keyed as in the bundle.
+        scconcept_model: Single-cell model the reference embeddings come from.
+        scconcept_version: Version of that model.
+
+    Returns:
+        The encoder identity and the cell space identity.
+    """
+    adapter_digest = hashlib.sha256(adapter_bytes).hexdigest()
+    fields = (
+        _CELL_SPACE_TAG,
+        adapter_digest,
+        _tensor_digest(head_tensors.get("img_tok_proj.weight")),
+        _tensor_digest(head_tensors.get("st_node_proj.weight")),
+        scconcept_model,
+        scconcept_version,
+    )
+    cell_space_digest = hashlib.sha256("|".join(fields).encode("utf-8")).hexdigest()
+    return adapter_digest[:_IDENTITY_DIGITS], cell_space_digest[:_IDENTITY_DIGITS]
+
+
+def _declared_property(
+    directory: Path,
+    config: Mapping[str, Any],
+    section: str,
+    name: str,
+    default: _Declared,
+) -> _Declared:
+    """Read a quantity a bundle states about itself, falling back to the package's own value."""
+    declared = config.get(section)
+    if declared is None:
+        return default
+    if not isinstance(declared, dict):
+        raise BundleError(
+            f"The bundle at {directory} states `{section}` as a value of type "
+            f"{type(declared).__name__} where an object naming {_BUNDLE_SECTIONS[section]} is "
+            "expected. Load a bundle whose configuration follows the published layout."
+        )
+    if name not in declared:
+        return default
+    value = declared[name]
+    if isinstance(default, str):
+        if not isinstance(value, str):
+            raise BundleError(
+                f"The bundle at {directory} states {section}.{name} as {value!r} where a string "
+                "is expected. Load a bundle whose configuration follows the published layout."
+            )
+    elif isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise BundleError(
+            f"The bundle at {directory} states {section}.{name} as {value!r} where a number is "
+            "expected. Load a bundle whose configuration follows the published layout."
+        )
+    if isinstance(default, int) and not float(value).is_integer():
+        raise BundleError(
+            f"The bundle at {directory} states {section}.{name} as {value!r} where an integer "
+            "is expected. Load a bundle whose configuration follows the published layout."
+        )
+    return type(default)(value)
+
+
+def _check_stated_identity(
+    directory: Path, config: Mapping[str, Any], encoder_id: str, cell_space_id: str
+) -> None:
+    """Refuse a bundle whose configuration states an identity its weights do not produce."""
+    produced = {"encoder_id": encoder_id, "cell_space_id": cell_space_id}
+    for name, value in produced.items():
+        stated = config.get(name)
+        if isinstance(stated, str) and stated != value:
+            raise BundleError(
+                f"The bundle at {directory} states {name} {stated!r} where its weights produce "
+                f"{value!r}. The configuration and the weights come from different runs."
+            )

alhena/_commands.py

@@ -0,0 +1,89 @@
+"""What the commands and the worked example share: their common options, and how they print."""
+
+from __future__ import annotations
+
+import argparse
+import warnings
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+
+import numpy as np
+
+
+def _add_cache_option(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--cache-dir",
+        type=Path,
+        default=None,
+        help="directory downloaded artifacts are cached in, overriding ALHENA_CACHE",
+    )
+
+
+def _add_quiet_option(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "-q",
+        "--quiet",
+        action="store_true",
+        help=(
+            "report no progress on standard error, download bars included; the results are "
+            "printed as usual"
+        ),
+    )
+
+
+def _add_backbone_option(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--backbone",
+        type=Path,
+        default=None,
+        help=(
+            "the UNI2-h weight file, or a directory holding one; ALHENA_BACKBONE, then the "
+            "Hugging Face cache, by default"
+        ),
+    )
+
+
+def _add_model_options(parser: argparse.ArgumentParser) -> None:
+    _add_backbone_option(parser)
+    parser.add_argument(
+        "--bundle",
+        default=None,
+        help=(
+            "directory holding the bundle files, or a repository owner/name; the published one "
+            "by default"
+        ),
+    )
+    _add_cache_option(parser)
+    parser.add_argument(
+        "--device",
+        default=None,
+        help=(
+            "device to run on: cpu, cuda, or mps for the GPU of an Apple silicon Mac; CUDA "
+            "where available, the processor otherwise"
+        ),
+    )
+
+
+def _one_line(text: object) -> str:
+    """Collapse a message onto one line, so a report never breaks in the middle of a field."""
+    return " ".join(str(text).split())
+
+
+def _share(count: int, total: int) -> str:
+    """Return a count as a share of a total, or a dash where the total is zero."""
+    return f"{count / total:.1%}" if total else "-"
+
+
+def _fixed(value: float, width: int, decimals: int = 3) -> str:
+    """Return a right-aligned number, or a dash where it is undefined."""
+    return f"{value:>{width}.{decimals}f}" if np.isfinite(value) else f"{'-':>{width}}"
+
+
+@contextmanager
+def _ignoring(*categories: type[Warning]) -> Iterator[None]:
+    """Leave the warnings of the given categories a block raises unreported."""
+    with warnings.catch_warnings():
+        for category in categories:
+            warnings.simplefilter("ignore", category)
+        yield

alhena/_constants.py

@@ -0,0 +1,247 @@
+"""Fixed quantities of the released ALHENA model and its reference registry.
+
+Nothing here is a tunable: changing a value produces a different model, not a different setting.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Final
+
+from alhena._errors import AlhenaError, AlhenaValueError
+
+# --- Distribution -----------------------------------------------------------------------
+
+WEIGHTS_REPO: Final[str] = "prism-oncology/ALHENA"
+"""Model hub repository publishing the encoder bundle."""
+REFERENCES_REPO: Final[str] = "prism-oncology/ALHENA-references"
+"""Model hub repository publishing the reference shards and their registry."""
+HUB_REVISION: Final[str] = "v0.1.0"
+"""Release tag of the weights and references repositories this version of the package reads."""
+BACKBONE_REPO: Final[str] = "MahmoodLab/UNI2-h"
+"""Model hub repository of the UNI2-h weights, gated by their authors."""
+
+ADAPTERS_FILE: Final[str] = "adapters.safetensors"
+HEADS_FILE: Final[str] = "heads.safetensors"
+BUNDLE_CONFIG_FILE: Final[str] = "config.json"
+REGISTRY_FILE: Final[str] = "registry.json"
+
+SHARD_SUFFIX: Final[str] = ".safetensors"
+"""Suffix of a reference shard file."""
+SHARD_DIRECTORY: Final[str] = "shards"
+"""Folder holding the shards, in the references repository and in a cache root."""
+
+# --- Backbone and adapters --------------------------------------------------------------
+
+BACKBONE_ARCHITECTURE: Final[str] = "vit_giant_patch14_224"
+
+BACKBONE_TIMM_KWARGS: Final[dict[str, object]] = {
+    "img_size": 224,
+    "patch_size": 14,
+    "depth": 24,
+    "num_heads": 24,
+    "init_values": 1e-5,
+    "embed_dim": 1536,
+    "mlp_ratio": 2.66667 * 2,
+    "num_classes": 0,
+    "no_embed_class": True,
+    "reg_tokens": 8,
+    "dynamic_img_size": True,
+}
+
+# Two layer classes of the architecture, resolved by name in encoder.build_backbone.
+BACKBONE_MLP_LAYER: Final[str] = "SwiGLUPacked"
+BACKBONE_ACT_LAYER: Final[str] = "SiLU"
+
+LORA_RANK: Final[int] = 64
+LORA_ALPHA: Final[float] = 32.0
+
+BACKBONE_DIM: Final[int] = 1536
+CELL_SPACE_DIM: Final[int] = 512
+SCCONCEPT_DIM: Final[int] = 512
+
+NUM_PREFIX_TOKENS: Final[int] = 9
+
+# --- Image geometry ---------------------------------------------------------------------
+
+INPUT_SIZE: Final[int] = 224
+"""Side of the square canvas the encoder reads, in pixels."""
+PATCH_SIZE: Final[int] = 14
+"""Side of one token, in pixels of the canvas."""
+TOKEN_GRID: Final[int] = INPUT_SIZE // PATCH_SIZE
+"""Tokens along each side of the canvas."""
+NUM_TOKENS: Final[int] = TOKEN_GRID * TOKEN_GRID
+"""Patch tokens of one canvas."""
+
+IMAGE_MEAN: Final[tuple[float, float, float]] = (0.485, 0.456, 0.406)
+IMAGE_STD: Final[tuple[float, float, float]] = (0.229, 0.224, 0.225)
+IMAGE_INTERPOLATION: Final[str] = "bilinear"
+
+# Microns per pixel the adapters were distilled at.
+DISTILLATION_MPP: Final[float] = 0.425
+BACKBONE_NATIVE_MPP: Final[float] = 0.5
+"""Native microns per pixel of UNI2-h, an operating point nothing resamples to."""
+REFERENCE_MPP: Final[float] = DISTILLATION_MPP
+"""Microns per pixel the encoder reads, which tiles of a declared resolution are brought to."""
+
+MPP_TOLERANCE: Final[float] = 0.02
+"""Relative difference between a declared mpp and the target above which tiles are resampled."""
+
+CROP_WARNING_FRACTION: Final[float] = 0.05
+"""Share of a field the center crop may discard before a `GeometryWarning` is raised."""
+
+MIN_MICROSCOPE_MPP: Final[float] = 0.02
+"""Finest microns per pixel of a microscope image: a tenth of the 0.2 micron a lens resolves."""
+MAX_MICROSCOPE_MPP: Final[float] = 20.0
+"""Coarsest microns per pixel of a microscope image, between a 1.25x scan and 600 dpi."""
+
+# --- Retrieval --------------------------------------------------------------------------
+
+DEFAULT_K: Final[int] = 30
+"""Reference neighbors each cell votes over."""
+DEFAULT_TAU: Final[float] = 0.03
+"""Softmax temperature over neighbor similarities."""
+
+RETRIEVAL_DEPTH: Final[int] = 200
+"""Neighbors retrieved, then scored again pair by pair, before the slice to k."""
+
+L2_EPS: Final[float] = 1e-12
+SOFTMAX_EPS: Final[float] = 1e-12
+ENTROPY_EPS: Final[float] = 1e-12
+POOL_EPS: Final[float] = 1e-6
+
+# --- Class axes -------------------------------------------------------------------------
+
+UNKNOWN_LABEL: Final[str] = "Unknown"
+"""Name of the unknown class, last in every class order, which no row is coded with."""
+
+LINEAGE_V1: Final[tuple[str, ...]] = (
+    "B_Plasma",
+    "Epithelial_Melanocyte",
+    "Myeloid",
+    "Stromal_Vascular",
+    "T_NK",
+)
+"""Classes of the `lineage_v1` axis, in the order of their codes (`label_order`)."""
+
+COMPARTMENT_V1: Final[tuple[str, ...]] = (
+    "Epithelial_Melanocyte",
+    "Immune",
+    "Stromal_Vascular",
+)
+"""Classes of the `compartment_v1` axis, in the order of their codes (`label_order`)."""
+
+CLASS_AXES: Final[dict[str, tuple[str, ...]]] = {
+    "lineage_v1": LINEAGE_V1,
+    "compartment_v1": COMPARTMENT_V1,
+}
+"""Declared class axes, by name."""
+
+DEFAULT_AXIS: Final[str] = "lineage_v1"
+"""Class axis used where none is named."""
+
+CLASS_COLORS: Final[dict[str, tuple[int, int, int]]] = {
+    "T_NK": (255, 15, 15),
+    "B_Plasma": (255, 143, 15),
+    "Myeloid": (255, 211, 15),
+    "Immune": (255, 123, 15),
+    "Stromal_Vascular": (113, 191, 18),
+    "Epithelial_Melanocyte": (39, 188, 178),
+    "Unknown": (143, 143, 143),
+}
+"""RGB color of each class in the figures of `alhena.viz`."""
+
+# --- Reference thresholds ---------------------------------------------------------------
+
+MIN_REFERENCE_CELLS_PER_CLASS: Final[int] = 200
+"""Reference cells below which a class is reported as thinly supported."""
+
+MIN_SUPPORT_TO_K_RATIO: Final[float] = 10.0
+"""Floor of the thinnest class's support over k, below which `EnvelopeWarning` is raised."""
+MIN_K_TO_CLASSES_RATIO: Final[float] = 3.0
+"""Floor of k over the number of classes, below which `EnvelopeWarning` is raised."""
+
+# --- Reference registry -----------------------------------------------------------------
+
+TISSUE_TO_SHARD: Final[dict[str, str]] = {
+    "Breast": "breast",
+    "BoneMarrow": "bone_marrow",
+    "Cervix": "cervix",
+    "Colon": "intestine",
+    "Heart": "heart",
+    "Kidney": "kidney",
+    "Liver": "liver_cell",
+    "Lung": "lung",
+    "LymphNode": "tonsil",
+    "Ovary": "ovary",
+    "Pancreas": "pancreas_cell",
+    "Prostate": "prostate",
+    "Skin": "skin",
+    "Tonsil": "tonsil",
+    "Uterus": "uterus",
+}
+"""Shard each tissue is served by, under its canonical organ name; tissues may share one."""
+
+# Once case, spacing and separators are ignored, no alias matches a tissue, a shard or another.
+TISSUE_ALIASES: Final[dict[str, str]] = {
+    # Adjectives of the organ, but not Cardiac or Cervical, which also name the cardia and the neck.
+    "Colonic": "Colon",
+    "Cutaneous": "Skin",
+    "Hepatic": "Liver",
+    "Mammary": "Breast",
+    "Ovarian": "Ovary",
+    "Pancreatic": "Pancreas",
+    "Prostatic": "Prostate",
+    "Pulmonary": "Lung",
+    "Renal": "Kidney",
+    "Tonsillar": "Tonsil",
+    "Uterine": "Uterus",
+    # The fuller anatomical name of the organ.
+    "Cervix uteri": "Cervix",
+    "Prostate gland": "Prostate",
+    "Uterine cervix": "Cervix",
+    # Parts or regions of the organ the atlas behind the shard samples, by the site of each cell.
+    "Bowel": "Colon",
+    "Colorectal": "Colon",
+    "Large intestine": "Colon",
+    "Rectum": "Colon",
+    # The intestine atlas holds ileum, cecum, appendix, colon and rectum, no duodenum or jejunum.
+    "Small intestine": "Colon",
+    "Corpus uteri": "Uterus",
+    "Endometrium": "Uterus",
+    "Myometrium": "Uterus",
+}
+"""Other names a tissue is accepted under, each mapped to its tissue in `TISSUE_TO_SHARD`."""
+
+SCCONCEPT_MODEL: Final[str] = "corpus40M-model30M"
+SCCONCEPT_VERSION: Final[str] = "v2"
+
+
+def label_order(axis: str) -> tuple[str, ...]:
+    """Return the class order of an axis, scorable classes sorted, then the unknown class.
+
+    The order fixes the code of every class and breaks ties in the vote.
+
+    Args:
+        axis: A key of `CLASS_AXES`.
+
+    Returns:
+        Class names in their canonical order.
+
+    Raises:
+        AlhenaValueError: If the axis is not one of the declared axes.
+    """
+    if axis not in CLASS_AXES:
+        raise AlhenaValueError(f"Unknown class axis {axis!r}. Declared axes: {sorted(CLASS_AXES)}.")
+    return (*sorted(CLASS_AXES[axis]), UNKNOWN_LABEL)
+
+
+def _check_class_names(names: Sequence[str], error: type[AlhenaError] = AlhenaValueError) -> None:
+    """Refuse a class name that no key of an .h5ad or zarr file can hold."""
+    for name in names:
+        if "/" in name:
+            raise error(
+                f"The class name {name!r} holds '/', which no key of an .h5ad or zarr file can "
+                "hold, so its results could not be written. Rename the class, for example "
+                f"{name.replace('/', '_')!r}."
+            )

alhena/_coverage.py

@@ -0,0 +1,77 @@
+"""What a reference cannot express, and whether `k` suits the cells of its classes."""
+
+from __future__ import annotations
+
+import warnings
+from collections.abc import Mapping
+
+from alhena._constants import (
+    MIN_K_TO_CLASSES_RATIO,
+    MIN_REFERENCE_CELLS_PER_CLASS,
+    MIN_SUPPORT_TO_K_RATIO,
+)
+from alhena._errors import PACKAGE_PREFIXES, EnvelopeWarning, ReferenceCoverageWarning
+
+THIN_SUPPORT_WARNING: str = "The thinnest class the"
+"""Opening of the warning that the thinnest class of a reference has too few cells for `k`."""
+
+
+def _missing_classes(support: Mapping[str, int]) -> tuple[str, ...]:
+    """Return the classes no reference cell carries, in class order."""
+    return tuple(name for name, count in support.items() if count == 0)
+
+
+def _thin_classes(support: Mapping[str, int]) -> tuple[str, ...]:
+    """Return the classes too few reference cells carry for retrieval to be reliable."""
+    return tuple(
+        name for name, count in support.items() if 0 < count < MIN_REFERENCE_CELLS_PER_CLASS
+    )
+
+
+def _thinnest_class(support: Mapping[str, int], k: int, reference: str | None = None) -> str | None:
+    """Return the sentence on the thinnest class a reference expresses, or None if `k` suits it."""
+    present = {name: count for name, count in support.items() if count > 0}
+    if not present or min(present.values()) / k >= MIN_SUPPORT_TO_K_RATIO:
+        return None
+    minimum = min(present.values())
+    thinnest = next(name for name, count in present.items() if count == minimum)
+    named = "reference" if reference is None else f"{reference} reference"
+    return (
+        f"{THIN_SUPPORT_WARNING} {named} expresses, {thinnest}, has {minimum} cells, fewer than "
+        f"the {k * MIN_SUPPORT_TO_K_RATIO:g} recommended for k={k}. Interpret predictions of "
+        f"{thinnest} with caution."
+    )
+
+
+def _warn_coverage(support: Mapping[str, int], k: int, axis: str, *, loading: bool) -> None:
+    """Warn of missing and thinnest classes, thin ones at load, and k over classes at annotation."""
+    missing = _missing_classes(support)
+    if missing:
+        warnings.warn(
+            f"The reference holds no cell of {', '.join(missing)} on the {axis} axis, so these "
+            "classes cannot be predicted with this reference. Their absence from the annotations "
+            "does not show that they are absent from the tissue.",
+            ReferenceCoverageWarning,
+            skip_file_prefixes=PACKAGE_PREFIXES,
+        )
+    thinly = _thin_classes(support) if loading else ()
+    if thinly:
+        counted = ", ".join(f"{name} ({support[name]})" for name in thinly)
+        warnings.warn(
+            f"The reference has fewer than {MIN_REFERENCE_CELLS_PER_CLASS} labeled cells for "
+            f"{counted} on the {axis} axis. Interpret predictions for each listed class with "
+            "caution.",
+            ReferenceCoverageWarning,
+            skip_file_prefixes=PACKAGE_PREFIXES,
+        )
+    sentence = _thinnest_class(support, k)
+    if sentence is not None:
+        warnings.warn(sentence, EnvelopeWarning, skip_file_prefixes=PACKAGE_PREFIXES)
+    if not loading and k / len(support) < MIN_K_TO_CLASSES_RATIO:
+        warnings.warn(
+            f"k={k} across {len(support)} classes is below the {MIN_K_TO_CLASSES_RATIO:g} "
+            "reference neighbors per class recommended by ALHENA. Interpret confidence values "
+            "with caution.",
+            EnvelopeWarning,
+            skip_file_prefixes=PACKAGE_PREFIXES,
+        )