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.