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
Return type

Callable

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
Return type

Callable

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: numpy.ndarray, eps: float, norm_p: Union[int, float, str]) → numpy.ndarray

Project values on the L_p norm ball of size eps.

Return type

ndarray

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

  • eps (float) – Maximum norm allowed.

  • norm_p – L_p norm to use for clipping. Only 1, 2, np.Inf and “inf” supported for now.

Returns

Values of values after projection.

art.utils.random_sphere(nb_points: int, nb_dims: int, radius: float, norm: Union[int, float, str]) → numpy.ndarray

Generate randomly m x n-dimension points 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 (float) – Radius of the sphere.

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

Returns

The generated random sphere.

art.utils.original_to_tanh(x_original: numpy.ndarray, clip_min: Union[float, numpy.ndarray], clip_max: Union[float, numpy.ndarray], tanh_smoother: float = 0.999999) → numpy.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: numpy.ndarray, clip_min: Union[float, numpy.ndarray], clip_max: Union[float, numpy.ndarray]) → numpy.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: numpy.ndarray, nb_classes: Optional[int] = None) → numpy.ndarray

Convert an array of labels to binary class matrix.

Return type

ndarray

Parameters
  • labels (ndarray) – 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, nb_classes=None)

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

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

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

Returns

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

Return type

np.ndarray

art.utils.check_and_transform_label_format(labels: numpy.ndarray, nb_classes: Optional[int] = None, return_one_hot: bool = True) → numpy.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.

  • 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: numpy.ndarray, nb_classes: int) → numpy.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: numpy.ndarray, classifier: CLASSIFIER_TYPE) → numpy.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: numpy.ndarray, classifier: CLASSIFIER_TYPE) → numpy.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: numpy.ndarray) → Tuple[numpy.ndarray, numpy.ndarray]

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

Return type

Tuple

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: numpy.ndarray) → numpy.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: numpy.ndarray, labels: numpy.ndarray, x_adv: numpy.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_success(classifier: CLASSIFIER_TYPE, x_clean: numpy.ndarray, labels: numpy.ndarray, x_adv: numpy.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: numpy.ndarray, labels: numpy.ndarray, abstain: bool = True) → Tuple[numpy.ndarray, int]

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

Return type

Tuple

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[numpy.ndarray, numpy.ndarray], Tuple[numpy.ndarray, numpy.ndarray], float, float]

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

Return type

Tuple

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, path: Optional[str] = None, extract: 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 (str) – 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.

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: numpy.ndarray, clip_values: Optional[CLIP_VALUES_TYPE], round_samples: float) → numpy.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: numpy.ndarray, y: numpy.ndarray, nb_classes: int = 10, clip_values: Optional[CLIP_VALUES_TYPE] = None) → Tuple[numpy.ndarray, numpy.ndarray]

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

Return type

Tuple

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: numpy.ndarray, classes: numpy.ndarray, num_classes: int) → List[numpy.ndarray]

Returns segmented data according to specified features.

Return type

List

Parameters
  • data (ndarray) – 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: numpy.ndarray, test_labels: numpy.ndarray, perf_function: Union[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: numpy.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.