noise_layer

Modules:

Name	Description
`base`
`cloak_noise`
`cloak_one_shot`
`diffusion_cloak`
`estimators`
`maskers`
`parameterizations`
`patch_cloak`
`patch_cloak_frequency_space`
`transformer_cloak`
`utils`

Classes:

Name	Description
`BaseNoiseLayer`	Applies a stochastic transformation to a `Tensor` using the given `Estimator`s.
`CloakNoiseLayer`	Applies an input independent stochastic transformation to a `Tensor` using `ParameterWrapper`,
`CloakNoiseLayer1`	Applies an input independent stochastic transformation to a `Tensor` using `ParameterWrapper`
`CloakNoiseLayer2`	Applies an input independent stochastic transformation to a `Tensor` using `ParameterWrapper`,
`CloakNoiseLayer2_NoClip`	Applies an input independent stochastic transformation to a `Tensor` using `ParameterWrapper`,
`CloakNoiseLayerOneShot`	Applies an input independent stochastic transformation to a `Tensor` using `ParameterWrapper`,
`PatchCloakNoiseLayer`	Applies an input-dependent stochastic transformation to an image in non-overlapping patches using `Conv2d`
`PatchCloakNoiseLayer1`	Applies an input-dependent stochastic transformation to an image in non-overlapping patches using `Conv2d`
`PatchCloakNoiseLayer2`	Applies an input-dependent stochastic transformation to an image in non-overlapping patches using `Conv2d`
`PatchCloakNoiseLayer2_NoClip`	Applies an input-dependent stochastic transformation to an image in non-overlapping patches using `Conv2d`
`PatchCloakNoiseLayerFrequencySpace`	Applies an input-dependent stochastic transformation to an image in frequency space in non-overlapping patches using `Conv2d`

BaseNoiseLayer ¶

Bases: Module, Generic[EstimatorModuleT, ParameterizationT, OptionalMaskerT]

Applies a stochastic transformation to a Tensor using the given Estimators.

Parameters:

Name	Type	Description	Default
`seed` ¶	`int \| None`	Seed for the random number generator used to generate the stochastic transformation. If `None`, the global RNG state is used.	required
`mean_estimator` ¶	`Estimator[EstimatorModuleT, None, None]`	The estimator to use to estimate the mean of the stochastic transformation.	required
`std_estimator` ¶	`Estimator[EstimatorModuleT, ParameterizationT, OptionalMaskerT]`	The estimator to use to estimate the standard deviation and optional input mask of the stochastic transformation.	required

Methods:

Name	Description
`__call__`	Transform the input data.
`__getstate__`	Prepare a serializable copy of `self.__dict__`.
`__init_subclass__`	Set the default dtype to `torch.float32` inside all subclass `__init__` methods.
`__setstate__`	Restore from a serialized copy of `self.__dict__`.
`forward`	Transform the input data.
`get_applied_transform_components_factory`	Create a function that returns the elements of the transform components (`'mean'` and `'std'`) applied during the most recent
`get_transformed_output_factory`	Create a function that returns the transformed output from the most recent forward pass.
`initial_seed`	Return the initial seed of the CPU device's random number generator.
`manual_seed`	Seed each of the random number generators.
`reset_parameters`	Reinitialize parameters and buffers.
`seed`	Seed each of the random number generators using a non-deterministic random number.

call ¶

__call__(
    input: Tensor,
    noise_mask: Tensor | None = None,
    **kwargs: Any,
) -> torch.Tensor

Transform the input data.

Parameters:

Name	Type	Description	Default
`input` ¶	`Tensor`	The input to transform.	required
`noise_mask` ¶	`Tensor \| None`	An optional mask that selects the elements of `input` to transform. Where the mask is `False`, the original `input` value is returned. Also used to select the elements of the sampled standard deviations to use to mask the `input`. If `None`, the entire `input` is transformed.	`None`
`**kwargs` ¶	`Any`	Additional keyword arguments to the estimator modules.	required

getstate ¶

__getstate__() -> dict[str, Any]

Prepare a serializable copy of self.__dict__.

__init_subclass__ ¶

__init_subclass__() -> None

Set the default dtype to torch.float32 inside all subclass __init__ methods.

setstate ¶

__setstate__(state: dict[str, Any]) -> None

Restore from a serialized copy of self.__dict__.

forward ¶

forward(
    input: Tensor,
    noise_mask: Tensor | None = None,
    **kwargs: Any,
) -> torch.Tensor

Transform the input data.

Parameters:

Name	Type	Description	Default
`input` ¶	`Tensor`	The input to transform.	required
`noise_mask` ¶	`Tensor \| None`	An optional mask that selects the elements of `input` to transform. Where the mask is `0`, the original `input` value is returned. Also used to select the elements of the sampled standard deviations to use to mask the `input`. If `None`, the entire `input` is transformed.	`None`
`**kwargs` ¶	`Any`	Additional keyword arguments to the estimator modules.	required

Returns:

Type	Description
`torch.Tensor`	The transformed input data.

get_applied_transform_components_factory ¶

get_applied_transform_components_factory() -> Callable[
    [], dict[str, torch.Tensor]
]

Create a function that returns the elements of the transform components ('mean' and 'std') applied during the most recent forward pass.

Specifically, the applied elements are those selected by the noise mask (if supplied) and standard deviation mask (if std_estimator.masker is not None). If no masks are used, all elements are returned.

The applied transform components are returned flattened.

This function is intended to be used to log histograms of the transform components.

Returns:

Type	Description
`Callable[[], dict[str, torch.Tensor]]`	A function that returns the the elements of the transform components applied during the most recent forward pass.

Examples:

>>> from torch import nn
>>> from stainedglass_core import model as sg_model, noise_layer as sg_noise_layer
>>> base_model = nn.Linear(20, 2)
>>> noisy_model = sg_model.NoisyModel(
...     sg_noise_layer.CloakNoiseLayer1,
...     base_model,
...     target_parameter="input",
... )
>>> get_applied_transform_components = (
...     noisy_model.noise_layer.get_applied_transform_components_factory()
... )
>>> input = torch.ones(1, 20)
>>> noise_mask = torch.tensor(5 * [False] + 15 * [True])
>>> output = noisy_model(input, noise_mask=noise_mask)
>>> applied_transform_components = get_applied_transform_components()
>>> applied_transform_components
{'mean': tensor(...), 'std': tensor(...)}
>>> {
...     component_name: component.shape
...     for component_name, component in applied_transform_components.items()
... }
{'mean': torch.Size([15]), 'std': torch.Size([15])}

get_transformed_output_factory ¶

get_transformed_output_factory() -> Callable[
    [], torch.Tensor
]

Create a function that returns the transformed output from the most recent forward pass.

If super batching is active, only the transformed half of the super batch output is returned.

Returns:

Type	Description
`Callable[[], torch.Tensor]`	A function that returns the transformed output from the most recent forward pass.

Examples:

>>> from stainedglass_core import noise_layer as sg_noise_layer
>>> noise_layer = sg_noise_layer.CloakNoiseLayer1()
>>> get_transformed_output = noise_layer.get_transformed_output_factory()
>>> input = torch.ones(2, 3, 32, 32)
>>> output = noise_layer(input)
>>> transformed_output = get_transformed_output()
>>> assert output.equal(transformed_output)

initial_seed ¶

initial_seed() -> int

Return the initial seed of the CPU device's random number generator.

manual_seed ¶

manual_seed(seed: int | None) -> None

Seed each of the random number generators.

Setting seed to None will destroy any existing generators.

Parameters:

Name	Type	Description	Default
`seed` ¶	`int \| None`	The seed to set.	required

reset_parameters ¶

reset_parameters() -> None

Reinitialize parameters and buffers.

This method is useful for initializing tensors created on the meta device.

seed ¶

seed() -> None

Seed each of the random number generators using a non-deterministic random number.

CloakNoiseLayer ¶

Bases: BaseNoiseLayer[ParameterWrapper, CloakStandardDeviationParameterization, Optional[PercentMasker]]

Applies an input independent stochastic transformation to a Tensor using ParameterWrapper, with standard deviations parameterized by CloakStandardDeviationParameterization, optional standard deviation-based input masking using PercentMasker, and optional output clamping.

Inspired by the Cloak algorithm defined in the paper: Not All Features Are Equal: Discovering Essential Features for Preserving Prediction Privacy.

Parameters:

Name	Type	Description	Default
`scale` ¶	`tuple[float, float]`	Used to set bound on the min and max standard deviation of the stochastic transformation.	`(0.0001, 2.0)`
`shallow` ¶	`float`	A temperature-like parameter which controls the spread of the parameterization function. Controls both the magnitude of parameterized standard deviations and their rate of change with respect to rhos.	`1.0`
`percent_to_mask` ¶	`float \| None`	The percentage of the input to mask.	`None`
`value_range` ¶	`tuple[float \| None, float \| None] \| None`	Minimum and maximum values of the range to clamp the output into.	`None`
`locs_requires_grad` ¶	`bool`	Whether the locs parameters (related to the means of the transform) have their gradients tracked.	`True`
`rhos_requires_grad` ¶	`bool`	Whether the rhos parameters (related to the standard deviations of the transform) have their gradients tracked.	`True`
`rhos_init` ¶	`float`	The initial values for the rhos.	`-4.0`
`seed` ¶	`int \| None`	Seed for the random number generator used to generate the stochastic transformation. If `None`, the global RNG state is used.	`None`

Warning

The directly learned locs and rhos used by this class are prone to vanishing when trained with weight decay regularization. To avoid this, ensure that optimizer parameter group(s) containing locs or rhos are configured with weight_decay=0.0.

Methods:

Name	Description
`__call__`	Transform the input data.
`__getstate__`	Prepare a serializable copy of `self.__dict__`.
`__init_subclass__`	Set the default dtype to `torch.float32` inside all subclass `__init__` methods.
`__setstate__`	Restore from a serialized copy of `self.__dict__`.
`forward`	Transform the input data.
`get_applied_transform_components_factory`	Create a function that returns the elements of the transform components (`'mean'` and `'std'`) applied during the most recent
`get_transformed_output_factory`	Create a function that returns the transformed output from the most recent forward pass.
`initial_seed`	Return the initial seed of the CPU device's random number generator.
`manual_seed`	Seed each of the random number generators.
`reset_parameters`	Reinitialize parameters and buffers.
`seed`	Seed each of the random number generators using a non-deterministic random number.

call ¶

__call__(
    input: Tensor,
    noise_mask: Tensor | None = None,
    **kwargs: Any,
) -> torch.Tensor

Transform the input data.

Parameters:

Name	Type	Description	Default
`input` ¶	`Tensor`	The input to transform.	required
`noise_mask` ¶	`Tensor \| None`	An optional mask that selects the elements of `input` to transform. Where the mask is `False`, the original `input` value is returned. Also used to select the elements of the sampled standard deviations to use to mask the `input`. If `None`, the entire `input` is transformed.	`None`
`**kwargs` ¶	`Any`	Additional keyword arguments to the estimator modules.	required

getstate ¶

__getstate__() -> dict[str, Any]

Prepare a serializable copy of self.__dict__.

__init_subclass__ ¶

__init_subclass__() -> None

Set the default dtype to torch.float32 inside all subclass __init__ methods.

setstate ¶

__setstate__(state: dict[str, Any]) -> None

Restore from a serialized copy of self.__dict__.

forward ¶

forward(
    input: Tensor,
    noise_mask: Tensor | None = None,
    **kwargs: Any,
) -> torch.Tensor

Transform the input data.

Parameters:

Name	Type	Description	Default
`input` ¶	`Tensor`	The input to transform.	required
`noise_mask` ¶	`Tensor \| None`	An optional mask that selects the elements of `input` to transform. Where the mask is `0`, the original `input` value is returned. Also used to select the elements of the sampled standard deviations to use to mask the `input`. If `None`, the entire `input` is transformed.	`None`
`**kwargs` ¶	`Any`	Additional keyword arguments to the estimator modules.	required

Returns:

Type	Description
`torch.Tensor`	The transformed input data.

get_applied_transform_components_factory ¶

get_applied_transform_components_factory() -> Callable[
    [], dict[str, torch.Tensor]
]

Create a function that returns the elements of the transform components ('mean' and 'std') applied during the most recent forward pass.

Specifically, the applied elements are those selected by the noise mask (if supplied) and standard deviation mask (if std_estimator.masker is not None). If no masks are used, all elements are returned.

The applied transform components are returned flattened.

This function is intended to be used to log histograms of the transform components.

Returns:

Type	Description
`Callable[[], dict[str, torch.Tensor]]`	A function that returns the the elements of the transform components applied during the most recent forward pass.

Examples:

>>> from torch import nn
>>> from stainedglass_core import model as sg_model, noise_layer as sg_noise_layer
>>> base_model = nn.Linear(20, 2)
>>> noisy_model = sg_model.NoisyModel(
...     sg_noise_layer.CloakNoiseLayer1,
...     base_model,
...     target_parameter="input",
... )
>>> get_applied_transform_components = (
...     noisy_model.noise_layer.get_applied_transform_components_factory()
... )
>>> input = torch.ones(1, 20)
>>> noise_mask = torch.tensor(5 * [False] + 15 * [True])
>>> output = noisy_model(input, noise_mask=noise_mask)
>>> applied_transform_components = get_applied_transform_components()
>>> applied_transform_components
{'mean': tensor(...), 'std': tensor(...)}
>>> {
...     component_name: component.shape
...     for component_name, component in applied_transform_components.items()
... }
{'mean': torch.Size([15]), 'std': torch.Size([15])}

get_transformed_output_factory ¶

get_transformed_output_factory() -> Callable[
    [], torch.Tensor
]

Create a function that returns the transformed output from the most recent forward pass.

If super batching is active, only the transformed half of the super batch output is returned.

Returns:

Type	Description
`Callable[[], torch.Tensor]`	A function that returns the transformed output from the most recent forward pass.

Examples:

>>> from stainedglass_core import noise_layer as sg_noise_layer
>>> noise_layer = sg_noise_layer.CloakNoiseLayer1()
>>> get_transformed_output = noise_layer.get_transformed_output_factory()
>>> input = torch.ones(2, 3, 32, 32)
>>> output = noise_layer(input)
>>> transformed_output = get_transformed_output()
>>> assert output.equal(transformed_output)

initial_seed ¶

initial_seed() -> int

Return the initial seed of the CPU device's random number generator.

manual_seed ¶

manual_seed(seed: int | None) -> None

Seed each of the random number generators.

Setting seed to None will destroy any existing generators.

Parameters:

Name	Type	Description	Default
`seed` ¶	`int \| None`	The seed to set.	required

reset_parameters ¶

reset_parameters() -> None

Reinitialize parameters and buffers.

This method is useful for initializing tensors created on the meta device.

seed ¶

seed() -> None

Seed each of the random number generators using a non-deterministic random number.

CloakNoiseLayer1 ¶

Bases: CloakNoiseLayer

Applies an input independent stochastic transformation to a Tensor using ParameterWrapper and with standard deviations parameterized by CloakStandardDeviationParameterization.

Inspired by the Cloak Step 1 algorithm defined in the paper: Not All Features Are Equal: Discovering Essential Features for Preserving Prediction Privacy

Parameters:

Name	Type	Description	Default
`scale` ¶	`tuple[float, float]`	Used to set bound on the min and max standard deviation of the stochastic transformation.	`(0.0001, 2.0)`
`shallow` ¶	`float`	A temperature-like parameter which controls the spread of the parameterization function. Controls both the magnitude of parameterized standard deviations and their rate of change with respect to rhos.	`1.0`
`locs` ¶	`bool`	Whether the locs parameters (related to the means of the transform) have their gradients tracked.	`True`
`rhos` ¶	`bool`	Whether the rhos parameters (related to the standard deviations of the transform) have their gradients tracked. Usually True.	`True`
`rhos_init` ¶	`float`	The initial values for the rhos.	`-4.0`
`seed` ¶	`int \| None`	Seed for the random number generator used to generate the stochastic transformation. If `None`, the global RNG state is used.	`None`

Warning

The directly learned locs and rhos used by this class are prone to vanishing when trained with weight decay regularization. To avoid this, ensure that optimizer parameter group(s) containing locs or rhos are configured with weight_decay=0.0.

Note

For maximum privacy preservation, Stained Glass Transform Step 1 should only be used to pre-train a Stained Glass Transform Step 2 (see CloakNoiseLayer2 or CloakNoiseLayer2_NoClip). First training a Step 1, then fine-tuning that transform with step 2 is a common recipe.

For a more convenient type Stained Glass Transform that requires only one step of training, see CloakNoiseLayerOneShot.

Note

In almost all cases, rhos_requires_grad should be True while training CloakNoiseLayer1.

Methods:

Name	Description
`__call__`	Transform the input data.
`__getstate__`	Prepare a serializable copy of `self.__dict__`.
`__init_subclass__`	Set the default dtype to `torch.float32` inside all subclass `__init__` methods.
`__setstate__`	Restore from a serialized copy of `self.__dict__`.
`forward`	Transform the input data.
`get_applied_transform_components_factory`	Create a function that returns the elements of the transform components (`'mean'` and `'std'`) applied during the most recent
`get_transformed_output_factory`	Create a function that returns the transformed output from the most recent forward pass.
`initial_seed`	Return the initial seed of the CPU device's random number generator.
`manual_seed`	Seed each of the random number generators.
`reset_parameters`	Reinitialize parameters and buffers.
`seed`	Seed each of the random number generators using a non-deterministic random number.

call ¶

__call__(
    input: Tensor,
    noise_mask: Tensor | None = None,
    **kwargs: Any,
) -> torch.Tensor

Transform the input data.

Parameters:

Name	Type	Description	Default
`input` ¶	`Tensor`	The input to transform.	required
`noise_mask` ¶	`Tensor \| None`	An optional mask that selects the elements of `input` to transform. Where the mask is `False`, the original `input` value is returned. Also used to select the elements of the sampled standard deviations to use to mask the `input`. If `None`, the entire `input` is transformed.	`None`
`**kwargs` ¶	`Any`	Additional keyword arguments to the estimator modules.	required

getstate ¶

__getstate__() -> dict[str, Any]

Prepare a serializable copy of self.__dict__.

__init_subclass__ ¶

__init_subclass__() -> None

Set the default dtype to torch.float32 inside all subclass __init__ methods.

setstate ¶

__setstate__(state: dict[str, Any]) -> None

Restore from a serialized copy of self.__dict__.

forward ¶

forward(
    input: Tensor,
    noise_mask: Tensor | None = None,
    **kwargs: Any,
) -> torch.Tensor

Transform the input data.

Parameters:

Name	Type	Description	Default
`input` ¶	`Tensor`	The input to transform.	required
`noise_mask` ¶	`Tensor \| None`	An optional mask that selects the elements of `input` to transform. Where the mask is `0`, the original `input` value is returned. Also used to select the elements of the sampled standard deviations to use to mask the `input`. If `None`, the entire `input` is transformed.	`None`
`**kwargs` ¶	`Any`	Additional keyword arguments to the estimator modules.	required

Returns:

Type	Description
`torch.Tensor`	The transformed input data.

get_applied_transform_components_factory ¶

get_applied_transform_components_factory() -> Callable[
    [], dict[str, torch.Tensor]
]

Create a function that returns the elements of the transform components ('mean' and 'std') applied during the most recent forward pass.

Specifically, the applied elements are those selected by the noise mask (if supplied) and standard deviation mask (if std_estimator.masker is not None). If no masks are used, all elements are returned.

The applied transform components are returned flattened.

This function is intended to be used to log histograms of the transform components.

Returns:

Type	Description
`Callable[[], dict[str, torch.Tensor]]`	A function that returns the the elements of the transform components applied during the most recent forward pass.

Examples:

>>> from torch import nn
>>> from stainedglass_core import model as sg_model, noise_layer as sg_noise_layer
>>> base_model = nn.Linear(20, 2)
>>> noisy_model = sg_model.NoisyModel(
...     sg_noise_layer.CloakNoiseLayer1,
...     base_model,
...     target_parameter="input",
... )
>>> get_applied_transform_components = (
...     noisy_model.noise_layer.get_applied_transform_components_factory()
... )
>>> input = torch.ones(1, 20)
>>> noise_mask = torch.tensor(5 * [False] + 15 * [True])
>>> output = noisy_model(input, noise_mask=noise_mask)
>>> applied_transform_components = get_applied_transform_components()
>>> applied_transform_components
{'mean': tensor(...), 'std': tensor(...)}
>>> {
...     component_name: component.shape
...     for component_name, component in applied_transform_components.items()
... }
{'mean': torch.Size([15]), 'std': torch.Size([15])}

get_transformed_output_factory ¶

get_transformed_output_factory() -> Callable[
    [], torch.Tensor
]

Create a function that returns the transformed output from the most recent forward pass.

If super batching is active, only the transformed half of the super batch output is returned.

Returns:

Type	Description
`Callable[[], torch.Tensor]`	A function that returns the transformed output from the most recent forward pass.

Examples:

>>> from stainedglass_core import noise_layer as sg_noise_layer
>>> noise_layer = sg_noise_layer.CloakNoiseLayer1()
>>> get_transformed_output = noise_layer.get_transformed_output_factory()
>>> input = torch.ones(2, 3, 32, 32)
>>> output = noise_layer(input)
>>> transformed_output = get_transformed_output()
>>> assert output.equal(transformed_output)

initial_seed ¶

initial_seed() -> int

Return the initial seed of the CPU device's random number generator.

manual_seed ¶

manual_seed(seed: int | None) -> None

Seed each of the random number generators.

Setting seed to None will destroy any existing generators.

Parameters:

Name	Type	Description	Default
`seed` ¶	`int \| None`	The seed to set.	required

reset_parameters ¶

reset_parameters() -> None

Reinitialize parameters and buffers.

This method is useful for initializing tensors created on the meta device.

seed ¶

seed() -> None

Seed each of the random number generators using a non-deterministic random number.

CloakNoiseLayer2 ¶

Bases: CloakNoiseLayer

Applies an input independent stochastic transformation to a Tensor using ParameterWrapper, with standard deviations parameterized by CloakStandardDeviationParameterization, standard deviation-based input masking using PercentMasker, and output clamping.

Inspired by the Cloak Step 2 algorithm defined in the paper: Not All Features Are Equal: Discovering Essential Features for Preserving Prediction Privacy

Parameters:

Name	Type	Description	Default
`scale` ¶	`tuple[float, float]`	Used to set bound on the min and max standard deviation of the stochastic transformation.	`(0.0001, 2.0)`
`percent_to_mask` ¶	`float`	The percentage of the outputs to mask.	required
`shallow` ¶	`float`	A temperature-like parameter which controls the spread of the parameterization function. Controls both the magnitude of parameterized standard deviations and their rate of change with respect to rhos.	`1.0`
`value_range` ¶	`tuple[float \| None, float \| None]`	Minimum and maximum values of the range to clamp the output into.	`(-1.0, 1.0)`
`seed` ¶	`int \| None`	Seed for the random number generator used to generate the stochastic transformation. If `None`, the global RNG state is used.	`None`

Note

Specifying percent_to_mask==0.0 with a NoClip variant of Cloak Step 2 is functionally equivalent to Cloak Step 1, as no masking occurs.

Note

In training mode, the threshold buffer is recalculated over the learned standard deviations of the stochastic transformation, and a new input mask is generated with each forward call. In eval mode, threshold is static, and the cached mask from the most recent mask calculation is used.

Raises:

Type	Description
`ValueError`	If `percent_to_mask` is not in [0, 1], inclusive.

Warning

The directly learned locs and rhos used by this class are prone to vanishing when trained with weight decay regularization. To avoid this, ensure that optimizer parameter group(s) containing locs or rhos are configured with weight_decay=0.0.

Note

For maximum privacy preservation, Stained Glass Transform Step 2 should be pre-trained from a Stained Glass Transform Step 1. For a more convenient type of Stained Glass Transform that requires only one step of training, see CloakNoiseLayerOneShot.

Note

Masking is done using a static threshold on the learned standard deviation of the stochastic transformation. This threshold is calculated from percent_to_mask when loading a pre-trained transform layer. Consequently, continuing to train the stochastic transformation will not affect masking. For a variant of Cloak Step 2 that recalculates its masking using percent_to_mask on each call (i.e. the masking can change during training), see CloakNoiseLayerOneShot.

Methods:

Name	Description
`__call__`	Transform the input data.
`__getstate__`	Prepare a serializable copy of `self.__dict__`.
`__init__`
`__init_subclass__`	Set the default dtype to `torch.float32` inside all subclass `__init__` methods.
`__setstate__`	Restore from a serialized copy of `self.__dict__`.
`forward`	Transform the input data.
`get_applied_transform_components_factory`	Create a function that returns the elements of the transform components (`'mean'` and `'std'`) applied during the most recent
`get_transformed_output_factory`	Create a function that returns the transformed output from the most recent forward pass.
`initial_seed`	Return the initial seed of the CPU device's random number generator.
`manual_seed`	Seed each of the random number generators.
`reset_parameters`	Reinitialize parameters and buffers.
`seed`	Seed each of the random number generators using a non-deterministic random number.

call ¶

__call__(
    input: Tensor,
    noise_mask: Tensor | None = None,
    **kwargs: Any,
) -> torch.Tensor

Transform the input data.

Parameters:

Name	Type	Description	Default
`input` ¶	`Tensor`	The input to transform.	required
`noise_mask` ¶	`Tensor \| None`	An optional mask that selects the elements of `input` to transform. Where the mask is `False`, the original `input` value is returned. Also used to select the elements of the sampled standard deviations to use to mask the `input`. If `None`, the entire `input` is transformed.	`None`
`**kwargs` ¶	`Any`	Additional keyword arguments to the estimator modules.	required

getstate ¶

__getstate__() -> dict[str, Any]

Prepare a serializable copy of self.__dict__.

init ¶

__init__(
    percent_to_mask: float,
    scale: tuple[float, float] = (0.0001, 2.0),
    shallow: float = 1.0,
    value_range: tuple[float | None, float | None] = (
        -1.0,
        1.0,
    ),
    seed: int | None = None,
) -> None

Changed in version 0.10.0: `threshold` and `percent_threshold` parameters were removed in favor of `percent_to_mask`

__init_subclass__ ¶

__init_subclass__() -> None

Set the default dtype to torch.float32 inside all subclass __init__ methods.

setstate ¶

__setstate__(state: dict[str, Any]) -> None

Restore from a serialized copy of self.__dict__.

forward ¶

forward(
    input: Tensor,
    noise_mask: Tensor | None = None,
    **kwargs: Any,
) -> torch.Tensor

Transform the input data.

Parameters:

Name	Type	Description	Default
`input` ¶	`Tensor`	The input to transform.	required
`noise_mask` ¶	`Tensor \| None`	An optional mask that selects the elements of `input` to transform. Where the mask is `0`, the original `input` value is returned. Also used to select the elements of the sampled standard deviations to use to mask the `input`. If `None`, the entire `input` is transformed.	`None`
`**kwargs` ¶	`Any`	Additional keyword arguments to the estimator modules.	required

Returns:

Type	Description
`torch.Tensor`	The transformed input data.

get_applied_transform_components_factory ¶

get_applied_transform_components_factory() -> Callable[
    [], dict[str, torch.Tensor]
]

Create a function that returns the elements of the transform components ('mean' and 'std') applied during the most recent forward pass.

Specifically, the applied elements are those selected by the noise mask (if supplied) and standard deviation mask (if std_estimator.masker is not None). If no masks are used, all elements are returned.

The applied transform components are returned flattened.

This function is intended to be used to log histograms of the transform components.

Returns:

Type	Description
`Callable[[], dict[str, torch.Tensor]]`	A function that returns the the elements of the transform components applied during the most recent forward pass.

Examples:

>>> from torch import nn
>>> from stainedglass_core import model as sg_model, noise_layer as sg_noise_layer
>>> base_model = nn.Linear(20, 2)
>>> noisy_model = sg_model.NoisyModel(
...     sg_noise_layer.CloakNoiseLayer1,
...     base_model,
...     target_parameter="input",
... )
>>> get_applied_transform_components = (
...     noisy_model.noise_layer.get_applied_transform_components_factory()
... )
>>> input = torch.ones(1, 20)
>>> noise_mask = torch.tensor(5 * [False] + 15 * [True])
>>> output = noisy_model(input, noise_mask=noise_mask)
>>> applied_transform_components = get_applied_transform_components()
>>> applied_transform_components
{'mean': tensor(...), 'std': tensor(...)}
>>> {
...     component_name: component.shape
...     for component_name, component in applied_transform_components.items()
... }
{'mean': torch.Size([15]), 'std': torch.Size([15])}

get_transformed_output_factory ¶

get_transformed_output_factory() -> Callable[
    [], torch.Tensor
]

Create a function that returns the transformed output from the most recent forward pass.

If super batching is active, only the transformed half of the super batch output is returned.

Returns:

Type	Description
`Callable[[], torch.Tensor]`	A function that returns the transformed output from the most recent forward pass.

Examples:

>>> from stainedglass_core import noise_layer as sg_noise_layer
>>> noise_layer = sg_noise_layer.CloakNoiseLayer1()
>>> get_transformed_output = noise_layer.get_transformed_output_factory()
>>> input = torch.ones(2, 3, 32, 32)
>>> output = noise_layer(input)
>>> transformed_output = get_transformed_output()
>>> assert output.equal(transformed_output)

initial_seed ¶

initial_seed() -> int

Return the initial seed of the CPU device's random number generator.

manual_seed ¶

manual_seed(seed: int | None) -> None

Seed each of the random number generators.

Setting seed to None will destroy any existing generators.

Parameters:

Name	Type	Description	Default
`seed` ¶	`int \| None`	The seed to set.	required

reset_parameters ¶

reset_parameters() -> None

Reinitialize parameters and buffers.

This method is useful for initializing tensors created on the meta device.

seed ¶

seed() -> None

Seed each of the random number generators using a non-deterministic random number.

CloakNoiseLayer2_NoClip ¶

Bases: CloakNoiseLayer

Applies an input independent stochastic transformation to a Tensor using ParameterWrapper, with standard deviations parameterized by CloakStandardDeviationParameterization, and standard deviation-based input masking using PercentMasker.

Inspired by the Cloak Step 2 algorithm defined in the paper: Not All Features Are Equal: Discovering Essential Features for Preserving Prediction Privacy

Parameters:

Name	Type	Description	Default
`scale` ¶	`tuple[float, float]`	Used to set bound on the min and max standard deviation of the stochastic transformation.	`(0.0001, 2.0)`
`percent_to_mask` ¶	`float`	The percentage of the outputs to mask.	required
`shallow` ¶	`float`	A temperature-like parameter which controls the spread of the parameterization function. Controls both the magnitude of parameterized standard deviations and their rate of change with respect to rhos.	`1.0`
`seed` ¶	`int \| None`	Seed for the random number generator used to generate the stochastic transformation. If `None`, the global RNG state is used.	`None`

Note

Specifying percent_to_mask==0.0 with a NoClip variant of Cloak Step 2 is functionally equivalent to Cloak Step 1, as no masking occurs.

Note

In training mode, the threshold buffer is recalculated over the learned standard deviations of the stochastic transformation, and a new input mask is generated with each forward call. In eval mode, threshold is static, and the cached mask from the most recent mask calculation is used.

Raises:

Type	Description
`ValueError`	If `percent_to_mask` is not in [0, 1], inclusive.

Warning

The directly learned locs and rhos used by this class are prone to vanishing when trained with weight decay regularization. To avoid this, ensure that optimizer parameter group(s) containing locs or rhos are configured with weight_decay=0.0.

Note

For maximum privacy preservation, Stained Glass Transform Step 2 should be pre-trained from a Stained Glass Transform Step 1.

For a more convenient type Stained Glass Transform that requires only one step of training, see CloakNoiseLayerOneShot.

Methods:

Name	Description
`__call__`	Transform the input data.
`__getstate__`	Prepare a serializable copy of `self.__dict__`.
`__init_subclass__`	Set the default dtype to `torch.float32` inside all subclass `__init__` methods.
`__setstate__`	Restore from a serialized copy of `self.__dict__`.
`forward`	Transform the input data.
`get_applied_transform_components_factory`	Create a function that returns the elements of the transform components (`'mean'` and `'std'`) applied during the most recent
`get_transformed_output_factory`	Create a function that returns the transformed output from the most recent forward pass.
`initial_seed`	Return the initial seed of the CPU device's random number generator.
`manual_seed`	Seed each of the random number generators.
`reset_parameters`	Reinitialize parameters and buffers.
`seed`	Seed each of the random number generators using a non-deterministic random number.

call ¶

__call__(
    input: Tensor,
    noise_mask: Tensor | None = None,
    **kwargs: Any,
) -> torch.Tensor

Transform the input data.

Parameters:

Name	Type	Description	Default
`input` ¶	`Tensor`	The input to transform.	required
`noise_mask` ¶	`Tensor \| None`	An optional mask that selects the elements of `input` to transform. Where the mask is `False`, the original `input` value is returned. Also used to select the elements of the sampled standard deviations to use to mask the `input`. If `None`, the entire `input` is transformed.	`None`
`**kwargs` ¶	`Any`	Additional keyword arguments to the estimator modules.	required

getstate ¶

__getstate__() -> dict[str, Any]

Prepare a serializable copy of self.__dict__.

__init_subclass__ ¶

__init_subclass__() -> None

Set the default dtype to torch.float32 inside all subclass __init__ methods.

setstate ¶

__setstate__(state: dict[str, Any]) -> None

Restore from a serialized copy of self.__dict__.

forward ¶

forward(
    input: Tensor,
    noise_mask: Tensor | None = None,
    **kwargs: Any,
) -> torch.Tensor

Transform the input data.

Parameters:

Name	Type	Description	Default
`input` ¶	`Tensor`	The input to transform.	required
`noise_mask` ¶	`Tensor \| None`	An optional mask that selects the elements of `input` to transform. Where the mask is `0`, the original `input` value is returned. Also used to select the elements of the sampled standard deviations to use to mask the `input`. If `None`, the entire `input` is transformed.	`None`
`**kwargs` ¶	`Any`	Additional keyword arguments to the estimator modules.	required

Returns:

Type	Description
`torch.Tensor`	The transformed input data.

get_applied_transform_components_factory ¶

get_applied_transform_components_factory() -> Callable[
    [], dict[str, torch.Tensor]
]

Create a function that returns the elements of the transform components ('mean' and 'std') applied during the most recent forward pass.

Specifically, the applied elements are those selected by the noise mask (if supplied) and standard deviation mask (if std_estimator.masker is not None). If no masks are used, all elements are returned.

The applied transform components are returned flattened.

This function is intended to be used to log histograms of the transform components.

Returns:

Type	Description
`Callable[[], dict[str, torch.Tensor]]`	A function that returns the the elements of the transform components applied during the most recent forward pass.

Examples:

>>> from torch import nn
>>> from stainedglass_core import model as sg_model, noise_layer as sg_noise_layer
>>> base_model = nn.Linear(20, 2)
>>> noisy_model = sg_model.NoisyModel(
...     sg_noise_layer.CloakNoiseLayer1,
...     base_model,
...     target_parameter="input",
... )
>>> get_applied_transform_components = (
...     noisy_model.noise_layer.get_applied_transform_components_factory()
... )
>>> input = torch.ones(1, 20)
>>> noise_mask = torch.tensor(5 * [False] + 15 * [True])
>>> output = noisy_model(input, noise_mask=noise_mask)
>>> applied_transform_components = get_applied_transform_components()
>>> applied_transform_components
{'mean': tensor(...), 'std': tensor(...)}
>>> {
...     component_name: component.shape
...     for component_name, component in applied_transform_components.items()
... }
{'mean': torch.Size([15]), 'std': torch.Size([15])}

get_transformed_output_factory ¶

get_transformed_output_factory() -> Callable[
    [], torch.Tensor
]

Create a function that returns the transformed output from the most recent forward pass.

If super batching is active, only the transformed half of the super batch output is returned.

Returns:

Type	Description
`Callable[[], torch.Tensor]`	A function that returns the transformed output from the most recent forward pass.

Examples:

>>> from stainedglass_core import noise_layer as sg_noise_layer
>>> noise_layer = sg_noise_layer.CloakNoiseLayer1()
>>> get_transformed_output = noise_layer.get_transformed_output_factory()
>>> input = torch.ones(2, 3, 32, 32)
>>> output = noise_layer(input)
>>> transformed_output = get_transformed_output()
>>> assert output.equal(transformed_output)

initial_seed ¶

initial_seed() -> int

Return the initial seed of the CPU device's random number generator.

manual_seed ¶

manual_seed(seed: int | None) -> None

Seed each of the random number generators.

Setting seed to None will destroy any existing generators.

Parameters:

Name	Type	Description	Default
`seed` ¶	`int \| None`	The seed to set.	required

reset_parameters ¶

reset_parameters() -> None

Reinitialize parameters and buffers.

This method is useful for initializing tensors created on the meta device.

seed ¶

seed() -> None

Seed each of the random number generators using a non-deterministic random number.

CloakNoiseLayerOneShot ¶

Bases: CloakNoiseLayer

Applies an input independent stochastic transformation to a Tensor using ParameterWrapper, with standard deviations parameterized by CloakStandardDeviationParameterization, and optional standard deviation-based input masking using PercentMasker.

The original Cloak Algorithm requires two steps to train. In the first step, the stochastic mapping is trained, and in the second step, masking is trained. This class allows for training in one step, by recalculating the threshold every forward pass.

For most use cases, this class is preferred over a multi-step Stained Glass Transform version, since it is simpler to use. For more advanced use cases, however, the multi-step version may be required, since it allows for more control over the masking process during training.

Parameters:

Name	Type	Description	Default
`scale` ¶	`tuple[float, float]`	Used to set bound on the min and max standard deviation of the generated stochastic transformation.	required
`percent_to_mask` ¶	`float`	The percentage of the outputs to mask.	required
`shallow` ¶	`float`	A temperature-like parameter which controls the spread of the parameterization function. Controls both the magnitude of parameterized standard deviations and their rate of change with respect to rhos.	`1.0`
`rhos_init` ¶	`float`	The initial values for the rhos.	`-4.0`
`seed` ¶	`int \| None`	Seed for the random number generator used to generate the stochastic transformation. If `None`, the global RNG state is used.	`None`

Notes

Specifying percent_to_mask==0.0 is functionally equivalent to Cloak Step 1, as no masking occurs.

Raises:

Type	Description
`ValueError`	If `percent_to_mask` is not specified.
`ValueError`	If `percent_to_mask` is not in [0, 1], inclusive.

Warning

The directly learned locs and rhos used by this class are prone to vanishing when trained with weight decay regularization. To avoid this, ensure that optimizer parameter group(s) containing locs or rhos are configured with weight_decay=0.0.

Examples:

>>> import torch
>>> noise_layer = CloakNoiseLayerOneShot(percent_to_mask=0.5, scale=(1e-4, 2.0))
>>> img = torch.rand((1, 3, 8, 8))
>>> transformed_img = noise_layer(img)
>>> transformed_img.shape == img.shape
True
>>> torch.allclose(transformed_img, img)
False

See paper: Not All Features Are Equal: Discovering Essential Features for Preserving Prediction Privacy.

Methods:

Name	Description
`__call__`	Transform the input data.
`__getstate__`	Prepare a serializable copy of `self.__dict__`.
`__init__`
`__init_subclass__`	Set the default dtype to `torch.float32` inside all subclass `__init__` methods.
`__setstate__`	Restore from a serialized copy of `self.__dict__`.
`forward`	Transform the input data.
`get_applied_transform_components_factory`	Create a function that returns the elements of the transform components (`'mean'` and `'std'`) applied during the most recent
`get_transformed_output_factory`	Create a function that returns the transformed output from the most recent forward pass.
`initial_seed`	Return the initial seed of the CPU device's random number generator.
`manual_seed`	Seed each of the random number generators.
`reset_parameters`	Reinitialize parameters and buffers.
`seed`	Seed each of the random number generators using a non-deterministic random number.

call ¶

__call__(
    input: Tensor,
    noise_mask: Tensor | None = None,
    **kwargs: Any,
) -> torch.Tensor

Transform the input data.

Parameters:

Name	Type	Description	Default
`input` ¶	`Tensor`	The input to transform.	required
`noise_mask` ¶	`Tensor \| None`	An optional mask that selects the elements of `input` to transform. Where the mask is `False`, the original `input` value is returned. Also used to select the elements of the sampled standard deviations to use to mask the `input`. If `None`, the entire `input` is transformed.	`None`
`**kwargs` ¶	`Any`	Additional keyword arguments to the estimator modules.	required

getstate ¶

__getstate__() -> dict[str, Any]

Prepare a serializable copy of self.__dict__.

init ¶

__init__(
    percent_to_mask: float,
    scale: tuple[float, float],
    shallow: float = 1.0,
    rhos_init: float = -4.0,
    seed: int | None = None,
) -> None

Changed in version 0.10.0: `threshold` and `percent_threshold` parameters were removed in favor of `percent_to_mask`

__init_subclass__ ¶

__init_subclass__() -> None

Set the default dtype to torch.float32 inside all subclass __init__ methods.

setstate ¶

__setstate__(state: dict[str, Any]) -> None

Restore from a serialized copy of self.__dict__.

forward ¶

forward(
    input: Tensor,
    noise_mask: Tensor | None = None,
    **kwargs: Any,
) -> torch.Tensor

Transform the input data.

Parameters:

Name	Type	Description	Default
`input` ¶	`Tensor`	The input to transform.	required
`noise_mask` ¶	`Tensor \| None`	An optional mask that selects the elements of `input` to transform. Where the mask is `0`, the original `input` value is returned. Also used to select the elements of the sampled standard deviations to use to mask the `input`. If `None`, the entire `input` is transformed.	`None`
`**kwargs` ¶	`Any`	Additional keyword arguments to the estimator modules.	required

Returns:

Type	Description
`torch.Tensor`	The transformed input data.

get_applied_transform_components_factory ¶

get_applied_transform_components_factory() -> Callable[
    [], dict[str, torch.Tensor]
]

Create a function that returns the elements of the transform components ('mean' and 'std') applied during the most recent forward pass.

Specifically, the applied elements are those selected by the noise mask (if supplied) and standard deviation mask (if std_estimator.masker is not None). If no masks are used, all elements are returned.

The applied transform components are returned flattened.

This function is intended to be used to log histograms of the transform components.

Returns:

Type	Description
`Callable[[], dict[str, torch.Tensor]]`	A function that returns the the elements of the transform components applied during the most recent forward pass.

Examples:

>>> from torch import nn
>>> from stainedglass_core import model as sg_model, noise_layer as sg_noise_layer
>>> base_model = nn.Linear(20, 2)
>>> noisy_model = sg_model.NoisyModel(
...     sg_noise_layer.CloakNoiseLayer1,
...     base_model,
...     target_parameter="input",
... )
>>> get_applied_transform_components = (
...     noisy_model.noise_layer.get_applied_transform_components_factory()
... )
>>> input = torch.ones(1, 20)
>>> noise_mask = torch.tensor(5 * [False] + 15 * [True])
>>> output = noisy_model(input, noise_mask=noise_mask)
>>> applied_transform_components = get_applied_transform_components()
>>> applied_transform_components
{'mean': tensor(...), 'std': tensor(...)}
>>> {
...     component_name: component.shape
...     for component_name, component in applied_transform_components.items()
... }
{'mean': torch.Size([15]), 'std': torch.Size([15])}

get_transformed_output_factory ¶

get_transformed_output_factory() -> Callable[
    [], torch.Tensor
]

Create a function that returns the transformed output from the most recent forward pass.

If super batching is active, only the transformed half of the super batch output is returned.

Returns:

Type	Description
`Callable[[], torch.Tensor]`	A function that returns the transformed output from the most recent forward pass.

Examples:

>>> from stainedglass_core import noise_layer as sg_noise_layer
>>> noise_layer = sg_noise_layer.CloakNoiseLayer1()
>>> get_transformed_output = noise_layer.get_transformed_output_factory()
>>> input = torch.ones(2, 3, 32, 32)
>>> output = noise_layer(input)
>>> transformed_output = get_transformed_output()
>>> assert output.equal(transformed_output)

initial_seed ¶

initial_seed() -> int

Return the initial seed of the CPU device's random number generator.

manual_seed ¶

manual_seed(seed: int | None) -> None

Seed each of the random number generators.

Setting seed to None will destroy any existing generators.

Parameters:

Name	Type	Description	Default
`seed` ¶	`int \| None`	The seed to set.	required

reset_parameters ¶

reset_parameters() -> None

Reinitialize parameters and buffers.

This method is useful for initializing tensors created on the meta device.

seed ¶

seed() -> None

Seed each of the random number generators using a non-deterministic random number.

PatchCloakNoiseLayer ¶

Bases: BaseNoiseLayer[Conv2d, CloakStandardDeviationParameterization, Optional[BatchwiseChannelwisePatchwisePercentMasker]]

Applies an input-dependent stochastic transformation to an image in non-overlapping patches using Conv2d estimators, with standard deviations parameterized by CloakStandardDeviationParameterization, optional standard deviation-based input masking using BatchwiseChannelwisePatchwisePercentMasker, and optional output clamping.

Parameters:

Name	Type	Description	Default
`color_channels` ¶	`int`	The number of color channels in the input.	required
`patch_size` ¶	`int \| tuple[int, int]`	Size of the patches to segment the input into. If an integer is given, a square patch is used.	required
`scale` ¶	`tuple[float, float]`	Minimum and maximum values of the range of standard deviations of the generated stochastic transformation.	`(0.0001, 2.0)`
`shallow` ¶	`float`	A temperature-like parameter which controls the spread of the parameterization function. Controls both the magnitude of parameterized standard deviations and their rate of change with respect to rhos.	`1.0`
`percent_to_mask` ¶	`float \| None`	The percentage of the outputs to mask per patch.	`None`
`value_range` ¶	`tuple[float \| None, float \| None] \| None`	Minimum and maximum values of the range to clamp the output into.	`None`
`padding_mode` ¶	`Literal['constant', 'reflect', 'replicate', 'circular']`	Type of padding. One of: constant, reflect, replicate, or circular. Defaults to constant.	`'constant'`
`padding_value` ¶	`float`	Fill value for constant padding.	`0.0`
`learn_locs_weights` ¶	`bool`	Whether to learn the weight parameters for the locs estimator. If `True`, only the weights will be learned, and the bias remains constant, otherwise weights are initialized to zero and only the bias is learned.	`True`
`freeze_std_estimator` ¶	`bool`	Whether to freeze the weight parameters for the std estimator. If `False`, this estimator will be trained simultaneously with masking and the locs estimator parameters.	`True`
`seed` ¶	`int \| None`	Seed for the random number generator used to generate the stochastic transformation. If `None`, the global RNG state is used.	`None`

Note

For estimators where we train the weights, we freeze their biases. We suspect that if both the biases and weights are trained together, the biases will converge faster than the weights, causing the weights to be trivial. This has not been verified experimentally. Our choices for initialization values and conditions subject to change in light of experimental evidence, and you are encouraged to challenge and improve our understanding of the effects of these choices.

Methods:

Name	Description
`__call__`	Transform the input data.
`__getstate__`	Prepare a serializable copy of `self.__dict__`.
`__init_subclass__`	Set the default dtype to `torch.float32` inside all subclass `__init__` methods.
`__setstate__`	Restore from a serialized copy of `self.__dict__`.
`forward`	Transform the input data.
`get_applied_transform_components_factory`	Create a function that returns the elements of the transform components (`'mean'` and `'std'`) applied during the most recent
`get_transformed_output_factory`	Create a function that returns the transformed output from the most recent forward pass.
`initial_seed`	Return the initial seed of the CPU device's random number generator.
`manual_seed`	Seed each of the random number generators.
`reset_parameters`	Reinitialize parameters and buffers.
`seed`	Seed each of the random number generators using a non-deterministic random number.

Attributes:

Name	Type	Description
`patch_size`	`tuple[int, int]`	The size of the patches to segment the input into.

patch_size `property` ¶

patch_size: tuple[int, int]

The size of the patches to segment the input into.

call ¶

__call__(
    input: Tensor,
    noise_mask: Tensor | None = None,
    **kwargs: Any,
) -> torch.Tensor

Transform the input data.

Parameters:

Name	Type	Description	Default
`input` ¶	`Tensor`	The input to transform.	required
`noise_mask` ¶	`Tensor \| None`	An optional mask that selects the elements of `input` to transform. Where the mask is `False`, the original `input` value is returned. Also used to select the elements of the sampled standard deviations to use to mask the `input`. If `None`, the entire `input` is transformed.	`None`
`**kwargs` ¶	`Any`	Additional keyword arguments to the estimator modules.	required

getstate ¶

__getstate__() -> dict[str, Any]

Prepare a serializable copy of self.__dict__.

__init_subclass__ ¶

__init_subclass__() -> None

Set the default dtype to torch.float32 inside all subclass __init__ methods.

setstate ¶

__setstate__(state: dict[str, Any]) -> None

Restore from a serialized copy of self.__dict__.

forward ¶

forward(
    input: Tensor,
    noise_mask: Tensor | None = None,
    **kwargs: Any,
) -> torch.Tensor

Transform the input data.

Parameters:

Name	Type	Description	Default
`input` ¶	`Tensor`	The input to transform.	required
`noise_mask` ¶	`Tensor \| None`	An optional mask that selects the elements of `input` to transform. Where the mask is `0`, the original `input` value is returned. Also used to select the elements of the sampled standard deviations to use to mask the `input`. If `None`, the entire `input` is transformed.	`None`
`**kwargs` ¶	`Any`	Additional keyword arguments to the estimator modules.	required

Returns:

Type	Description
`torch.Tensor`	The transformed input data.

get_applied_transform_components_factory ¶

get_applied_transform_components_factory() -> Callable[
    [], dict[str, torch.Tensor]
]

Create a function that returns the elements of the transform components ('mean' and 'std') applied during the most recent forward pass.

Specifically, the applied elements are those selected by the noise mask (if supplied) and standard deviation mask (if std_estimator.masker is not None). If no masks are used, all elements are returned.

The applied transform components are returned flattened.

This function is intended to be used to log histograms of the transform components.

Returns:

Type	Description
`Callable[[], dict[str, torch.Tensor]]`	A function that returns the the elements of the transform components applied during the most recent forward pass.

Examples:

>>> from torch import nn
>>> from stainedglass_core import model as sg_model, noise_layer as sg_noise_layer
>>> base_model = nn.Linear(20, 2)
>>> noisy_model = sg_model.NoisyModel(
...     sg_noise_layer.CloakNoiseLayer1,
...     base_model,
...     target_parameter="input",
... )
>>> get_applied_transform_components = (
...     noisy_model.noise_layer.get_applied_transform_components_factory()
... )
>>> input = torch.ones(1, 20)
>>> noise_mask = torch.tensor(5 * [False] + 15 * [True])
>>> output = noisy_model(input, noise_mask=noise_mask)
>>> applied_transform_components = get_applied_transform_components()
>>> applied_transform_components
{'mean': tensor(...), 'std': tensor(...)}
>>> {
...     component_name: component.shape
...     for component_name, component in applied_transform_components.items()
... }
{'mean': torch.Size([15]), 'std': torch.Size([15])}

get_transformed_output_factory ¶

get_transformed_output_factory() -> Callable[
    [], torch.Tensor
]

Create a function that returns the transformed output from the most recent forward pass.

If super batching is active, only the transformed half of the super batch output is returned.

Returns:

Type	Description
`Callable[[], torch.Tensor]`	A function that returns the transformed output from the most recent forward pass.

Examples:

>>> from stainedglass_core import noise_layer as sg_noise_layer
>>> noise_layer = sg_noise_layer.CloakNoiseLayer1()
>>> get_transformed_output = noise_layer.get_transformed_output_factory()
>>> input = torch.ones(2, 3, 32, 32)
>>> output = noise_layer(input)
>>> transformed_output = get_transformed_output()
>>> assert output.equal(transformed_output)

initial_seed ¶

initial_seed() -> int

Return the initial seed of the CPU device's random number generator.

manual_seed ¶

manual_seed(seed: int | None) -> None

Seed each of the random number generators.

Setting seed to None will destroy any existing generators.

Parameters:

Name	Type	Description	Default
`seed` ¶	`int \| None`	The seed to set.	required

reset_parameters ¶

reset_parameters() -> None

Reinitialize parameters and buffers.

This method is useful for initializing tensors created on the meta device.

seed ¶

seed() -> None

Seed each of the random number generators using a non-deterministic random number.

PatchCloakNoiseLayer1 ¶

Bases: PatchCloakNoiseLayer

Applies an input-dependent stochastic transformation to an image in non-overlapping patches using Conv2d estimators and with standard deviations parameterized by CloakStandardDeviationParameterization.

Parameters:

Name	Type	Description	Default
`color_channels` ¶	`int`	The number of color channels in the input.	required
`patch_size` ¶	`int \| tuple[int, int]`	The size of the patches over which the stochastic transformation is estimated.	required
`scale` ¶	`tuple[float, float]`	The range of standard deviations of the stochastic transformation.	required
`shallow` ¶	`float`	A temperature-like parameter which controls the spread of the parameterization function. Controls both the magnitude of parameterized standard deviations and their rate of change with respect to rhos.	`1.0`
`padding_mode` ¶	`Literal['constant', 'reflect', 'replicate', 'circular']`	The padding mode to use when extracting patches.	`'constant'`
`padding_value` ¶	`float`	The value to use when padding the input.	`0.0`
`learn_locs_weights` ¶	`bool`	Whether to only learn the locs estimator weights or else to only learn the locs estimator bias.	`True`
`seed` ¶	`int \| None`	Seed for the random number generator used to generate the stochastic transformation. If `None`, the global RNG state is used.	`None`

Note

For maximum privacy preservation, Stained Glass Patch Transform Step 1 should only be used to pre-train a Stained Glass Transform Patch Step 2 (see PatchCloakNoiseLayer1_NoClip). First training a Step 1, then fine-tuning that transform with step 2 is a common recipe.

Methods:

Name	Description
`__call__`	Transform the input data.
`__getstate__`	Prepare a serializable copy of `self.__dict__`.
`__init_subclass__`	Set the default dtype to `torch.float32` inside all subclass `__init__` methods.
`__setstate__`	Restore from a serialized copy of `self.__dict__`.
`forward`	Transform the input data.
`get_applied_transform_components_factory`	Create a function that returns the elements of the transform components (`'mean'` and `'std'`) applied during the most recent
`get_transformed_output_factory`	Create a function that returns the transformed output from the most recent forward pass.
`initial_seed`	Return the initial seed of the CPU device's random number generator.
`manual_seed`	Seed each of the random number generators.
`reset_parameters`	Reinitialize parameters and buffers.
`seed`	Seed each of the random number generators using a non-deterministic random number.

Attributes:

Name	Type	Description
`patch_size`	`tuple[int, int]`	The size of the patches to segment the input into.

patch_size `property` ¶

patch_size: tuple[int, int]

The size of the patches to segment the input into.

call ¶

__call__(
    input: Tensor,
    noise_mask: Tensor | None = None,
    **kwargs: Any,
) -> torch.Tensor

Transform the input data.

Parameters:

Name	Type	Description	Default
`input` ¶	`Tensor`	The input to transform.	required
`noise_mask` ¶	`Tensor \| None`	An optional mask that selects the elements of `input` to transform. Where the mask is `False`, the original `input` value is returned. Also used to select the elements of the sampled standard deviations to use to mask the `input`. If `None`, the entire `input` is transformed.	`None`
`**kwargs` ¶	`Any`	Additional keyword arguments to the estimator modules.	required

getstate ¶

__getstate__() -> dict[str, Any]

Prepare a serializable copy of self.__dict__.

__init_subclass__ ¶

__init_subclass__() -> None

Set the default dtype to torch.float32 inside all subclass __init__ methods.

setstate ¶

__setstate__(state: dict[str, Any]) -> None

Restore from a serialized copy of self.__dict__.

forward ¶

forward(
    input: Tensor,
    noise_mask: Tensor | None = None,
    **kwargs: Any,
) -> torch.Tensor

Transform the input data.

Parameters:

Name	Type	Description	Default
`input` ¶	`Tensor`	The input to transform.	required
`noise_mask` ¶	`Tensor \| None`	An optional mask that selects the elements of `input` to transform. Where the mask is `0`, the original `input` value is returned. Also used to select the elements of the sampled standard deviations to use to mask the `input`. If `None`, the entire `input` is transformed.	`None`
`**kwargs` ¶	`Any`	Additional keyword arguments to the estimator modules.	required

Returns:

Type	Description
`torch.Tensor`	The transformed input data.

get_applied_transform_components_factory ¶

get_applied_transform_components_factory() -> Callable[
    [], dict[str, torch.Tensor]
]

Create a function that returns the elements of the transform components ('mean' and 'std') applied during the most recent forward pass.

Specifically, the applied elements are those selected by the noise mask (if supplied) and standard deviation mask (if std_estimator.masker is not None). If no masks are used, all elements are returned.

The applied transform components are returned flattened.

This function is intended to be used to log histograms of the transform components.

Returns:

Type	Description
`Callable[[], dict[str, torch.Tensor]]`	A function that returns the the elements of the transform components applied during the most recent forward pass.

Examples:

>>> from torch import nn
>>> from stainedglass_core import model as sg_model, noise_layer as sg_noise_layer
>>> base_model = nn.Linear(20, 2)
>>> noisy_model = sg_model.NoisyModel(
...     sg_noise_layer.CloakNoiseLayer1,
...     base_model,
...     target_parameter="input",
... )
>>> get_applied_transform_components = (
...     noisy_model.noise_layer.get_applied_transform_components_factory()
... )
>>> input = torch.ones(1, 20)
>>> noise_mask = torch.tensor(5 * [False] + 15 * [True])
>>> output = noisy_model(input, noise_mask=noise_mask)
>>> applied_transform_components = get_applied_transform_components()
>>> applied_transform_components
{'mean': tensor(...), 'std': tensor(...)}
>>> {
...     component_name: component.shape
...     for component_name, component in applied_transform_components.items()
... }
{'mean': torch.Size([15]), 'std': torch.Size([15])}

get_transformed_output_factory ¶

get_transformed_output_factory() -> Callable[
    [], torch.Tensor
]

Create a function that returns the transformed output from the most recent forward pass.

If super batching is active, only the transformed half of the super batch output is returned.

Returns:

Type	Description
`Callable[[], torch.Tensor]`	A function that returns the transformed output from the most recent forward pass.

Examples:

>>> from stainedglass_core import noise_layer as sg_noise_layer
>>> noise_layer = sg_noise_layer.CloakNoiseLayer1()
>>> get_transformed_output = noise_layer.get_transformed_output_factory()
>>> input = torch.ones(2, 3, 32, 32)
>>> output = noise_layer(input)
>>> transformed_output = get_transformed_output()
>>> assert output.equal(transformed_output)

initial_seed ¶

initial_seed() -> int

Return the initial seed of the CPU device's random number generator.

manual_seed ¶

manual_seed(seed: int | None) -> None

Seed each of the random number generators.

Setting seed to None will destroy any existing generators.

Parameters:

Name	Type	Description	Default
`seed` ¶	`int \| None`	The seed to set.	required

reset_parameters ¶

reset_parameters() -> None

Reinitialize parameters and buffers.

This method is useful for initializing tensors created on the meta device.

seed ¶

seed() -> None

Seed each of the random number generators using a non-deterministic random number.

PatchCloakNoiseLayer2 ¶

Bases: PatchCloakNoiseLayer

Applies an input-dependent stochastic transformation to an image in non-overlapping patches using Conv2d estimators, with standard deviations parameterized by CloakStandardDeviationParameterization, standard deviation-based input masking using BatchwiseChannelwisePatchwisePercentMasker, and output clamping.

Parameters:

Name	Type	Description	Default
`color_channels` ¶	`int`	The number of color channels in the input.	required
`patch_size` ¶	`int \| tuple[int, int]`	Size of the patches to segment the input into. If an integer is given, a square patch is used.	required
`scale` ¶	`tuple[float, float]`	Minimum and maximum values of the range of standard deviations of the generated stochastic transformation.	required
`percent_to_mask` ¶	`float`	The percentage of the outputs to mask per patch.	required
`shallow` ¶	`float`	A temperature-like parameter which controls the spread of the parameterization function. Controls both the magnitude of parameterized standard deviations and their rate of change with respect to rhos.	`1.0`
`value_range` ¶	`tuple[float \| None, float \| None]`	Minimum and maximum values of the range to clamp the output into.	`(-1.0, 1.0)`
`padding_mode` ¶	`Literal['constant', 'reflect', 'replicate', 'circular']`	Type of padding. One of: constant, reflect, replicate, or circular. Defaults to constant.	`'constant'`
`padding_value` ¶	`float`	Fill value for constant padding.	`0.0`
`learn_locs_weights` ¶	`bool`	Whether to learn the weight parameters for the locs estimator. If `True`, only the weights will be learned, and the bias remains constant, otherwise weights are initialized to zero and only the bias is learned.	`True`
`freeze_std_estimator` ¶	`bool`	Whether to freeze the weight parameters for the std estimator. If `False`, this estimator will be trained simultaneously with masking and the locs estimator parameters.	`True`
`seed` ¶	`int \| None`	Seed for the random number generator used to generate the stochastic transformation. If `None`, the global RNG state is used.	`None`

Note

For maximum privacy preservation, Stained Glass Transform Patch Step 2 should be pre-trained from a Stained Glass Transform Patch Step 1.

Methods:

Name	Description
`__call__`	Transform the input data.
`__getstate__`	Prepare a serializable copy of `self.__dict__`.
`__init__`
`__init_subclass__`	Set the default dtype to `torch.float32` inside all subclass `__init__` methods.
`__setstate__`	Restore from a serialized copy of `self.__dict__`.
`forward`	Transform the input data.
`get_applied_transform_components_factory`	Create a function that returns the elements of the transform components (`'mean'` and `'std'`) applied during the most recent
`get_transformed_output_factory`	Create a function that returns the transformed output from the most recent forward pass.
`initial_seed`	Return the initial seed of the CPU device's random number generator.
`manual_seed`	Seed each of the random number generators.
`reset_parameters`	Reinitialize parameters and buffers.
`seed`	Seed each of the random number generators using a non-deterministic random number.

Attributes:

Name	Type	Description
`patch_size`	`tuple[int, int]`	The size of the patches to segment the input into.

patch_size `property` ¶

patch_size: tuple[int, int]

The size of the patches to segment the input into.

call ¶

__call__(
    input: Tensor,
    noise_mask: Tensor | None = None,
    **kwargs: Any,
) -> torch.Tensor

Transform the input data.

Parameters:

Name	Type	Description	Default
`input` ¶	`Tensor`	The input to transform.	required
`noise_mask` ¶	`Tensor \| None`	An optional mask that selects the elements of `input` to transform. Where the mask is `False`, the original `input` value is returned. Also used to select the elements of the sampled standard deviations to use to mask the `input`. If `None`, the entire `input` is transformed.	`None`
`**kwargs` ¶	`Any`	Additional keyword arguments to the estimator modules.	required

getstate ¶

__getstate__() -> dict[str, Any]

Prepare a serializable copy of self.__dict__.

init ¶

__init__(
    color_channels: int,
    patch_size: int | tuple[int, int],
    scale: tuple[float, float],
    percent_to_mask: float,
    shallow: float = 1.0,
    value_range: tuple[float | None, float | None] = (
        -1.0,
        1.0,
    ),
    padding_mode: Literal[
        "constant", "reflect", "replicate", "circular"
    ] = "constant",
    padding_value: float = 0.0,
    learn_locs_weights: bool = True,
    freeze_std_estimator: bool = True,
    seed: int | None = None,
) -> None

Changed in version 0.10.0: `threshold` and `percent_threshold` parameters were removed in favor of `percent_to_mask`

__init_subclass__ ¶

__init_subclass__() -> None

Set the default dtype to torch.float32 inside all subclass __init__ methods.

setstate ¶

__setstate__(state: dict[str, Any]) -> None

Restore from a serialized copy of self.__dict__.

forward ¶

forward(
    input: Tensor,
    noise_mask: Tensor | None = None,
    **kwargs: Any,
) -> torch.Tensor

Transform the input data.

Parameters:

Name	Type	Description	Default
`input` ¶	`Tensor`	The input to transform.	required
`noise_mask` ¶	`Tensor \| None`	An optional mask that selects the elements of `input` to transform. Where the mask is `0`, the original `input` value is returned. Also used to select the elements of the sampled standard deviations to use to mask the `input`. If `None`, the entire `input` is transformed.	`None`
`**kwargs` ¶	`Any`	Additional keyword arguments to the estimator modules.	required

Returns:

Type	Description
`torch.Tensor`	The transformed input data.

get_applied_transform_components_factory ¶

get_applied_transform_components_factory() -> Callable[
    [], dict[str, torch.Tensor]
]

Create a function that returns the elements of the transform components ('mean' and 'std') applied during the most recent forward pass.

Specifically, the applied elements are those selected by the noise mask (if supplied) and standard deviation mask (if std_estimator.masker is not None). If no masks are used, all elements are returned.

The applied transform components are returned flattened.

This function is intended to be used to log histograms of the transform components.

Returns:

Type	Description
`Callable[[], dict[str, torch.Tensor]]`	A function that returns the the elements of the transform components applied during the most recent forward pass.

Examples:

>>> from torch import nn
>>> from stainedglass_core import model as sg_model, noise_layer as sg_noise_layer
>>> base_model = nn.Linear(20, 2)
>>> noisy_model = sg_model.NoisyModel(
...     sg_noise_layer.CloakNoiseLayer1,
...     base_model,
...     target_parameter="input",
... )
>>> get_applied_transform_components = (
...     noisy_model.noise_layer.get_applied_transform_components_factory()
... )
>>> input = torch.ones(1, 20)
>>> noise_mask = torch.tensor(5 * [False] + 15 * [True])
>>> output = noisy_model(input, noise_mask=noise_mask)
>>> applied_transform_components = get_applied_transform_components()
>>> applied_transform_components
{'mean': tensor(...), 'std': tensor(...)}
>>> {
...     component_name: component.shape
...     for component_name, component in applied_transform_components.items()
... }
{'mean': torch.Size([15]), 'std': torch.Size([15])}

get_transformed_output_factory ¶

get_transformed_output_factory() -> Callable[
    [], torch.Tensor
]

Create a function that returns the transformed output from the most recent forward pass.

If super batching is active, only the transformed half of the super batch output is returned.

Returns:

Type	Description
`Callable[[], torch.Tensor]`	A function that returns the transformed output from the most recent forward pass.

Examples:

>>> from stainedglass_core import noise_layer as sg_noise_layer
>>> noise_layer = sg_noise_layer.CloakNoiseLayer1()
>>> get_transformed_output = noise_layer.get_transformed_output_factory()
>>> input = torch.ones(2, 3, 32, 32)
>>> output = noise_layer(input)
>>> transformed_output = get_transformed_output()
>>> assert output.equal(transformed_output)

initial_seed ¶

initial_seed() -> int

Return the initial seed of the CPU device's random number generator.

manual_seed ¶

manual_seed(seed: int | None) -> None

Seed each of the random number generators.

Setting seed to None will destroy any existing generators.

Parameters:

Name	Type	Description	Default
`seed` ¶	`int \| None`	The seed to set.	required

reset_parameters ¶

reset_parameters() -> None

Reinitialize parameters and buffers.

This method is useful for initializing tensors created on the meta device.

seed ¶

seed() -> None

Seed each of the random number generators using a non-deterministic random number.

PatchCloakNoiseLayer2_NoClip ¶

Bases: PatchCloakNoiseLayer

Applies an input-dependent stochastic transformation to an image in non-overlapping patches using Conv2d estimators, with standard deviations parameterized by CloakStandardDeviationParameterization, and standard deviation-based input masking using BatchwiseChannelwisePatchwisePercentMasker.

Parameters:

Name	Type	Description	Default
`color_channels` ¶	`int`	The number of color channels in the input.	required
`patch_size` ¶	`int \| tuple[int, int]`	Size of the patches to segment the input into. If an integer is given, a square patch is used.	required
`scale` ¶	`tuple[float, float]`	Minimum and maximum values of the range of standard deviations of the generated stochastic transformation.	required
`percent_to_mask` ¶	`float`	The percentage of the outputs to mask per patch.	required
`shallow` ¶	`float`	A temperature-like parameter which controls the spread of the parameterization function. Controls both the magnitude of parameterized standard deviations and their rate of change with respect to rhos.	`1.0`
`padding_mode` ¶	`Literal['constant', 'reflect', 'replicate', 'circular']`	Type of padding. One of: constant, reflect, replicate, or circular. Defaults to constant.	`'constant'`
`padding_value` ¶	`float`	Fill value for constant padding.	`0.0`
`learn_locs_weights` ¶	`bool`	Whether to learn the weight parameters for the locs estimator. If `True`, only the weights will be learned, and the bias remains constant, otherwise weights are initialized to zero and only the bias is learned.	`True`
`freeze_std_estimator` ¶	`bool`	Whether to freeze the weight parameters for the std estimator. If `True`, this estimator will be trained simultaneously with masking and the locs estimator parameters.	`True`
`seed` ¶	`int \| None`	Seed for the random number generator used to generate the stochastic transformation. If `None`, the global RNG state is used.	`None`

Note

For maximum privacy preservation, Stained Glass Transform Patch Step 2 should be pre-trained from a Stained Glass Transform Patch Step 1.

Methods:

Name	Description
`__call__`	Transform the input data.
`__getstate__`	Prepare a serializable copy of `self.__dict__`.
`__init__`
`__init_subclass__`	Set the default dtype to `torch.float32` inside all subclass `__init__` methods.
`__setstate__`	Restore from a serialized copy of `self.__dict__`.
`forward`	Transform the input data.
`get_applied_transform_components_factory`	Create a function that returns the elements of the transform components (`'mean'` and `'std'`) applied during the most recent
`get_transformed_output_factory`	Create a function that returns the transformed output from the most recent forward pass.
`initial_seed`	Return the initial seed of the CPU device's random number generator.
`manual_seed`	Seed each of the random number generators.
`reset_parameters`	Reinitialize parameters and buffers.
`seed`	Seed each of the random number generators using a non-deterministic random number.

Attributes:

Name	Type	Description
`patch_size`	`tuple[int, int]`	The size of the patches to segment the input into.

patch_size `property` ¶

patch_size: tuple[int, int]

The size of the patches to segment the input into.

call ¶

__call__(
    input: Tensor,
    noise_mask: Tensor | None = None,
    **kwargs: Any,
) -> torch.Tensor

Transform the input data.

Parameters:

Name	Type	Description	Default
`input` ¶	`Tensor`	The input to transform.	required
`noise_mask` ¶	`Tensor \| None`	An optional mask that selects the elements of `input` to transform. Where the mask is `False`, the original `input` value is returned. Also used to select the elements of the sampled standard deviations to use to mask the `input`. If `None`, the entire `input` is transformed.	`None`
`**kwargs` ¶	`Any`	Additional keyword arguments to the estimator modules.	required

getstate ¶

__getstate__() -> dict[str, Any]

Prepare a serializable copy of self.__dict__.

init ¶

__init__(
    color_channels: int,
    patch_size: int | tuple[int, int],
    scale: tuple[float, float],
    percent_to_mask: float,
    shallow: float = 1.0,
    padding_mode: Literal[
        "constant", "reflect", "replicate", "circular"
    ] = "constant",
    padding_value: float = 0.0,
    learn_locs_weights: bool = True,
    freeze_std_estimator: bool = True,
    seed: int | None = None,
) -> None

Changed in version 0.10.0: `threshold` and `percent_threshold` parameters were removed in favor of `percent_to_mask`

__init_subclass__ ¶

__init_subclass__() -> None

Set the default dtype to torch.float32 inside all subclass __init__ methods.

setstate ¶

__setstate__(state: dict[str, Any]) -> None

Restore from a serialized copy of self.__dict__.

forward ¶

forward(
    input: Tensor,
    noise_mask: Tensor | None = None,
    **kwargs: Any,
) -> torch.Tensor

Transform the input data.

Parameters:

Name	Type	Description	Default
`input` ¶	`Tensor`	The input to transform.	required
`noise_mask` ¶	`Tensor \| None`	An optional mask that selects the elements of `input` to transform. Where the mask is `0`, the original `input` value is returned. Also used to select the elements of the sampled standard deviations to use to mask the `input`. If `None`, the entire `input` is transformed.	`None`
`**kwargs` ¶	`Any`	Additional keyword arguments to the estimator modules.	required

Returns:

Type	Description
`torch.Tensor`	The transformed input data.

get_applied_transform_components_factory ¶

get_applied_transform_components_factory() -> Callable[
    [], dict[str, torch.Tensor]
]

Create a function that returns the elements of the transform components ('mean' and 'std') applied during the most recent forward pass.

Specifically, the applied elements are those selected by the noise mask (if supplied) and standard deviation mask (if std_estimator.masker is not None). If no masks are used, all elements are returned.

The applied transform components are returned flattened.

This function is intended to be used to log histograms of the transform components.

Returns:

Type	Description
`Callable[[], dict[str, torch.Tensor]]`	A function that returns the the elements of the transform components applied during the most recent forward pass.

Examples:

>>> from torch import nn
>>> from stainedglass_core import model as sg_model, noise_layer as sg_noise_layer
>>> base_model = nn.Linear(20, 2)
>>> noisy_model = sg_model.NoisyModel(
...     sg_noise_layer.CloakNoiseLayer1,
...     base_model,
...     target_parameter="input",
... )
>>> get_applied_transform_components = (
...     noisy_model.noise_layer.get_applied_transform_components_factory()
... )
>>> input = torch.ones(1, 20)
>>> noise_mask = torch.tensor(5 * [False] + 15 * [True])
>>> output = noisy_model(input, noise_mask=noise_mask)
>>> applied_transform_components = get_applied_transform_components()
>>> applied_transform_components
{'mean': tensor(...), 'std': tensor(...)}
>>> {
...     component_name: component.shape
...     for component_name, component in applied_transform_components.items()
... }
{'mean': torch.Size([15]), 'std': torch.Size([15])}

get_transformed_output_factory ¶

get_transformed_output_factory() -> Callable[
    [], torch.Tensor
]

Create a function that returns the transformed output from the most recent forward pass.

If super batching is active, only the transformed half of the super batch output is returned.

Returns:

Type	Description
`Callable[[], torch.Tensor]`	A function that returns the transformed output from the most recent forward pass.

Examples:

>>> from stainedglass_core import noise_layer as sg_noise_layer
>>> noise_layer = sg_noise_layer.CloakNoiseLayer1()
>>> get_transformed_output = noise_layer.get_transformed_output_factory()
>>> input = torch.ones(2, 3, 32, 32)
>>> output = noise_layer(input)
>>> transformed_output = get_transformed_output()
>>> assert output.equal(transformed_output)

initial_seed ¶

initial_seed() -> int

Return the initial seed of the CPU device's random number generator.

manual_seed ¶

manual_seed(seed: int | None) -> None

Seed each of the random number generators.

Setting seed to None will destroy any existing generators.

Parameters:

Name	Type	Description	Default
`seed` ¶	`int \| None`	The seed to set.	required

reset_parameters ¶

reset_parameters() -> None

Reinitialize parameters and buffers.

This method is useful for initializing tensors created on the meta device.

seed ¶

seed() -> None

Seed each of the random number generators using a non-deterministic random number.

PatchCloakNoiseLayerFrequencySpace ¶

Bases: PatchCloakNoiseLayer

Applies an input-dependent stochastic transformation to an image in frequency space in non-overlapping patches using Conv2d estimators, with standard deviations parameterized by CloakStandardDeviationParameterization, optional standard deviation-based input masking using BatchwiseChannelwisePatchwisePercentMasker, and optional output clamping.

Parameters:

Name	Type	Description	Default
`color_channels` ¶	`int`	The number of color channels in the input.	required
`patch_size` ¶	`int \| tuple[int, int]`	Size of the patches to segment the input into. If an integer is given, a square patch is used.	required
`scale` ¶	`tuple[float, float]`	Minimum and maximum values of the range of standard deviations of the generated stochastic transformation.	required
`percent_to_mask` ¶	`float`	The percentage of the outputs to mask per patch.	required
`shallow` ¶	`float`	A fixed temperature like parameter which alters the scale of the standard deviation of the stochastic transformation.	`1.0`
`value_range` ¶	`tuple[float \| None, float \| None]`	Minimum and maximum values of the range to clamp the output into.	`(-1.0, 1.0)`
`frequency_range` ¶	`tuple[float, float]`	Minimum and maximum values of the range in the frequency domain to clamp the output into.	`(-inf, inf)`
`padding_mode` ¶	`Literal['constant', 'reflect', 'replicate', 'circular']`	Type of padding. One of: constant, reflect, replicate, or circular. Defaults to `"constant"`.	`'constant'`
`padding_value` ¶	`float`	Value to pad with if padding_mode is constant.	`0.0`
`learn_locs_weights` ¶	`bool`	Whether to learn the weight parameters for the locs estimator. If `True`, only the weights will be learned, and the bias remains constant, otherwise weights are initialized to zero and only the bias is learned. Defaults to `True`.	`True`
`preserve_average_color` ¶	`bool`	Whether to preserve the average color per patch of the original image in the perturbed output. Defaults to `True`.	`True`
`normalization` ¶	`Normalization`	Which `Normalization` to apply to the pixel space representation of the perturbed output to make it a valid image. Defaults to "clamp".	`<Normalization.CLAMP: 'clamp'>`
`seed` ¶	`int \| None`	Seed for the random number generator used to generate the stochastic transformation. If `None`, the global RNG state is used.	`None`

Raises:

Type	Description
`ValueError`	If the patch_size is not square.
`NotImplementedError`	If a known normalization mode without a corresponding normalization function is encountered.

Methods:

Name	Description
`__call__`	Transform the input data.
`__getstate__`	Prepare a serializable copy of `self.__dict__`.
`__init__`
`__init_subclass__`	Set the default dtype to `torch.float32` inside all subclass `__init__` methods.
`__setstate__`	Restore from a serialized copy of `self.__dict__`.
`forward`	Transform the input data.
`get_applied_transform_components_factory`	Create a function that returns the elements of the transform components (`'mean'` and `'std'`) applied during the most recent
`get_transformed_output_factory`	Create a function that returns the transformed output from the most recent forward pass.
`initial_seed`	Return the initial seed of the CPU device's random number generator.
`manual_seed`	Seed each of the random number generators.
`reset_parameters`	Reinitialize parameters and buffers.
`seed`	Seed each of the random number generators using a non-deterministic random number.

Attributes:

Name	Type	Description
`patch_size`	`tuple[int, int]`	The size of the patches to segment the input into.

patch_size `property` ¶

patch_size: tuple[int, int]

The size of the patches to segment the input into.

call ¶

__call__(
    input: Tensor,
    noise_mask: Tensor | None = None,
    **kwargs: Any,
) -> torch.Tensor

Transform the input data.

Parameters:

Name	Type	Description	Default
`input` ¶	`Tensor`	The input to transform.	required
`noise_mask` ¶	`Tensor \| None`	An optional mask that selects the elements of `input` to transform. Where the mask is `False`, the original `input` value is returned. Also used to select the elements of the sampled standard deviations to use to mask the `input`. If `None`, the entire `input` is transformed.	`None`
`**kwargs` ¶	`Any`	Additional keyword arguments to the estimator modules.	required

getstate ¶

__getstate__() -> dict[str, Any]

Prepare a serializable copy of self.__dict__.

init ¶

__init__(color_channels: int, patch_size: int | tuple[int, int], scale: tuple[float, float], percent_to_mask: float, shallow: float = 1.0, value_range: tuple[float | None, float | None] = (-1.0, 1.0), frequency_range: tuple[float, float] = (-inf, inf), padding_mode: Literal['constant', 'reflect', 'replicate', 'circular'] = 'constant', padding_value: float = 0.0, learn_locs_weights: bool = True, preserve_average_color: bool = True, normalization: Normalization = <Normalization.CLAMP: 'clamp'>, seed: int | None = None) -> None

Changed in version 0.10.0: `threshold` and `percent_threshold` parameters were removed in favor of `percent_to_mask`

__init_subclass__ ¶

__init_subclass__() -> None

Set the default dtype to torch.float32 inside all subclass __init__ methods.

setstate ¶

__setstate__(state: dict[str, Any]) -> None

Restore from a serialized copy of self.__dict__.

forward ¶

forward(
    input: Tensor,
    noise_mask: Tensor | None = None,
    **kwargs: Any,
) -> torch.Tensor

Transform the input data.

Parameters:

Name	Type	Description	Default
`input` ¶	`Tensor`	The input to transform.	required
`noise_mask` ¶	`Tensor \| None`	An optional mask that selects the elements of `input` to transform. Where the mask is `0`, the original `input` value is returned. Also used to select the elements of the sampled standard deviations to use to mask the `input`. If `None`, the entire `input` is transformed.	`None`
`**kwargs` ¶	`Any`	Additional keyword arguments to the estimator modules.	required

Returns:

Type	Description
`torch.Tensor`	The transformed input data.

get_applied_transform_components_factory ¶

get_applied_transform_components_factory() -> Callable[
    [], dict[str, torch.Tensor]
]

Create a function that returns the elements of the transform components ('mean' and 'std') applied during the most recent forward pass.

Specifically, the applied elements are those selected by the noise mask (if supplied) and standard deviation mask (if std_estimator.masker is not None). If no masks are used, all elements are returned.

The applied transform components are returned flattened.

This function is intended to be used to log histograms of the transform components.

Returns:

Type	Description
`Callable[[], dict[str, torch.Tensor]]`	A function that returns the the elements of the transform components applied during the most recent forward pass.

Examples:

>>> from torch import nn
>>> from stainedglass_core import model as sg_model, noise_layer as sg_noise_layer
>>> base_model = nn.Linear(20, 2)
>>> noisy_model = sg_model.NoisyModel(
...     sg_noise_layer.CloakNoiseLayer1,
...     base_model,
...     target_parameter="input",
... )
>>> get_applied_transform_components = (
...     noisy_model.noise_layer.get_applied_transform_components_factory()
... )
>>> input = torch.ones(1, 20)
>>> noise_mask = torch.tensor(5 * [False] + 15 * [True])
>>> output = noisy_model(input, noise_mask=noise_mask)
>>> applied_transform_components = get_applied_transform_components()
>>> applied_transform_components
{'mean': tensor(...), 'std': tensor(...)}
>>> {
...     component_name: component.shape
...     for component_name, component in applied_transform_components.items()
... }
{'mean': torch.Size([15]), 'std': torch.Size([15])}

get_transformed_output_factory ¶

get_transformed_output_factory() -> Callable[
    [], torch.Tensor
]

Create a function that returns the transformed output from the most recent forward pass.

If super batching is active, only the transformed half of the super batch output is returned.

Returns:

Type	Description
`Callable[[], torch.Tensor]`	A function that returns the transformed output from the most recent forward pass.

Examples:

>>> from stainedglass_core import noise_layer as sg_noise_layer
>>> noise_layer = sg_noise_layer.CloakNoiseLayer1()
>>> get_transformed_output = noise_layer.get_transformed_output_factory()
>>> input = torch.ones(2, 3, 32, 32)
>>> output = noise_layer(input)
>>> transformed_output = get_transformed_output()
>>> assert output.equal(transformed_output)

initial_seed ¶

initial_seed() -> int

Return the initial seed of the CPU device's random number generator.

manual_seed ¶

manual_seed(seed: int | None) -> None

Seed each of the random number generators.

Setting seed to None will destroy any existing generators.

Parameters:

Name	Type	Description	Default
`seed` ¶	`int \| None`	The seed to set.	required

reset_parameters ¶

reset_parameters() -> None

Reinitialize parameters and buffers.

This method is useful for initializing tensors created on the meta device.

seed ¶

seed() -> None

Seed each of the random number generators using a non-deterministic random number.

noise_layer

BaseNoiseLayer ¶

seed ¶

mean_estimator ¶

std_estimator ¶

__call__ ¶

input ¶

noise_mask ¶

**kwargs ¶

__getstate__ ¶

__init_subclass__ ¶

__setstate__ ¶

forward ¶

input ¶

noise_mask ¶

**kwargs ¶

get_applied_transform_components_factory ¶

get_transformed_output_factory ¶

initial_seed ¶

manual_seed ¶

seed ¶

reset_parameters ¶

seed ¶

CloakNoiseLayer ¶

scale ¶

shallow ¶

percent_to_mask ¶

value_range ¶

locs_requires_grad ¶

rhos_requires_grad ¶

rhos_init ¶

seed ¶

__call__ ¶

input ¶

noise_mask ¶

**kwargs ¶

__getstate__ ¶

__init_subclass__ ¶

__setstate__ ¶

forward ¶

input ¶

noise_mask ¶

**kwargs ¶

get_applied_transform_components_factory ¶

get_transformed_output_factory ¶

initial_seed ¶

manual_seed ¶

seed ¶

reset_parameters ¶

seed ¶

CloakNoiseLayer1 ¶

scale ¶

shallow ¶

locs ¶

rhos ¶

rhos_init ¶

seed ¶

__call__ ¶

input ¶

noise_mask ¶

**kwargs ¶

__getstate__ ¶

__init_subclass__ ¶

__setstate__ ¶

forward ¶

input ¶

noise_mask ¶

**kwargs ¶

get_applied_transform_components_factory ¶

get_transformed_output_factory ¶

initial_seed ¶

manual_seed ¶

seed ¶

reset_parameters ¶

seed ¶

CloakNoiseLayer2 ¶

scale ¶

percent_to_mask ¶

shallow ¶

value_range ¶

`seed` ¶

`mean_estimator` ¶

`std_estimator` ¶

call ¶

`input` ¶

`noise_mask` ¶

`**kwargs` ¶

getstate ¶

setstate ¶

`input` ¶

`noise_mask` ¶

`**kwargs` ¶

`seed` ¶

`scale` ¶

`shallow` ¶

`percent_to_mask` ¶

`value_range` ¶

`locs_requires_grad` ¶

`rhos_requires_grad` ¶

`rhos_init` ¶

`seed` ¶

call ¶

`input` ¶

`noise_mask` ¶

`**kwargs` ¶

getstate ¶

setstate ¶

`input` ¶

`noise_mask` ¶

`**kwargs` ¶

`seed` ¶

`scale` ¶

`shallow` ¶

`locs` ¶

`rhos` ¶

`rhos_init` ¶

`seed` ¶

call ¶

`input` ¶

`noise_mask` ¶

`**kwargs` ¶

getstate ¶

setstate ¶

`input` ¶

`noise_mask` ¶

`**kwargs` ¶

`seed` ¶

`scale` ¶

`percent_to_mask` ¶

`shallow` ¶

`value_range` ¶

`seed` ¶

call ¶

`input` ¶

`noise_mask` ¶

`**kwargs` ¶

getstate ¶

init ¶

setstate ¶

`input` ¶

`noise_mask` ¶

`**kwargs` ¶

`seed` ¶

`scale` ¶

`percent_to_mask` ¶

`shallow` ¶

`seed` ¶

call ¶

`input` ¶

`noise_mask` ¶

`**kwargs` ¶

getstate ¶

setstate ¶

`input` ¶

`noise_mask` ¶

`**kwargs` ¶

`seed` ¶

`scale` ¶

`percent_to_mask` ¶

`shallow` ¶