`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: ndarray, eps: Union[int, float, ndarray], norm_p: Union[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: Union[int, float, ndarray], norm: Union[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: Union[float, ndarray], clip_max: Union[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: Union[float, ndarray], clip_max: Union[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: Union[ndarray, List[float]], nb_classes: Optional[int] = 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: Optional[int] = 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: Optional[int], 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).

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: 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

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

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

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

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: Union[str, List[str]], path: Optional[str] = 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: Optional[Tuple[Union[int, float, ndarray], Union[int, float, ndarray]]], 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: Optional[Tuple[Union[int, float, ndarray], Union[int, float, ndarray]]] = None) → Tuple[ndarray, 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: Union[ndarray, List[int]], classes: ndarray, num_classes: int) → List[ndarray]¶

Returns segmented data according to specified features.

Return type:

List

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: 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: 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`¶