Welcome to fast.ai’s documentation!

This documentation is in an early development stage. Feel free to contribute!

Anatomy of a deep learning library

The fastai library combines the best elements of software automation and modern deep learning. The deep learning principles are well covered by the course material, but the design of the code itself also reveals a lot of insights into the practical matters of putting it all together.

Working with data

A substantial amount of the code in the fastai library is dedicated to reading, writing, reshaping, polishing, and otherwise working with data. There are a few places where this sort of logic is concentrated.

• fastai.core: contains a number of helpers for translating your data into common shapes like np.array, torch.Tensor, or torch.autograd.Variable.
• fastai.dataloader: is a variant of torch.util.data.DataLoader that uses threads instead of processes, reducing overhead and speeding everything up. As with a normal DataLoader, we iterate over a Dataset in batches rather than one example at a time. There are also conveniences here for working with a few differently shaped inputs that are common in practice.
• fastai.transforms: adapts parts of the cv2 library for use in deep learning. Some of these are essential or best practices, like cropping, normalization, or flipping channels to be the first tensor axis (remember that pytorch puts the channels first!). Others are optional or context-dependent, like scaling, padding, flipping, rotating, or blurring the image. In addition, there are specific transformations for training data, which can translate a 4-tuple (left, top, right, bottom) bounding box into the equivalent black and white image for training (corners only or the whole box).
• fastai.dataset: has a bunch of utilities for working with data arranged as files on disk. Most notably these help resize and sample data, including the splitting off of a validation set. Also noteworthy is BaseDataset, which extends torch.utils.data.Dataset, and all of its descendants. Those describe the different ways to load files arranged on disk, and a few bits of metadata like whether the output is a regression or classfication. After wrapping in a DataLoader the training, validation, and an optional test data set are all bundled together into a ModelData for use in the rest of the code.
• fastai.structured: has methods that can massage a pd.DataFrame into friendlier forms for learning. This includes dealing with missing values, ensuring correct data types, normalizing numerical inputs and one-hot encoding categories, and some lightweight feature engineering on dates.
• fastai.text: has similarly intended utilities for reading and tokenizing text data.

The training loop

After the data is loaded, it still needs to be used as part of a training loop. Torch has dealt with a lot of the modeling problem, but it did not come with training loop batteries included. Fortunately fastai does, and it’s a major value add.

• fastai.layer_optimizer: makes it easier to manipulate the learning rate and weight decay in an optimizer. Scheduling these parameters is important for state of the art results, and so these hooks are frequently used by callbacks e.g. in the learning rate finder.
• fastai.sgdr: contains a bunch of callbacks for use in the optimizer. Each callback is updated when training begins or ends, when batches begin, and when batches or epochs end. Those last two of those also see the validation loss and metrics, and can return True if they wish to halt training. This abstraction is quite powerful, and is used for a lot of essential features like the learning rate finder, cosine annealing, and an improved implementation of L2 regularization that doesn’t hork the Adam optimizer.
• fastai.model: contains all of the low-level fastai training utilities. Stepper wraps together a model, optimizer, loss function, and clipping or other regularization. Each step receives a batch, runs the model, evaluates the loss function, and asks the optimizer to update the parameters. The fit(…) method creates that Stepper from the relevant inputs and then feeds it from a ModelData, iterating over epochs and then the training data in batches. At the end of each epoch, the model is evaluated against the validation data. This training loop is also where the callback logic is used, triggering at training/batch/epoch beginning and end. After training is finished, this file also contains a bunch of helper methods to run the model on new data.
• fastai.learner: is the top of the core fitting stack, bundling together a ModelData with a model, and composing the lower-level utilities as conveniently as possible. That includes configuration of callbacks for training or learning rate finding, with nice defaults, as well as other creature comforts like training freezing and test-time augmentation.
• Each problem domain has a specific Learner subclass to set the right loss criterion and add any domain-specific conveniences: ConvLearner in fastai.conv_learner: for working with images, RNN_Learner in fastai.text: for sequences, and StructuredLearner in fastai.column_data: for data frames.

Introduction

• Home
• Contribute to the library
  • Introduction
  • Style Guide
    • Symbol naming
    • Layout
    • Algorithms
    • Other stuff
    • Documentation
  • Fastai Abbreviation Guide
  • Module Decisions
    • Image Data
  • Testing Style
    • Testing patterns
  • FAQ
• Contribute to the documentation
  • Project goals and approach
  • How to contribute
  • How to build locally

Data Handling

• fastai.core
• fastai.dataloader
  • Introduction and Overview
  • Class DataLoader
    • Methods
• fastai.transforms
  • Introduction and Overview
  • Normalization
    • Normalizing for Pretrained Models
    • Normalizing with Custom Statistics
  • Adding Augmentation
    • Predefined Augmentations
    • Custom Augmentations
  • Available Transformations
    • The currently implemented transformations are:
• fastai.dataset
• fastai.structured
• fastai.text

Model Training

• fastai.layer_optimizer
• fastai.sgdr
• fastai.model
• fastai.learner

Examples

• This is a test notebook