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:
- wsi
WSIData 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_encoderon 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_byinstead;bywill be removed in 0.14.0.
- wsi
- 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']