Skip to content

Patch Constructor

Source

Patch constructor package. Patch constructors output a patch for a given index.

BasicPatchConstr

Bases: PatchConstr

Construct standard CAREamics input and optional target patches.

This constructor can be used for both training and prediction pipelines.

Parameters:

  • patching_strategy (Patching) –

    Strategy that maps dataset indices to patch specifications.

  • input_extractor (PatchExtractor) –

    Extractor for input patches.

  • target_extractor (PatchExtractor or None, default: None ) –

    Extractor for target patches. Can be None for self-supervised algorithms or prediction pipelines.

  • channels (Sequence[int] or None, default: None ) –

    Channel indices to extract. If None, all channels are extracted.

input_shapes property

Return input image shapes.

Returns:

n_patches property

Return the number of available patches.

Returns:

  • int –

    Number of available patches.

target_shapes property

Return target image shapes, if targets exist.

Returns:

  • Sequence[Sequence[int]] or None –

    Target image shapes in SC(Z)YX format, if targets exist, otherwise None.

__init__(patching_strategy, input_extractor, target_extractor=None, channels=None)

Initialize the basic patch constructor.

Parameters:

  • patching_strategy (Patching) –

    Strategy that maps dataset indices to patch specifications.

  • input_extractor (PatchExtractor) –

    Extractor for input patches.

  • target_extractor (PatchExtractor or None, default: None ) –

    Extractor for target patches. Can be None for self-supervised algorithms or prediction pipelines.

  • channels (Sequence[int] or None, default: None ) –

    Channel indices to extract. If None, all channels are extracted.

construct_patch(index)

Construct the input and optional target patch for an index.

Parameters:

  • index (int) –

    Dataset index to map to a patch specification.

Returns:

  • input_patch ( NDArray[Any] ) –

    Input patch with axes C(Z)YX.

  • target_patch ( NDArray[Any] or None ) –

    Target patch with axes C(Z)YX when a target extractor is available, otherwise None.

  • patch_spec ( PatchSpecs ) –

    Patch specification used to extract the patches.

get_input_image_metadata(patch_spec)

Return metadata for the input image described by a patch specification.

Parameters:

  • patch_spec (PatchSpecs) –

    Patch specification containing the input image index.

Returns:

get_patch_indices(data_idx)

Get the patch indices will return patches for a specific image_stack.

The image_stack corresponds to the given data_idx.

Parameters:

  • data_idx (int) –

    An index that corresponds to a given image_stack.

Returns:

  • sequence of int –

    A sequence of patch indices, that when used to index the CAREamicsDataset will return a patch that comes from theimage_stackcorresponding to the givendata_idx`.

get_principal_input(input_patch)

Return the principal input patch.

The principal input is used for calculating statistics for normalization.

Parameters:

  • input_patch (NDArray[Any]) –

    Input patch with axes C(Z)YX.

Returns:

  • NDArray[Any] –

    The unchanged input patch with axes C(Z)YX.

get_target_image_metadata(patch_spec)

Return metadata for the target image described by a patch specification.

Parameters:

  • patch_spec (PatchSpecs) –

    Patch specification containing the target image index.

Returns:

  • ImageMetadata | None –

    Metadata for the target image when targets exist, otherwise None.

IndependentTargetsMsPatchConstr

Bases: PatchConstr

Construct MicroSplit patches from independent target structures.

The data for different target structures may have different shapes.

Synthetic inputs are created by summing patches from random locations in the data, alpha_ranges are used to decide the weight of each channel.

Parameters:

  • patching_strategies (Sequence[Patching]) –

    One patching strategy per target structure source.

  • target_extractors (Sequence[PatchExtractor]) –

    One extractor per target structure source.

  • multiscale_count (int) –

    Number of lateral context inputs.

  • padding_mode ((reflect, wrap), default: "reflect" ) –

    Padding mode used when lateral context extends beyond image boundaries.

  • alpha_ranges (Sequence[tuple[float, float]] or None) –

    Sampling ranges for channel mixing weights. If None, every target source gets a fixed weight of 1 / n_channels.

  • rng (Generator or None, default: None ) –

    Random number generator. If None, a default generator is created.

input_shapes property

Return input image shapes.

Returns:

n_patches property

Return the number of available patches.

Returns:

  • int –

    Number of patches available from the principal target channel source.

target_shapes property

Return target image shapes.

Returns:

__init__(patching_strategies, target_extractors, multiscale_count, padding_mode, alpha_ranges, rng=None)

Initialize the training mode II patch constructor.

Parameters:

  • patching_strategies (Sequence[Patching]) –

    One patching strategy per target structure source.

  • target_extractors (Sequence[PatchExtractor]) –

    One extractor per target structure source.

  • multiscale_count (int) –

    Number of lateral context inputs.

  • padding_mode ((reflect, wrap), default: "reflect" ) –

    Padding mode used when lateral context extends beyond image boundaries.

  • alpha_ranges (Sequence[tuple[float, float]] or None) –

    Sampling ranges for channel mixing weights. If None, every target source gets a fixed weight of 1 / n_channels.

  • rng (Generator or None, default: None ) –

    Random number generator. If None, a default generator is created.

construct_patch(index)

Construct the synthetic input and target patch for an index.

Parameters:

  • index (int) –

    Dataset index for the principal target channel source.

Returns:

  • input_patch ( NDArray[Any] ) –

    Synthetic input patch with axes L(Z)YX, where L is the lateral context input axis ordered from the native patch scale to larger context scales.

  • target_patch ( NDArray[Any] ) –

    Target patch with axes C(Z)YX.

  • patch_spec ( UncorrelatedPatchSpecs ) –

    Patch specification containing one location per target channel source.

get_input_image_metadata(patch_spec)

Return metadata for the input image.

Parameters:

  • patch_spec (PatchSpecs) –

    Uncorrelated patch specification identifying all channel source images.

Returns:

  • ImageMetadata –

    Metadata for the principal input image with additional per-channel source metadata.

get_patch_indices(data_idx)

Get the patch indices will return patches for a specific image_stack.

The image_stack corresponds to the given data_idx.

Parameters:

  • data_idx (int) –

    An index that corresponds to a given image_stack.

Returns:

  • sequence of int –

    A sequence of patch indices, that when used to index the CAREamicsDataset will return a patch that comes from theimage_stackcorresponding to the givendata_idx`.

get_principal_input(input_patch)

Return the principal input without lateral context.

Parameters:

  • input_patch (NDArray[Any]) –

    Input patch with axes L(Z)YX, where L is the lateral context input axis.

Returns:

  • NDArray[Any] –

    Principal input with axes C(Z)YX.

get_target_image_metadata(patch_spec)

Return metadata for the target image.

Parameters:

  • patch_spec (PatchSpecs) –

    Uncorrelated patch specification identifying all channel source images.

Returns:

  • ImageMetadata –

    Metadata for the principal target image with additional per-channel source metadata.

MultiChannelTargetMsPatchConstr

Bases: PatchConstr

Construct MicroSplit patches from multiplexed images of target channels.

Synthetic inputs are created by summing the target channels, alpha_ranges are used to decide the weight of each channel.

Parameters:

  • patching_strategy (Patching) –

    Strategy that maps dataset indices to patch specifications.

  • target_extractor (PatchExtractor) –

    Extractor for multiplexed target channels.

  • multiscale_count (int) –

    Number of lateral context inputs.

  • padding_mode ((reflect, wrap), default: "reflect" ) –

    Padding mode used when lateral context extends beyond image boundaries.

  • alpha_ranges (Sequence[tuple[float, float]] or None) –

    Sampling ranges for channel mixing weights. If None, every channel gets a fixed weight of 1 / n_channels.

  • uncorrelated_channel_prob (float) –

    Probability of sampling channels from different patch locations.

  • channels (Sequence[int] or None, default: None ) –

    Channel indices to use from the target data. If None, all channels are used.

  • rng (Generator or None, default: None ) –

    Random number generator. If None, a default generator is created.

input_shapes property

Return input image shapes.

Returns:

n_patches property

Return the number of available patches.

Returns:

  • int –

    Number of patches available from the patching strategy.

target_shapes property

Return target image shapes.

Returns:

__init__(patching_strategy, target_extractor, multiscale_count, padding_mode, alpha_ranges, uncorrelated_channel_prob, channels=None, rng=None)

Initialize the training mode I patch constructor.

Parameters:

  • patching_strategy (Patching) –

    Strategy that maps dataset indices to patch specifications.

  • target_extractor (PatchExtractor) –

    Extractor for jointly acquired target channels.

  • multiscale_count (int) –

    Number of lateral context inputs.

  • padding_mode ((reflect, wrap), default: "reflect" ) –

    Padding mode used when lateral context extends beyond image boundaries.

  • alpha_ranges (Sequence[tuple[float, float]] | None) –

    Sampling ranges for channel mixing weights. If None, every channel gets a fixed weight of 1 / n_channels.

  • uncorrelated_channel_prob (float) –

    Probability of sampling channels from different patch locations.

  • channels (Sequence[int] | None, default: None ) –

    Channel indices to use from the target data. If None, all channels are used.

  • rng (Generator or None, default: None ) –

    Random number generator. If None, a default generator is created.

construct_patch(index)

Construct the synthetic input and target patch for an index.

Parameters:

  • index (int) –

    Dataset index to map to a patch specification.

Returns:

  • input_patch ( NDArray[Any] ) –

    Synthetic input patch with axes L(Z)YX, where L is the lateral context input axis ordered from the native patch scale to larger context scales.

  • target_patch ( NDArray[Any] ) –

    Target patch with axes C(Z)YX.

  • patch_spec ( PatchSpecs or UncorrelatedPatchSpecs ) –

    Standard patch specification for correlated channels, or uncorrelated patch specification when channels are sampled from different locations.

get_input_image_metadata(patch_spec)

Return metadata for the input image.

Parameters:

  • patch_spec (PatchSpecs) –

    Patch specification identifying the input image. Uncorrelated patch specs include metadata for each channel location.

Returns:

  • ImageMetadata –

    Metadata for the input image or principal uncorrelated input image.

get_patch_indices(data_idx)

Get the patch indices will return patches for a specific image_stack.

The image_stack corresponds to the given data_idx.

Parameters:

  • data_idx (int) –

    An index that corresponds to a given image_stack.

Returns:

  • sequence of int –

    A sequence of patch indices, that when used to index the CAREamicsDataset will return a patch that comes from theimage_stackcorresponding to the givendata_idx`.

get_principal_input(input_patch)

Return the principal input without lateral context.

Parameters:

  • input_patch (NDArray[Any]) –

    Input patch with axes L(Z)YX, where L is the lateral context input axis.

Returns:

  • NDArray[Any] –

    Principal input with axes C(Z)YX.

get_target_image_metadata(patch_spec)

Return metadata for the target image.

Parameters:

  • patch_spec (PatchSpecs) –

    Patch specification identifying the target image. Uncorrelated patch specs include metadata for each channel location.

Returns:

  • ImageMetadata –

    Metadata for the target image or principal uncorrelated target image.

PairedInputTargetMsPatchConstr

Bases: PatchConstr

Construct MicroSplit patches from paired input and target images.

Parameters:

  • patching_strategy (Patching) –

    Strategy that maps dataset indices to patch specifications.

  • input_extractor (PatchExtractor) –

    Extractor for real input images.

  • target_extractor (PatchExtractor) –

    Extractor for target images.

  • multiscale_count (int) –

    Number of lateral context inputs.

  • padding_mode ((reflect, wrap), default: "reflect" ) –

    Padding mode used when lateral context extends beyond image boundaries.

input_shapes property

Return input image shapes.

Returns:

n_patches property

Return the number of available patches.

Returns:

  • int –

    Number of patches available from the patching strategy.

target_shapes property

Return target image shapes.

Returns:

__init__(patching_strategy, input_extractor, target_extractor, multiscale_count, padding_mode)

Initialize the training mode III patch constructor.

Parameters:

  • patching_strategy (Patching) –

    Strategy that maps dataset indices to patch specifications.

  • input_extractor (PatchExtractor) –

    Extractor for real input images.

  • target_extractor (PatchExtractor) –

    Extractor for target images.

  • multiscale_count (int) –

    Number of lateral context inputs.

  • padding_mode ((reflect, wrap), default: "reflect" ) –

    Padding mode used when lateral context extends beyond image boundaries.

construct_patch(index)

Construct the real input and target patch for an index.

Parameters:

  • index (int) –

    Dataset index to map to a patch specification.

Returns:

  • input_patch ( NDArray[Any] ) –

    Real input patch with axes L(Z)YX, where L is the lateral context input axis ordered from the native patch scale to larger context scales.

  • target_patch ( NDArray[Any] ) –

    Target patch with axes C(Z)YX.

  • patch_spec ( PatchSpecs ) –

    Patch specification used to extract the patches.

get_input_image_metadata(patch_spec)

Return metadata for the input image.

Parameters:

  • patch_spec (PatchSpecs) –

    Patch specification identifying the input image.

Returns:

get_patch_indices(data_idx)

Get the patch indices will return patches for a specific image_stack.

The image_stack corresponds to the given data_idx.

Parameters:

  • data_idx (int) –

    An index that corresponds to a given image_stack.

Returns:

  • sequence of int –

    A sequence of patch indices, that when used to index the CAREamicsDataset will return a patch that comes from theimage_stackcorresponding to the givendata_idx`.

get_principal_input(input_patch)

Return the principal input without lateral context.

Parameters:

  • input_patch (NDArray[Any]) –

    Input patch with axes L(Z)YX, where L is the lateral context input axis.

Returns:

  • NDArray[Any] –

    Principal input with axes C(Z)YX.

get_target_image_metadata(patch_spec)

Return metadata for the target image.

Parameters:

  • patch_spec (PatchSpecs) –

    Patch specification identifying the target image.

Returns:

PatchConstr

Bases: Protocol

Module for extracting and constructing inputs and targets.

input_shapes property

Return input image shapes.

n_patches property

The number of patches.

target_shapes property

Return target image shapes, if targets exist.

construct_patch(index)

Construct the patch that will be input into the model.

Parameters:

  • index (int) –

    The index of the patch, the index has to be less than n_patches.

Returns:

  • input ( NDArray[Any] ) –

    The input patch.

  • target ( NDArray[Any] | None ) –

    The target patch.

  • patch_spec ( PatchSpecs ) –

    The patch specification.

get_input_image_metadata(patch_spec)

Return metadata for the input image.

Parameters:

  • patch_spec (PatchSpecs) –

    Patch specification identifying the input image.

Returns:

get_patch_indices(data_idx)

Get the patch indices will return patches for a specific image_stack.

The image_stack corresponds to the given data_idx.

Parameters:

  • data_idx (int) –

    An index that corresponds to a given image_stack.

Returns:

  • sequence of int –

    A sequence of patch indices, that when used to index the CAREamicsDataset will return a patch that comes from theimage_stackcorresponding to the givendata_idx`.

get_principal_input(input_patch)

Get the principal input.

This is useful for tasks such as the calculation of stats for normalization.

Parameters:

  • input_patch (NDArray[Any]) –

    The complete input.

Returns:

  • NDArray[Any] –

    The principal input (C(Z)YX).

get_target_image_metadata(patch_spec)

Return metadata for the target image, if targets exist.

Parameters:

  • patch_spec (PatchSpecs) –

    Patch specification identifying the target image.

Returns:

  • ImageMetadata or None –

    Metadata for the target image, or None for input-only datasets.

PredMsPatchConstr

Bases: PatchConstr

Construct MicroSplit prediction patches.

Parameters:

  • patching_strategy (TiledPatching) –

    Strategy that maps dataset indices to tiled patch specifications.

  • input_extractor (PatchExtractor) –

    Extractor for prediction input images.

  • multiscale_count (int) –

    Number of lateral context inputs.

  • padding_mode ((reflect, wrap), default: "reflect" ) –

    Padding mode used when lateral context extends beyond image boundaries.

input_shapes property

Return input image shapes.

Returns:

n_patches property

Return the number of available patches.

Returns:

  • int –

    Number of patches available from the tiled patching strategy.

target_shapes property

Return target image shapes, if targets exist.

Returns:

  • None –

    Prediction datasets do not have target images.

__init__(patching_strategy, input_extractor, multiscale_count, padding_mode)

Initialize the prediction patch constructor.

Parameters:

  • patching_strategy (TiledPatching) –

    Strategy that maps dataset indices to tiled patch specifications.

  • input_extractor (PatchExtractor) –

    Extractor for prediction input images.

  • multiscale_count (int) –

    Number of lateral context inputs.

  • padding_mode ((reflect, wrap), default: "reflect" ) –

    Padding mode used when lateral context extends beyond image boundaries.

construct_patch(index)

Construct the input patch for prediction.

Parameters:

  • index (int) –

    Dataset index to map to a tile specification.

Returns:

  • input_patch ( NDArray[Any] ) –

    Prediction input patch with axes L(Z)YX, where L is the lateral context input axis ordered from the native patch scale to larger context scales.

  • target_patch ( None ) –

    Prediction datasets do not have target patches.

  • patch_spec ( TileSpecs ) –

    Tile specification used to extract the patch.

get_input_image_metadata(patch_spec)

Return metadata for the input image.

Parameters:

  • patch_spec (PatchSpecs) –

    Patch specification identifying the input image.

Returns:

get_patch_indices(data_idx)

Get the patch indices will return patches for a specific image_stack.

The image_stack corresponds to the given data_idx.

Parameters:

  • data_idx (int) –

    An index that corresponds to a given image_stack.

Returns:

  • sequence of int –

    A sequence of patch indices, that when used to index the CAREamicsDataset will return a patch that comes from theimage_stackcorresponding to the givendata_idx`.

get_principal_input(input_patch)

Return the principal input without lateral context.

Parameters:

  • input_patch (NDArray[Any]) –

    Input patch with axes L(Z)YX, where L is the lateral context input axis.

Returns:

  • NDArray[Any] –

    Principal input with axes C(Z)YX.

get_target_image_metadata(patch_spec)

Return metadata for the target image.

Parameters:

  • patch_spec (PatchSpecs) –

    Patch specification. It is accepted to satisfy the protocol but is unused because prediction datasets do not have targets.

Returns:

  • None –

    Prediction datasets do not have target images.