cornucopia.base

Transform

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

Bases: Module

Base class for all transforms

Parameters:

Name	Type	Description	Default
`returns`	`[list or dict of] str`	Which tensors to return. Most transforms accept `'input'` and `'output'` as valid returns.	`None`
`append`	`bool`	Append the (structure of) returned tensors to the parent structure.	`False`
`prefix`	`bool`	If `append` and parent is a dict, prefix the child's key with the parent key.	`True`
`include`	`str or list[str]`	List of keys to which the transform should apply	`None`
`exclude`	`str or list[str]`	List of keys to which the transform should not apply	`None`

forward

forward(*a, **k)

Apply the transform recursively.

Parameters:

Name	Type	Description	Default
`x`	`[nested list or dict of] tensor`	Input tensors, with shape `(C, *shape)`	required

Returns:

Type	Description
`[nested list or dict of] tensor`	Output tensors. with shape `(C, *shape)`

FinalTransform

FinalTransform(**kwargs)

Bases: Transform

Mixin for determinstic transforms.

xform

xform(x)

Apply the transform to a tensor

Parameters:

Name	Type	Description	Default
`x`	`(C_inp, *spatial_inp) tensor`		required

Returns:

Name	Type	Description
`y`	`(C_out, *spatial_out) tensor`

make_inverse

make_inverse()

Generate the inverse transform

inverse

inverse(*a, **k)

Apply the inverse transform recursively

Parameters:

Name	Type	Description	Default
`x`	`[nested list or dict of] tensor`	Input tensors, with shape `(C, *shape)`	required

Returns:

Type	Description
`[nested list or dict of] tensor`	Output tensors. with shape `(C, *shape)`

IdentityTransform

IdentityTransform(**kwargs)

Bases: FinalTransform

Identity transform

SharedMixin

Mixin for transforms that have parameters (e.g. random ones) that may be shared across tensors and/or channels or independent across tensors and/or channels.

NonFinalTransform

NonFinalTransform(*, shared=False, **kwargs)

Bases: SharedMixin, Transform

Transforms whose parameters depend on features of the input transform (shape, dtype, etc)

Parameters:

Name	Type	Description	Default
`shared`	`(channels, tensors, channels + tensor, '')`	'channel': the same transform is applied to all channels in a tensor, but different transforms are used in different tensors. 'tensors': the same transform is applied to all tensors, but with a different transform for each channel. 'channels+tensors' or True: the same transform is applied to all channels of all tensors. '' or False: A different transform is applied to each channel and each tensor.	`'channels'`

SpecialMixin

Mixin for special transforms (i.e. transforms of transforms)

make_inverse

make_inverse()

Generate the inverse transform

inverse

inverse(*a, **k)

Apply the inverse transform recursively

Parameters:

Name	Type	Description	Default
`x`	`[nested list or dict of] tensor`	Input tensors, with shape `(C, *shape)`	required

Returns:

Type	Description
`[nested list or dict of] tensor`	Output tensors. with shape `(C, *shape)`

SequentialTransform

SequentialTransform(transforms, **kwargs)

Bases: SpecialMixin, SharedMixin, Transform

A sequence of transforms

Example

Sequences can be built explicitly, or simply by adding transforms together:

t1 = MultFieldTransform()
t2 = GaussianNoiseTransform()
seq = SequentialTransform([t1, t2])     # explicit
seq = t1 + t2                           # implicit

Sequences can also be extended by addition:

seq += SmoothTransform()

Parameters:

Name	Type	Description	Default
`transforms`	`list[Transform]`	A list of transforms to apply sequentially.	required

Other Parameters:

Name	Type	Description
`shared`	`(channels, tensors, channels + tensor, '')`	'channel': the same sequence is applied to all channels in a tensor, but different transforms are used in different tensors. 'tensors': the same transform is applied to all tensors, but with a different transform for each channel. 'channels+tensors' or True: the same transform is applied to all channels of all tensors. None or False: A different transform is applied to each channel and each tensor.
`include`	`str or list[str]`	List of keys to which the transform should apply
`exclude`	`str or list[str]`	List of keys to which the transform should not apply

PerChannelTransform

PerChannelTransform(transforms, **kwargs)

Bases: SpecialMixin, Transform

Apply a different transform to each channel

Parameters:

Name	Type	Description	Default
`transforms`	`list[Transform]`	A list of transforms to apply to each channel.	required

MaybeTransform

MaybeTransform(transform, prob=0.5, *, shared=True, **kwargs)

Bases: SpecialMixin, SharedMixin, Transform

Randomly apply a transform

20% chance of adding noise

import cornucopia as cc
gauss = cc.GaussianNoiseTransform()

Explicit call to the class:

 img = cc.MaybeTransform(gauss, 0.2)(img)

Implicit call using syntactic sugar:

img = (0.2 * gauss)(img)

```

Default for shared changed from False to True

Parameters:

Name	Type	Description	Default
`transform`	`Transform`	A transform to randomly apply	required
`prob`	`float`	Probability to apply the transform	`0.5`
`shared`	`(channels, tensors, channels + tensor, '')`	Roll the dice once for all input tensors	`'channels'`

SwitchTransform

SwitchTransform(transforms, prob=0, *, shared=True, **kwargs)

Bases: SpecialMixin, SharedMixin, Transform

Randomly choose a transform to apply

Randomly apply either Gaussian or Chi noise

import cornucopia as cc
gauss = cc.GaussianNoiseTransform()
chi = cc.ChiNoiseTransform()

Explicit call to the class:

img = cc.SwitchTransform([gauss, chi])(img)

Implicit call using syntactic sugar:

img = (gauss | chi)(img)

Functional call:

img = cc.switch({gauss: 0.5, chi: 0.5})(img)

Default for shared changed from False to True

Parameters:

Name	Type	Description	Default
`transforms`	`list[Transform]`	A list of transforms to sample from	required
`prob`	`list[float]`	Probability of applying each transform	`0`
`shared`	`(channels, tensors, channels + tensor, '')`	Roll the dice once for all input tensors	`'channels'`

IncludeKeysTransform

IncludeKeysTransform(transform, keys, union=True)

Bases: SpecialMixin, Transform

Context manager for keys to include

Use as a transform

from cornucopia import IncludeKeysTransform
newxform = IncludeKeysTransform(xform, "image)
image, label = newxform(image=image, label=label)

Use as a context manager with as

from cornucopia import IncludeKeysTransform
with IncludeKeysTransform(xform, "image") as newxform:
    image, label = newxform(image=image, label=label)

Use as a context manager with

from cornucopia import IncludeKeysTransform
with IncludeKeysTransform(xform, "image"):
    image, label = xform(image=image, label=label)

Use as a context manager (alias)

from cornucopia import context as ctx
with ctx.include(xform, "image") as newxform:
    image, label = newxform(image=image, label=label)

Parameters:

Name	Type	Description	Default
`transform`	`Transform`	Transform to apply	required
`keys`	`[sequence of] str`	Keys to include	required
`union`	`bool`	Include the union of what was already included and `keys`	`True`

ExcludeKeysTransform

ExcludeKeysTransform(transform, keys, union=True)

Bases: SpecialMixin, Transform

Context manager for keys to exclude. Can also be used as a transform.

Use as a transform

from cornucopia import ExcludeKeysTransform
newxform = ExcludeKeysTransform(xform, "image)
image, label = newxform(image=image, label=label)

Use as a context manager with as

from cornucopia import ExcludeKeysTransform
with ExcludeKeysTransform(xform, "image") as newxform:
    image, label = newxform(image=image, label=label)

Use as a context manager with

from cornucopia import ExcludeKeysTransform
with ExcludeKeysTransform(xform, "image"):
    image, label = xform(image=image, label=label)

Use as a context manager (alias)

from cornucopia import context as ctx
with ctx.exclude(xform, "image") as newxform:
    image, label = newxform(image=image, label=label)

Parameters:

Name	Type	Description	Default
`transform`	`Transform`	Transform to apply	required
`keys`	`[sequence of] str`	Keys to include	required
`union`	`bool`	Exclude the union of what was already excluded and `keys`	`True`

SharedTransform

SharedTransform(transform, mode=unset)

Bases: SpecialMixin, SharedMixin, Transform

Context manager for sharing transforms across channels / tensors. Can also be used as a transform.

Use as a context manager (alias)

from cornucopia import context as ctx
with ctx.shared(xform, "channels") as newxform:
    image = newxform(image)

Parameters:

Name	Type	Description	Default
`transform`	`Transform`	Transform to apply	required
`mode`	`(channels, tensors, channels + tensor, '')`		`'channels'`

ReturningTransform

ReturningTransform(transform, returns=None)

Bases: SpecialMixin, Transform

Context manager for sharing transforms across channels / tensors

Use as a context manager (alias)

from cornucopia import context as ctx
with ctx.returns(xform, "channels") as newxform:
    image = newxform(image)

MappedTransform

MappedTransform(*mapargs, nested=False, default=None, **mapkwargs)

Bases: SpecialMixin, Transform

Transforms that are applied to specific positional or arguments

Example

img = torch.randn([1, 32, 32])
seg = torch.randn([3, 32, 32]).softmax(0)

# positional variant
trf = MappedTransform(GaussianNoise(), None)
img, seg = trf(img, seg)

# keyword variant
trf = MappedTransform(image=GaussianNoise())
img, seg = trf(image=img, label=seg)

# alternative version
dat = {'img': torch.randn([1, 32, 32]),
       'seg': torch.randn([3, 32, 32]).softmax(0)}
dat = MappedTransform(img=GaussianNoise(), nested=True)(dat)

Parameters:

Name	Type	Description	Default
`mapargs`	`tuple[Transform]`	Transform to apply to positional arguments	`()`
`mapkwargs`	`dict[str, Transform]`	Transform to apply to keyword arguments	`{}`
`nested`	`bool`	Recursively traverse the inputs until we find matching dictionaries. Only `mapkwargs` are accepted if "nested".	`False`
`default`	`Transform`	Transform to apply if nothing is specifically mapped	`None`

RandomizedTransform

RandomizedTransform(transform, sample=tuple(), ksample=dict(), *, shared=False, **kwargs)

Bases: NonFinalTransform

Transform generated by randomizing some parameters of another transform.

ctx.randomize is an alias for RandomizedTransform

Gaussian noise with randomized variance

Object call

import cornucopia as cc
hypernoise = cc.RandomizedTransform(cc.GaussianNoise, [cc.Uniform()])
img = hypernoise(img)

Delayed call

import cornucopia as cc
MyRandomNoise = cc.randomize(cc.GaussianNoise)
hypernoise = MyRandomNoise(cc.Uniform())
img = hypernoise(img)

Parameters:

Name	Type	Description	Default
`transform`	`callable(...) -> Transform`	A Transform subclass or a function that constructs a Transform.	required
`sample`	`[list or dict of] callable`	A collection of functions that generate parameter values provided to `transform`. Can be args-like or kwargs-like arguments.	`tuple()`
`ksample`	`dict[callable]`	Must be kwargs-like arguments.	`dict()`

Other Parameters:

Name	Type	Description
`shared`	`(channels, tensors, channels + tensors, '')`	Share random parameters across tensors and/or channels