/spatial-microenvironment-subset

name: spatial-microenvironment-subset
description: Load when extracting a niche / microenvironment subset around a center cell-type by spatial
  radius from a labelled spatial AnnData, producing a smaller AnnData of centers + their within-radius
  neighbours. Skip when running global tissue-domain detection (use spatial-domains); cross-condition
  comparison (use spatial-condition).
trigger: microenvironment, neighborhood subset, spatial radius, neighboring cells, nearby cells, tumor microenvironment, extract cells within 50 microns
tags:
- spatial
- microenvironment
- niche
- subsetting
- neighbourhood
- visium
- xenium

spatial-microenvironment-subset

When to use

Extract centers and nearby observations. Use spatial-domains for global regions and spatial-condition for condition comparisons.

Use from a step

from skills._sdk.notebook import load_skill, read_input, write_output
library = load_skill("spatial-microenvironment-subset")
data = read_input("input.h5ad")
data = library.subset(data, center_key="cell_type", center_values=["Tumor"], radius_native=50)
write_output(library.selection_table(data), "tables/results.csv")

Run [examples/example_step.py](examples/example_step.py) through the step runner.

API

<!-- api:begin generated from _api.py; regenerate with run.py api <skill dir> --write -->

`subset(adata, *, center_values: list[str], center_key: str | None=None, radius_native: float | None=None, radius_microns: float | None=None, microns_per_coordinate_unit: float | None=None, data_type: str | None=None, include_centers: bool=True, target_key: str | None=None, target_values: list[str] | None=None)`

Return a new neighborhood AnnData; expression matrices remain unchanged.

:param adata: Labelled AnnData with spatial coordinates; X, layers and raw are sliced. :param center_values: Labels defining centers, required as in the CLI. :param center_key: Label column; None selects the first recognized label column. :param radius_native: Positive coordinate-unit radius; default None requires radius_microns. :param radius_microns: Positive micron radius, exclusive with radius_native. :param microns_per_coordinate_unit: Explicit positive scale; None uses platform metadata. :param data_type: Optional platform hint used to resolve units, as in the CLI. :param include_centers: True retains centers regardless of the target-label filter. :param target_key: Optional neighbor label column; None uses the center column. :param target_values: Optional allowed neighbor labels; None admits all labels. :returns: A new AnnData with role, distance and JSON diagnostics. :raises ValueError: Invalid radius, labels, units, coordinates or an empty selection.

`run_info(adata, *, keep: bool=True) -> dict`

Read selection counts and resolved coordinate units.

:param adata: AnnData returned by subset. :param keep: True retains diagnostics; False removes them for CLI serialization. :returns: Selection diagnostics, or an empty dict before analysis.

`selection_table(adata)`

Return coordinates, center identities and nearest-center distances.

:param adata: AnnData returned by subset; expression values are not read. :returns: One DataFrame row per selected observation. :raises KeyError: Selection columns are absent.

`selection_figure(adata)`

Plot selected centers and neighbors in coordinate units.

:param adata: AnnData returned by subset; reads coordinates and microenv_role. :returns: A matplotlib Figure without saving it. :raises KeyError: Selection roles are absent.

<!-- api:end -->

Methods and parameters

KD-tree distances select observations near a center. Exactly one native or micron radius is required; micron distances require known coordinate units. See [parameters](references/parameters.md) and [methodology](references/methodology.md).

Gotchas

• `subset` returns a copy and raises ValueError for missing centers or empty selections. `selection_table` adds micron distances only when a scale is known.
• `run_info(keep=False)` removes library diagnostics before CLI serialization.

Inputs and outputs

The library returns AnnData, DataFrames or Figures without file writes. The CLI keeps reports, result.json, tables and conditional gallery outputs. See the complete [output contract](references/output_contract.md) for filenames and conditions.

CLI

python skills/spatial/spatial-microenvironment-subset/spatial_microenvironment_subset.py --input data.h5ad --output results/spatial-microenvironment-subset --center-values Tumor --radius-native 50

See also

• [Methodology](references/methodology.md)
• [Parameters](references/parameters.md)
• [Output contract](references/output_contract.md)

Dependencies

`anndata`, `matplotlib`, `numpy`, `pandas`, `scanpy`, `scipy`