FAQ

1. How to build the doc?

Sometimes, the online doc is not consistent with the latest code. In this case, you can build the doc by yourself. First, you need to install sphinx, which is used to build doc.

pip install -U sphinx

Second, you need to download a pytorch-style html.zip into directory docs/build and unzip it. Some browsers may identify it as malicious file. You can safely ignore those warnings.

Then, in the directory docs run the following command

make html

Also, warnings during make process doesn’t matter and can be ignored.

Finally, you can open the docs in docs/build/html/index.html

2. How to customize model?

A typical classifier has 3 components.

• backbone: usually ResNet network to extract feature maps.

• bottleneck: random initialized bottleneck layers between backbone and head to increase model capacity

• head: classifier head which outputs final predictions.

The way we construct an image classifier is as follows.

import common.modules.Classifier

# define classifier
classifier = Classifier(backbone=your_backbone, num_classes=num_classes, bottleneck=your_bottleneck,
    bottleneck_dim=your_bottleneck_dim, finetune=True)

Below are some examples on how to change these components.

2.1 Define a new backbone

import torch.nn as nn


class FeatureExtractor(nn.Module):

    def __init__(self):
        pass

    def forward(self, x):
        pass

    @property
    def out_features(self):
        pass

your_backbone = FeatureExtractor()

Notice your FeatureExtractor should implement out_features method, which returns the dimension of output features.

2.2 Define a new bottleneck

import torch.nn as nn

your_bottleneck = nn.Sequential(
    nn.AdaptiveAvgPool2d(output_size=(1, 1)), # for 2d images only
    nn.Flatten(),
    nn.Linear(512, 512),
    nn.BatchNorm1d(512),
    nn.ReLU()
)

2.3 Override get_parameters method

In DA settings, we usually use smaller learning rates for backbone parameters, typically 0.1x compared to other layers. If you want to use other strategies such as different momentum, different weight_decay for different parts, you should inherit Classifier and override get_parameters method.

Below we use same learning rate for backbone, bottleneck and head. And momentum factor of 0.9 is used for bottleneck and head.

import torch.nn as nn
import common.modules.Classifier

class ImageClassifier(Classifier):

    def __init__(self):
        pass

    def get_parameters(self):
        params = [
            {"params": self.backbone.parameters()},
            {"params": self.bottleneck.parameters(), "momentum": 0.9},
            {"params": self.head.parameters(), "momentum": 0.9},
        ]
        return params

3. How to customize datasets?

If you want to implement your own vision datasets, you can use torchvision.datasets.VisionDataset or common.vision.datasets.ImageList.

Before using ImageList, you need to prepare a txt file dog_cat.txt. In this file, each line should has the following format:

path/to/dog/0.jpg 0
path/to/cat/1.jpg 1

where the first part is a relative file path, and the second part is an integer label.

The way to construct an dog-cat dataset is

import torch.nn as nn
import common.vision.datasets.ImageList

dataset = ImageList(root="your_root", classes=("dog", "cat"), data_list_file="dog_cat.txt")