harpy.tb.add_feature_matrix

harpy.tb.add_feature_matrix(sdata, labels_name, image_name, *, table_name=None, output_table_name=None, feature_key, features, channels=None, overwrite_output_table=False, overwrite_feature_key=False, to_coordinate_system='global', region_key='fov_labels', instance_key='cell_ID', feature_matrices_key='feature_matrices', chunks=None, run_on_gpu=False)

Compute per-instance feature matrices from labels and optional image data.

This function computes requested object-level features from one or more labels elements and writes the resulting numeric matrix into .obsm[feature_key] of a target table. Companion metadata describing the matrix schema and inputs is stored in .uns[feature_matrices_key][feature_key], including explicit source_channels for intensity-derived features.

Features are aligned onto table rows by (region_key, instance_key), not by row order. This makes the resulting matrix immediately reusable in downstream workflows that expect feature matrices in .obsm.

The function supports two modes:

• If table_name is None, a new annotated table is created first and output_table_name is required.

• If table_name is provided, the existing table is updated in place by writing or replacing obsm[feature_key] for the selected labels element or elements.

Supported intensity features are "sum", "mean", "var", "min", "max", "kurtosis", and "skew". Supported morphology features are "area", "eccentricity", "major_axis_length", "minor_axis_length", "perimeter", "convex_area", "equivalent_diameter", "major_minor_axis_ratio", "perim_square_over_area", "major_axis_equiv_diam_ratio", "convex_hull_resid", and "centroid_dif".

Parameters:

• sdata (SpatialData) – The input SpatialData object.

• labels_name (str | list[str]) – Labels element or elements from which object features are computed. When a list is provided, one feature matrix block is computed per labels element and aligned onto the target table using region_key and instance_key.

• image_name (str | list[str] | None) – Image element or elements used for intensity-derived features. This is required if any requested feature is intensity-derived. If a list is provided, it must either have length 1 or match labels_name. If only morphology features are requested, a provided image_name is ignored.

• table_name (str | None (default: None)) – Existing table element in sdata.tables to update. If None, a new annotated table is created and written to output_table_name.

• output_table_name (str | None (default: None)) – Name of the output table element to create when table_name is None. This parameter is not allowed when updating an existing table.

• feature_key (str) – Key used to store the computed feature matrix in adata.obsm.

• features (tuple[str, ...] | list[str]) – Requested feature names. Duplicate names are ignored while preserving order.

• channels (int | str | list[int] | list[str] | None (default: None)) – Channel selection for intensity-derived features. Channels can be given by index, by name, or as a list of indices or names. If None, all channels of the image element are used.

• overwrite_output_table (bool (default: False)) – If True, overwrite output_table_name when creating a new table.

• overwrite_feature_key (bool (default: False)) – If True, replace an existing adata.obsm[feature_key] when updating an existing table.

• to_coordinate_system (str | list[str] (default: 'global')) – Coordinate system or systems used when pairing image and labels elements. If a list is provided, it must either have length 1 or match labels_name.

• region_key (str (default: 'fov_labels')) – Column name in adata.obs identifying the source labels element. This is used when creating a new table and for aligning computed rows onto a target table.

• instance_key (str (default: 'cell_ID')) – Column name in adata.obs identifying the instance id. This is used when creating a new table and for aligning computed rows onto a target table.

• feature_matrices_key (str (default: 'feature_matrices')) – Key in adata.uns under which metadata for computed feature matrices is stored.

• chunks (str | int | tuple[int, ...] | None (default: None)) – Optional chunk specification used to rechunk image and labels arrays during feature extraction. Rechunking on disk ahead of time is often more efficient.

• run_on_gpu (bool (default: False)) – Whether to use GPU-backed execution where supported. If GPU execution is requested but CuPy is not available, Harpy falls back to CPU execution.

Return type:

SpatialData

Returns:

: The updated SpatialData object.

See also

harpy.tb.allocate_intensity

Allocate intensity-derived features into a table.

harpy.tb.add_regionprops

Add morphology features to table observations.

Examples

import harpy as hp

sdata = hp.datasets.xenium_human_ovarian_cancer(
    subset=True,
    processed=False,
)

sdata = hp.tb.add_feature_matrix(
    sdata,
    labels_name="cell_labels_global",
    image_name="morphology_focus_global",
    table_name=None,
    output_table_name="table_cell_features",
    feature_key="cell_features",
    features=["mean", "area"],
    overwrite_output_table=True,
)

sdata["table_cell_features"].obsm["cell_features"].shape