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: Union[int, float, numpy.ndarray], 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 – 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: Union[int, float, numpy.ndarray], 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 – 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: Union[numpy.ndarray, List[float]], nb_classes: Optional[int] = None) → numpy.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: numpy.ndarray, nb_classes: Optional[int] = None)¶ Convert an array of floating point labels to binary class matrix.
- 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 labels 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).
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_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, 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 (
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.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: numpy.ndarray, clip_values: Optional[Tuple[Union[int, float, numpy.ndarray], Union[int, float, numpy.ndarray]]], 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[Tuple[Union[int, float, numpy.ndarray], Union[int, float, numpy.ndarray]]] = 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: Union[numpy.ndarray, List[int]], classes: numpy.ndarray, num_classes: int) → List[numpy.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: 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.