Home

Training Models

The Spatial AI Library (SAIL) provides a configuration-based framework for training deep learning models that integrate satellite imagery, geospatial covariates, and tabular data.
This page explains how to train models using YAML configuration files, manage outputs, and understand the available model options.

---

1. Overview

All model training in SAIL is controlled through a YAML configuration file that specifies:

• The dataset source and type
• The model architecture and parameters
• Training hyperparameters (e.g., epochs, learning rate, device)
• Optional validation or explainability tasks

This design abstracts away implementation details, allowing users to launch complex experiments with a single command.

---

2. Running Training Jobs

Command-line usage

To start training, specify the path to your configuration file:

python launch.py --config configs/phl_geoconv_regression.yaml

Once the process begins, SAIL:

1. Loads the configuration file.
2. Builds the dataset and model specified.
3. Trains for the defined number of epochs.
4. Saves checkpoints, logs, and metrics in the defined output_dir.

---

3. Example Configuration

Below is a minimal example for training a GeoConv-based regression model on a DHS indicator dataset:

task: train
experiment_name: "usaid_dhs_pct_water_improved"
output_dir: "artifacts/checkpoints/phl_geoconv_income"

dataset:
  type: json
  data_root: "/data/phl"
  prefix: "pct_improved_water_africa"
  batch_size: 16
  img_size: [224, 224]
  num_workers: 0
  seed: 1337

model:
  name: geoconv
  params:
    pretrained: false

trainer:
  epochs: 1
  lr: 1e-4
  device: "cuda"
  save_every: 1
  eval_every: 1
  early_stop: null

Each configuration parameter maps directly to an internal module in SAIL:

Section	Purpose
task	Specifies whether to train, validate, or run explainability analyses
experiment_name	Unique name used for checkpoints and logs
dataset	Defines dataset type, location, and preprocessing parameters
model	Selects the architecture and initialization settings
trainer	Controls training hyperparameters and device setup

---

4. Output Structure

After training, results are stored in the directory defined by output_dir.
A typical output directory includes:

artifacts/checkpoints/phl_geoconv_income/
├── config_used.yaml
├── epoch_001.pth
├── train_log.csv
├── val_metrics.csv
└── tensorboard/ (optional)

• config_used.yaml: exact configuration used for the run
• .pth files: model checkpoints
• train_log.csv: training metrics (loss, epoch time, etc.)
• val_metrics.csv: validation metrics when applicable

---

5. Available Models

SAIL includes several baseline and specialized architectures registered in the ModelRegistry.
Each can be selected by setting the model.name field in the configuration.

5.1 GeoConvNativeRegressor (geoconv)

A coordinate-conditioned convolutional network where filter weights are predicted based on spatial coordinates.
Useful for spatially adaptive regression tasks, especially when modeling continuous outcomes such as wealth or education indices.

5.2 ResNet18Classifier (resnet18)

A standard ResNet-18 backbone wrapped for geospatial regression or classification.
Can be initialized with pretrained ImageNet weights for transfer learning.

5.3 Tang2015CNN (tang2015)

A replication of the CNN architecture introduced in “Mapping Poverty using Satellite Imagery” (Jean et al., 2016; Tang et al., 2015).
Serves as a baseline for socioeconomic prediction tasks.

5.4 EfficientNetB0 (efficientnet_b0)

A compact, efficient CNN that balances accuracy and performance.
Useful for small datasets or lightweight experimentation.

5.5 TransformerRegressor (transformer)

A ViT-style model that learns patch-based representations from imagery.
Supports future extensions for attention-based spatial reasoning and domain adaptation.

---

6. Pretrained Weights

Some models (e.g., ResNet18, EfficientNet) can be initialized with pretrained weights.
To do so, set pretrained: true in your configuration file:

model:
  name: resnet18
  params:
    pretrained: true

For models that do not support pretrained weights, the parameter is ignored.

---

7. Logging and Metrics

Training progress is automatically logged each epoch, including loss and learning rate.
Metrics are saved in CSV format for compatibility with standard data analysis tools (e.g., pandas, Excel).

Custom metrics (e.g., R², RMSE, MAE) are computed automatically during validation or testing phases.

---

8. Reproducibility

Every run saves a copy of the full configuration (config_used.yaml) in the output directory.
This ensures experiments can be replicated exactly, even months later.

It is good practice to:

• Version your configuration files in Git.
• Record dataset versions or sources in the YAML header.
• Use a consistent random seed across runs for comparability.

---

9. Next Steps

After completing training, you can:

• Validate your model on the held-out test set using task: validate.
• Generate explanations or spatial sensitivity analyses using task: explain.

Detailed instructions for these steps are provided in the Validation and Explainability Wiki pages.