Databases

Introduction

The python library integrates pre-defined modules for several well-known database used in the deep learning community, such as MNIST, GTSRB, CIFAR10 and so on. That way, no extra step is necessary to be able to directly build a network and learn it on these database. The library allow you to add pre-process data with built in Transformation.

Database

The python library provide you with multiple object to manipulate common database.

Loading hand made database can be done using n2d2.database.DIR.

Like in the following example :

# Creating the database object
db = n2d2.database.DIR()

provider = n2d2.provider.DataProvider(db, data_dims)

# The zeroes represent the depth to seek the data.
db.load(data_path, 0, label_path, 0)

# With this line we put all the data in the learn partition:
db.partition_stimuli(learn=1, validation=0, test=0)
provider.set_partition("Learn")

inputs_tensor = provider.read_random_batch()

DIR

Loading a custom database

Hand made database stored in files directories are directly supported with the DIR_Database module. For example, suppose your database is organized as following :

  • GST/airplanes: 800 images

  • GST/car_side: 123 images

  • GST/Faces: 435 images

  • GST/Motorbikes: 798 images

You can then instanciate this database as input of your neural network using the following line:

database = n2d2.database.DIR("./GST", learn=0.4, validation=0.2)

Each subdirectory will be treated as a different label, so there will be 4 different labels, named after the directory name.

The stimuli are equi-partitioned for the learning set and the validation set, meaning that the same number of stimuli for each category is used. If the learn fraction is 0.4 and the validation fraction is 0.2, as in the example above, the partitioning will be the following:

Label ID

Label name

Learn set

Validation set

Test set

[0.5ex] 0

airplanes

49

25

726

1

car_side

49

25

49

2

Faces

49

25

361

3

Motorbikes

49

25

724

Total:

196

100

1860

Note

If equiv_label_partitioning is 1 (default setting), the number of stimuli per label that will be partitioned in the learn and validation sets will correspond to the number of stimuli from the label with the fewest stimuli.

To load and partition more than one DataPath, one can use the n2d2.database.Database.load() method.

This method will load data in the partition Unpartitionned, you can move the stimuli in the Learn, Validation or Test partition using the n2d2.database.Database.partition_stimuli() method.

Handling labelization

By default, your labels will be ordered by alphabetical order. If you need your label to be in a specific order, you can specify it using an exterior file we will name it label.dat for this example :

airplanes 0
car_side 1
Motorbikes 3
Faces 2

Then to load the database we will use :

database = n2d2.database.DIR("./GST", learn=0.4, validation=0.2, label_path="./label.dat", label_depth=0)

Warning

It is important to specify label_depth=0 if you are specifying label_path !

class n2d2.database.DIR(data_path, learn, test=None, validation=0.0, depth=1, label_path='', label_depth=1, roi_file='', roi_dir='', roi_extension='json', per_label_partitioning=True, equiv_label_partitioning=True, ignore_mask=None, valid_extensions=None, **config_parameters)

Allow you to load your own database.

N2D2()

Return the N2D2 object.

__init__(data_path, learn, test=None, validation=0.0, depth=1, label_path='', label_depth=1, roi_file='', roi_dir='', roi_extension='json', per_label_partitioning=True, equiv_label_partitioning=True, ignore_mask=None, valid_extensions=None, **config_parameters)
Parameters:

  • data_path (str) – Path to the dataset file.

  • learn (float) – If per_label_partitioning is True, fraction of images used for the learning; else, number of images used for the learning, regardless of their labels

  • test (float, optional) – If per_label_partitioning is True, fraction of images used for the test; else, number of images used for the test, regardless of their labels, default= [1.0-Learn-Validation]

  • validation (float, optional) – If per_label_partitioning is True, fraction of images used for the validation; else, number of images used for the validation, regardless of their labels, default=0.0

  • depth (int, optional) – Number of sub-directory levels to include, defaults=1

  • label_path (str, optional) – Path to the label file, if not empty label_path should be set to 0, defaults=””

  • label_depth (int, optional) – Number of sub-directory name levels used to form the data labels, defaults=1

  • roi_file (str, optional) – File containing the stimuli ROIs. If a ROI file is specified, label_depth should be set to -1, default=””

  • roi_dir (str, optional) – Directory containing the stimuli ROIs, default=””

  • roi_extension (str, optional) – Extension of the ROI files (used only if roi_dir is specified) , default=”json”

  • per_label_partitioning (bool, optional) – If True, the Learn, Validation and Test parameters represent the fraction of the total stimuli to be partitioned in each set, instead of a number of stimuli, default=True

  • equiv_label_partitioning (bool, optional) – If True, the stimuli are equi-partitioned in the learn and validation sets, meaning that the same number of stimuli for each label is used (only when per_label_partitioning is True). The remaining stimuli are partitioned in the test set, default=True

  • ignore_mask (list, optional) – List of mask strings to ignore. If any is present in a file path, the file gets ignored. The usual * and + wildcards are allowed, default=[]

  • valid_extensions (list, optional) – List of valid stimulus file extensions (if left empty, any file extension is considered a valid stimulus), default=[]

  • load_data_in_memory (boolean, optional) – if True cache data in memory, default=False

classmethod download(path: str | None = None) → None

Download the dataset at the defined path

Parameters:

path (str, optional) – Path where to download the dataset, default=$(N2D2_DATA)

get_label_name(label_idx)
Parameters:

label_idx (int) – Index of the label

Returns:

Label name

Return type:

string

get_nb_stimuli(partition)

Return the number fo stimuli available for this partition

Parameters:

partition (str) – The partition can be Learn, Validation, Test, Unpartitioned

get_parameter(key)
Parameters:

key (str) – Parameter name

get_partition_summary()

Print the number of stimuli for each partition.

classmethod is_downloadable() → bool
Returns:

True if the database is downloadable.

Return type:

bool

partition_stimuli(learn: float, validation: float, test: float)

Partition the Unpartitioned data with the given ratio (the sum of the given ratio must be equal to 1).

Parameters:

  • learn (float) – Ratio for the Learn partition.

  • validation (float) – Ratio for the Validation partition.

  • test (float) – Ratio for the Test partition.

Numpy

The n2d2.database.Numpy allows to create a database using Numpy array. This can be especially usefull if you already have a dataloader written in Python.

Note

The labels are optional, this can be usefull if you have previously trained your model and only need data to calibrate you model using the n2d2.quantizer.PTQ() function.

Usage example

import n2d2
import numpy as np

db = n2d2.database.Numpy()
db.load([
        np.ones([1,2,3]),
        np.zeros([1,2,3]),
        np.ones([1,2,3]),
        np.zeros([1,2,3]),
],
[
        0,
        1,
        0,
        1
])
db.partition_stimuli(1., 0., 0.) # Learn Validation Test

provider = n2d2.provider.DataProvider(db, [3, 2, 1], batch_size=2)
provider.set_partition("Learn")
print("First stimuli :")
print(next(provider))
class n2d2.database.Numpy(**config_parameters)

Numpy database, creates a database from Numpy Array.

N2D2()

Return the N2D2 object.

__init__(**config_parameters)
Parameters:

load_data_in_memory (boolean, optional) – if True cache data in memory, default=False

classmethod download(path: str | None = None) → None

Download the dataset at the defined path

Parameters:

path (str, optional) – Path where to download the dataset, default=$(N2D2_DATA)

get_label_name(label_idx)
Parameters:

label_idx (int) – Index of the label

Returns:

Label name

Return type:

string

get_nb_stimuli(partition)

Return the number fo stimuli available for this partition

Parameters:

partition (str) – The partition can be Learn, Validation, Test, Unpartitioned

get_parameter(key)
Parameters:

key (str) – Parameter name

get_partition_summary()

Print the number of stimuli for each partition.

classmethod is_downloadable() → bool
Returns:

True if the database is downloadable.

Return type:

bool

load(stimuli_list: List[ndarray], labels_list: List[int] | None = None, partition: str | None = None, channels_first: bool = True)

Load numpy array as input and int as labels. By default, the loaded stimuli are stored in the Unpartitioned partition. At the moment only integers labels are supported. If label_list is not filled, all labels are set to 0.

Parameters:

  • stimuli_list (List[ndarray]) – List of stimulus, stimulus must respect the format [C, H, W], if channel_first is False the format is [H, W, C].

  • labels_list (List[int], optional) – List of label, if None, every label are set to 0, default=None

  • partition (str, optional) – The partition can be Learn, Validation, Test, Unpartitioned, by default data are stored in the``Unpartitioned`` partition (see n2d2.database.numpy.partition_stimuli()) , default=None

  • channels_first (bool, optional) – If True, the stimuli format is [C, H, W], else [H, W, C], default=True

partition_stimuli(learn: float, validation: float, test: float)

Partition the Unpartitioned data with the given ratio (the sum of the given ratio must be equal to 1).

Parameters:

  • learn (float) – Ratio for the Learn partition.

  • validation (float) – Ratio for the Validation partition.

  • test (float) – Ratio for the Test partition.

MNIST

class n2d2.database.MNIST(data_path, **config_parameters)

MNIST database [LBBH98]. Label are hard coded, you don’t need to specify a path to the label file.

N2D2()

Return the N2D2 object.

__init__(data_path, **config_parameters)
Parameters:

  • data_path (str) – Path to the database

  • label_path (str, optional) – Path to the label, default=””

  • extract_roi (boolean, optional) – Set if we extract region of interest, default=False

  • validation (float, optional) – Fraction of the learning set used for validation, default=0.0

  • load_data_in_memory (boolean, optional) – if True cache data in memory, default=False

classmethod download(path: str | None = None) → None

Download the dataset at the defined path

Parameters:

path (str, optional) – Path where to download the dataset, default=$(N2D2_DATA)

get_label_name(label_idx)
Parameters:

label_idx (int) – Index of the label

Returns:

Label name

Return type:

string

get_nb_stimuli(partition)

Return the number fo stimuli available for this partition

Parameters:

partition (str) – The partition can be Learn, Validation, Test, Unpartitioned

get_parameter(key)
Parameters:

key (str) – Parameter name

get_partition_summary()

Print the number of stimuli for each partition.

classmethod is_downloadable() → bool
Returns:

True if the database is downloadable.

Return type:

bool

partition_stimuli(learn: float, validation: float, test: float)

Partition the Unpartitioned data with the given ratio (the sum of the given ratio must be equal to 1).

Parameters:

  • learn (float) – Ratio for the Learn partition.

  • validation (float) – Ratio for the Validation partition.

  • test (float) – Ratio for the Test partition.

ILSVRC2012

class n2d2.database.ILSVRC2012(learn, **config_parameters)

ILSVRC2012 database [RDS+15].

N2D2()

Return the N2D2 object.

__init__(learn, **config_parameters)
Parameters:

  • learn (float) – Fraction of images used for the learning

  • use_validation_for_test (bool, optional) – If True, use the validation partition for test, default=False

  • load_data_in_memory (boolean, optional) – if True cache data in memory, default=False

classmethod download(path: str | None = None) → None

Download the dataset at the defined path

Parameters:

path (str, optional) – Path where to download the dataset, default=$(N2D2_DATA)

get_label_name(label_idx)
Parameters:

label_idx (int) – Index of the label

Returns:

Label name

Return type:

string

get_nb_stimuli(partition)

Return the number fo stimuli available for this partition

Parameters:

partition (str) – The partition can be Learn, Validation, Test, Unpartitioned

get_parameter(key)
Parameters:

key (str) – Parameter name

get_partition_summary()

Print the number of stimuli for each partition.

classmethod is_downloadable() → bool
Returns:

True if the database is downloadable.

Return type:

bool

partition_stimuli(learn: float, validation: float, test: float)

Partition the Unpartitioned data with the given ratio (the sum of the given ratio must be equal to 1).

Parameters:

  • learn (float) – Ratio for the Learn partition.

  • validation (float) – Ratio for the Validation partition.

  • test (float) – Ratio for the Test partition.

CIFAR10

class n2d2.database.CIFAR10(**config_parameters)

CIFAR10 database [Kri09].

N2D2()

Return the N2D2 object.

__init__(**config_parameters)
Parameters:

  • data_path (str, optional) – Path to the database, default=”$N2D2_DATA/cifar-10-binary”

  • validation (float, optional) – Fraction of the learning set used for validation, default=0.0

  • load_data_in_memory (boolean, optional) – if True cache data in memory, default=False

classmethod download(path: str | None = None) → None

Download the dataset at the defined path

Parameters:

path (str, optional) – Path where to download the dataset, default=$(N2D2_DATA)

get_label_name(label_idx)
Parameters:

label_idx (int) – Index of the label

Returns:

Label name

Return type:

string

get_nb_stimuli(partition)

Return the number fo stimuli available for this partition

Parameters:

partition (str) – The partition can be Learn, Validation, Test, Unpartitioned

get_parameter(key)
Parameters:

key (str) – Parameter name

get_partition_summary()

Print the number of stimuli for each partition.

classmethod is_downloadable() → bool
Returns:

True if the database is downloadable.

Return type:

bool

partition_stimuli(learn: float, validation: float, test: float)

Partition the Unpartitioned data with the given ratio (the sum of the given ratio must be equal to 1).

Parameters:

  • learn (float) – Ratio for the Learn partition.

  • validation (float) – Ratio for the Validation partition.

  • test (float) – Ratio for the Test partition.

CIFAR100

class n2d2.database.CIFAR100(**config_parameters)

CIFAR100 database [Kri09].

N2D2()

Return the N2D2 object.

__init__(**config_parameters)
Parameters:

  • data_path (str, optional) – Path to the database, default=”$N2D2_DATA/cifar-100-binary”

  • validation (float, optional) – Fraction of the learning set used for validation, default=0.0

  • use_coarse (bool, optional) – If True, use the coarse labeling (10 labels instead of 100), default=False

  • load_data_in_memory (boolean, optional) – if True cache data in memory, default=False

classmethod download(path: str | None = None) → None

Download the dataset at the defined path

Parameters:

path (str, optional) – Path where to download the dataset, default=$(N2D2_DATA)

get_label_name(label_idx)
Parameters:

label_idx (int) – Index of the label

Returns:

Label name

Return type:

string

get_nb_stimuli(partition)

Return the number fo stimuli available for this partition

Parameters:

partition (str) – The partition can be Learn, Validation, Test, Unpartitioned

get_parameter(key)
Parameters:

key (str) – Parameter name

get_partition_summary()

Print the number of stimuli for each partition.

classmethod is_downloadable() → bool
Returns:

True if the database is downloadable.

Return type:

bool

partition_stimuli(learn: float, validation: float, test: float)

Partition the Unpartitioned data with the given ratio (the sum of the given ratio must be equal to 1).

Parameters:

  • learn (float) – Ratio for the Learn partition.

  • validation (float) – Ratio for the Validation partition.

  • test (float) – Ratio for the Test partition.

Cityscapes

class n2d2.database.Cityscapes(**config_parameters)

Cityscapes database [COR+16].

Warning

Don’t forget to install the libjsoncpp-dev package on your device if you wish to use this database.

N2D2()

Return the N2D2 object.

__init__(**config_parameters)
Parameters:

  • inc_train_extra (boolean, optional) – If True, includes the left 8-bit images - trainextra set (19,998 images), default=False

  • use_coarse (boolean, optional) – If True, only use coarse annotations (which are the only annotations available for the trainextra set), default=False

  • single_instance_labels (boolean, optional) – If True, convert group labels to single instance labels (for example, cargroup becomes car), default=True

  • load_data_in_memory (boolean, optional) – if True cache data in memory, default=False

classmethod download(path: str | None = None) → None

Download the dataset at the defined path

Parameters:

path (str, optional) – Path where to download the dataset, default=$(N2D2_DATA)

get_label_name(label_idx)
Parameters:

label_idx (int) – Index of the label

Returns:

Label name

Return type:

string

get_nb_stimuli(partition)

Return the number fo stimuli available for this partition

Parameters:

partition (str) – The partition can be Learn, Validation, Test, Unpartitioned

get_parameter(key)
Parameters:

key (str) – Parameter name

get_partition_summary()

Print the number of stimuli for each partition.

classmethod is_downloadable() → bool
Returns:

True if the database is downloadable.

Return type:

bool

partition_stimuli(learn: float, validation: float, test: float)

Partition the Unpartitioned data with the given ratio (the sum of the given ratio must be equal to 1).

Parameters:

  • learn (float) – Ratio for the Learn partition.

  • validation (float) – Ratio for the Validation partition.

  • test (float) – Ratio for the Test partition.

GTSRB

class n2d2.database.GTSRB(validation, **config_parameters)

The German Traffic Sign Benchmark (https://benchmark.ini.rub.de/) is a multi-class, single-image classification challenge held at the International Joint Conference on Neural Networks (IJCNN) 2011.

N2D2()

Return the N2D2 object.

__init__(validation, **config_parameters)
Parameters:

  • validation (float) – Fraction of the learning set used for validation

  • load_data_in_memory (boolean, optional) – if True cache data in memory, default=False

classmethod download(path: str | None = None) → None

Download the dataset at the defined path

Parameters:

path (str, optional) – Path where to download the dataset, default=$(N2D2_DATA)

get_label_name(label_idx)
Parameters:

label_idx (int) – Index of the label

Returns:

Label name

Return type:

string

get_nb_stimuli(partition)

Return the number fo stimuli available for this partition

Parameters:

partition (str) – The partition can be Learn, Validation, Test, Unpartitioned

get_parameter(key)
Parameters:

key (str) – Parameter name

get_partition_summary()

Print the number of stimuli for each partition.

classmethod is_downloadable() → bool
Returns:

True if the database is downloadable.

Return type:

bool

partition_stimuli(learn: float, validation: float, test: float)

Partition the Unpartitioned data with the given ratio (the sum of the given ratio must be equal to 1).

Parameters:

  • learn (float) – Ratio for the Learn partition.

  • validation (float) – Ratio for the Validation partition.

  • test (float) – Ratio for the Test partition.

Transformations

class n2d2.transform.Transformation(**config_parameters)
N2D2()

Return the N2D2 object.

abstract __init__(**config_parameters)
Parameters:

apply_to (str, optional) – To which partition the transform is applied. One of: LearnOnly, ValidationOnly, TestOnly, NoLearn, NoValidation, NoTest, All, default=”All”

get_parameter(key)
Parameters:

key (str) – Parameter name

Composite

class n2d2.transform.Composite(transformations, **config_parameters)

A composition of transformations.

N2D2()

Return the N2D2 object.

__init__(transformations, **config_parameters)
Parameters:

  • transformations (list) – List of the transformations to use.

  • apply_to (str, optional) – To which partition the transform is applied. One of: LearnOnly, ValidationOnly, TestOnly, NoLearn, NoValidation, NoTest, All, default=”All”

get_parameter(key)
Parameters:

key (str) – Parameter name

get_transformations()

Return the list of transformations applied by the composite transformation

PadCrop

class n2d2.transform.PadCrop(width, height, **config_parameters)

Pad/crop the image to a specified size.

N2D2()

Return the N2D2 object.

__init__(width, height, **config_parameters)

Possible values for border_type parameter : ConstantBorder: pad with BorderValue, ReplicateBorder: last element is replicated throughout, like aaaaaa|abcdefgh|hhhhhhh, ReflectBorder: border will be mirror reflection of the border elements, like fedcba|abcdefgh|hgfedcb, WrapBorder: it will look like cdefgh|abcdefgh|abcdefg, MinusOneReflectBorder: same as ReflectBorder but with a slight change, like gfedcb|abcdefgh|gfedcba, MeanBorder: pad with the mean color of the image

Parameters:

  • width (int) – Width of the padded/cropped image

  • height (int) – height of the padded/cropped image

  • border_type (str, optional) – Border type used when padding, default=”MinusOneReflectBorder”

  • border_value (list, optional) – Background color used when padding with BorderType is ConstantBorder, default=[0.0, 0.0, 0.0]

  • apply_to (str, optional) – To which partition the transform is applied. One of: LearnOnly, ValidationOnly, TestOnly, NoLearn, NoValidation, NoTest, All, default=”All”

get_parameter(key)
Parameters:

key (str) – Parameter name

Distortion

class n2d2.transform.Distortion(**config_parameters)

Apply elastic distortion to the image. This transformation is generally used on-the-fly (so that a different distortion is performed for each image), and for the learning only.

N2D2()

Return the N2D2 object.

__init__(**config_parameters)
Parameters:

  • elastic_gaussian_size (int, optional) – Size of the gaussian for elastic distortion (in pixels), default=15

  • elastic_sigma (float, optional) – Sigma of the gaussian for elastic distortion, default=6.0

  • elastic_scaling (float, optional) – Scaling of the gaussian for elastic distortion, default=0.0

  • scaling (float, optional) – Maximum random scaling amplitude (+/-, in percentage), default=0.0

  • rotation (float, optional) – Maximum random rotation amplitude (+/-, in °), default=0.0

  • apply_to (str, optional) – To which partition the transform is applied. One of: LearnOnly, ValidationOnly, TestOnly, NoLearn, NoValidation, NoTest, All, default=”All”

get_parameter(key)
Parameters:

key (str) – Parameter name

Rescale

class n2d2.transform.Rescale(width, height, **config_parameters)

Rescale the image to a specified size.

N2D2()

Return the N2D2 object.

__init__(width, height, **config_parameters)
Parameters:

  • width (int) – Width of the rescaled image

  • height (int) – Height of the rescaled image

  • keep_aspect_ratio (bool, optional) – If true, keeps the aspect ratio of the image, default=False

  • resize_to_fit (bool, optional) – If true, resize along the longest dimension when KeepAspectRatio is true, default=True

  • apply_to (str, optional) – To which partition the transform is applied. One of: LearnOnly, ValidationOnly, TestOnly, NoLearn, NoValidation, NoTest, All, default=”All”

get_parameter(key)
Parameters:

key (str) – Parameter name

Reshape

class n2d2.transform.Reshape(nb_rows, **config_parameters)

Reshape the data to a specified size.

N2D2()

Return the N2D2 object.

__init__(nb_rows, **config_parameters)
Parameters:

  • nb_rows (int) – New number of rows

  • nb_cols (int, optional) – New number of cols (0 = no check), default=0

  • nb_channels (int, optional) – New number of channels (0 = no change), default=0

  • apply_to (str, optional) – To which partition the transform is applied. One of: LearnOnly, ValidationOnly, TestOnly, NoLearn, NoValidation, NoTest, All, default=”All”

get_parameter(key)
Parameters:

key (str) – Parameter name

ColorSpace

class n2d2.transform.ColorSpace(color_space, **config_parameters)
N2D2()

Return the N2D2 object.

__init__(color_space, **config_parameters)

Possible values for color_space parameter :

  • BGR: convert any gray, BGR or BGRA image to BGR,

  • RGB: convert any gray, BGR or BGRA image to RGB,

  • HSV: convert BGR image to HSV,

  • HLS: convert BGR image to HLS,

  • YCrCb: convert BGR image to YCrCb,

  • CIELab: convert BGR image to CIELab,

  • CIELuv: convert BGR image to CIELuv,

  • RGB_to_BGR: convert RGB image to BGR,

  • RGB_to_HSV: convert RGB image to HSV,

  • RGB_to_HLS: convert RGB image to HLS,

  • RGB_to_YCrCb: convert RGB image to YCrCb,

  • RGB_to_CIELab: convert RGB image to CIELab,

  • RGB_to_CIELuv: convert RGB image to CIELuv,

  • HSV_to_BGR: convert HSV image to BGR,

  • HSV_to_RGB: convert HSV image to RGB,

  • HLS_to_BGR: convert HLS image to BGR,

  • HLS_to_RGB: convert HLS image to RGB,

  • YCrCb_to_BGR: convert YCrCb image to BGR,

  • YCrCb_to_RGB: convert YCrCb image to RGB,

  • CIELab_to_BGR: convert CIELab image to BGR,

  • CIELab_to_RGB: convert CIELab image to RGB,

  • CIELuv_to_BGR: convert CIELuv image to BGR,

  • CIELuv_to_RGB: convert CIELuv image to RGB.

Parameters:

  • color_space (str) – Convert image color.

  • apply_to (str, optional) – To which partition the transform is applied. One of: LearnOnly, ValidationOnly, TestOnly, NoLearn, NoValidation, NoTest, All, default=”All”

get_parameter(key)
Parameters:

key (str) – Parameter name

Flip

class n2d2.transform.Flip(**config_parameters)

Image flip transformation.

N2D2()

Return the N2D2 object.

__init__(**config_parameters)
Parameters:

  • horizontal_flip (bool, optional) – If true, flip the image horizontally, default=False

  • vertical_flip (bool, optional) – If true, flip the image vertically, default=False

  • random_horizontal_flip (bool, optional) – If true, randomly flip the image horizontally, default=False

  • random_vertical_flip (bool, optional) – If true, randomly flip the image vertically, default=False

  • apply_to (str, optional) – To which partition the transform is applied. One of: LearnOnly, ValidationOnly, TestOnly, NoLearn, NoValidation, NoTest, All, default=”All”

get_parameter(key)
Parameters:

key (str) – Parameter name

RangeAffine

class n2d2.transform.RangeAffine(first_operator, first_value, **config_parameters)

Apply an affine transformation to the values of the image.

N2D2()

Return the N2D2 object.

__init__(first_operator, first_value, **config_parameters)
Parameters:

  • first_operator (str) – First operator, can be Plus, Minus, Multiplies, Divides

  • first_value (float) – First value

  • second_operator (str, optional) – Second operator, can be Plus, Minus, Multiplies, Divides, default=”Plus”

  • second_value (float, optional) – Second value, default=0.0

  • apply_to (str, optional) – To which partition the transform is applied. One of: LearnOnly, ValidationOnly, TestOnly, NoLearn, NoValidation, NoTest, All, default=”All”

get_parameter(key)
Parameters:

key (str) – Parameter name

SliceExtraction

class n2d2.transform.SliceExtraction(width, height, **config_parameters)

Extract a slice from an image.

N2D2()

Return the N2D2 object.

__init__(width, height, **config_parameters)

Possible values for border_type ConstantBorder: pad with BorderValue, ReplicateBorder: last element is replicated throughout, like aaaaaa|abcdefgh|hhhhhhh, ReflectBorder: border will be mirror reflection of the border elements, like fedcba|abcdefgh|hgfedcb, WrapBorder: it will look like cdefgh|abcdefgh|abcdefg, MinusOneReflectBorder: same as ReflectBorder but with a slight change, like gfedcb|abcdefgh|gfedcba, MeanBorder: pad with the mean color of the image

Parameters:

  • width (int) – Width of the slice to extract

  • height (int) – Height of the slice to extract

  • offset_x (int, optional) – X offset of the slice to extract, default=0

  • offset_y (int, optional) – Y offset of the slice to extract, default=0

  • random_offset_x (bool, optional) – If true, the X offset is chosen randomly, default=False

  • random_offset_y (bool, optional) – If true, the Y offset is chosen randomly, default=False

  • random_rotation (bool, optional) – If true, extract randomly rotated slices, default=False

  • random_rotation_range (list, optional) – Range of the random rotations, in degrees, counterclockwise (if RandomRotation is enabled), default=[0.0, 360.0]

  • random_scaling (bool, optional) – If true, extract randomly scaled slices, default=False

  • random_scaling_range (list, optional) – Range of the random scaling (if RandomRotation is enabled), default=[0.8, 1.2]

  • allow_padding (bool, optional) – If true, zero-padding is allowed if the image is smaller than the slice to extract, default=False

  • border_type (str, optional) – Border type used when padding, default=”MinusOneReflectBorder”

  • apply_to (str, optional) – To which partition the transform is applied. One of: LearnOnly, ValidationOnly, TestOnly, NoLearn, NoValidation, NoTest, All, default=”All”

get_parameter(key)
Parameters:

key (str) – Parameter name

RandomResizeCrop

class n2d2.transform.RandomResizeCrop(width, height, **config_parameters)
N2D2()

Return the N2D2 object.

__init__(width, height, **config_parameters)
Parameters:

  • width (int) – Width of the image to Crop.

  • height (int) – Height of the image to Crop.

  • apply_to (str, optional) – To which partition the transform is applied. One of: LearnOnly, ValidationOnly, TestOnly, NoLearn, NoValidation, NoTest, All, default=”All”

get_parameter(key)
Parameters:

key (str) – Parameter name

ChannelExtraction

class n2d2.transform.ChannelExtraction(channel, **config_parameters)

Extract an image channel.

N2D2()

Return the N2D2 object.

__init__(channel, **config_parameters)

The channel parameter can take the following values : Blue: blue channel in the BGR colorspace, or first channel of any colorspace, Green: green channel in the BGR colorspace, or second channel of any colorspace, Red: red channel in the BGR colorspace, or third channel of any colorspace, Hue: hue channel in the HSV colorspace, Saturation: saturation channel in the HSV colorspace, Value: value channel in the HSV colorspace, Gray: gray conversion, Y: Y channel in the YCbCr colorspace, Cb: Cb channel in the YCbCr colorspace, Cr: Cr channel in the YCbCr colorspace

Parameters:

  • channel (str) – channel to extract

  • apply_to (str, optional) – To which partition the transform is applied. One of: LearnOnly, ValidationOnly, TestOnly, NoLearn, NoValidation, NoTest, All, default=”All”

get_parameter(key)
Parameters:

key (str) – Parameter name

Sending data to the Neural Network

Once a database is loaded, n2d2 use n2d2.provider.DataProvider to provide data to the neural network.

The n2d2.provider.DataProvider will automatically apply the n2d2.transform.Transformation to the dataset. To add a transformation to the provider, you should use the method n2d2.transform.Transformation.add_transformation().

class n2d2.provider.DataProvider(database, size, random_read=False, **config_parameters)

Provide the data to the network.

N2D2()

Return the N2D2 object.

__init__(database, size, random_read=False, **config_parameters)
Parameters:

  • database (n2d2.database.Database) – Database used to read data from

  • size (list) – Size of the data, in the format [W, H, C].

  • batch_size (int, optional) – Batch size, default=1

  • composite_stimuli (bool, optional) – If True, use pixel-wise stimuli labels, default=False

  • random_read (boolean, optional) – if False we use get_batch when iterating other the provider, else we use get get_random_batch, default = False

  • name (str, optional) – Provider name, default = Provider_id

add_on_the_fly_transformation(transformation)

Add transformation to apply to the dataset when reading them.

Parameters:

transformation (n2d2.transformation.Transformation) – Transformation to apply

add_transformation(transformation: Transformation)

Apply transformation to the dataset.

Parameters:

transformation (n2d2.transformation.Transformation) – Transformation to apply

all_batchs_provided()
Returns:

Return True if all batchs have been provided for the current partition.

Return type:

bool

get_batch_size()
Returns:

Batch size

Return type:

int

get_data()
Returns:

Data.

Return type:

n2d2.Tensor

get_database()
Returns:

Give the database

Return type:

n2d2.database.Database

get_deepnet()
Returns:

DeepNet object

Return type:

n2d2.deepnet.DeepNet

get_labels()
Returns:

Labels associated with the current batch.

Return type:

n2d2.Tensor

get_name()
Returns:

Name of the data provider

Return type:

str

get_parameter(key)
Parameters:

key (str) – Parameter name

get_partition()
Returns:

The partition can be Learn, Validation, Test, Unpartitioned

Return type:

str

get_transformations()

Return the transformation (OnTheFly or not) associated to the provider object.

normalize_stimuli()

Normalize the integer value range of stimuli between [0,1]

read_batch(idx: int = None)
Parameters:

idx (int) – Start index to begin reading the stimuli

Returns:

Return a batch of data

Return type:

n2d2.Tensor

read_random_batch()
Returns:

Return a random batch

Return type:

n2d2.Tensor

set_batch(shuffle=True)
Parameters:

shuffle (bool, optional) – If true the data will be shuffled, default=True

set_partition(partition)
Parameters:

partition (str) – The partition can be Learn, Validation, Test, Unpartitioned

set_reading_randomly(random_read)

Set if we use get_batch or get_random_batch when iterating other the provider

Parameters:

random_read (bool) – If True, the provider will give stimuli in a random order.

Example

In this example, we will show you how to create a n2d2.database.Database, n2d2.provider.Provider and apply n2d2.transformation.Transformation to the data.

We will use the n2d2.database.MNIST database driver, rescale the images to a 32x32 pixels size and then print the data used for the learning.

# Loading data
database = n2d2.database.MNIST(data_path=path, validation=0.1)

# Initializing DataProvider
provider = n2d2.provider.DataProvider(database, [32, 32, 1], batch_size=batch_size)

# Applying Transformation
provider.add_transformation(n2d2.transform.Rescale(width=32, height=32))

# Setting the partition of data we will use
provider.set_partition("Learn")

# Iterating other the inputs
for inputs in provider:
        print(inputs)