utils

startorch.utils

Contain utility functions.

startorch.utils.batch

Contain utility functions for batches.

startorch.utils.batch.scale_batch

scale_batch(
    batch: Tensor, scale: str = "identity"
) -> Tensor

Scale a batch.

Parameters:

Name	Type	Description	Default
batch	Tensor	The batch to scale.	required
scale	str	The scaling transformation.	'identity'

Returns:

Type	Description
Tensor	The scaled batch.

Example usage:

>>> import torch
>>> from startorch.utils.batch import scale_batch
>>> batch = torch.arange(10).view(2, 5)
>>> scale_batch(batch, scale="asinh")
tensor([[0.0000, 0.8814, 1.4436, 1.8184, 2.0947],
        [2.3124, 2.4918, 2.6441, 2.7765, 2.8934]])

startorch.utils.conversion

Contain utility functions to convert objects.

startorch.utils.conversion.to_array

to_array(data: Sequence | Tensor | ndarray) -> ndarray

Convert the input to a numpy.ndarray.

Parameters:

Name	Type	Description	Default
data	Sequence | Tensor | ndarray	The data to convert to an array.	required

Returns:

Type	Description
ndarray	A NumPy array.

Example usage:

>>> from startorch.utils.conversion import to_array
>>> x = to_array([1, 2, 3, 4, 5])
>>> x
array([1, 2, 3, 4, 5])

startorch.utils.conversion.to_tensor

to_tensor(data: Tensor | ndarray | Sequence) -> Tensor

Convert the input to a torch.Tensor.

Parameters:

Name	Type	Description	Default
data	Tensor | ndarray | Sequence	The data to convert to a tensor.	required

Returns:

Type	Description
Tensor	A tensor.

Example usage:

>>> from startorch.utils.conversion import to_tensor
>>> x = to_tensor([1, 2, 3, 4, 5])
>>> x
tensor([1, 2, 3, 4, 5])

startorch.utils.conversion.to_tuple

to_tuple(value: Any) -> tuple

Convert a value to a tuple.

This function is a no-op if the input is a tuple.

Parameters:

Name	Type	Description	Default
value	Any	The value to convert.	required

Returns:

Type	Description
tuple	The input value in a tuple.

Example usage:

>>> from startorch.utils.conversion import to_tuple
>>> to_tuple(1)
(1,)
>>> to_tuple("abc")
('abc',)

startorch.utils.format

Contain utility functions to format strings.

startorch.utils.format.str_target_object

str_target_object(config: dict) -> str

Get a string that indicates the target object in the config.

Parameters:

Name	Type	Description	Default
config	dict	A config using the object_factory library. This dict is expected to have a key '_target_' to indicate the target object.	required

Returns:

Type	Description
str	A string with the target object.

Example usage:

>>> from startorch.utils.format import str_target_object
>>> str_target_object({OBJECT_TARGET: "something.MyClass"})
[_target_: something.MyClass]
>>> str_target_object({})
[_target_: N/A]

startorch.utils.format.str_weighted_modules

str_weighted_modules(
    modules: Sequence,
    weights: Sequence,
    num_spaces: int = 2,
) -> str

Compute a pretty representation of a sequence of modules where each module is associated to a weight.

Parameters:

Name	Type	Description	Default
modules	Sequence	The modules.	required
weights	Sequence	The weights. The weights should have the same length that modules.	required
num_spaces	int	The number of spaces used for the indentation.	2

Returns:

Type	Description
str	The string representation of the modules.

Example usage:

>>> from startorch.utils.format import str_weighted_modules
>>> print(str_weighted_modules(modules=["abc", "something\nelse"], weights=[1, 2]))
(0) [weight=1] abc
(1) [weight=2] something
  else

startorch.utils.imports

Implement some utility functions to manage optional dependencies.

startorch.utils.imports.check_iden

check_iden() -> None

Check if the iden package is installed.

Raises:

Type	Description
RuntimeError	if the iden package is not installed.

Example usage:

>>> from startorch.utils.imports import check_iden
>>> check_iden()

startorch.utils.imports.check_matplotlib

check_matplotlib() -> None

Check if the matplotlib package is installed.

Raises:

Type	Description
RuntimeError	if the matplotlib package is not installed.

Example usage:

>>> from startorch.utils.imports import check_matplotlib
>>> check_matplotlib()

startorch.utils.imports.check_plotly

check_plotly() -> None

Check if the plotly package is installed.

Raises:

Type	Description
RuntimeError	if the plotly package is not installed.

Example usage:

>>> from startorch.utils.imports import check_plotly
>>> check_plotly()

startorch.utils.imports.is_iden_available

is_iden_available() -> bool

Indicate if the iden package is installed or not.

Example usage:

>>> from startorch.utils.imports import is_iden_available
>>> is_iden_available()

startorch.utils.imports.is_matplotlib_available

is_matplotlib_available() -> bool

Indicate if the matplotlib package is installed or not.

Example usage:

>>> from startorch.utils.imports import is_matplotlib_available
>>> is_matplotlib_available()

startorch.utils.imports.is_plotly_available

is_plotly_available() -> bool

Indicate if the plotly package is installed or not.

Example usage:

>>> from startorch.utils.imports import is_plotly_available
>>> is_plotly_available()

startorch.utils.mask

Contain utility functions to mask values.

startorch.utils.mask.mask_by_row

mask_by_row(
    tensor: Tensor,
    n: int,
    mask_value: float = 0.0,
    rng: Generator | None = None,
) -> Tensor

Set to 0 some values in each row.

Parameters:

Name	Type	Description	Default
tensor	Tensor	The input tensor with the data to zero. This input must be a 2D tensor.	required
n	int	The number of values to mask for each row.	required
mask_value	float	The value used to mask.	0.0
rng	Generator | None	An optional random number generator.	None

Returns:

Type	Description
Tensor	The tensor with the masked values.

Raises:

Type	Description
ValueError	if the number of dimension is not 2.
ValueError	if number of values to mask is incorrect.

Example usage:

>>> import torch
>>> from startorch.utils.mask import mask_by_row
>>> tensor = torch.arange(10).view(2, 5)
>>> mask_by_row(tensor, n=2)
tensor([[...]])

startorch.utils.mask.mask_square_matrix

mask_square_matrix(
    matrix: Tensor,
    n: int,
    mask_value: float = 0.0,
    rng: Generator | None = None,
) -> Tensor

Mask some values of a square matrix.

This function is designed to mask all the rows and columns with the same number.

Parameters:

Name	Type	Description	Default
matrix	Tensor	The input tensor with the data to zero. This input must be a 2D tensor.	required
n	int	The number of values to mask for each row.	required
mask_value	float	The value used to mask.	0.0
rng	Generator | None	An optional random number generator.	None

Returns:

Type	Description
Tensor	The tensor with the masked values.

Raises:

Type	Description
ValueError	if the number of dimension is not 2.
ValueError	if number of values to mask is incorrect.

Example usage:

>>> import torch
>>> from startorch.utils.mask import mask_by_row
>>> tensor = torch.arange(10).view(2, 5)
>>> mask_by_row(tensor, n=2)
tensor([[...]])

startorch.utils.tensor

Contain utility functions for PyTorch tensors.

startorch.utils.tensor.circulant

circulant(vector: Tensor) -> Tensor

Return a circulant matrix of shape (n, n).

Parameters:

Name	Type	Description	Default
vector	Tensor	The base vector of shape (n,) used to generate the circulant matrix.	required

Returns:

Type	Description
Tensor	A circulant matrix of shape (n, n).

Raises:

Type	Description
ValueError	if the input tensor is not a vector.

Example usage:

>>> import torch
>>> from startorch.utils.tensor import circulant
>>> c = circulant(torch.arange(5))
>>> c
tensor([[0, 1, 2, 3, 4],
        [4, 0, 1, 2, 3],
        [3, 4, 0, 1, 2],
        [2, 3, 4, 0, 1],
        [1, 2, 3, 4, 0]])
>>> c = circulant(torch.tensor([1, 2, 3, 0]))
>>> c
tensor([[1, 2, 3, 0],
        [0, 1, 2, 3],
        [3, 0, 1, 2],
        [2, 3, 0, 1]])

startorch.utils.tensor.shapes_are_equal

shapes_are_equal(tensors: Sequence[Tensor]) -> bool

Return True if the shapes of several tensors are equal, otherwise False.

This method does not check the values or the data type of the tensors.

Parameters:

Name	Type	Description	Default
tensors	Sequence[Tensor]	The tensors to check.	required

Returns:

Type	Description
bool	True if all the tensors have the same shape, otherwise False. By design, this function returns False if no tensor is provided.

Example usage:

>>> import torch
>>> from startorch.utils.tensor import shapes_are_equal
>>> shapes_are_equal([torch.rand(2, 3), torch.rand(2, 3)])
True
>>> shapes_are_equal([torch.rand(2, 3), torch.rand(2, 3, 1)])
False

startorch.utils.validation

Contain utility functions to validate values.

startorch.utils.validation.check_feature_size

check_feature_size(value: int | Any, low: int = 1) -> None

Check if the given value is a valid feature size i.e. number of features.

Parameters:

Name	Type	Description	Default
value	int | Any	The value to check.	required
low	int	The minimum value (inclusive).	1

Raises:

Type	Description
TypeError	if the input is not an integer.
RuntimeError	if the value is not greater than 0

Example usage:

>>> import torch
>>> from startorch.utils.validation import check_feature_size
>>> check_feature_size(5)

startorch.utils.validation.check_integer_ge

check_integer_ge(
    value: int | Any, low: int, name: str
) -> None

Check if the given value is a valid positive integer.

Parameters:

Name	Type	Description	Default
value	int | Any	The value to check.	required
low	int	The minimum value (inclusive).	required
name	str	The variable name.	required

Raises:

Type	Description
TypeError	if the input is not an integer.
RuntimeError	if the value is not greater than 0

Example usage:

>>> import torch
>>> from startorch.utils.validation import check_integer_ge
>>> check_integer_ge(5, low=0, name="feature_size")

startorch.utils.validation.check_interval

check_interval(
    value: float | Any, low: float, high: float, name: str
) -> None

Check if the given value is an interval.

Parameters:

Name	Type	Description	Default
value	float | Any	The value to check.	required
low	float	The minimum value (inclusive).	required
high	float	The maximum value (exclusive).	required
name	str	The variable name.	required

Raises:

Type	Description
TypeError	if the input is not an integer or float.
RuntimeError	if the value is not in the interval

Example usage:

>>> import torch
>>> from startorch.utils.validation import check_interval
>>> check_interval(1, low=-1.0, high=2.0, name="my_variable")

startorch.utils.validation.check_num_examples

check_num_examples(value: int | Any) -> None

Check if the given value is a valid number of examples.

Parameters:

Name	Type	Description	Default
value	int | Any	The value to check.	required

Raises:

Type	Description
TypeError	if the input is not an integer.
RuntimeError	if the value is not greater than 0

Example usage:

>>> import torch
>>> from startorch.utils.validation import check_num_examples
>>> check_num_examples(5)

startorch.utils.validation.check_std

check_std(value: float | Any, name: str = 'std') -> None

Check if the given value is a valid standard deviation.

Parameters:

Name	Type	Description	Default
value	float | Any	The value to check.	required
name	str	The variable name.	'std'

Raises:

Type	Description
TypeError	if the input is not an integer or float.
RuntimeError	if the value is not greater than 0

Example usage:

>>> import torch
>>> from startorch.utils.validation import check_std
>>> check_std(1.2)

startorch.utils.weight

Contain utility functions to prepare weighted generators.

startorch.utils.weight.prepare_probabilities

prepare_probabilities(
    weights: Tensor | Sequence[float],
) -> Tensor

Convert un-normalized positive weights to probabilities.

Parameters:

Name	Type	Description	Default
weights	Tensor | Sequence[float]	The vector of weights associated to each category. The weights have to be positive. It must be a float tensor of shape (num_categories,) or a Sequence.	required

Returns:

Type	Description
Tensor	The vector of probability associated at each category. The output is a torch.Tensor of type float and shape (num_categories,)

Raises:

Type	Description
ValueError	if the weights are not valid.

Example usage:

>>> from startorch.utils.weight import prepare_probabilities
>>> prepare_probabilities([1, 1, 1, 1])
tensor([0.2500, 0.2500, 0.2500, 0.2500])

startorch.utils.weight.prepare_weighted_generators

prepare_weighted_generators(
    generators: Sequence[dict],
) -> tuple[tuple[Any, ...], tuple[float, ...]]

Prepare the tensor generators.

Each dictionary in the input tuple/list should have the following items:

- a key ``'generator'`` which indicates the tensor generator
    or its configuration.
- an optional key ``'weight'`` with a float value which
    indicates the weight of the tensor generator.
    If this key is absent, the weight is set to ``1.0``.

Parameters:

Name	Type	Description	Default
generators	Sequence[dict]	The tensor generators and their weights. See above to learn about the expected format.	required

Returns:

Type	Description
tuple[tuple[Any, ...], tuple[float, ...]]	A tuple with two items: - a tuple of generators or their configurations - a tuple of generator weights

Example usage:

>>> from startorch.utils.weight import prepare_weighted_generators
>>> from startorch.tensor import RandUniform, RandNormal
>>> prepare_weighted_generators(
...     (
...         {"weight": 2.0, "generator": RandUniform()},
...         {"weight": 1.0, "generator": RandNormal()},
...     )
... )
((RandUniformTensorGenerator(low=0.0, high=1.0), RandNormalTensorGenerator(mean=0.0, std=1.0)), (2.0, 1.0))