Config#
DeepForest uses a config.yaml file to control hyperparameters related to model training and evaluation. This allows all the relevant parameters to live in one location and be easily changed when exploring new models. This file is packaged with DeepForest is loaded via the OmegaConf library when you create a deepforest instance.
DeepForest includes a default sample config file named config.yaml (at src/conf/config.yaml). Users have the option to override this file by creating their own custom config file. OmegaConf will look in this folder first, but if you provide a path to a config, that one will be overlaid on top of the default. This means you don’t need to specify every parameter, but it is best practice to copy the full configuration.
Please note that if you would like for deepforest to save the config file on reload (using deepforest.save_model), the config.yaml must be updated instead of updating the dictionary of an already loaded model.
# Config file for DeepForest pytorch module
# Cpu workers for data loaders
# Dataloaders
workers: 0
devices: auto
accelerator: auto
batch_size: 1
# Model Architecture
architecture: 'retinanet'
nms_thresh: 0.05
score_thresh: 0.1
# Set model name to None to initialize from scratch
model:
name: 'weecology/deepforest-tree'
revision: 'main'
# If this label dict is specified, and it differs
# from the model downloaded from the hub, the model
# will be updated to reflect the new class list. By
# default, this is blank and is populated when the
# model is loaded.
#
# label_dict:
# Tree: 0
# num_classes: 1
#
label_dict:
num_classes:
# Pre-processing parameters
path_to_raster:
patch_size: 400
patch_overlap: 0.05
annotations_xml:
rgb_dir:
path_to_rgb:
train:
csv_file:
root_dir:
# Optimizer initial learning rate
lr: 0.001
scheduler:
type:
params:
# Common parameters
T_max: 10
eta_min: 0.00001
lr_lambda: "0.95 ** epoch" # For lambdaLR and multiplicativeLR
step_size: 30 # For stepLR
gamma: 0.1 # For stepLR, multistepLR, and exponentialLR
milestones: [50, 100] # For multistepLR
# ReduceLROnPlateau parameters (used if type is not explicitly mentioned)
mode: "min"
factor: 0.1
patience: 10
threshold: 0.0001
threshold_mode: "rel"
cooldown: 0
min_lr: 0
eps: 0.00000001
# How many epochs to run for
epochs: 1
# Useful debugging flag in pytorch lightning, set to True to get a single batch of training to test settings.
fast_dev_run: False
# preload images to GPU memory for fast training. This depends on GPU size and number of images.
preload_images: False
validation:
csv_file:
root_dir:
preload_images: False
size:
# For retinanet you may prefer val_classification, but the default val_loss
# should work with all models
lr_plateau_target: val_loss
# Intersection over union evaluation
iou_threshold: 0.4
val_accuracy_interval: 20
predict:
pin_memory: False
cropmodel:
batch_size: 4
num_workers: 0
lr: 0.0001
scheduler:
type: ReduceLROnPlateau
params:
mode: min
factor: 0.5
patience: 5
threshold: 0.0001
threshold_mode: rel
cooldown: 0
min_lr: 0
eps: 1.0e-08
balance_classes: False
resize:
- 224
- 224
Passing config arguments at runtime using a dict#
It can often be useful to pass config args directly to a model instead of editing the config file. By using a dict containing the config keys and their values. Values provided in this dict will override values provided in config.yaml.
from deepforest import main
# Default model has 1 class
m = main.deepforest()
print(m.config.num_classes)
# But we can override using config args, make sure to specify a new label dict.
m = main.deepforest(config_args={"num_classes":2, "label_dict": {"Alive":0,"Dead":1}})
print(m.config.num_classes)
# These can also be nested for train and val arguments
m = main.deepforest(config_args={"train":{"epochs":7}})
print(m.config.train.epochs)
Dataloaders#
workers#
Number of workers to perform asynchronous data generation during model training. Corresponds to num_workers in pytorch base class. To turn off asynchronous data generation set workers = 0.
devices#
The number of cpus/gpus to use during model training. Deepforest has been tested on up to 8 gpu and follows a pytorch lightning module, which means it can inherit any of the scaling functionality from this library, including TPU support.
accelerator#
Most commonly, cpu, gpu or tpu as well as other options listed:
If gpu, it can be helpful to specify the data parallelization strategy. This can be done using the strategy arg in main.create_trainer()
from deepforest import model as m
m.create_trainer(logger=comet_logger, strategy="ddp")
This is passed to the pytorch-lightning trainer, documented in the link above for multi-gpu training.
batch_size#
Number of images per batch during training. GPU memory limits this usually between 5-10
nms_thresh#
Non-max suppression threshold. The higher scoring predicted box is kept when predictions overlap by greater than nms_thresh. For details see torchvision docs
score_thresh#
Score threshold of predictions to keep. Predictions with less than this threshold are removed from output. The score threshold can be updated anytime by modifying the config. For example, if you want predictions with boxes greater than 0.3, update the config
m.config.score_thresh = 0.3
This will be updated when you can predict_tile, predict_image, predict_file, or evaluate
Train#
csv_file#
Path to csv_file for training annotations. Annotations are .csv files with headers image_path, xmin, ymin, xmax, ymax, label. image_path are relative to the root_dir.
For example this file should have entries like myimage.tif not /path/to/myimage.tif
root_dir#
Directory to search for images in the csv_file image_path column
lr#
Learning rate for the training optimization. By default the optimizer is stochastic gradient descent with momentum. A learning rate scheduler is used based on validation loss
from torch import optim
optim.SGD(self.model.parameters(), lr=self.config.train.lr, momentum=0.9)
A learning rate scheduler is used to adjust the learning rate based on validation loss. The default scheduler is ReduceLROnPlateau:
import torch
self.scheduler = torch.optim.lr_scheduler.ReduceLROnPlateau(self.optimizer, mode='min',
factor=0.1, patience=10,
verbose=True, threshold=0.0001,
threshold_mode='rel', cooldown=0,
min_lr=0, eps=1e-08)
This default scheduler can be overridden by specifying a different scheduler in the config_args:
scheduler_config = {
"type": "cosine", # or "lambdaLR", "multiplicativeLR", "stepLR", "multistepLR", "exponentialLR", "reduceLROnPlateau"
"params": {
# Scheduler-specific parameters
}
}
config_args = {
"train": {
"lr": 0.01,
"scheduler": scheduler_config,
"csv_file": "path/to/annotations.csv",
"root_dir": "path/to/root_dir",
"fast_dev_run": False,
"epochs": 2
},
"validation": {
"csv_file": "path/to/annotations.csv",
"root_dir": "path/to/root_dir"
}
}
The scheduler types supported are:
cosine: CosineAnnealingLR
lambdaLR: LambdaLR
multiplicativeLR: MultiplicativeLR
stepLR: StepLR
multistepLR: MultiStepLR
exponentialLR: ExponentialLR
reduceLROnPlateau: ReduceLROnPlateau
Epochs#
The number of times to run a full pass of the dataloader during model training.
fast_dev_run#
A useful pytorch lightning flag that will run a debug run to test inputs. See pytorch lightning docs
preload_images#
For large training runs, the time spent reading each image and passing it to the GPU can be a significant performance bottleneck.
If the training dataset is small enough to fit into GPU memory, pinning the entire dataset to memory before training will increase training speed. Warning, if the pinned memory is too large, the GPU will overflow/core dump and training will crash.
Validation#
Optional validation dataloader to run during training.
csv_file#
Path to csv_file for validation annotations. Annotations are .csv files with headers image_path, xmin, ymin, xmax, ymax, label. image_path are relative to the root_dir.
For example this file should have entries like myimage.tif not /path/to/myimage.tif
root_dir#
Directory to search for images in the csv_file image_path column
val_accuracy_interval#
Compute and log the classification accuracy of the predicted results computed every X epochs. This incurs some reductions in speed of training and is most useful for multi-class models. To deactivate, set to an number larger than epochs.
CropModel#
The cropmodel section contains configuration options specific to the CropModel class, used for classification of detected objects.
batch_size#
Number of images per batch during crop model training and prediction. Default is 4.
num_workers#
Number of workers for data loading during crop model training. Set to 0 to disable multiprocessing.
lr#
Learning rate for the crop model optimizer (Adam). Default is 0.0001.
scheduler#
Learning rate scheduler configuration for the crop model. Default is ReduceLROnPlateau with specific parameters.
balance_classes#
Boolean flag to enable weighted sampling for imbalanced datasets. When set to True, uses weighted_random sampling to give more weight to underrepresented classes during training. Default is False.
resize#
A list of two integers [height, width] specifying the dimensions to resize input images to before feeding them to the model. Default is [224, 224]. This can be customized for models that expect different input sizes:
from deepforest.model import CropModel
# Use default 224x224 resize
crop_model = CropModel()
# Or use custom resize dimensions
crop_model = CropModel(config_args={"resize": [300, 300]})