art.utils

Module providing convenience functions.

Deprecation Operations

art.utils.deprecated(end_version: str, *, reason: str = '', replaced_by: str = '') Callable

Deprecate a function or method and raise a DeprecationWarning.

The @deprecated decorator is used to deprecate functions and methods. Several cases are supported. For example one can use it to deprecate a function that has become redundant or rename a function. The following code examples provide different use cases of how to use decorator.

@deprecated("0.1.5", replaced_by="sum")
def simple_addition(a, b):
    return a + b
Parameters:
  • end_version (str) – Release version of removal.

  • reason (str) – Additional deprecation reason.

  • replaced_by (str) – Function that replaces deprecated function.

art.utils.deprecated_keyword_arg(identifier: str, end_version: str, *, reason: str = '', replaced_by: str = '') Callable

Deprecate a keyword argument and raise a DeprecationWarning.

The @deprecated_keyword_arg decorator is used to deprecate keyword arguments. The deprecated keyword argument must default to Deprecated. Several use cases are supported. For example one can use it to to rename a keyword identifier. The following code examples provide different use cases of how to use the decorator.

@deprecated_keyword_arg("print", "1.1.0", replaced_by="verbose")
def simple_addition(a, b, print=Deprecated, verbose=False):
    if verbose:
        print(a + b)
    return a + b

@deprecated_keyword_arg("verbose", "1.1.0")
def simple_addition(a, b, verbose=Deprecated):
    return a + b
Parameters:
  • identifier (str) – Keyword identifier.

  • end_version (str) – Release version of removal.

  • reason (str) – Additional deprecation reason.

  • replaced_by (str) – Function that replaces deprecated function.

Math Operations

art.utils.projection(values: ndarray, eps: int | float | ndarray, norm_p: int | float | str) ndarray

Project values on the L_p norm ball of size eps.

Return type:

ndarray

Parameters:
  • values (ndarray) – Array of perturbations to clip.

  • eps – Maximum norm allowed.

  • norm_p – L_p norm to use for clipping. Only 1, 2 , np.Inf 1.1 and 1.2 supported for now. 1.1 and 1.2 compute orthogonal projections on l1-ball, using two different algorithms

Returns:

Values of values after projection.

art.utils.random_sphere(nb_points: int, nb_dims: int, radius: int | float | ndarray, norm: int | float | str) ndarray

Generate uniformly at random m x n-dimension points in the norm-norm ball with radius radius and centered around 0.

Return type:

ndarray

Parameters:
  • nb_points (int) – Number of random data points.

  • nb_dims (int) – Dimensionality of the sphere.

  • radius – Radius of the sphere.

  • norm – Current support: 1, 2, np.inf, “inf”.

Returns:

The generated random sphere.

art.utils.original_to_tanh(x_original: ndarray, clip_min: float | ndarray, clip_max: float | ndarray, tanh_smoother: float = 0.999999) ndarray

Transform input from original to tanh space.

Return type:

ndarray

Parameters:
  • x_original (ndarray) – An array with the input to be transformed.

  • clip_min – Minimum clipping value.

  • clip_max – Maximum clipping value.

  • tanh_smoother (float) – Scalar for multiplying arguments of arctanh to avoid division by zero.

Returns:

An array holding the transformed input.

art.utils.tanh_to_original(x_tanh: ndarray, clip_min: float | ndarray, clip_max: float | ndarray) ndarray

Transform input from tanh to original space.

Return type:

ndarray

Parameters:
  • x_tanh (ndarray) – An array with the input to be transformed.

  • clip_min – Minimum clipping value.

  • clip_max – Maximum clipping value.

Returns:

An array holding the transformed input.

Label Operations

art.utils.to_categorical(labels: ndarray | List[float], nb_classes: int | None = None) ndarray

Convert an array of labels to binary class matrix.

Return type:

ndarray

Parameters:
  • labels – An array of integer labels of shape (nb_samples,).

  • nb_classes – The number of classes (possible labels).

Returns:

A binary matrix representation of y in the shape (nb_samples, nb_classes).

art.utils.float_to_categorical(labels: ndarray, nb_classes: int | None = None)

Convert an array of floating point labels to binary class matrix.

Parameters:
  • labels (ndarray) – An array of floating point labels of shape (nb_samples,)

  • nb_classes – The number of classes (possible labels)

Returns:

A binary matrix representation of labels in the shape (nb_samples, nb_classes)

Return type:

np.ndarray

art.utils.check_and_transform_label_format(labels: ndarray, nb_classes: int | None, return_one_hot: bool = True) ndarray

Check label format and transform to one-hot-encoded labels if necessary

Return type:

ndarray

Parameters:
  • labels (ndarray) – An array of integer labels of shape (nb_samples,), (nb_samples, 1) or (nb_samples, nb_classes).

  • nb_classes – The number of classes. If None the number of classes is determined automatically.

  • return_one_hot (bool) – True if returning one-hot encoded labels, False if returning index labels.

Returns:

Labels with shape (nb_samples, nb_classes) (one-hot) or (nb_samples,) (index).

art.utils.random_targets(labels: ndarray, nb_classes: int) ndarray

Given a set of correct labels, randomly changes some correct labels to target labels different from the original ones. These can be one-hot encoded or integers.

Return type:

ndarray

Parameters:
  • labels (ndarray) – The correct labels.

  • nb_classes (int) – The number of classes for this model.

Returns:

An array holding the randomly-selected target classes, one-hot encoded.

art.utils.least_likely_class(x: ndarray, classifier: CLASSIFIER_TYPE) ndarray

Compute the least likely class predictions for sample x. This strategy for choosing attack targets was used in (Kurakin et al., 2016).

Return type:

ndarray

Parameters:
  • x (ndarray) – A data sample of shape accepted by classifier.

  • classifier – The classifier used for computing predictions.

Returns:

Least-likely class predicted by classifier for sample x in one-hot encoding.

art.utils.second_most_likely_class(x: ndarray, classifier: CLASSIFIER_TYPE) ndarray

Compute the second most likely class predictions for sample x. This strategy can be used for choosing target labels for an attack to improve its chances to succeed.

Return type:

ndarray

Parameters:
  • x (ndarray) – A data sample of shape accepted by classifier.

  • classifier – The classifier used for computing predictions.

Returns:

Second most likely class predicted by classifier for sample x in one-hot encoding.

art.utils.get_label_conf(y_vec: ndarray) Tuple[ndarray, ndarray]

Returns the confidence and the label of the most probable class given a vector of class confidences

Parameters:

y_vec (ndarray) – Vector of class confidences, no. of instances as first dimension.

Returns:

Confidences and labels.

art.utils.get_labels_np_array(preds: ndarray) ndarray

Returns the label of the most probable class given a array of class confidences.

Return type:

ndarray

Parameters:

preds (ndarray) – Array of class confidences, nb of instances as first dimension.

Returns:

Labels.

art.utils.compute_success_array(classifier: CLASSIFIER_TYPE, x_clean: ndarray, labels: ndarray, x_adv: ndarray, targeted: bool = False, batch_size: int = 1) ndarray

Compute the success rate of an attack based on clean samples, adversarial samples and targets or correct labels.

Return type:

ndarray

Parameters:
  • classifier – Classifier used for prediction.

  • x_clean (ndarray) – Original clean samples.

  • labels (ndarray) – Correct labels of x_clean if the attack is untargeted, or target labels of the attack otherwise.

  • x_adv (ndarray) – Adversarial samples to be evaluated.

  • targeted (bool) – True if the attack is targeted. In that case, labels are treated as target classes instead of correct labels of the clean samples.

  • batch_size (int) – Batch size.

Returns:

Percentage of successful adversarial samples.

art.utils.compute_success(classifier: CLASSIFIER_TYPE, x_clean: ndarray, labels: ndarray, x_adv: ndarray, targeted: bool = False, batch_size: int = 1) float

Compute the success rate of an attack based on clean samples, adversarial samples and targets or correct labels.

Return type:

float

Parameters:
  • classifier – Classifier used for prediction.

  • x_clean (ndarray) – Original clean samples.

  • labels (ndarray) – Correct labels of x_clean if the attack is untargeted, or target labels of the attack otherwise.

  • x_adv (ndarray) – Adversarial samples to be evaluated.

  • targeted (bool) – True if the attack is targeted. In that case, labels are treated as target classes instead of correct labels of the clean samples.

  • batch_size (int) – Batch size.

Returns:

Percentage of successful adversarial samples.

art.utils.compute_accuracy(preds: ndarray, labels: ndarray, abstain: bool = True) Tuple[float, float]

Compute the accuracy rate and coverage rate of predictions In the case where predictions are abstained, those samples are ignored.

Parameters:
  • preds (ndarray) – Predictions.

  • labels (ndarray) – Correct labels of x.

  • abstain (bool) – True if ignore abstained prediction, False if count them as incorrect.

Returns:

Tuple of accuracy rate and coverage rate.

Dataset Operations

art.utils.load_dataset(name: str) Tuple[Tuple[ndarray, ndarray], Tuple[ndarray, ndarray], float, float]

Loads or downloads the dataset corresponding to name. Options are: mnist, cifar10, stl10, iris, nursery and diabetes.

Parameters:

name (str) – Name of the dataset.

Returns:

The dataset separated in training and test sets as (x_train, y_train), (x_test, y_test), min, max.

Raises:

NotImplementedError – If the dataset is unknown.

art.utils.get_file(filename: str, url: str | List[str], path: str | None = None, extract: bool = False, verbose: bool = False) str

Downloads a file from a URL if it not already in the cache. The file at indicated by url is downloaded to the path path (default is ~/.art/data). and given the name filename. Files in tar, tar.gz, tar.bz, and zip formats can also be extracted. This is a simplified version of the function with the same name in Keras.

Return type:

str

Parameters:
  • filename (str) – Name of the file.

  • url – Download URL.

  • path – Folder to store the download. If not specified, ~/.art/data is used instead.

  • extract (bool) – If true, tries to extract the archive.

  • verbose (bool) – If true, print download progress bar.

Returns:

Path to the downloaded file.

art.utils.make_directory(dir_path: str) None

Creates the specified tree of directories if needed.

Parameters:

dir_path (str) – Folder or file path.

art.utils.clip_and_round(x: ndarray, clip_values: Tuple[int | float | ndarray, int | float | ndarray] | None, round_samples: float) ndarray

Rounds the input to the correct level of granularity. Useful to ensure data passed to classifier can be represented in the correct domain, e.g., [0, 255] integers verses [0,1] or [0, 255] floating points.

Return type:

ndarray

Parameters:
  • x (ndarray) – Sample input with shape as expected by the model.

  • clip_values – Tuple of the form (min, max) representing the minimum and maximum values allowed for features, or None if no clipping should be performed.

  • round_samples (float) – The resolution of the input domain to round the data to, e.g., 1.0, or 1/255. Set to 0 to disable.

art.utils.preprocess(x: ndarray, y: ndarray, nb_classes: int = 10, clip_values: Tuple[int | float | ndarray, int | float | ndarray] | None = None) Tuple[ndarray, ndarray]

Scales x to [0, 1] and converts y to class categorical confidences.

Parameters:
  • x (ndarray) – Data instances.

  • y (ndarray) – Labels.

  • nb_classes (int) – Number of classes in dataset.

  • clip_values – Original data range allowed value for features, either one respective scalar or one value per feature.

Returns:

Rescaled values of x, y.

art.utils.segment_by_class(data: ndarray | List[int], classes: ndarray, num_classes: int) List[ndarray]

Returns segmented data according to specified features.

Parameters:
  • data – Data to be segmented.

  • classes (ndarray) – Classes used to segment data, e.g., segment according to predicted label or to y_train or other array of one hot encodings the same length as data.

  • num_classes (int) – How many features.

Returns:

Segmented data according to specified features.

art.utils.performance_diff(model1: CLASSIFIER_TYPE, model2: CLASSIFIER_TYPE, test_data: ndarray, test_labels: ndarray, perf_function: str | Callable = 'accuracy', **kwargs) float

Calculates the difference in performance between two models on the test_data with a performance function.

Note: For multi-label classification, f1 scores will use ‘micro’ averaging unless otherwise specified.

Return type:

float

Parameters:
  • model1 – A trained ART classifier.

  • model2 – Another trained ART classifier.

  • test_data (ndarray) – The data to test both model’s performance.

  • test_labels (ndarray) – The labels to the testing data.

  • perf_function – The performance metric to be used. One of [‘accuracy’, ‘f1’] or a callable function (true_labels, model_labels[, kwargs]) -> float.

  • kwargs – Arguments to add to performance function.

Returns:

The difference in performance performance(model1) - performance(model2).

Raises:

ValueError – If an unsupported performance function is requested.

art.utils.is_probability(vector: ndarray) bool

Check if an 1D-array is a probability vector.

Return type:

bool

Parameters:

vector (ndarray) – An 1D-array.

Returns:

True if it is a probability vector.