secml.ml.features.normalization

CNormalizer

class secml.ml.features.normalization.c_normalizer.CNormalizer(preprocess=None)[source]

Bases: secml.ml.features.c_preprocess.CPreProcess

Common interface for normalization preprocessing algorithms.

Attributes
class_type

Defines class type.

logger

Logger for current object.

preprocess

Inner preprocessor (if any).

verbose

Verbosity level of logger output.

Methods

backward(self[, w])

Returns the preprocessor gradient wrt data.

copy(self)

Returns a shallow copy of current class.

create([class_item])

This method creates an instance of a class with given type.

create_chain(class_items, kwargs_list)

Creates a chain of preprocessors.

deepcopy(self)

Returns a deep copy of current class.

fit(self, x[, y])

Fit transformation algorithm.

fit_transform(self, x[, y, caching])

Fit preprocessor using data and then transform data.

forward(self, x[, caching])

Apply the transformation algorithm on data.

get_class_from_type(class_type)

Return the class associated with input type.

get_params(self)

Returns the dictionary of class parameters.

get_subclasses()

Get all the subclasses of the calling class.

gradient(self, x[, w])

Compute gradient at x by doing a forward and a backward pass.

inverse_transform(self, x)

Revert data to original form.

is_linear(self)

Returns True for linear normalizers.

list_class_types()

This method lists all types of available subclasses of calling one.

load(path)

Loads class from pickle object.

save(self, path)

Save class object using pickle.

set(self, param_name, param_value[, copy])

Set a parameter that has a specific name to a specific value.

set_params(self, params_dict[, copy])

Set all parameters passed as a dictionary {key: value}.

timed([msg])

Timer decorator.

transform(self, x[, caching])

Apply the transformation algorithm on data.

is_linear(self)[source]

Returns True for linear normalizers.

CNormalizerLinear

class secml.ml.features.normalization.c_normalizer_linear.CNormalizerLinear(preprocess=None)[source]

Bases: secml.ml.features.normalization.c_normalizer.CNormalizer

Standardizes array by linearly scaling each feature.

Input data must have one row for each patterns, so features to scale are on each array’s column.

The standardization is given by:

X_scaled = m * X(axis=0) + q

where m, q are specific constants for each normalization.

Notes

Differently from numpy, we manage flat vectors as 2-Dimensional of shape (1, array.size). This means that normalizing a flat vector is equivalent to transform array.atleast_2d(). To obtain a numpy-style normalization of flat vectors, transpose array first.

Attributes
b

Returns the bias of the linear normalizer.

class_type

Defines class type.

logger

Logger for current object.

preprocess

Inner preprocessor (if any).

verbose

Verbosity level of logger output.

w

Returns the step of the linear normalizer.

Methods

backward(self[, w])

Returns the preprocessor gradient wrt data.

copy(self)

Returns a shallow copy of current class.

create([class_item])

This method creates an instance of a class with given type.

create_chain(class_items, kwargs_list)

Creates a chain of preprocessors.

deepcopy(self)

Returns a deep copy of current class.

fit(self, x[, y])

Fit transformation algorithm.

fit_transform(self, x[, y, caching])

Fit preprocessor using data and then transform data.

forward(self, x[, caching])

Apply the transformation algorithm on data.

get_class_from_type(class_type)

Return the class associated with input type.

get_params(self)

Returns the dictionary of class parameters.

get_subclasses()

Get all the subclasses of the calling class.

gradient(self, x[, w])

Compute gradient at x by doing a forward and a backward pass.

inverse_transform(self, x)

Revert data to original form.

is_linear(self)

Returns True for linear normalizers.

list_class_types()

This method lists all types of available subclasses of calling one.

load(path)

Loads class from pickle object.

save(self, path)

Save class object using pickle.

set(self, param_name, param_value[, copy])

Set a parameter that has a specific name to a specific value.

set_params(self, params_dict[, copy])

Set all parameters passed as a dictionary {key: value}.

timed([msg])

Timer decorator.

transform(self, x[, caching])

Apply the transformation algorithm on data.

abstract property b

Returns the bias of the linear normalizer.

is_linear(self)[source]

Returns True for linear normalizers.

abstract property w

Returns the step of the linear normalizer.

CNormalizerMeanStd

class secml.ml.features.normalization.c_normalizer_mean_std.CNormalizerMeanSTD(**kwargs)[source]

Bases: secml.ml.features.normalization.c_normalizer_mean_std.CNormalizerMeanStd

Deprecated since version 0.10: use CNormalizerMeanStd instead.

Normalize with given mean and standard deviation.

Attributes
b

Returns the bias of the linear normalizer.

class_type

Defines class type.

logger

Logger for current object.

mean

Mean to use for normalization.

preprocess

Inner preprocessor (if any).

std

Variance to use for normalization.

verbose

Verbosity level of logger output.

w

Returns the slope of the linear normalizer.

with_std

True if normalizer should transform array using variance too.

Methods

backward(self[, w])

Returns the preprocessor gradient wrt data.

copy(self)

Returns a shallow copy of current class.

create([class_item])

This method creates an instance of a class with given type.

create_chain(class_items, kwargs_list)

Creates a chain of preprocessors.

deepcopy(self)

Returns a deep copy of current class.

fit(self, x[, y])

Fit transformation algorithm.

fit_transform(self, x[, y, caching])

Fit preprocessor using data and then transform data.

forward(self, x[, caching])

Apply the transformation algorithm on data.

get_class_from_type(class_type)

Return the class associated with input type.

get_params(self)

Returns the dictionary of class parameters.

get_subclasses()

Get all the subclasses of the calling class.

gradient(self, x[, w])

Compute gradient at x by doing a forward and a backward pass.

inverse_transform(self, x)

Revert data to original form.

is_linear(self)

Returns True for linear normalizers.

list_class_types()

This method lists all types of available subclasses of calling one.

load(path)

Loads class from pickle object.

save(self, path)

Save class object using pickle.

set(self, param_name, param_value[, copy])

Set a parameter that has a specific name to a specific value.

set_params(self, params_dict[, copy])

Set all parameters passed as a dictionary {key: value}.

timed([msg])

Timer decorator.

transform(self, x[, caching])

Apply the transformation algorithm on data.

class secml.ml.features.normalization.c_normalizer_mean_std.CNormalizerMeanStd(mean=None, std=None, with_std=True, preprocess=None)[source]

Bases: secml.ml.features.normalization.c_normalizer_linear.CNormalizerLinear

Normalize with given mean and standard deviation.

If mean/std are tuples of multiple values, input is expected to be uniformly splittable in a number of channels equal to the number of values in the tuples. Both input tuples must have the same length.

Result will be: (input[channel] - mean[channel]) / std[channel]

If mean and std are None, values to use as mean and std will be computed from data. The result wil be an array with 0 mean or/and unit variance (if with_std parameter is True, default). In this case, the standard deviation calculated by numpy is the maximum likelihood estimate, i.e. the second moment of the set of values about their mean. See also CArray.std for more information.

Parameters
meanscalar or tuple of scalars or None, optional

Mean to use for normalization. If a tuple, each value represent a channel of the input. The number of features of the training data should be divisible by the number of values of the tuple. If a scalar, the same value is applied to all features. If None, mean is computed from training data. Cannot be None if std is not None and with_std is True.

stdscalar or tuple of scalars or None, optional

Variance to use for normalization. If a tuple, each value represent a channel of the input. The number of features of the training data should be divisible by the number of values of the tuple. If a scalar, the same value is applied to all features. If None, std is computed from training data. Cannot be None if mean is not None and with_std is True.

with_stdbool, optional

If True (default), normalizer scales array using std too. If False, std parameter is ignored.

preprocessCPreProcess or str or None, optional

Features preprocess to be applied to input data. Can be a CPreProcess subclass or a string with the type of the desired preprocessor. If None, input data is used as is.

Attributes
class_type‘mean-std’

Defines class type.

Methods

backward(self[, w])

Returns the preprocessor gradient wrt data.

copy(self)

Returns a shallow copy of current class.

create([class_item])

This method creates an instance of a class with given type.

create_chain(class_items, kwargs_list)

Creates a chain of preprocessors.

deepcopy(self)

Returns a deep copy of current class.

fit(self, x[, y])

Fit transformation algorithm.

fit_transform(self, x[, y, caching])

Fit preprocessor using data and then transform data.

forward(self, x[, caching])

Apply the transformation algorithm on data.

get_class_from_type(class_type)

Return the class associated with input type.

get_params(self)

Returns the dictionary of class parameters.

get_subclasses()

Get all the subclasses of the calling class.

gradient(self, x[, w])

Compute gradient at x by doing a forward and a backward pass.

inverse_transform(self, x)

Revert data to original form.

is_linear(self)

Returns True for linear normalizers.

list_class_types()

This method lists all types of available subclasses of calling one.

load(path)

Loads class from pickle object.

save(self, path)

Save class object using pickle.

set(self, param_name, param_value[, copy])

Set a parameter that has a specific name to a specific value.

set_params(self, params_dict[, copy])

Set all parameters passed as a dictionary {key: value}.

timed([msg])

Timer decorator.

transform(self, x[, caching])

Apply the transformation algorithm on data.

property b

Returns the bias of the linear normalizer.

property mean

Mean to use for normalization.

One value for each training array feature.

property std

Variance to use for normalization.

One value for each training array feature.

transform(self, x, caching=False)[source]

Apply the transformation algorithm on data.

Parameters
xCArray

Array to be transformed. Shape of input array depends on the algorithm itself.

caching: bool

True if preprocessed input should be cached for backward pass.

Returns
CArray

Transformed input data.

property w

Returns the slope of the linear normalizer.

property with_std

True if normalizer should transform array using variance too.

CNormalizerMinMax

class secml.ml.features.normalization.c_normalizer_minmax.CNormalizerMinMax(feature_range=None, preprocess=None)[source]

Bases: secml.ml.features.normalization.c_normalizer_linear.CNormalizerLinear

Standardizes array by scaling each feature to a given range.

This estimator scales and translates each feature individually such that it is in the given range on the training array, i.e. between zero and one.

Input data must have one row for each patterns, so features to scale are on each array’s column.

The standardization is given by:

X_std = (X - X.min(axis=0)) / (X.max(axis=0) - X.min(axis=0))
X_scaled = X_std * (max - min) + min

where min, max = feature_range.

Parameters
feature_rangetuple of scalars or None, optional

Desired range of transformed data, tuple of 2 scalars where feature_range[0] is the minimum and feature_range[1] is the maximum value. If feature_range is None, features will be scaled using (0., 1.) range.

preprocessCPreProcess or str or None, optional

Features preprocess to be applied to input data. Can be a CPreProcess subclass or a string with the type of the desired preprocessor. If None, input data is used as is.

Notes

Differently from numpy, we manage flat vectors as 2-Dimensional of shape (1, array.size). This means that normalizing a flat vector is equivalent to transform array.atleast_2d(). To obtain a numpy-style normalization of flat vectors, transpose array first.

Examples

>>> from secml.array import CArray
>>> from secml.ml.features.normalization import CNormalizerMinMax
>>> array = CArray([[1., -1., 2.], [2., 0., 0.], [0., 1., -1.]])
>>> print(CNormalizerMinMax().fit_transform(array))
CArray([[0.5      0.       1.      ]
 [1.       0.5      0.333333]
 [0.       1.       0.      ]])
>>> print(CNormalizerMinMax(feature_range=(-1,1)).fit_transform(array))
CArray([[ 0.       -1.        1.      ]
 [ 1.        0.       -0.333333]
 [-1.        1.       -1.      ]])
Attributes
class_type‘min-max’

Defines class type.

Methods

backward(self[, w])

Returns the preprocessor gradient wrt data.

copy(self)

Returns a shallow copy of current class.

create([class_item])

This method creates an instance of a class with given type.

create_chain(class_items, kwargs_list)

Creates a chain of preprocessors.

deepcopy(self)

Returns a deep copy of current class.

fit(self, x[, y])

Fit transformation algorithm.

fit_transform(self, x[, y, caching])

Fit preprocessor using data and then transform data.

forward(self, x[, caching])

Apply the transformation algorithm on data.

get_class_from_type(class_type)

Return the class associated with input type.

get_params(self)

Returns the dictionary of class parameters.

get_subclasses()

Get all the subclasses of the calling class.

gradient(self, x[, w])

Compute gradient at x by doing a forward and a backward pass.

inverse_transform(self, x)

Revert data to original form.

is_linear(self)

Returns True for linear normalizers.

list_class_types()

This method lists all types of available subclasses of calling one.

load(path)

Loads class from pickle object.

save(self, path)

Save class object using pickle.

set(self, param_name, param_value[, copy])

Set a parameter that has a specific name to a specific value.

set_params(self, params_dict[, copy])

Set all parameters passed as a dictionary {key: value}.

timed([msg])

Timer decorator.

transform(self, x[, caching])

Apply the transformation algorithm on data.

property b

Returns the bias of the linear normalizer.

property feature_range

Desired range of transformed data.

property max

Maximum of training array per feature.

Returns
train_maxCArray

Flat dense array with the maximum of each feature of the training array. If the scaler has not been trained yet, returns None.

property min

Minimum of training array per feature.

Returns
train_minCArray

Flat dense array with the minimum of each feature of the training array. If the scaler has not been trained yet, returns None.

property w

Returns the slope of the linear normalizer.

CNormalizerUnitNorm

class secml.ml.features.normalization.c_normalizer_unitnorm.CNormalizerUnitNorm(order=2, preprocess=None)[source]

Bases: secml.ml.features.normalization.c_normalizer.CNormalizer

Normalize patterns individually to unit norm.

Each pattern (i.e. each row of the data matrix) with at least one non zero component is rescaled independently of other patterns so that its norm (l1 or l2) equals one.

For the Row normalizer, no training routine is needed, so using fit_normalize() method is suggested for clarity. Use fit() method, which does nothing, only to streamline a pipelined environment.

Parameters
order{1, 2}, optional

Order of the norm to normalize each pattern with. Only 1 (‘l1’) and 2 (‘l2’) norm are supported. 2 (‘l2’) is default. For sparse arrays, only 2nd order norm is supported.

preprocessCPreProcess or str or None, optional

Features preprocess to be applied to input data. Can be a CPreProcess subclass or a string with the type of the desired preprocessor. If None, input data is used as is.

Notes

Differently from numpy, we manage flat vectors as 2-Dimensional of shape (1, array.size). This means that normalizing a flat vector is equivalent to transform array.atleast_2d(). To obtain a numpy-style normalization of flat vectors, transpose array first.

Examples

>>> from secml.array import CArray
>>> from secml.ml.features.normalization import CNormalizerUnitNorm
>>> array = CArray([[1., -1., 2.], [2., 0., 0.], [0., 1., -1.]])
>>> dense_normalized = CNormalizerUnitNorm().fit_transform(array)
>>> print(dense_normalized)
CArray([[ 0.408248 -0.408248  0.816497]
 [ 1.        0.        0.      ]
 [ 0.        0.707107 -0.707107]])
>>> print(CNormalizerUnitNorm(order=1).fit_transform(array))
CArray([[ 0.25 -0.25  0.5 ]
 [ 1.    0.    0.  ]
 [ 0.    0.5  -0.5 ]])
Attributes
class_type‘unit-norm’

Defines class type.

Methods

backward(self[, w])

Returns the preprocessor gradient wrt data.

copy(self)

Returns a shallow copy of current class.

create([class_item])

This method creates an instance of a class with given type.

create_chain(class_items, kwargs_list)

Creates a chain of preprocessors.

deepcopy(self)

Returns a deep copy of current class.

fit(self, x[, y])

Fit transformation algorithm.

fit_transform(self, x[, y, caching])

Fit preprocessor using data and then transform data.

forward(self, x[, caching])

Apply the transformation algorithm on data.

get_class_from_type(class_type)

Return the class associated with input type.

get_params(self)

Returns the dictionary of class parameters.

get_subclasses()

Get all the subclasses of the calling class.

gradient(self, x[, w])

Compute gradient at x by doing a forward and a backward pass.

inverse_transform(self, x)

Revert data to original form.

is_linear(self)

Returns True for linear normalizers.

list_class_types()

This method lists all types of available subclasses of calling one.

load(path)

Loads class from pickle object.

save(self, path)

Save class object using pickle.

set(self, param_name, param_value[, copy])

Set a parameter that has a specific name to a specific value.

set_params(self, params_dict[, copy])

Set all parameters passed as a dictionary {key: value}.

timed([msg])

Timer decorator.

transform(self, x[, caching])

Apply the transformation algorithm on data.

property norm

Returns the norm of each training array’s patterns.

property order

Returns the order of the norm used for patterns normalization.

CNormalizerDNN

class secml.ml.features.normalization.c_normalizer_dnn.CNormalizerDNN(net, out_layer=None, preprocess=<no value>)[source]

Bases: secml.ml.features.normalization.c_normalizer.CNormalizer

Normalized features are the DNN deepfeatures

Parameters
netCClassifierDNN

DNN to be used for extracting deepfeatures. This must be already trained.

out_layerstr or None, optional

Identifier of the layer at which the features must be retrieved. If None, the output of last layer will be returned.

Notes

Any additional inner preprocess should not be passed as the preprocess parameter but to the DNN instead.

Attributes
class_type‘dnn’

Defines class type.

Methods

backward(self[, w])

Returns the preprocessor gradient wrt data.

copy(self)

Returns a shallow copy of current class.

create([class_item])

This method creates an instance of a class with given type.

create_chain(class_items, kwargs_list)

Creates a chain of preprocessors.

deepcopy(self)

Returns a deep copy of current class.

fit(self, x[, y])

Fit normalization algorithm using data.

fit_transform(self, x[, y, caching])

Fit preprocessor using data and then transform data.

forward(self, x[, caching])

Apply the transformation algorithm on data.

get_class_from_type(class_type)

Return the class associated with input type.

get_params(self)

Returns the dictionary of class parameters.

get_subclasses()

Get all the subclasses of the calling class.

gradient(self, x[, y, w])

Returns the normalizer gradient wrt data.

inverse_transform(self, x)

Revert data to original form.

is_linear(self)

Returns True for linear normalizers.

list_class_types()

This method lists all types of available subclasses of calling one.

load(path)

Loads class from pickle object.

save(self, path)

Save class object using pickle.

set(self, param_name, param_value[, copy])

Set a parameter that has a specific name to a specific value.

set_params(self, params_dict[, copy])

Set all parameters passed as a dictionary {key: value}.

timed([msg])

Timer decorator.

transform(self, x[, caching])

Apply the transformation algorithm on data.

fit(self, x, y=None)[source]

Fit normalization algorithm using data.

This fit function is just a placeholder and simply returns the normalizer itself.

Parameters
xCArray

Array to be used for training normalization algorithm. Shape of input array depends on the algorithm itself.

yCArray or None, optional

Flat array with the label of each pattern. Not Used.

Returns
CNormalizer

Instance of the trained normalizer.

gradient(self, x, y=None, w=None)[source]

Returns the normalizer gradient wrt data.

Parameters
xCArray

Data array, 2-Dimensional or ravel.

yint or None, optional

Index of the class wrt the gradient must be computed. This could be not required if w is passed.

wCArray or None, optional

If CArray, will be passed to backward in the net and must have a proper shape depending on the chosen output layer.

Returns
gradientCArray

Gradient of the normalizer wrt input data. Vector-like array.

property net

The DNN.

transform(self, x, caching=False)[source]

Apply the transformation algorithm on data.

This extracts the deepfeatures at the specified layer of the DNN.

Parameters
xCArray

Array to be transformed.

Returns
CArray

Deepfeatures at the specified DNN layer. Shape depends on the neural network layer shape.