Skip to content

cornucopia.labels

This module contains transforms that operate on label maps.

OneHotFinalTransform 

OneHotFinalTransform(labels, keep_background=True, dtype=None, **kwargs)

Bases: FinalTransform

Final transform for OneHotTransform.

Parameters:

Name Type Description Default
labels list[int | list[int]]

Mapping from output label to input label(s).

 required
keep_background bool

If True, the first one-hot class is the background class, and the one hot tensor sums to one.

 True
dtype dtype | None

Use a different dtype for the one-hot

 None

OneHotTransform 

OneHotTransform(label_map=None, label_ref=None, keep_background=True, dtype=None, **kwargs)

Bases: NonFinalTransform

Transform a volume of integer labels into a one-hot representation

Parameters:

Name Type Description Default
label_map list or [list of] int

Map one-hot classes to [list of] labels or label names

Should not include the background class

 None
label_ref dict[int] -> str

Map label values to label names

 None
keep_background bool

If True, the first one-hot class is the background class, and the one hot tensor sums to one.

 True
dtype dtype

Use a different dtype for the one-hot

 None

Final class-attribute instance-attribute 

Final = OneHotFinalTransform

The transform type returned by make_final.

Next class-attribute instance-attribute 

Next = OneHotFinalTransform

The transform type returned by make_final.

ArgMaxTransform 

ArgMaxTransform(*, returns=None, append=False, prefix=True, include=None, exclude=None, consume=None)

Bases: FinalTransform

Take the argmax along the channel dimension

RelabelFinalTransform 

RelabelFinalTransform(labels, **kwargs)

Bases: FinalTransform

Relabel a label map using a fixed mapping scheme.

Note

  • The labels are mapped to the range {1..len(labels)}.

  • If an element of this list is a sublist of indices, indices in the sublist are merged.

  • All labels absent from the list are mapped to 0.

Parameters:

Name Type Description Default
labels list of [list of] int

Relabeling scheme.

 required

RelabelTransform 

RelabelTransform(labels=None, **kwargs)

Bases: NonFinalTransform

Relabel a label map.

Note

  • The labels are mapped to the range {1..len(labels)}.

  • If an element of this list is a sublist of indices, indices in the sublist are merged.

  • All labels absent from the list are mapped to 0.

Parameters:

Name Type Description Default
labels list of [list of] int | None

Relabeling scheme.

 None

Final class-attribute instance-attribute 

Final = RelabelFinalTransform

The transform type returned by make_final.

Next class-attribute instance-attribute 

Next = RelabelFinalTransform

The transform type returned by make_final.

GaussianMixtureFinalTransform 

GaussianMixtureFinalTransform(mu, sigma, fwhm=None, background=None, dtype=None, **kwargs)

Bases: FinalTransform

Sample from a Gaussian mixture with known cluster parameters.

Parameters:

Name Type Description Default
mu (K,) list[float] | tensor

Mean of each cluster.

 required
sigma (K,) list[float] | tensor

Standard deviation of each cluster.

 required
fwhm float | (K,) list[float] | tensor | None

Width of a within-class smoothing kernel.

 None
background int | None

Index of background channel, which does not get filled.

 None
dtype dtype | None

Output data type. Only used if input is an integer label map.

 None

GaussianMixtureTransform 

GaussianMixtureTransform(mu=None, sigma=None, fwhm=0, background=None, dtype=None, *, shared=False, **kwargs)

Bases: NonFinalTransform

Sample from a Gaussian mixture with known cluster assignment

Parameters:

Name Type Description Default
mu list[float]

Mean of each cluster. Default: random in (0, 1).

 None
sigma list[float]

Standard deviation of each cluster. Default: 1/nb_classes.

 None
fwhm float or list[float]

Width of a within-class smoothing kernel.

 0
background int | None

Index of background channel, which does not get filled. Default: fill all classes.

 None
dtype dtype

Output data type. Only used if input is an integer label map.

 None

Next class-attribute instance-attribute 

Next = GaussianMixtureFinalTransform

The transform type returned by make_final.

Final class-attribute instance-attribute 

Final = GaussianMixtureFinalTransform

The transform type returned by make_final.

RandomGaussianMixtureTransform 

RandomGaussianMixtureTransform(mu=1, sigma=0.05, fwhm=2, background=None, dtype=None, *, shared=False, **kwargs)

Bases: NonFinalTransform

Sample from a randomized Gaussian mixture with known cluster assignment.

Parameters:

Name Type Description Default
mu Sampler | [list of] float

Sampling function for cluster means, or upper bound

 1
sigma Sampler | [list of] float

Sampling function for cluster standard deviations, or upper bound

 0.05
fwhm Sampler | [list of] float

Sampling function for smoothing width, or upper bound

 2
background int | None

Index of background channel

 None

Next class-attribute instance-attribute 

Next = GaussianMixtureTransform

The transform type returned by make_final(..., max_depth=1).

Final class-attribute instance-attribute 

Final = GaussianMixtureFinalTransform

The transform type returned by make_final(..., max_depth=inf).

SmoothLabelMap 

SmoothLabelMap(nb_classes=2, shape=5, soft=False, *, shared=False, **kwargs)

Bases: NonFinalTransform

Generate a random label map

Parameters:

Name Type Description Default
nb_classes int

Number of classes

 2
shape [list of] int

Number of spline control points

 5
soft bool

Return a soft (one-hot) label map

 False
shared bool

Apply the same field to all channels

 False

RandomSmoothLabelMap 

RandomSmoothLabelMap(nb_classes=8, shape=5, soft=False, *, shared=False, shared_field=None, **kwargs)

Bases: NonFinalTransform

Generate a random label map with random hyper-parameters

Parameters:

Name Type Description Default
nb_classes Sampler | int

Maximum number of classes

 8
shape Sampler | [list of] int

Maximum number of spline control points

 5
soft bool

Return a soft (one-hot) label map

 False

Other Parameters:

Name Type Description
shared (channels, tensors, channels + tensors, '')

Shared hyperparameters across tensors/channels
shared_field (channels, tensors, channels + tensors, '')

Shared random fields across tensors/channels

Next class-attribute instance-attribute 

Next = SmoothLabelMap

The transform type returned by make_final(..., max_depth=1).

Final class-attribute instance-attribute 

Final = ReturnValueTransform

The transform type returned by make_final(..., max_depth=inf).

ErodeLabelTransform 

ErodeLabelTransform(labels=tuple(), radius=3, method='conv', new_labels=False, **kwargs)

Bases: FinalTransform

Morphological erosion.

Parameters:

Name Type Description Default
labels [sequence of] int

Labels to erode

 tuple()
radius [sequence of] int

Erosion radius (per label)

 3
method (conv, l1, l2)

Method to use to compute the distance map. If 'conv', use the L1 distance computed using a series of convolutions. The radius will be rounded to the nearest integer. Otherwise, use the appropriate distance transform.

 'conv'
new_labels bool | [sequence of] int

If not False, the eroded portion of each label gives rise to a new label. If True, create new unique labels.

 False

DilateLabelTransform 

DilateLabelTransform(labels=tuple(), radius=3, method='conv', **kwargs)

Bases: FinalTransform

Morphological dilation.

Parameters:

Name Type Description Default
labels [sequence of] int

Labels to dilate. By default, all but zero.

 tuple()
radius [sequence of] int

Dilation radius (per label)

 3
method (conv, l1, l2)

Method to use to compute the distance map. If 'conv', use the L1 distance computed using a series of convolutions. The radius will be rounded to the nearest integer. Otherwise, use the appropriate distance transform.

 'conv'

RandomErodeLabelTransform 

RandomErodeLabelTransform(labels=0.5, radius=3, method='conv', new_labels=False, *, shared=False, **kwargs)

Bases: NonFinalTransform

Morphological erosion with random radius/labels.

Parameters:

Name Type Description Default
labels Sampler | float | [sequence of] int

Labels to erode. If a float in 0..1, probability of eroding a label

 0.5
radius Sampler | int

Erosion radius (per label). Either an int sampler, or an upper bound.

 3
method (conv, l1, l2)

Method to use to compute the distance map. If 'conv', use the L1 distance computed using a series of convolutions. The radius will be rounded to the nearest integer. Otherwise, use the appropriate distance transform.

 'conv'
new_labels bool | [sequence of] int

If not False, the eroded portion of each label gives rise to a new label. If True, create new unique labels.

 False

Other Parameters:

Name Type Description
shared (channels, tensors, channels + tensors, '')

Shared hyperparameters across tensors/channels

Final class-attribute instance-attribute 

Final = ErodeLabelTransform

The transform type returned by make_final.

Next class-attribute instance-attribute 

Next = ErodeLabelTransform

The transform type returned by make_final.

RandomDilateLabelTransform 

RandomDilateLabelTransform(labels=0.5, radius=3, method='conv', *, shared=False, **kwargs)

Bases: NonFinalTransform

Morphological dilation with random radius/labels.

Parameters:

Name Type Description Default
labels Sampler | float | [sequence of] int

Labels to dilate. If a float in 0..1, probability of dilating a label

 0.5
radius Sampler | int

Dilation radius (per label). Either an int sampler, or an upper bound.

 3
method (conv, l1, l2)

Method to use to compute the distance map. If 'conv', use the L1 distance computed using a series of convolutions. The radius will be rounded to the nearest integer. Otherwise, use the appropriate distance transform.

 'conv'

Other Parameters:

Name Type Description
shared (channels, tensors, channels + tensors, '')

Shared hyperparameters across tensors/channels

Final class-attribute instance-attribute 

Final = DilateLabelTransform

The transform type returned by make_final.

Next class-attribute instance-attribute 

Next = DilateLabelTransform

The transform type returned by make_final.

SmoothMorphoLabelFinalTransform 

SmoothMorphoLabelFinalTransform(fields, labels=1, min_radius=-30, max_radius=3, method='conv', **kwargs)

Bases: FinalTransform

Morphological erosion/dilation with spatially varying radius.

Parameters:

Name Type Description Default
fields Transform | (K|1, *spatial) tensor

Transform that generates the radius field(s). The output is expected to be in [0, 1].

 required
labels [sequence of (K,)] int

Labels to erode/dilate. By default, 1.

 1
min_radius [sequence of (K,)] int

Minimum erosion (if < 0) or dilation (if > 0) radius (per label).

 -30
max_radius [sequence of (K,)] int

Maximum erosion (if < 0) or dilation (if > 0) radius (per label).

 3
method (conv, l1, l2)

Method to use to compute the distance map.

 'conv'

SmoothMorphoLabelTransform 

SmoothMorphoLabelTransform(labels=tuple(), min_radius=-3, max_radius=3, shape=5, method='conv', *, shared=False, **kwargs)

Bases: NonFinalTransform

Morphological erosion with spatially varying radius.

Note

We're actually computing the level set of each label and pushing it up and down using a smooth "radius" map. In theory, this can create "holes" or "islands", which would not happen with a normal erosion. With radii that are small and radius map that are smooth compared to the label size, it should be fine.

Warning

The radius maps are sampled for each tensor. It is impossible to share them across tensors. The only shared options are therefore channels or False.

Parameters:

Name Type Description Default
labels [sequence of] int

Labels to erode

 tuple()
min_radius [sequence of] int

Minimum erosion (if < 0) or dilation (if > 0) radius (per label)

 -3
max_radius [sequence of] int

Maximum erosion (if < 0) or dilation (if > 0) radius (per label)

 3
shape [sequence of] int

Number of nodes in the smooth radius map

 5
method (conv, l1, l2)

Method to use to compute the distance map. If 'conv', use the L1 distance computed using a series of convolutions. The radius will be rounded to the nearest integer. Otherwise, use the appropriate distance transform.

 'conv'

Final class-attribute instance-attribute 

Final = SmoothMorphoLabelFinalTransform

The transform type returned by make_final.

Next class-attribute instance-attribute 

Next = SmoothMorphoLabelFinalTransform

The transform type returned by make_final.

RandomSmoothMorphoLabelTransform 

RandomSmoothMorphoLabelTransform(labels=0.5, min_radius=-3, max_radius=3, shape=5, method='conv', *, shared=False, shared_fields=None, **kwargs)

Bases: NonFinalTransform

Morphological erosion/dilation with smooth random radius/labels.

Parameters:

Name Type Description Default
labels Sampler or float or [sequence of] int

Labels to dilate. If a float in 0..1, probability of eroding a label

 0.5
min_radius [sequence of] int

Minimum erosion (if < 0) or dilation (if > 0) radius (per label) Either an int sampler, or an upper bound.

 -3
max_radius [sequence of] int

Maximum erosion (if < 0) or dilation (if > 0) radius (per label) Either an int sampler, or an upper bound.

 3
shape [sequence of] int

Number of nodes in the smooth radius map Either an int sampler, or an upper bound.

 5
method (conv, l1, l2)

Method to use to compute the distance map. If 'conv', use the L1 distance computed using a series of convolutions. The radius will be rounded to the nearest integer. Otherwise, use the appropriate distance transform.

 'conv'

Next class-attribute instance-attribute 

Next = SmoothMorphoLabelTransform

The transform type returned by make_final(..., max_depth=1).

Final class-attribute instance-attribute 

Final = SmoothMorphoLabelFinalTransform

The transform type returned by make_final(..., max_depth=inf).

SmoothShallowLabelFinalTransform 

SmoothShallowLabelFinalTransform(fields, labels=tuple(), max_width=5, min_width=1, background_labels=tuple(), method='l2', **kwargs)

Bases: FinalTransform

Make labels "empty", with a border of a given size.

Parameters:

Name Type Description Default
fields Transform | (K|1, *spatial) tensor

Transform that generates the width field(s). The output is expected to be in [0, 1].

 required
labels [sequence of (K,)] int

Labels to make shallow. By default, all but zero.

 tuple()
max_width [sequence of (K,)] int

Maximum border width (per label)

 5
min_width [sequence of (K,)] int

Minimum border width (per label)

 1
background_labels [sequence of (K,)] int

Labels that are allowed to grow into the shallow space (default: all that are not in labels)

 tuple()
method (l1, l2)

Method to use to compute the distance map.

 'l1'

SmoothShallowLabelTransform 

SmoothShallowLabelTransform(labels=tuple(), max_width=5, min_width=1, shape=5, background_labels=tuple(), method='l2', *, shared=False, **kwargs)

Bases: NonFinalTransform

Make labels "empty", with a border of a given size.

Parameters:

Name Type Description Default
labels [sequence of] int

Labels to make shallow

 tuple()
max_width [sequence of] int

Maximum border width (per label)

 5
min_width [sequence of] int

Minimum border width (per label)

 1
shape [sequence of] int

Number of nodes in the smooth width map

 5
background_labels [sequence of] int

Labels that are allowed to grow into the shallow space (default: all that are not in labels)

 tuple()
method (l1, l2)

Method to use to compute the distance map.

 'l1'

Final class-attribute instance-attribute 

Final = SmoothShallowLabelFinalTransform

The transform type returned by make_final.

Next class-attribute instance-attribute 

Next = SmoothShallowLabelFinalTransform

The transform type returned by make_final.

RandomSmoothShallowLabelTransform 

RandomSmoothShallowLabelTransform(labels=0.5, max_width=5, min_width=1, shape=5, background_labels=tuple(), method='l2', *, shared=False, shared_fields=None, **kwargs)

Bases: NonFinalTransform

Make labels "empty", with a border of a given (random) size.

Parameters:

Name Type Description Default
labels Sampler | float | [sequence of] int

Labels to make shallow If a float in 0..1, probability of eroding a label

 0.5
max_width Sampler | [sequence of] float

Maximum border width (per label) Either an int sampler, or an upper bound.

 5
min_width Sampler | [sequence of] float

Minimum border width (per label) Either an int sampler, or an upper bound.

 1
shape Sampler | [sequence of] int

Number of nodes in the smooth width map Either an int sampler, or an upper bound.

 5
background_labels Sampler | [sequence of] int

Labels that are allowed to grow into the shallow space (default: all that are not in labels)

 tuple()
method (l1, l2)

Method to use to compute the distance map. If 'conv', use the L1 distance computed using a series of convolutions. The radius will be rounded to the nearest integer. Otherwise, use the appropriate distance transform.

 'l1'

Next class-attribute instance-attribute 

Next = SmoothShallowLabelTransform

The transform type returned by make_final(..., max_depth=1).

Final class-attribute instance-attribute 

Final = SmoothShallowLabelFinalTransform

The transform type returned by make_final(..., max_depth=inf).

BernoulliTransform 

BernoulliTransform(prob=0.1, *, shared=False, **kwargs)

Bases: NonFinalTransform

Randomly mask voxels

Parameters:

Name Type Description Default
prob float

Probability of masking out a voxel

 0.1

Other Parameters:

Name Type Description
returns [list or dict of] {'input', 'output', 'noise'}

Which tensor to return
shared bool

Same mask shared across channels

Next class-attribute instance-attribute 

Next = MulValueTransform

The transform type returned by make_final.

Final class-attribute instance-attribute 

Final = MulValueTransform

The transform type returned by make_final.

SmoothBernoulliTransform 

SmoothBernoulliTransform(prob=0.1, shape=5, *, shared=False, shared_noise=False, **kwargs)

Bases: NonFinalTransform

Randomly mask voxels

Parameters:

Name Type Description Default
prob float

Probability of masking out a voxel

 0.1
shape int or sequence[int]

Number of control points in the smooth field

 5
returns [list or dict of] {'input', 'output', 'noise'}

Which tensor to return

 required
shared bool

Same probability field shared across channels/tensor

 False
shared_noise bool

Same mask shared across channels/tensor

 False

Final class-attribute instance-attribute 

Final = MulValueTransform

The transform type returned by make_final.

Next class-attribute instance-attribute 

Next = MulValueTransform

The transform type returned by make_final.

BernoulliDiskTransform 

BernoulliDiskTransform(prob=0.1, radius=2, value=0, method='l2', *, shared=False, **kwargs)

Bases: NonFinalTransform

Randomly mask voxels in balls at random locations

Parameters:

Name Type Description Default
prob float

Probability of masking out a voxel

 0.1
radius float or Sampler

Disk radius

 2
value float or int or {min, max, rand}

Value to set in the disks

 0
method (conv, l1, l2)

Method used to compute the distance map

 'conv'
returns [list or dict of] {'input', 'output', 'disks'}

Which tensor to return

 required
shared bool

Same mask shared across channels

 False

Final class-attribute instance-attribute 

Final = FillValueTransform

The transform type returned by make_final.

Next class-attribute instance-attribute 

Next = FillValueTransform

The transform type returned by make_final.

SmoothBernoulliDiskTransform 

SmoothBernoulliDiskTransform(prob=0.1, radius=2, shape=5, value=0, method='l2', *, shared=False, shared_field=None, **kwargs)

Bases: NonFinalTransform

Randomly mask voxels in balls at random locations

Parameters:

Name Type Description Default
prob float

Probability of masking out a voxel A probability field is sampled from a smooth random field.

 0.1
radius float or (float, float)

Max or Min/Max disk radius, sampled from a smooth random field.

 2
shape int or sequence[int]

Number of control points in the random field

 5
value float or int or {min, max, rand}

Value to set in the disks. If 'rand', a random value in the input range is used for each disk.

 0
method (conv, l1, l2)

Method used to compute the distance map

 'conv'
returns [list or dict of] {'input', 'output', 'disks'}

Which tensor to return

 required
shared bool

Same mask shared across channels

 False

Final class-attribute instance-attribute 

Final = FillValueTransform

The transform type returned by make_final.

Next class-attribute instance-attribute 

Next = FillValueTransform

The transform type returned by make_final.