/mug

a PyTorch code to train a deep learning model to predict urban settlements in satellite images based on demographic and geospatial data

Primary LanguageJupyter NotebookApache License 2.0Apache-2.0

Model of Urban Growth

This repository contains code to mount a dataset which connects demographic and geospatial data using torchgeo and a deep learning model with sequence-to-sequence convLSTM architecture with training, validation and testing for urban settlements prediction. The model training used a time series from Worldpop.org between 2000 and 2004 and the test carried out used datafrom the year 2005.

Download data

The data can be downloaded into a new directory **/worldpop/** . For this test, we are using land cover, water, roads and slope information. The connection between different datasets will performed by the code in src/mug/dataset/* using Torchgeo.

These data files are downloaded using FTP:

  • Slope: ftp://ftp.worldpop.org.uk/GIS/Covariates/Global_2000_2020/0_Mosaicked/Slope/slope100m.tif
  • Water: ftp://ftp.worldpop.org.uk/GIS/Covariates/Global_2000_2020/0_Mosaicked/OSM_Water/BinaryMosaic_1_0_NoData/osmwater100m_1_0_NoData.tif
  • Roads: ftp://ftp.worldpop.org.uk/GIS/Covariates/Global_2000_2020/0_Mosaicked/OSM_Roads/BinaryMosaic_1_0_NoData/osmhighway100m8-1710nd.tif

More details can be found in src/mug/datasets/worldpop.py.

Installation

Clone this repository.

$ git clone git@github.com:IBM/mug.git
$ export MUG_HOME='./mug'

Creating the virtual environment

First, you will need to install Python, version 3.12.2. The following instructions assume you are already in the mug repo root directory.

  1. Create the env: python3 -m venv venv
  2. Activate the env: source ./venv/bin/activate
  3. Install all packages: pip install -r ./requirements.txt
  4. Install mug in editable mode:pip install -e .

Here are the commands as one script:

python3 -m venv venv
source ./venv/bin/activate
pip install -r ./requirements.txt
pip install -e .

Usage

There are two ways of run the code: by notebook or by script

Notebook

Note

You will have to activate the virtual environment everytime you need to use mug.

For instance, if you want to work with mug on jupyter, you will need to run the following commands in a freshly started shell:

source ./venv/bin/activate
jupyter-notebook trainjupyter_s2s_main.ipynb

Python script

Note

You will have to activate the virtual environment everytime you need to use mug.

For instance, if you want to work with mug using a Python script file you will need to run the following commands in a freshly started shell:

source ./venv/bin/activate
python script_mug_s2s.py --parameter_file='parameters_variable.yaml'

File Structure

src/mug/            
├─ cli/                     - utilities regarding an alternative code to load data and model 
├─ dataset/                 - dataset management (download, processing, generation )
├── nn/                     - model architecture
├─ samples/                 - sample generation
└─ utils/                   - utilities regarding evaluation

requirements.txt            - Python library requirements
rois.csv                    - config file with region of interest using latitude and longitude of each city      
parameters_variable.yaml    - parameter file with hyperparameters
script_mug_s2s.py           - main script to load the data, train, valid and test the sequence-to-sequence convLSTM model 
trainjupyter_s2s_main.ipynb - main notebook code to load the data, train, valid and test the sequence-to-sequence convLSTM model

Results (test images)