transformer

startorch.transformer

Contain data transformers.

startorch.transformer.Add

Bases: BaseTransformer

Implements a tensor transformer that adds multiple tensors.

Parameters:

Name	Type	Description	Default
inputs	Sequence[str]	The keys to add.	required
output	str	The key that contains the output tensor.	required
exist_ok	bool	If False, an exception is raised if the output key already exists. Otherwise, the value associated to the output key is updated.	False

Raises:

Type	Description
ValueError	if inputs is empty.

Example usage:

>>> import torch
>>> from startorch.transformer import AddTransformer
>>> transformer = AddTransformer(inputs=["input1", "input2"], output="output")
>>> transformer
AddTransformer(
  (inputs): ('input1', 'input2')
  (output): output
  (exist_ok): False
)
>>> data = {
...     "input1": torch.tensor([[0.0, -1.0, 2.0], [-4.0, 5.0, -6.0]]),
...     "input2": torch.tensor([[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]]),
... }
>>> out = transformer.transform(data)
>>> out
{'input1': tensor([[ 0., -1.,  2.], [-4.,  5., -6.]]),
 'input2': tensor([[1., 2., 3.], [4., 5., 6.]]),
 'output': tensor([[ 1.,  1.,  5.], [ 0., 10.,  0.]])}

startorch.transformer.AddTransformer

Bases: BaseTransformer

Implements a tensor transformer that adds multiple tensors.

Parameters:

Name	Type	Description	Default
inputs	Sequence[str]	The keys to add.	required
output	str	The key that contains the output tensor.	required
exist_ok	bool	If False, an exception is raised if the output key already exists. Otherwise, the value associated to the output key is updated.	False

Raises:

Type	Description
ValueError	if inputs is empty.

Example usage:

>>> import torch
>>> from startorch.transformer import AddTransformer
>>> transformer = AddTransformer(inputs=["input1", "input2"], output="output")
>>> transformer
AddTransformer(
  (inputs): ('input1', 'input2')
  (output): output
  (exist_ok): False
)
>>> data = {
...     "input1": torch.tensor([[0.0, -1.0, 2.0], [-4.0, 5.0, -6.0]]),
...     "input2": torch.tensor([[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]]),
... }
>>> out = transformer.transform(data)
>>> out
{'input1': tensor([[ 0., -1.,  2.], [-4.,  5., -6.]]),
 'input2': tensor([[1., 2., 3.], [4., 5., 6.]]),
 'output': tensor([[ 1.,  1.,  5.], [ 0., 10.,  0.]])}

startorch.transformer.BaseTensorTransformer

Bases: BaseTransformer

Define the base class to transform a tensor.

Parameters:

Name	Type	Description	Default
input	str	The key that contains the input tensor.	required
output	str	The key that contains the output tensor.	required
exist_ok	bool	If False, an exception is raised if the output key already exists. Otherwise, the value associated to the output key is updated.	False

Example usage:

>>> import torch
>>> from startorch.transformer import LookupTable
>>> transformer = LookupTable(
...     weights=torch.tensor([5.0, 4.0, 3.0, 2.0, 1.0, 0.0]), index="index", output="output"
... )
>>> transformer
LookupTableTransformer(size=6, index=index, output=output, exist_ok=False)
>>> data = {"index": torch.tensor([[1, 2, 3], [4, 0, 2]])}
>>> out = transformer.transform(data)
>>> out
{'index': tensor([[1, 2, 3], [4, 0, 2]]), 'output': tensor([[4., 3., 2.], [1., 5., 3.]])}

startorch.transformer.BaseTransformer

Bases: ABC

Define the base class to transform a batch of data.

A child class has to implement the transform method.

Example usage:

>>> import torch
>>> from startorch.transformer import Identity
>>> transformer = Identity()
>>> transformer
IdentityTransformer(copy=True)
>>> data = {"key": torch.tensor([[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]])}
>>> out = transformer.transform(data)
>>> out
{'key': tensor([[1., 2., 3.],
                [4., 5., 6.]])}

startorch.transformer.BaseTransformer.transform abstractmethod

transform(
    data: dict[Hashable, Tensor],
    *,
    rng: Transformer | None = None
) -> dict[Hashable, Tensor]

Transform the input data.

Parameters:

Name	Type	Description	Default
data	dict[Hashable, Tensor]	The data to transform.	required
rng	Transformer | None	An optional random number transformer.	None

Returns:

Type	Description
dict[Hashable, Tensor]	The transformed data.

Example usage:

>>> import torch
>>> from startorch.transformer import Identity
>>> transformer = Identity()
>>> data = {'key': torch.tensor([[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]])}
>>> out = transformer.transform(data)
>>> out
{'key': tensor([[1., 2., 3.],
                [4., 5., 6.]])}

startorch.transformer.Div

Bases: BaseTransformer

Implements a tensor transformer that computes the division between two tensors.

This transformer is equivalent to: output = dividend / divisor

Parameters:

Name	Type	Description	Default
dividend	str	The key that contains the dividend.	required
divisor	str	The key that contains the divisor.	required
output	str	The key that contains the output tensor.	required
rounding_mode	str | None	The type of rounding applied to the result. - None: true division. - "trunc": rounds the results of the division towards zero. - "floor": floor division.	None
exist_ok	bool	If False, an exception is raised if the output key already exists. Otherwise, the value associated to the output key is updated.	False

Example usage:

>>> import torch
>>> from startorch.transformer import DivTransformer
>>> transformer = DivTransformer(dividend="input1", divisor="input2", output="output")
>>> transformer
DivTransformer(dividend=input1, divisor=input2, output=output, rounding_mode=None, exist_ok=False)
>>> data = {
...     "input1": torch.tensor([[0.0, -1.0, 2.0], [-4.0, 5.0, -6.0]]),
...     "input2": torch.tensor([[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]]),
... }
>>> out = transformer.transform(data)
>>> out
{'input1': tensor([[ 0., -1.,  2.], [-4.,  5., -6.]]),
 'input2': tensor([[1., 2., 3.], [4., 5., 6.]]),
 'output': tensor([[ 0.0000, -0.5000,  0.6667], [-1.0000,  1.0000, -1.0000]])}

startorch.transformer.DivTransformer

Bases: BaseTransformer

Implements a tensor transformer that computes the division between two tensors.

This transformer is equivalent to: output = dividend / divisor

Parameters:

Name	Type	Description	Default
dividend	str	The key that contains the dividend.	required
divisor	str	The key that contains the divisor.	required
output	str	The key that contains the output tensor.	required
rounding_mode	str | None	The type of rounding applied to the result. - None: true division. - "trunc": rounds the results of the division towards zero. - "floor": floor division.	None
exist_ok	bool	If False, an exception is raised if the output key already exists. Otherwise, the value associated to the output key is updated.	False

Example usage:

>>> import torch
>>> from startorch.transformer import DivTransformer
>>> transformer = DivTransformer(dividend="input1", divisor="input2", output="output")
>>> transformer
DivTransformer(dividend=input1, divisor=input2, output=output, rounding_mode=None, exist_ok=False)
>>> data = {
...     "input1": torch.tensor([[0.0, -1.0, 2.0], [-4.0, 5.0, -6.0]]),
...     "input2": torch.tensor([[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]]),
... }
>>> out = transformer.transform(data)
>>> out
{'input1': tensor([[ 0., -1.,  2.], [-4.,  5., -6.]]),
 'input2': tensor([[1., 2., 3.], [4., 5., 6.]]),
 'output': tensor([[ 0.0000, -0.5000,  0.6667], [-1.0000,  1.0000, -1.0000]])}

startorch.transformer.Exponential

Bases: BaseTensorTransformer

Implement a tensor transformer that samples values from an Exponential distribution.

The input must be a sequence of tensors with a single item. This tensor is interpreted as the rate parameters of the Exponential distribution.

Parameters:

Name	Type	Description	Default
rate	str	The key that contains the rate values of the Exponential distribution.	required
output	str	The key that contains the output values sampled from the Exponential distribution.	required
exist_ok	bool	If False, an exception is raised if the output key already exists. Otherwise, the value associated to the output key is updated.	False

Example usage:

>>> import torch
>>> from startorch.transformer import Exponential
>>> transformer = Exponential(rate="rate", output="output")
>>> transformer
ExponentialTransformer(rate=rate, output=output, exist_ok=False)
>>> data = {"rate": torch.tensor([[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]])}
>>> out = transformer.transform(data)
>>> out
{'rate': tensor([[1., 2., 3.],
                 [4., 5., 6.]]),
 'output': tensor([[...]])}

startorch.transformer.ExponentialTransformer

Bases: BaseTensorTransformer

Implement a tensor transformer that samples values from an Exponential distribution.

The input must be a sequence of tensors with a single item. This tensor is interpreted as the rate parameters of the Exponential distribution.

Parameters:

Name	Type	Description	Default
rate	str	The key that contains the rate values of the Exponential distribution.	required
output	str	The key that contains the output values sampled from the Exponential distribution.	required
exist_ok	bool	If False, an exception is raised if the output key already exists. Otherwise, the value associated to the output key is updated.	False

Example usage:

>>> import torch
>>> from startorch.transformer import Exponential
>>> transformer = Exponential(rate="rate", output="output")
>>> transformer
ExponentialTransformer(rate=rate, output=output, exist_ok=False)
>>> data = {"rate": torch.tensor([[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]])}
>>> out = transformer.transform(data)
>>> out
{'rate': tensor([[1., 2., 3.],
                 [4., 5., 6.]]),
 'output': tensor([[...]])}

startorch.transformer.Fmod

Bases: BaseTransformer

Implements a tensor transformer that computes the element-wise remainder of division between two tensors.

This transformer is equivalent to: output = dividend % divisor

Parameters:

Name	Type	Description	Default
dividend	str	The key that contains the dividend.	required
divisor	str	The key that contains the divisor.	required
output	str	The key that contains the output tensor.	required
exist_ok	bool	If False, an exception is raised if the output key already exists. Otherwise, the value associated to the output key is updated.	False

Example usage:

>>> import torch
>>> from startorch.transformer import FmodTransformer
>>> transformer = FmodTransformer(dividend="input1", divisor="input2", output="output")
>>> transformer
FmodTransformer(dividend=input1, divisor=input2, output=output, exist_ok=False)
>>> data = {
...     "input1": torch.tensor([[0.0, -1.0, 2.0], [-3.0, 6.0, -7.0]]),
...     "input2": torch.tensor([[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]]),
... }
>>> out = transformer.transform(data)
>>> out
{'input1': tensor([[ 0., -1.,  2.], [-3.,  6., -7.]]),
 'input2': tensor([[1., 2., 3.], [4., 5., 6.]]),
 'output': tensor([[ 0., -1.,  2.], [-3.,  1., -1.]])}

startorch.transformer.FmodTransformer

Bases: BaseTransformer

Implements a tensor transformer that computes the element-wise remainder of division between two tensors.

This transformer is equivalent to: output = dividend % divisor

Parameters:

Name	Type	Description	Default
dividend	str	The key that contains the dividend.	required
divisor	str	The key that contains the divisor.	required
output	str	The key that contains the output tensor.	required
exist_ok	bool	If False, an exception is raised if the output key already exists. Otherwise, the value associated to the output key is updated.	False

Example usage:

>>> import torch
>>> from startorch.transformer import FmodTransformer
>>> transformer = FmodTransformer(dividend="input1", divisor="input2", output="output")
>>> transformer
FmodTransformer(dividend=input1, divisor=input2, output=output, exist_ok=False)
>>> data = {
...     "input1": torch.tensor([[0.0, -1.0, 2.0], [-3.0, 6.0, -7.0]]),
...     "input2": torch.tensor([[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]]),
... }
>>> out = transformer.transform(data)
>>> out
{'input1': tensor([[ 0., -1.,  2.], [-3.,  6., -7.]]),
 'input2': tensor([[1., 2., 3.], [4., 5., 6.]]),
 'output': tensor([[ 0., -1.,  2.], [-3.,  1., -1.]])}

startorch.transformer.Identity

Bases: BaseTransformer

Implement the identity transformation.

Parameters:

Name	Type	Description	Default
copy	bool	If True, it returns a copy of the input tensor, otherwise it returns the input tensor.	True

Example usage:

>>> import torch
>>> from startorch.transformer import Identity
>>> transformer = Identity()
>>> transformer
IdentityTransformer(copy=True)
>>> data = {"key": torch.tensor([[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]])}
>>> out = transformer.transform(data)
>>> out
{'key': tensor([[1., 2., 3.],
                [4., 5., 6.]])}

startorch.transformer.IdentityTransformer

Bases: BaseTransformer

Implement the identity transformation.

Parameters:

Name	Type	Description	Default
copy	bool	If True, it returns a copy of the input tensor, otherwise it returns the input tensor.	True

Example usage:

>>> import torch
>>> from startorch.transformer import Identity
>>> transformer = Identity()
>>> transformer
IdentityTransformer(copy=True)
>>> data = {"key": torch.tensor([[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]])}
>>> out = transformer.transform(data)
>>> out
{'key': tensor([[1., 2., 3.],
                [4., 5., 6.]])}

startorch.transformer.Linear

Bases: BaseTransformer

Implement a transformer that computes a linear transformation.

Parameters:

Name	Type	Description	Default
value	str	The key that contains the input values. The linear transformation is applied on these values.	required
slope	str	The key that contains the slope values.	required
intercept	str	The key that contains the intercept values.	required
output	str	The key that contains the output values.	required
exist_ok	bool	If False, an exception is raised if the output key already exists. Otherwise, the value associated to the output key is updated.	False

Example usage:

>>> import torch
>>> from startorch.transformer import Linear
>>> transformer = Linear(
...     value="value", slope="slope", intercept="intercept", output="output"
... )
>>> transformer
LinearTransformer(value=value, slope=slope, intercept=intercept, output=output, exist_ok=False)
>>> data = {
...     "value": torch.tensor([[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]]),
...     "slope": torch.tensor([[2.0, 2.0, 2.0], [4.0, 4.0, 4.0]]),
...     "intercept": torch.tensor([[1.0, 1.0, 1.0], [-1.0, -1.0, -1.0]]),
... }
>>> out = transformer.transform(data)
>>> out
{'value': tensor([[1., 2., 3.], [4., 5., 6.]]),
 'slope': tensor([[2., 2., 2.], [4., 4., 4.]]),
 'intercept': tensor([[ 1.,  1.,  1.], [-1., -1., -1.]]),
 'output': tensor([[ 3.,  5.,  7.], [15., 19., 23.]])}

startorch.transformer.LinearTransformer

Bases: BaseTransformer

Implement a transformer that computes a linear transformation.

Parameters:

Name	Type	Description	Default
value	str	The key that contains the input values. The linear transformation is applied on these values.	required
slope	str	The key that contains the slope values.	required
intercept	str	The key that contains the intercept values.	required
output	str	The key that contains the output values.	required
exist_ok	bool	If False, an exception is raised if the output key already exists. Otherwise, the value associated to the output key is updated.	False

Example usage:

>>> import torch
>>> from startorch.transformer import Linear
>>> transformer = Linear(
...     value="value", slope="slope", intercept="intercept", output="output"
... )
>>> transformer
LinearTransformer(value=value, slope=slope, intercept=intercept, output=output, exist_ok=False)
>>> data = {
...     "value": torch.tensor([[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]]),
...     "slope": torch.tensor([[2.0, 2.0, 2.0], [4.0, 4.0, 4.0]]),
...     "intercept": torch.tensor([[1.0, 1.0, 1.0], [-1.0, -1.0, -1.0]]),
... }
>>> out = transformer.transform(data)
>>> out
{'value': tensor([[1., 2., 3.], [4., 5., 6.]]),
 'slope': tensor([[2., 2., 2.], [4., 4., 4.]]),
 'intercept': tensor([[ 1.,  1.,  1.], [-1., -1., -1.]]),
 'output': tensor([[ 3.,  5.,  7.], [15., 19., 23.]])}

startorch.transformer.LookupTable

Bases: BaseTensorTransformer

Implement a tensor transformer that replaces indices by values from the lookup table.

Parameters:

Name	Type	Description	Default
weights	Tensor	The weights of the lookup table.	required
index	str	The key that contains the input indices of the lookup table. The tensor must be of long data type.	required
output	str	The key that contains the output values from the lookup table.	required
exist_ok	bool	If False, an exception is raised if the output key already exists. Otherwise, the value associated to the output key is updated.	False

Example usage:

>>> import torch
>>> from startorch.transformer import LookupTable
>>> transformer = LookupTable(
...     weights=torch.tensor([5.0, 4.0, 3.0, 2.0, 1.0, 0.0]), index="index", output="output"
... )
>>> transformer
LookupTableTransformer(size=6, index=index, output=output, exist_ok=False)
>>> data = {"index": torch.tensor([[1, 2, 3], [4, 0, 2]])}
>>> out = transformer.transform(data)
>>> out
{'index': tensor([[1, 2, 3], [4, 0, 2]]), 'output': tensor([[4., 3., 2.], [1., 5., 3.]])}

startorch.transformer.LookupTableTransformer

Bases: BaseTensorTransformer

Implement a tensor transformer that replaces indices by values from the lookup table.

Parameters:

Name	Type	Description	Default
weights	Tensor	The weights of the lookup table.	required
index	str	The key that contains the input indices of the lookup table. The tensor must be of long data type.	required
output	str	The key that contains the output values from the lookup table.	required
exist_ok	bool	If False, an exception is raised if the output key already exists. Otherwise, the value associated to the output key is updated.	False

Example usage:

>>> import torch
>>> from startorch.transformer import LookupTable
>>> transformer = LookupTable(
...     weights=torch.tensor([5.0, 4.0, 3.0, 2.0, 1.0, 0.0]), index="index", output="output"
... )
>>> transformer
LookupTableTransformer(size=6, index=index, output=output, exist_ok=False)
>>> data = {"index": torch.tensor([[1, 2, 3], [4, 0, 2]])}
>>> out = transformer.transform(data)
>>> out
{'index': tensor([[1, 2, 3], [4, 0, 2]]), 'output': tensor([[4., 3., 2.], [1., 5., 3.]])}

startorch.transformer.Mul

Bases: BaseTransformer

Implements a tensor transformer that multiplies multiple tensors.

Parameters:

Name	Type	Description	Default
inputs	Sequence[str]	The keys to multiply.	required
output	str	The key that contains the output tensor.	required
exist_ok	bool	If False, an exception is raised if the output key already exists. Otherwise, the value associated to the output key is updated.	False

Raises:

Type	Description
ValueError	if inputs is empty.

Example usage:

>>> import torch
>>> from startorch.transformer import MulTransformer
>>> transformer = MulTransformer(inputs=["input1", "input2"], output="output")
>>> transformer
MulTransformer(
  (inputs): ('input1', 'input2')
  (output): output
  (exist_ok): False
)
>>> data = {
...     "input1": torch.tensor([[0.0, -1.0, 2.0], [-4.0, 5.0, -6.0]]),
...     "input2": torch.tensor([[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]]),
... }
>>> out = transformer.transform(data)
>>> out
{'input1': tensor([[ 0., -1.,  2.], [-4.,  5., -6.]]),
 'input2': tensor([[1., 2., 3.], [4., 5., 6.]]),
 'output': tensor([[  0.,  -2.,   6.], [-16.,  25., -36.]])}

startorch.transformer.MulTransformer

Bases: BaseTransformer

Implements a tensor transformer that multiplies multiple tensors.

Parameters:

Name	Type	Description	Default
inputs	Sequence[str]	The keys to multiply.	required
output	str	The key that contains the output tensor.	required
exist_ok	bool	If False, an exception is raised if the output key already exists. Otherwise, the value associated to the output key is updated.	False

Raises:

Type	Description
ValueError	if inputs is empty.

Example usage:

>>> import torch
>>> from startorch.transformer import MulTransformer
>>> transformer = MulTransformer(inputs=["input1", "input2"], output="output")
>>> transformer
MulTransformer(
  (inputs): ('input1', 'input2')
  (output): output
  (exist_ok): False
)
>>> data = {
...     "input1": torch.tensor([[0.0, -1.0, 2.0], [-4.0, 5.0, -6.0]]),
...     "input2": torch.tensor([[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]]),
... }
>>> out = transformer.transform(data)
>>> out
{'input1': tensor([[ 0., -1.,  2.], [-4.,  5., -6.]]),
 'input2': tensor([[1., 2., 3.], [4., 5., 6.]]),
 'output': tensor([[  0.,  -2.,   6.], [-16.,  25., -36.]])}

startorch.transformer.Poisson

Bases: BaseTensorTransformer

Implement a tensor transformer that samples values from a Poisson distribution.

The input must be a sequence of tensors with a single item. This tensor is interpreted as the rate parameters of the Poisson distribution.

Parameters:

Name	Type	Description	Default
rate	str	The key that contains the rate values of the Poisson distribution.	required
output	str	The key that contains the output values sampled from the Poisson distribution.	required
exist_ok	bool	If False, an exception is raised if the output key already exists. Otherwise, the value associated to the output key is updated.	False

Example usage:

>>> import torch
>>> from startorch.transformer import Poisson
>>> transformer = Poisson(rate="rate", output="output")
>>> transformer
PoissonTransformer(rate=rate, output=output, exist_ok=False)
>>> data = {"rate": torch.tensor([[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]])}
>>> out = transformer.transform(data)
>>> out
{'rate': tensor([[1., 2., 3.],
                 [4., 5., 6.]]),
 'output': tensor([[...]])}

startorch.transformer.PoissonTransformer

Bases: BaseTensorTransformer

Implement a tensor transformer that samples values from a Poisson distribution.

The input must be a sequence of tensors with a single item. This tensor is interpreted as the rate parameters of the Poisson distribution.

Parameters:

Name	Type	Description	Default
rate	str	The key that contains the rate values of the Poisson distribution.	required
output	str	The key that contains the output values sampled from the Poisson distribution.	required
exist_ok	bool	If False, an exception is raised if the output key already exists. Otherwise, the value associated to the output key is updated.	False

Example usage:

>>> import torch
>>> from startorch.transformer import Poisson
>>> transformer = Poisson(rate="rate", output="output")
>>> transformer
PoissonTransformer(rate=rate, output=output, exist_ok=False)
>>> data = {"rate": torch.tensor([[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]])}
>>> out = transformer.transform(data)
>>> out
{'rate': tensor([[1., 2., 3.],
                 [4., 5., 6.]]),
 'output': tensor([[...]])}

startorch.transformer.RemoveKeys

Bases: BaseTransformer

Implements a transformer that removes some keys.

Parameters:

Name	Type	Description	Default
keys	Sequence[str]	The keys to remove. The other keys will be kept in the output.	required
missing_ok	bool	If False, an exception is raised if the key is missing. Otherwise, the missing key is ignored.	False

Example usage:

>>> import torch
>>> from startorch.transformer import RemoveKeysTransformer
>>> transformer = RemoveKeysTransformer(keys=["input3"])
>>> transformer
RemoveKeysTransformer(
  (keys): ('input3',)
  (missing_ok): False
)
>>> data = {
...     "input1": torch.tensor([[0.0, -1.0, 2.0], [-4.0, 5.0, -6.0]]),
...     "input2": torch.tensor([[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]]),
...     "input3": torch.randn(2, 4),
... }
>>> out = transformer.transform(data)
>>> out
{'input1': tensor([[ 0., -1.,  2.], [-4.,  5., -6.]]),
 'input2': tensor([[1., 2., 3.], [4., 5., 6.]])}

startorch.transformer.RemoveKeysTransformer

Bases: BaseTransformer

Implements a transformer that removes some keys.

Parameters:

Name	Type	Description	Default
keys	Sequence[str]	The keys to remove. The other keys will be kept in the output.	required
missing_ok	bool	If False, an exception is raised if the key is missing. Otherwise, the missing key is ignored.	False

Example usage:

>>> import torch
>>> from startorch.transformer import RemoveKeysTransformer
>>> transformer = RemoveKeysTransformer(keys=["input3"])
>>> transformer
RemoveKeysTransformer(
  (keys): ('input3',)
  (missing_ok): False
)
>>> data = {
...     "input1": torch.tensor([[0.0, -1.0, 2.0], [-4.0, 5.0, -6.0]]),
...     "input2": torch.tensor([[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]]),
...     "input3": torch.randn(2, 4),
... }
>>> out = transformer.transform(data)
>>> out
{'input1': tensor([[ 0., -1.,  2.], [-4.,  5., -6.]]),
 'input2': tensor([[1., 2., 3.], [4., 5., 6.]])}

startorch.transformer.SelectKeys

Bases: BaseTransformer

Implements a transformer that selects a subset of keys.

Parameters:

Name	Type	Description	Default
keys	Sequence[str]	The keys to select. The other keys will not be in the output.	required
missing_ok	bool	If False, an exception is raised if the key is missing. Otherwise, the missing key is ignored.	False

Example usage:

>>> import torch
>>> from startorch.transformer import SelectKeysTransformer
>>> transformer = SelectKeysTransformer(keys=["input1", "input2"])
>>> transformer
SelectKeysTransformer(
  (keys): ('input1', 'input2')
  (missing_ok): False
)
>>> data = {
...     "input1": torch.tensor([[0.0, -1.0, 2.0], [-4.0, 5.0, -6.0]]),
...     "input2": torch.tensor([[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]]),
...     "input3": torch.randn(2, 4),
... }
>>> out = transformer.transform(data)
>>> out
{'input1': tensor([[ 0., -1.,  2.], [-4.,  5., -6.]]),
 'input2': tensor([[1., 2., 3.], [4., 5., 6.]])}

startorch.transformer.SelectKeysTransformer

Bases: BaseTransformer

Implements a transformer that selects a subset of keys.

Parameters:

Name	Type	Description	Default
keys	Sequence[str]	The keys to select. The other keys will not be in the output.	required
missing_ok	bool	If False, an exception is raised if the key is missing. Otherwise, the missing key is ignored.	False

Example usage:

>>> import torch
>>> from startorch.transformer import SelectKeysTransformer
>>> transformer = SelectKeysTransformer(keys=["input1", "input2"])
>>> transformer
SelectKeysTransformer(
  (keys): ('input1', 'input2')
  (missing_ok): False
)
>>> data = {
...     "input1": torch.tensor([[0.0, -1.0, 2.0], [-4.0, 5.0, -6.0]]),
...     "input2": torch.tensor([[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]]),
...     "input3": torch.randn(2, 4),
... }
>>> out = transformer.transform(data)
>>> out
{'input1': tensor([[ 0., -1.,  2.], [-4.,  5., -6.]]),
 'input2': tensor([[1., 2., 3.], [4., 5., 6.]])}

startorch.transformer.Sequential

Bases: BaseTransformer

Implement a transformer that sequentially computes transformations.

Parameters:

Name	Type	Description	Default
transformers	Sequence[BaseTransformer | dict]	The sequence of transformers or their configurations.	required

Example usage:

>>> import torch
>>> from startorch.transformer import Sequential, TensorTransformer
>>> from startorch.tensor.transformer import Abs, Clamp
>>> transformer = Sequential(
...     [
...         TensorTransformer(transformer=Abs(), input="input", output="output1"),
...         TensorTransformer(
...             transformer=Clamp(min=-1, max=2), input="input", output="output2"
...         ),
...     ]
... )
>>> transformer
SequentialTransformer(
  (0): TensorTransformer(
      (transformer): AbsTensorTransformer()
      (input): input
      (output): output1
      (exist_ok): False
    )
  (1): TensorTransformer(
      (transformer): ClampTensorTransformer(min=-1, max=2)
      (input): input
      (output): output2
      (exist_ok): False
    )
)
>>> data = {"input": torch.tensor([[1.0, -2.0, 3.0], [-4.0, 5.0, -6.0]])}
>>> out = transformer.transform(data)
>>> out
{'input': tensor([[ 1., -2.,  3.],
                  [-4.,  5., -6.]]),
 'output1': tensor([[1., 2., 3.],
                    [4., 5., 6.]]),
 'output2': tensor([[ 1., -1.,  2.],
                    [-1.,  2., -1.]])}

startorch.transformer.SequentialTransformer

Bases: BaseTransformer

Implement a transformer that sequentially computes transformations.

Parameters:

Name	Type	Description	Default
transformers	Sequence[BaseTransformer | dict]	The sequence of transformers or their configurations.	required

Example usage:

>>> import torch
>>> from startorch.transformer import Sequential, TensorTransformer
>>> from startorch.tensor.transformer import Abs, Clamp
>>> transformer = Sequential(
...     [
...         TensorTransformer(transformer=Abs(), input="input", output="output1"),
...         TensorTransformer(
...             transformer=Clamp(min=-1, max=2), input="input", output="output2"
...         ),
...     ]
... )
>>> transformer
SequentialTransformer(
  (0): TensorTransformer(
      (transformer): AbsTensorTransformer()
      (input): input
      (output): output1
      (exist_ok): False
    )
  (1): TensorTransformer(
      (transformer): ClampTensorTransformer(min=-1, max=2)
      (input): input
      (output): output2
      (exist_ok): False
    )
)
>>> data = {"input": torch.tensor([[1.0, -2.0, 3.0], [-4.0, 5.0, -6.0]])}
>>> out = transformer.transform(data)
>>> out
{'input': tensor([[ 1., -2.,  3.],
                  [-4.,  5., -6.]]),
 'output1': tensor([[1., 2., 3.],
                    [4., 5., 6.]]),
 'output2': tensor([[ 1., -1.,  2.],
                    [-1.,  2., -1.]])}

startorch.transformer.SineWave

Bases: BaseTransformer

Implement a transformer that computes a linear transformation.

Parameters:

Name	Type	Description	Default
value	str	The key that contains the input values. The sine wave transformation is applied on these values.	required
frequency	str	The key that contains the frequency values.	required
phase	str	The key that contains the phase values.	required
amplitude	str	The key that contains the amplitude values.	required
output	str	The key that contains the output values.	required
exist_ok	bool	If False, an exception is raised if the output key already exists. Otherwise, the value associated to the output key is updated.	False

Example usage:

>>> import torch
>>> from startorch.transformer import SineWave
>>> transformer = SineWave(
...     value="value",
...     frequency="frequency",
...     phase="phase",
...     amplitude="amplitude",
...     output="output",
... )
>>> transformer
SineWaveTransformer(value=value, frequency=frequency, phase=phase, amplitude=amplitude, output=output, exist_ok=False)
>>> data = {
...     "value": torch.tensor([[0.1, 0.2, 0.3], [0.5, 0.6, 0.7]]),
...     "frequency": torch.tensor([[2.0, 2.0, 2.0], [4.0, 4.0, 4.0]]),
...     "phase": torch.tensor([[1.0, 1.0, 1.0], [-1.0, -1.0, -1.0]]),
...     "amplitude": torch.tensor([[1.0, 1.0, 1.0], [2.0, 2.0, 2.0]]),
... }
>>> out = transformer.transform(data)
>>> out
{'value': tensor([[0.1000, 0.2000, 0.3000], [0.5000, 0.6000, 0.7000]]),
 'frequency': tensor([[2., 2., 2.], [4., 4., 4.]]),
 'phase': tensor([[ 1.,  1.,  1.], [-1., -1., -1.]]),
 'amplitude': tensor([[1., 1., 1.], [2., 2., 2.]]),
 'output': tensor([[ 0.7739, -0.3632, -0.9983], [-1.6829,  1.9967, -1.5478]])}

startorch.transformer.SineWaveTransformer

Bases: BaseTransformer

Implement a transformer that computes a linear transformation.

Parameters:

Name	Type	Description	Default
value	str	The key that contains the input values. The sine wave transformation is applied on these values.	required
frequency	str	The key that contains the frequency values.	required
phase	str	The key that contains the phase values.	required
amplitude	str	The key that contains the amplitude values.	required
output	str	The key that contains the output values.	required
exist_ok	bool	If False, an exception is raised if the output key already exists. Otherwise, the value associated to the output key is updated.	False

Example usage:

>>> import torch
>>> from startorch.transformer import SineWave
>>> transformer = SineWave(
...     value="value",
...     frequency="frequency",
...     phase="phase",
...     amplitude="amplitude",
...     output="output",
... )
>>> transformer
SineWaveTransformer(value=value, frequency=frequency, phase=phase, amplitude=amplitude, output=output, exist_ok=False)
>>> data = {
...     "value": torch.tensor([[0.1, 0.2, 0.3], [0.5, 0.6, 0.7]]),
...     "frequency": torch.tensor([[2.0, 2.0, 2.0], [4.0, 4.0, 4.0]]),
...     "phase": torch.tensor([[1.0, 1.0, 1.0], [-1.0, -1.0, -1.0]]),
...     "amplitude": torch.tensor([[1.0, 1.0, 1.0], [2.0, 2.0, 2.0]]),
... }
>>> out = transformer.transform(data)
>>> out
{'value': tensor([[0.1000, 0.2000, 0.3000], [0.5000, 0.6000, 0.7000]]),
 'frequency': tensor([[2., 2., 2.], [4., 4., 4.]]),
 'phase': tensor([[ 1.,  1.,  1.], [-1., -1., -1.]]),
 'amplitude': tensor([[1., 1., 1.], [2., 2., 2.]]),
 'output': tensor([[ 0.7739, -0.3632, -0.9983], [-1.6829,  1.9967, -1.5478]])}

startorch.transformer.Sub

Bases: BaseTransformer

Implements a tensor transformer that computes the difference between two tensors.

This transformer is equivalent to: output = minuend - subtrahend

Parameters:

Name	Type	Description	Default
minuend	str	The key that contains the minuend.	required
subtrahend	str	The key that contains the subtrahend.	required
output	str	The key that contains the output tensor.	required
exist_ok	bool	If False, an exception is raised if the output key already exists. Otherwise, the value associated to the output key is updated.	False

Example usage:

>>> import torch
>>> from startorch.transformer import SubTransformer
>>> transformer = SubTransformer(minuend="input1", subtrahend="input2", output="output")
>>> transformer
SubTransformer(minuend=input1, subtrahend=input2, output=output, exist_ok=False)
>>> data = {
...     "input1": torch.tensor([[0.0, -1.0, 2.0], [-4.0, 5.0, -6.0]]),
...     "input2": torch.tensor([[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]]),
... }
>>> out = transformer.transform(data)
>>> out
{'input1': tensor([[ 0., -1.,  2.], [-4.,  5., -6.]]),
 'input2': tensor([[1., 2., 3.], [4., 5., 6.]]),
 'output': tensor([[ -1.,  -3.,  -1.], [ -8.,   0., -12.]])}

startorch.transformer.SubTransformer

Bases: BaseTransformer

Implements a tensor transformer that computes the difference between two tensors.

This transformer is equivalent to: output = minuend - subtrahend

Parameters:

Name	Type	Description	Default
minuend	str	The key that contains the minuend.	required
subtrahend	str	The key that contains the subtrahend.	required
output	str	The key that contains the output tensor.	required
exist_ok	bool	If False, an exception is raised if the output key already exists. Otherwise, the value associated to the output key is updated.	False

Example usage:

>>> import torch
>>> from startorch.transformer import SubTransformer
>>> transformer = SubTransformer(minuend="input1", subtrahend="input2", output="output")
>>> transformer
SubTransformer(minuend=input1, subtrahend=input2, output=output, exist_ok=False)
>>> data = {
...     "input1": torch.tensor([[0.0, -1.0, 2.0], [-4.0, 5.0, -6.0]]),
...     "input2": torch.tensor([[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]]),
... }
>>> out = transformer.transform(data)
>>> out
{'input1': tensor([[ 0., -1.,  2.], [-4.,  5., -6.]]),
 'input2': tensor([[1., 2., 3.], [4., 5., 6.]]),
 'output': tensor([[ -1.,  -3.,  -1.], [ -8.,   0., -12.]])}

startorch.transformer.TensorTransformer

Bases: BaseTransformer

Implements a generic tensor transformer.

Parameters:

Name	Type	Description	Default
transformer	BaseTensorTransformer | dict	The tensor transformer or its configuration.	required
input	str	The key that contains the input tensor.	required
output	str	The key that contains the output tensor.	required
exist_ok	bool	If False, an exception is raised if the output key already exists. Otherwise, the value associated to the output key is updated.	False

Example usage:

>>> import torch
>>> from startorch.transformer import TensorTransformer
>>> from startorch.tensor.transformer import Abs
>>> transformer = TensorTransformer(transformer=Abs(), input="input", output="output")
>>> transformer
TensorTransformer(
  (transformer): AbsTensorTransformer()
  (input): input
  (output): output
  (exist_ok): False
)
>>> data = {"input": torch.tensor([[0.0, -1.0, 2.0], [-4.0, 5.0, -6.0]])}
>>> out = transformer.transform(data)
>>> out
{'input': tensor([[ 0., -1.,  2.],
                  [-4.,  5., -6.]]),
 'output': tensor([[0., 1., 2.],
                   [4., 5., 6.]])}

startorch.transformer.is_transformer_config

is_transformer_config(config: dict) -> bool

Indicate if the input configuration is a configuration for a BaseTransformer.

This function only checks if the value of the key _target_ is valid. It does not check the other values. If _target_ indicates a function, the returned type hint is used to check the class.

Parameters:

Name	Type	Description	Default
config	dict	The configuration to check.	required

Returns:

Type	Description
bool	True if the input configuration is a configuration for a BaseTransformer object.

Example usage:

>>> from startorch.transformer import is_transformer_config
>>> is_transformer_config({"_target_": "startorch.transformer.Identity"})
True

startorch.transformer.setup_transformer

setup_transformer(
    transformer: BaseTransformer | dict,
) -> BaseTransformer

Set up a tensor transformer.

The tensor transformer is instantiated from its configuration by using the BaseTransformer factory function.

Parameters:

Name	Type	Description	Default
transformer	BaseTransformer | dict	A tensor transformer or its configuration.	required

Returns:

Type	Description
BaseTransformer	A tensor transformer.

Example usage:

>>> from startorch.transformer import setup_transformer
>>> setup_transformer({"_target_": "startorch.transformer.Identity"})
IdentityTransformer(copy=True)

startorch.transformer.sine_wave

sine_wave(
    value: Tensor,
    frequency: Tensor,
    phase: Tensor,
    amplitude: Tensor,
) -> Tensor

Return the output of the sine-wave transformation.

This function computes the following transformation: output = amplitude * sin(2 * pi * frequency * value + phase)

All the tensors must have the same shape.

Parameters:

Name	Type	Description	Default
value	Tensor	The values that are used as input.	required
frequency	Tensor	The frequency values.	required
phase	Tensor	The phase values.	required
amplitude	Tensor	The amplitude values.	required

Returns:

Type	Description
Tensor	The transformed values.

Example usage:

>>> import math
>>> import torch
>>> from startorch.transformer import sine_wave
>>> out = sine_wave(
...     value=torch.tensor([[0.0, 0.5, 1.0, 1.5, 2.0], [0.0, 0.25, 0.5, 0.75, 1.0]]),
...     frequency=torch.tensor([[0.5, 0.5, 0.5, 0.5, 0.5], [1.0, 1.0, 1.0, 1.0, 1.0]]),
...     phase=torch.tensor([[0.0, 0.0, 0.0, 0.0, 0.0], [0.5 * math.pi, 0.5 * math.pi, 0.5 * math.pi, 0.5 * math.pi, 0.5 * math.pi]]),
...     amplitude=torch.tensor([[2.0, 2.0, 2.0, 2.0, 2.0], [1.0, 1.0, 1.0, 1.0, 1.0]]),
... )
>>> out
tensor([[ 0.0000e+00,  2.0000e+00, -1.7485e-07, -2.0000e+00,  3.4969e-07],
        [ 1.0000e+00, -8.7423e-08, -1.0000e+00,  1.7485e-07,  1.0000e+00]])