# lightonml.encoding¶

## lightonml.encoding.base¶

### Encoders¶

These modules contains implementations of Encoders that can transform data in the binary uint8 format required by the OPU. Compatible with numpy.ndarray and torch.Tensor.

class BaseTransformer[source]

Bases: object

Base class for all basic encoders and decoders. Mainly for avoiding empty fit methods and provide an automatic fit_transform method.

fit(X, y=None)[source]

No-op, exists for compatibility with the scikit-learn API.

Parameters
• X – 2D np.ndarray or torch.Tensor

• y – 1D np.ndarray or torch.Tensor

Returns

Encoder object

transform(X)[source]

Function to encode or decode an array X.

Parameters

X – 2D np.ndarray or torch.Tensor

Returns

2D np.ndarray or torch.Tensor of uint8

class BinaryThresholdEncoder(threshold_enc='auto', greater_is_one=True)[source]

Implements binary encoding using a threshold function.

Parameters
• threshold_enc (int or str) – Threshold for the binary encoder. Default 0. ‘auto’ will set threshold_enc to feature-wise median of the data passed to the fit function.

• greater_is_one (bool) – If True, above threshold is 1 and below 0. Vice versa if False.

threshold_enc

Threshold for the binary encoder.

Type

int or str

greater_is_one

If True, above threshold is 1 and below 0. Vice versa if False.

Type

bool

fit(X, y=None)[source]

When threshold_enc is ‘auto’, this method sets it to a vector containing the median of each column of X. Otherwise, it does nothing except print a warning in case threshold_enc is not in the range covered by X.

Parameters
• X (np.ndarray,) – the input data to encode.

• y (np.ndarray,) – the targets data.

Returns

self

Return type

BinaryThresholdEncoding

transform(X)[source]

Transforms any numpy array in a uint8 binary array of [0, 1].

Parameters

X (np.ndarray or torch.Tensor) – the input data to encode.

Returns

X_enc – uint8 containing only zeros and ones the encoded data.

Return type

np.ndarray or torch.Tensor

class ConcatenatedBitPlanEncoder(n_bits=8, starting_bit=0)[source]

Implements an encoding that works by concatenating bitplanes along the feature dimension.

n_bits + starting_bit must be lower than the bitwidth of data that are going to be fed to the encoder. E.g. if X.dtype is uint8, then n_bits + starting_bit must be lower than 8. If instead X.dtype is uint32, then n_bits + starting_bit must be lower than 32.

Read more in the Examples section.

Parameters
• n_bits (int, defaults to 8,) – number of bits to keep during the encoding. Must be positive.

• starting_bit (int, defaults to 0,) – bit used to start the encoding, previous bits will be thrown away. Must be positive.

n_bits

number of bits to keep during the encoding.

Type

int,

starting_bit

bit used to start the encoding, previous bits will be thrown away.

Type

int,

transform(X)[source]

Performs the encoding.

Parameters

X (2D np.ndarray of uint8, 16, 32 or 64 [n_samples, n_features],) – input data to encode.

Returns

X_enc – encoded input data. A line is arranged as [bits_for_first_feature, …, bits_for_last_feature].

Return type

2D np.ndarray of uint8 [n_samples, n_features*n_bits]

class ConcatenatedFloat32Encoder(sign_bit=True, exp_bits=8, mantissa_bits=23)[source]

Implements an encoding that works by concatenating bitplanes and selecting how many bits to keep for sign, mantissa and exponent of the float32.

Parameters
• sign_bit (bool, defaults to True,) – if True keeps the bit for the sign.

• exp_bits (int, defaults to 8,) – number of bits of the exponent to keep.

• mantissa_bits (int, defaults to 23,) – number of bits of the mantissa to keep.

sign_bit

if True keeps the bit for the sign.

Type

bool, defaults to True,

exp_bits

number of bits of the exponent to keep.

Type

int, defaults to 8,

mantissa_bits

number of bits of the mantissa to keep.

Type

int, defaults to 23,

n_bits

total number of bits to keep.

Type

int,

indices

list of the indices of the bits to keep.

Type

list,

transform(X)[source]

Performs the encoding.

Parameters

X (2D np.ndarray of float32 [n_samples, n_features],) – input data to encode.

Returns

X_enc – encoded input data.

Return type

2D np.ndarray of uint8 [n_samples*n_bits, n_features],

class ConcatenatingBitPlanDecoder(n_bits=8, decoding_decay=0.5)[source]

Implements a decoding that works by concatenating bitplanes.

n_bits MUST be the same value used in SeparatedBitPlanEncoder. Read more in the Examples section.

Parameters
• n_bits (int, defaults to 8,) – number of bits used during the encoding.

• decoding_decay (float, defaults to 0.5,) – decay to apply to the bits during the decoding.

n_bits

number of bits used during the encoding.

Type

int,

decoding_decay

decay to apply to the bits during the decoding.

Type

float, defaults to 0.5,

transform(X)[source]

Performs the decoding.

Parameters

X (2D np.ndarray of uint8 or uint16,) – input data to decode.

Returns

X_dec – decoded data.

Return type

2D np.ndarray of floats

class Float32Encoder(sign_bit=True, exp_bits=8, mantissa_bits=23)[source]

Implements an encoding that works by separating bitplans and selecting how many bits to keep for sign, mantissa and exponent of the float32.

Parameters
• sign_bit (bool, defaults to True,) – if True keeps the bit for the sign.

• exp_bits (int, defaults to 8,) – number of bits of the exponent to keep.

• mantissa_bits (int, defaults to 23,) – number of bits of the mantissa to keep.

sign_bit

if True keeps the bit for the sign.

Type

bool, defaults to True,

exp_bits

number of bits of the exponent to keep.

Type

int, defaults to 8,

mantissa_bits

number of bits of the mantissa to keep.

Type

int, defaults to 23,

n_bits

total number of bits to keep.

Type

int,

indices

list of the indices of the bits to keep.

Type

list,

transform(X)[source]

Performs the encoding.

Parameters

X (2D np.ndarray of float32 [n_samples, n_features],) – input data to encode.

Returns

X_enc – encoded input data.

Return type

2D np.ndarray of uint8 [n_samples*n_bits, n_features],

class MultiThresholdEncoder(thresholds='linspace', n_bins=8, columnwise=False)[source]

Implements binary encoding using multiple thresholds.

Parameters
• thresholds (list, np.ndarray or str) – thresholds for the binary encoder. If a list or an array is passed, the thresholds will be used unmodified. If thresholds=’linspace’, the values will be evenly distributed along the data range. If thresholds=’quantile’, the values will be set to the quantiles corresponding to n_bins. If n_bins=4, the thresholds will be the 1st, 2nd and 3rd quartiles.

• columnwise (bool,) – whether to use different thresholds for each column or a common set of thresholds for everything.

• n_bins (int,) – if thresholds is ‘linspace’ or ‘quantiles’, n_bins - 1 thresholds will be created?

thresholds

thresholds for the binary encoder.

Type

np.ndarray,

columnwise

whether to use different thresholds for each column or a common set of thresholds for everything.

Type

bool,

n_bins

number of different values the encoding can take. A value is encoded into n_bins-1 bits.

Type

int,

fit(X, y=None)[source]

If thresholds is not None, this method doesn’t do anything. If thresholds is None, computes n_bins thresholds equally spaced on the range of X. The range of X is determined column-wise but the number of bins is the same for all features.

Parameters
• X (2D np.ndarray) –

• y (1D np.ndarray) –

Returns

self

Return type

MultiThresholdEncoder

transform(X)[source]

Transforms an array to a uint8 binary array of [0, 1].

The bins defined by the thresholds are not mutually exclusive, i.e a value x will activate all the bins corresponding to thresholds lesser than x.

Parameters

X (np.ndarray of size n_sample x n_features) – The input data to encode.

Returns

X_enc – The encoded data.

Return type

np.ndarray of uint8, of size n_samples x (n_features x n_bins)

class NoDecoding[source]

Implements a No-Op Decoding class for API consistency.

transform(X)[source]

Function to encode or decode an array X.

Parameters

X – 2D np.ndarray or torch.Tensor

Returns

2D np.ndarray or torch.Tensor of uint8

class NoEncoding[source]

Implements a No-Op Encoding class for API consistency.

transform(X)[source]

Function to encode or decode an array X.

Parameters

X – 2D np.ndarray or torch.Tensor

Returns

2D np.ndarray or torch.Tensor of uint8

class SeparatedBitPlanDecoder(precision, magnitude_p=1, magnitude_n=0, decoding_decay=0.5)[source]
transform(X)[source]

Function to encode or decode an array X.

Parameters

X – 2D np.ndarray or torch.Tensor

Returns

2D np.ndarray or torch.Tensor of uint8

class SeparatedBitPlanEncoder(precision=6, **kwargs)[source]

Implements an encoder for floating point input

Parameters

precision (int, optional) – The number of binary projections that are preformed to reconstruct an unsigned floating point projection. if the input contains both positive and negative values, the total number of projections is 2*precision

Returns

X_bits

Return type

np.array(dtype = np.unit8)

get_params()[source]

internal information necessary to undo the transformation, must be passed to the SeparatedBitPlanDecoder init.

transform(X)[source]

Function to encode or decode an array X.

Parameters

X – 2D np.ndarray or torch.Tensor

Returns

2D np.ndarray or torch.Tensor of uint8

class SequentialBaseTwoEncoder(n_gray_levels=16)[source]

Implements a base 2 encoding.

E.g. $$5$$ is written $$101$$ in base 2: $$1 * 2^2 + 0 * 2^1 + 1 * 2^0$$ = (1)*4 +(0)*2 +(1)*1, so the encoder will give 1111001.

Parameters

n_gray_levels (int,) – number of values that can be encoded. Must be a power of 2.

n_gray_levels

number of values that can be encoded. Must be a power of 2.

Type

int,

n_bits

number of bits needed to encode n_gray_levels values.

Type

int,

offset

value to subtract to get the minimum to 0.

Type
scale

scaling factor to normalize the data.

Type
fit(X, y=None)[source]

Computes parameters for the normalization.

Must be run only on the training set to avoid leaking information to the dev/test set.

Parameters
• X (np.ndarray of uint [n_samples, n_features],) – the input data to encode.

• y (np.ndarray,) – the targets data.

Returns

self

Return type

SequentialBaseTwoEncoder.

normalize(X)[source]

Normalize the data in the right range before the integer casting.

Parameters

X (np.ndarray of uint [n_samples, n_features],) – the input data to normalize.

Returns

X_norm – normalized data.

Return type

np.ndarray of uint8 [n_samples, n_features],

transform(X)[source]

Performs the encoding.

Parameters

X (2D np.ndarray of uint [n_samples, n_features],) – input data to encode.

Returns

X_enc – encoded input data.

Return type

2D np.ndarray of uint8 [n_samples, n_features*(n_gray_levels-1)

## lightonml.encoding.models¶

class AE(*args: Any, **kwargs: Any)[source]

Bases: torch.nn.

class ConvAE(*args: Any, **kwargs: Any)[source]

Bases: torch.nn.

Autoencoder consisting of two convolutional layers (encoder, decoder).

Parameters
• in_ch (int,) – number of input channels

• out_ch (int,) – number of output channels

• kernel_size (int or tuple,) – size of the convolutional filters

• beta (float, default 1.,) – inverse temperature for tanh(beta x)

• stride (int or tuple, optional, default 1,) – stride of the convolution

• padding (int or tuple, optional, default 0,) – zero-padding added to both sides of the input

• padding_mode (str, optional, default 'zeros',) – ‘zeros’ or ‘circular’

• dilation (int or tuple, optional, default 1,) – spacing between kernel elements

• groups (int, optional, default 1,) – number of blocked connections from input to output channels

• bias (bool, optional, default True,) – adds a learnable bias to the output.

• flatten (bool, default False,) – whether to return a 2D flattened array (batch_size, x) or a 4D (batch_size, out_ch, out_h, out_w) when encoding

encoder

encoding layer

Type

nn.Conv2d,

decoder

decoding layer

Type

nn.TransposeConv2d,

beta

inverse temperature for tanh(beta x)

Type
flatten

whether to return a 2D flattened array (batch_size, x) or a 4D (batch_size, out_ch, out_h, out_w) when encoding

Type

bool, default False,

forward(input)[source]

Returns the reconstructed input or the binary code, depending on self.training. Call eval() on the module for the binary code, train() for the reconstruction.

Parameters

input (torch.Tensor,) – tensor holding the input data

Returns

• rec (torch.Tensor float,) – if self.training=True returns the reconstruction of the input

• binary_code (torch.Tensor uint8,) – tensor holding the binary code if self.training=False.

class EncoderDecoder(*args: Any, **kwargs: Any)[source]

Bases: torch.nn.

Autoencoder consisting of two dense layers (encoder, decoder). The decoder weights are the transpose of the encoder ones. Backpropagation updates the decoder, in this way the encoder is also updated despite the non-differentiable non-linearity. Architecture from Tissier et al. (https://arxiv.org/abs/1803.09065).

Parameters
• input_size (int,) – size of the input

• hidden_size (int,) – size of the hidden layer

proj

encoding-decoding layer

Type

nn.Linear,

forward(input)[source]

Returns the reconstructed input or the binary code, depending on self.training. Call eval() on the module for the binary code, train() for the reconstruction.

Parameters

input (torch.Tensor,) – tensor holding the input data

Returns

• rec (torch.Tensor float,) – if self.training=True returns the reconstruction of the input

• binary_code (torch.Tensor uint8,) – tensor holding the binary code if self.training=False.

class LinearAE(*args: Any, **kwargs: Any)[source]

Bases: torch.nn.

Autoencoder consisting of two dense layers (encoder, decoder). The autoencoder learns to produce a binary output starting from tanh(beta x)/beta with beta=1 and gradually increasing beta to resemble a step function

Parameters
• input_size (int,) – size of the input

• hidden_size (int,) – size of the hidden layer

• beta (float, default 1.,) – inverse temperature for tanh(beta x)

encoder

encoding layer

Type

nn.Linear,

decoder

decoding layer

Type

nn.Linear,

beta

inverse temperature for tanh(beta x)

Type
forward(input)[source]

Returns the reconstructed input or the binary code, depending on self.training. Call eval() on the module for the binary code, train() for the reconstruction.

Parameters

input (torch.Tensor,) – tensor holding the input data

Returns

• rec (torch.Tensor float,) – if self.training=True returns the reconstruction of the input

• binary_code (torch.Tensor uint8,) – tensor holding the binary code if self.training=False.

train(model, dataloader, optimizer, criterion=torch.nn.functional.mse_loss, epochs=10, beta_interval=5, device=None, verbose=True)[source]

Utility function to train autoencoders quickly.

Parameters
• model (nn.Module,) – autoencoder to trained

• optimizer (torch.optim.Optimizer,) – optimizer used to perform the training

• criterion (callable, default torch.nn.functional.mse_loss) – loss function for training

• epochs (int, default 10,) – number of epochs of training

• beta_interval (int, default 5,) – interval in epochs for beta increase by factor 10

• device (str, 'cpu' or 'cuda:{idx}') – device used to perform the training.

• verbose (bool, default True,) – whether to print info on the training

Returns

model – trained model

Return type

nn.Module,