`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]) → 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 and np.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]) → 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.

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) → numpy.ndarray¶

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

Paper link: https://arxiv.org/abs/1607.02533

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) → 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, 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, 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.

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.

Return type

float

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, model2: Classifier, 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.

art.utils¶

Deprecation Operations¶

Math Operations¶

Label Operations¶

Dataset Operations¶

`art.utils`¶