lazyslide.tl.feature_aggregation

lazyslide.tl.feature_aggregation#

feature_aggregation(wsi, feature_key, layer_key=None, encoder='mean', tile_key='tiles', agg_by=None, agg_key=None, amp=None, autocast_dtype=None, device=None, *, compile=None, compile_kws=None, by=None)#

Aggregate features by groups.

The feature aggregation is done by applying an encoder to a group of features to acquire a 1d representation of the group. Notice that the final shape of the aggregated features might not be the same as the original features.

Parameters:
wsiWSIData

The whole-slide image object.

feature_keystr

The key to indicate which feature to aggregate.

layer_keystr, optional

The key of the layer in the feature table.

encoderstr, default: ‘mean’

How to aggregate the tile features:

  • A numpy reduction: ‘mean’, ‘median’, ‘sum’, ‘std’, ‘var’, …

  • A slide encoder registry key (see Models), e.g. ‘prism’, ‘titan’ or ‘madeleine’; ‘chief’ and ‘gigapath’ are short for their slide encoders. The features must come from the encoder’s paired tile encoder (vision_encoder on its model card, e.g. ‘virchow’ for ‘prism’), at the tile size and mpp that encoder expects.

tile_keystr, default: ‘tiles’

The key of the tiles dataframe in the spatial data object.

agg_bystr or list of str, default: None

The level to aggregate the features.

  • By default will aggregate the features from all tiles in the slide.

  • Column name in tile dataframe: Aggregate the features by specific column. For example, to aggregate by tissue pieces, set agg_by=’tissue_id’.

agg_keystr, optional

The key to store the aggregated features. If not provided, the key will be ‘agg_{agg_by}’, or ‘agg_slide’ when aggregating the whole slide.

ampbool, optional

Whether to use automatic mixed precision. Only used by model-based encoders.

autocast_dtypetorch.dtype, optional

The dtype for automatic mixed precision.

devicestr, optional

The device to use for inference. If not provided, the device will be automatically selected.

compilebool, optional

Whether to compile the encoder with torch.compile(). Compilation is best-effort and is silently skipped for models that do not support it. Only used by model-based encoders.

compile_kwsdict, optional

Keyword arguments passed to torch.compile().

bystr or list of str, optional

Deprecated since version 0.13.0: Use agg_by instead; by will be removed in 0.14.0.

Returns:
None

Note

The aggregation features and operation will be recorded in the uns slot of features AnnData. The aggregated features will only be added to the varm slot if their shape is the same as the original features.

Examples

>>> import lazyslide as zs
>>> wsi = zs.datasets.sample(with_data=False)
>>> zs.pp.find_tissues(wsi)
>>> zs.pp.tile_tissues(wsi, 256, mpp=0.5)
>>> zs.tl.feature_extraction(wsi, "resnet50")
>>> zs.tl.feature_aggregation(wsi, feature_key="resnet50", agg_by="tissue_id")
>>> wsi.tables['resnet50_tiles'].uns['agg_ops']['agg_tissue_id']