datagenerator.shattered_grad

Attributes

data

Classes

ShatteredGradientsDataset

A class intended to generate data and weights that exhibit shattered gradient phenomena.

Module Contents

class datagenerator.shattered_grad.ShatteredGradientsDataset(seed: int = 0, n_features: int = 5, n_samples: int = 100, discontinuity_ratios: List | None = None, bias: float = 0.5, act_fun: str = 'Relu', two_distributions_flag: bool = False, proportion: float = 0.2, classification: bool = False, **kwargs: Any)

Bases: xaiunits.datagenerator.WeightedFeaturesDataset

A class intended to generate data and weights that exhibit shattered gradient phenomena.

This class generates weights depending on the activation function and the discontinuity ratios. The discontinuity ratio is a set of real numbers (one per feature), so small perturbations around this discontinuity ratio significantly impact the model’s explanation.

Inherits from:: WeightedFeaturesDataset: Class extending BaseFeaturesDataset with support for weighted features

weights

Weights applied to each feature.

Type:: Tensor

weight_range

The range (min, max) within which random weights are generated.

Type:: tuple

weighted_samples

The samples after applying weights.

Type:: Tensor

Initializes a ShatteredGradientsDataset object.

Parameters:

seed (int) – Seed for reproducibility. Defaults to 0.
n_features (int) – Number of features. Defaults to 5.
n_samples (int) – Number of samples. Defaults to 100.
discontinuity_ratios (list, optional) – Ratios indicating feature discontinuity. If None, ratios are generated randomly. Defaults to None. Example: (1, -3, 4, 2, -2)
bias (float) – Bias value. Defaults to 0.5.
act_fun (str) – Activation function (“Relu”, “Gelu”, or “Sigmoid”). Defaults to “Relu”.
two_distributions_flag (bool) – Flag for using two distributions. Defaults to False.
proportion (float) – Proportion of samples for narrow distribution when using two distributions. Defaults to 0.2.
classification (bool) – Flag for classification. Defaults to False.
**kwargs –
Arbitrary keyword arguments passed to the base class constructor, including:
- sample_std_dev_narrow (float): Standard deviation for sample creation noise in narrow distribution. Defaults to 0.05.
- sample_std_dev_wide (float): Standard deviation for sample creation noise in wide distribution. Defaults to 10.
- weight_scale (float): Scalar value to multiply all generated weights with.
- label_std_dev (float): Noise standard deviation to generate labels. Defaults to 0.

_initialize_with_narrow_wide_distributions(seed: int, n_features: int, n_samples: int, discontinuity_ratios: List, bias: float, act_fun: str, proportion: float, classification: bool, kwargs: Dict | None) → None

Initializes the dataset with narrow and wide distributions.

This method sets up the dataset with narrow and wide distributions. It generates a dataset with the first portion of data belonging to the narrow distribution dependent on sample_std_dev_narrow. Similarly, the second portion of the dataset will belong to the wider distribution, depending on sample_std_dev_wide.

It also initializes the weights dependent on discontinuity ratios and weight_scale.

Parameters:

seed (int) – Seed for random number generation to ensure reproducibility.
n_features (int) – Number of features in the dataset.
n_samples (int) – Number of samples in the dataset.
discontinuity_ratios (list) – List of discontinuity ratios for each feature.
bias (float) – Bias value to adjust the weight scale.
act_fun (str) – Activation function name (‘Relu’, ‘Gelu’, or ‘Sigmoid’).
proportion (float) – Proportion of narrow samples to wide samples.
classification (bool) – Indicates if the dataset is for classification (True) or regression (False).
**kwargs –
Arbitrary keyword arguments passed to the base class constructor, including:
- sample_std_dev_narrow (float): Standard deviation for sample creation noise in narrow distribution. Defaults to 0.05.
- sample_std_dev_wide (float): Standard deviation for sample creation noise in wide distribution. Defaults to 10.
- weight_scale (float): Scalar value to multiply all generated weights with.
- label_std_dev (float): Noise standard deviation to generate labels. Defaults to 0.

_initialize_with_narrow_distribution(seed: int, n_features: int, n_samples: int, discontinuity_ratios: List, bias: float, act_fun: str, classification: bool, kwargs: Dict | None)

Initializes the dataset with just a narrow distribution.

It generates a dataset with the first portion of data belonging to the narrow distribution dependent on sample_std_dev_narrow.

It also initializes the weights dependent on discontinuity ratios and weight_scale.

Parameters:

seed (int) – Seed for random number generation to ensure reproducibility.
n_features (int) – Number of features in the dataset.
n_samples (int) – Number of samples in the dataset.
discontinuity_ratios (list) – List of discontinuity ratios for each feature.
bias (float) – Bias value to adjust the weight scale.
act_fun (str) – Activation function name (‘Relu’, ‘Gelu’, or ‘Sigmoid’).
proportion (float) – Proportion of narrow samples to wide samples.
classification (bool) – Indicates if the dataset is for classification (True) or regression (False).
**kwargs –
Arbitrary keyword arguments passed to the base class constructor, including:
- sample_std_dev_narrow (float): Standard deviation for sample creation noise in narrow distribution. Defaults to 0.05.
- weight_scale (float): Scalar value to multiply all generated weights with.
- label_std_dev (float): Noise standard deviation to generate labels. Defaults to 0.

_initialize_samples_narrow_wide(n_samples: int, proportion: float, distribution_narrow: torch.distributions.Distribution, distribution_wide: torch.distributions.Distribution) → Tuple[torch.Tensor, torch.distributions.Distribution]

Initializes synthetic samples with narrow and wide distributions.

Parameters:

n_samples (int) – Total number of samples to generate.
proportion (float) – Proportion of samples that should belong to the narrow distribution. It should be between 0 and 1, where 0 indicates no narrow samples, and 1 indicates all samples are narrow.
distribution_narrow (torch.distributions.Distribution) – Narrow distribution object.
distribution_wide (torch.distributions.Distribution) – Wide distribution object.

Returns:

A tuple containing the generated samples and the distribution used.

Return type:

tuple

_initialize_discontinuity_ratios(discontinuity_ratios: List | None, n_features: int) → List[torch.Tensor]

Initialize discontinuity ratios for each feature in the dataset.

If discontinuity_ratios is None, this method generates initial discontinuity ratios for each feature based on the specified n_features.

Parameters:

discontinuity_ratios (list | NoneType) – List of discontinuity ratios for each feature. If None, new discontinuity ratios will be generated.
n_features (int) – Number of features in the dataset.

Returns:

List of discontinuity ratios for each feature.

Return type:

list

Raises:

AssertionError – If there are no positive or negative ratios, if discontinuity_ratios is not a list, or if the length of discontinuity_ratios does not match n_features.

_get_default_distribution_narrow(n_features: int, kwargs: Dict | None) → Tuple[torch.distributions.Distribution, Dict]

Returns the default narrow distribution for the dataset.

This method sets the default narrow distribution based on the provided kwargs or defaults. The sample_std_dev_narrow is used to determine the covariance matrix of the distribution.

Parameters:

n_features (int) – Number of features in the dataset.
kwargs (dict) –
Additional keyword arguments for configuration:
- sample_std_dev_narrow (float): Used to determine the covariance matrix of the distribution.

Returns:

A tuple containing the default narrow distribution and the modified kwargs.

Return type:

tuple

_get_default_distribution_wide(n_features: int, kwargs: Dict | None) → Tuple[torch.distributions.Distribution, Dict]

Returns the default wide distribution for the dataset.

This method sets up the default wide distribution based on the provided kwargs or defaults. The sample_std_dev_wide is used to determine the covariance matrix of the distribution.

Parameters:

n_features (int) – Number of features in the dataset.
kwargs (dict) –
Additional keyword arguments for configuration:
- sample_std_dev_wide (float): Used to determine the covariance matrix of the distribution.

Returns:

A tuple containing the default wide distribution and the modified kwargs.

Return type:

tuple

_default_activation_function(act_fun: str, classification: bool) → torch.nn.Module

Returns the default activation function based on the provided function name and task type.

Parameters:

act_fun (str or nn.Module) – Name or instance of the activation function (‘Relu’, ‘Gelu’, ‘Sigmoid’), or a custom activation function instance.
classification (bool) – Indicates if the dataset is for classification (True) or regression (False).

Returns:

The default activation function is based on the specified name, instance, and task type.

Return type:

nn.Module

Raises:

KeyError – If the provided activation function is not one of ‘Relu’, ‘Gelu’, or ‘Sigmoid’, and it does not match the type of a custom activation function already defined in the mapping.

_get_weight_scale(kwargs: Dict | None, act_fun: str) → Dict

Adjust the weight scaling factor based on the activation function used.

This method calculates and updates the weight scaling factor in the kwargs dictionary based on the provided activation function. A different default weight scale is applied for’ Sigmoid’ activation than other activation functions.

Parameters:

kwargs (dict) – Additional keyword arguments, potentially including ‘weight_scale’. If the user does not specify weight_scale, Default is implemented.
act_fun (str) – Name of the activation function (‘Relu’, ‘Gelu’, or ‘Sigmoid’).

Returns:

Updated kwargs with the ‘weight_scale’ value adjusted according to the activation function.

Return type:

dict

Raises:

KeyError – If the activation function is not one of ‘Relu’, ‘Gelu’, or ‘Sigmoid’.

_generate_default_weights(n_features: int, weight_scale: float, act_fun: str) → torch.Tensor

Generate default weights based on discontinuity ratios, bias, and activation function.

Parameters:

n_features (int) – Number of features in the dataset.
weight_scale (float) – Scaling factor for weight initialization.
act_fun (str) – Name of the activation function (‘Relu’, ‘Gelu’, or ‘Sigmoid’).

Returns:

Default weights for each feature, adjusted based on discontinuity ratios, bias, and activation function.

Return type:

torch.Tensor

Raises:

ZeroDivisionError – If the sum of positive or negative ratios is zero, indicating a configuration issue.

generate_model() → torch.nn.Module

Generate a model using the Shattered Gradients Neural Network architecture.

Returns:: An instance of the ShatteredGradientsNN model.
Return type:: model.ShatteredGradientsNN

__getitem__(idx: int, others: List[str] = []) → Tuple[Any, Ellipsis]

Retrieve a sample and its associated label by index.

Parameters:

idx (int) – Index of the sample to retrieve.
others (list) – Additional items to retrieve. Defaults to [].

Returns:

Tuple containing the sample and its label.

Return type:

tuple

property default_metric: None

The default metric for evaluating the performance of explanation methods applied to this dataset.

For this dataset, the default metric is the max sensitivity metric.

Returns:

A class that wraps around the default metric to be instantiated: within the pipeline.

Return type:

type

datagenerator.shattered_grad.data