a2pm 1.2.0

Adaptative Perturbation Pattern Method

A2PM is a gray-box method for the generation of realistic adversarial examples. It benefits from a modular architecture to assign an independent sequence of adaptative perturbation patterns to each class, which analyze specific feature subsets to create valid and coherent data perturbations.

This method was developed to address the diverse constraints of domains with tabular data, such as cybersecurity. It can be advantageous for adversarial attacks against machine learning classifiers, as well as for adversarial training strategies. This Python 3 implementation provides out-of-the-box compatibility with the Scikit-Learn library.

If you use A2PM, please cite the primary research article: https://doi.org/10.3390/fi14040108

Check out the official documentation: https://a2pm.readthedocs.io/en/latest

Explore the public source code repository: https://github.com/vitorinojoao/a2pm

How To Install

The package and its dependencies can be installed using the pip package manager:

pip install a2pm

Alternatively, the repository can be downloaded and the package installed from the local directory:

pip install .

How To Setup

The package can be accessed through the following imports:

from a2pm import A2PMethod
from a2pm.callbacks import BaseCallback, MetricCallback, TimeCallback
from a2pm.patterns import BasePattern, CombinationPattern, IntervalPattern
from a2pm.wrappers import BaseWrapper, KerasWrapper, SklearnWrapper, TorchWrapper

A2PM can be created with a simple base configuration of Interval and/or Combination pattern sequences, which have several possible parameters:

pattern = (

    # First pattern to be applied: Interval
    {
        "type": "interval",
        "features": list(range(0, 20)),
        "integer_features": list(range(10, 20)),
        "ratio": 0.1,
        "max_ratio": 0.3,
        "missing_value": 0.0,
        "probability": 0.6,
    },

    # Second pattern to be applied: Combination
    {
        "type": "combination",
        "features": list(range(20, 40)),
        "locked_features": list(range(30, 40)),
        "probability": 0.4,
    },
)

method = A2PMethod(pattern)

To support domains with complex constraints, the method is highly configurable:

# General pattern sequence that will be applied to new data classes
pattern = (

    # An instantiated pattern
    MyCustomPattern(1, 2),

    # A pattern configuration
    {
        "type": MyCustomPattern,
        "param_name_1": 3,
        "param_name_2": 4,
    },
)

# Pre-assigned mapping of data classes to pattern sequences
preassigned_patterns = {

    # None to disable the perturbation of this class
    "class_label_1": None,

    # Specific pattern sequence that will be applied to this class
    "class_label_2": (
        MyCustomPattern(5, 6),
        {
            "type": MyCustomPattern,
            "param_name_1": 7,
            "param_name_2": 8,
        },
    ),
}

method = A2PMethod(pattern, preassigned_patterns)

How To Use

A2PM can be utilized through the ‘fit’, ‘partial_fit’, ‘transform’ and ‘generate’ methods, as well as their respective shortcuts:

# Adapts to new data, and then creates adversarial examples
X_adversarial = method.fit_transform(X, y)

# Encapsulates a Tensorflow/Keras classification model
classifier = KerasWrapper(my_model, my_custom_class_labels)

# Adapts to new data, and then performs an untargeted attack against a classifier
X_adversarial = method.fit_generate(classifier, X, y)

# Adapts to new data, and then performs a targeted attack against a classifier
X_adversarial = method.fit_generate(classifier, X, y, y_target)

To analyze specific aspects of the method, callback functions can be called before the attack starts (iteration 0) and after each attack iteration (iteration 1, 2, …):

X_adversarial = method.fit_generate(
    classifier,
    X,
    y,
    y_target,

    # Additional configuration
    iterations=10,
    patience=2,

    callback=[

        # Time consumption
        TimeCallback(verbose=2),

        # Evaluation metrics
        MetricCallback(classifier, y, my_custom_scorers, verbose=2),

        # An instantiated callback
        MyCustomCallback(),

        # A simple callback function
        MyCustomFunction,
    ],
)