The data block API¶

The data block API lets you customize how to create a DataBunch by isolating the underlying parts of that process in separate blocks, mainly:

1. Where are the inputs and how to create them?
2. How to split the data into a training and validation set?
3. How to label the inputs?
4. What transforms to apply?
5. How to add a test set?
6. How to wrap in dataloaders and create the DataBunch?

For each of those questions, you can have multiple possible blocks: your inputs might be in a folder, a csv file, a dataframe. You may want to split them randomly, by certain indexes or depending on the folder they are in. You can have your labels in your csv file or your dataframe, but it may come from folders or a specific function of the input. You may or may not have data augmentation to deal with. Or a test set. Finally you have to set the arguments to put the data together in a DataBunch (batch size, collate function...)

The data block API is called as such because you can mix and match each one of those blocks with the others, allowing you total flexibility to create your customized DataBunch for training. The factory methods of the various DataBunch are great for beginners but you can't always make your data fit in the tracks they require.

As usual, we'll begin with end-to-end examples, then switch to the details of each of those parts.

Examples of use¶

Let's begin by our traditional MNIST example.

In vision.data, we create an easy DataBunch suitable for classification by simply typing:

This is aimed at data that is in folders following an ImageNet style, with a train and valid directory containing each one subdirectory per class, where all the pictures are. There is also a test set containing unlabelled pictures. With the data block API, we can group everything together like this:

Let's look at another example from vision.data with the planet dataset. This time, it's a multiclassification problem with the labels in a csv file and no given split between valid and train data, so we use a random split. The factory method is:

With the data block API we can rewrite this like that:

The data block API also allows you to get your data together in problems for which there is no direct ImageDataBunch factory method. For a segmentation task, for instance, we can use it to quickly get a DataBunch. Let's take the example of the camvid dataset. The images are in an 'images' folder and their corresponding mask is in a 'labels' folder.

We have a file that gives us the names of the classes (what each code inside the masks corresponds to: a pedestrian, a tree, a road...)

And we define the following function that infers the mask filename from the image filename.

Then we can easily define a DataBunch using the data block API. Here we need to use tfm_y=True in the transform call because we need the same transforms to be applied to the target mask as were applied to the image.

Another example for object detection. We use our tiny sample of the COCO dataset here. There is a helper function in the library that reads the annotation file and returns the list of images names with the list of labelled bboxes associated to it. We convert it to a dictionary that maps image names with their bboxes and then write the function that will give us the target for each image filename.

The following code is very similar to what we saw before. The only new addition is the use of special function to collate the samples in batches. This comes from the fact that our images may have multiple bounding boxes, so we need to pad them to the largest number of bounding boxes.

But vision isn't the only application where the data block API works, it can also be used for text or tabular data. With ouy sample of the IMDB dataset (labelled texts in a csv file), here is how to get the data together for a language model.

For a classification problem, we just have to change the way labelling is done. Here we use the column 'label' of our csv.

Lastly, for tabular data, we just have to pass the name of our categorical and continuous variables as an extra argument. We also add PreProcessor that are going to be applied to our data once the splitting and the labelling is done.

Step 1: Provide inputs¶

The basic class to get your inputs into is the following one. It's also the same class that will contain all of your labels (hence the name ItemList).

This class regroups the inputs for our model in items and saves a path attribute which is where it will look for any files (image files, csv file with labels...) create_func is applied to items to get the final output. label_cls will be called to create the labels from the result of the label function, xtra contains additional information (usually an underlying dataframe) and processor is to be applied to the inputs after the splitting and labelling.

It has multiple subclasses depending on the type of data you're handling. Here is a quick list:

• CategoryList for labels in classification
• MultiCategoryList for labels in a multi classification problem
• FloatList for float labels in a regression problem
• ImageItemList for data that are images
• SegmentationItemList like ImageItemList but will default labels to SegmentationLabelList
• SegmentationLabelList for segmentation masks
• ObjectItemList like ImageItemList but will default labels to ObjectLabelList
• ObjectLabelList for object detection
• PointsItemList for points (of the type ImagePoints)
• TextList for text data
• TextFilesList for text data stored in files
• TabularList for tabular data

Once you have selected the class that is suitable, you can instantiate it with one of the following factory methods

Optional step: filter your data¶

The factory method may have grabbed too many items. For instance, if you were searching sub folders with the from_folder method, you may have gotten files you don't want. To remove those, you can use one of the following methods.

Writing your own ItemList¶

First check if you can't easily customize one of the existing subclass by:

• changing the create_func (example: opening images with your custom function and not open_image)
• applying a custom processor (see step 4)
• changing the default label_cls for the label creation.

If this isn't the case and you really need to write your own class, here is what you should code:

class MyCustomItemList():
    #If you need custom arguments you will have to overwrite __init__ and new like this.
    def __init__(self, items:Iterator, my_args, **kwargs):
        super().__init__(items, **kwargs)
        #store my args, initialize what is needed.

    def new(self, items:Iterator, **kwargs)->'NumericalizedTextList':
        #Retrive your custom args stored and send them to new like this
        return super().new(items=items,  my_args, **kwargs)

    #This is how to get your data stored at index i
    def get(self, i):
        o = super().get(i)
        return what you need from o

You can add custom splitting or labelling methods if you need them.

Step 2: Split the data between the training and the validation set¶

This step is normally straightforward, you just have to pick oe of the following functions depending on what you need.

Step 3: Label the inputs¶

To label your inputs, use one of the following functions. Note that even if it's not in the documented arguments, you can always pass a label_cls that will be used to create those labels (the default is the one from your input ItemList, and if there is none, it will go to CategoryList, MultiCategoryList or FloatList depending on the type of the labels).

ItemList suitable for storing labels in items belonging to classes. If None are passed, classes will be determined by the unique different labels. processor will default to CategoryProcessor.

ItemList suitable for storing list of labels in items belonging to classes. If None are passed, classes will be determined by the unique different labels. sep is used to split the content of items in a list of labels.

ItemList suitable for storing the floats in items for regression. Will add a log if this flag is True.

Invisible step: preprocessing¶

This isn't seen tehre in the API, but if you passed a processor (or a list of them) in your initial ItemList during step 1, it will be applied here. A processor is a transformation that is applied to all the inputs once and for all, with a state computed on the training set that is then applied without modification on the validation set (and maybe the test set). For instance, it can be processing texts to tokenize then numericalize them. In that case we want the validation set to be numericalized with exactly the same vocabulary as the training set.

Another example is in tabular data, where we fill missing values with (for instance) the median computed on the training set. That statistic is stored in the inner state of the PreProcessor and applied on the validation set.

This is the generic class for all processors.

Process one item. This method needs to be written in any subclass.

Process a dataset. This default to apply process_one on every item of ds.

PreProcessor that will convert labels to codes usings classes (if passed) in a single classificatio problem.

PreProcessor that will convert labels to codes usings classes (if passed) in a single multi-classificatio problem.

Optional steps¶

Add transforms¶

Transforms differ from processors in the sense they are applied on the fly when we grab one item. They also may change each time we ask for the same item in the case of random transforms.

This is primary for the vision application. The kwargs are the one expected by the type of transforms you pass. tfm_y is among them and if set to True, the transforms will be applied to input and target.

Add a test set¶

To add a test set, you can use one of the two following methods.

Step 4: convert to a DataBunch¶

This last step is usually pretty straightforward. You just have to include all the arguments we pass to DataBunch.create (bs, num_workers, collate_fn). The class called to create a DataBunch is set in the _bunch attribute of the inputs of the training set if you need to modify it. Normally, the various subclasses we showed before handle that for you.

Inner classes¶

The basic dataset in fastai. Inputs are in x, targets in y. Optionally apply tfms to x and also y if tfm_y is True.

Data in path split between several streams of inputs, train, valid and maybe test.

Helper functions¶

Undocumented Methods - Methods moved below this line will intentionally be hidden¶

New Methods - Please document or move to the undocumented section¶