BurnSAVe Dataset

Each thematic category in the dataset contains one or more GeoTIFF (.tif) files. Individual GeoTIFF files may consist of either a single band or multiple bands, depending on the variable and its temporal representation (e.g., static layers versus event-centered time series).

Within each year folder, files are named using the following convention:

{n}L_{MTBS_ID}.tif

where:

• {n}L indicates the number of bands (layers) contained in the GeoTIFF file.
• MTBS_ID is the unique MTBS fire identifier.

Example

4L_AZ3237811092720200606.tif

This filename indicates:

• 4L: a four-band GeoTIFF file.
• AZ3237811092720200606: the MTBS fire ID.

The final eight digits of the MTBS fire ID encode the fire ignition date in the format:

YYYYMMDD

For the example above, the ignition date is June 6, 2020 (2020-06-06).

Nested File Structure

Base_Data
├── Burnseverity_fireintensity_metrics
│   ├── Soil Burn Severity Classes (SBS)
│   │   ├── 2012
│   │   │   ├── 1L_az3415011088320120614.tif
│   │   │   └── …
│   │   ├── 2013
│   │   │   ├── 1L_AZ3143511076720130517.tif
│   │   │   └── …
│   │   └── …
│   │
│   ├── Vegetation Burn Severity (VBS)
│   │   ├── 2012
│   │   │   ├── 4L_OR4227712061220200815.tif
│   │   │   └── …
│   │   └── …
│   │
│   └── Fire Intensity Proxy (FRP)
│       ├── 2012
│       │   ├── 3L_az3415011088320120614.tif
│       │   └── …
│       └── …
│
├── Landsurface Vegetation Topography
│   ├── Ecoregions_Level_1_2_3
│   │   ├── 2012
│   │   │   ├── 3L_az3415011088320120614.tif
│   │   │   └── …
│   │   └── …
│   │
│   ├── Vegetation and Land Cover (LANDFIRE)
│   │   ├── 2012
│   │   │   ├── 2L_az3415011088320120614.tif
│   │   │   └── …
│   │   └── …
│   │
│   ├── Landsurface Temperature (LST)
│   │   ├── 25L_Day_Median
│   │   │   ├── 2012
│   │   │   │   ├── 25L_az3415011088320120614.tif
│   │   │   │   └── …
│   │   │   └── …
│   │   │
│   │   ├── 25L_Day_Std
│   │   │   ├── 2012
│   │   │   │   ├── 25L_az3415011088320120614.tif
│   │   │   │   └── …
│   │   │   └── …
│   │   │
│   │   ├── 25L_Night_Median
│   │   │   ├── 2012
│   │   │   │   ├── 25L_az3415011088320120614.tif
│   │   │   │   └── …
│   │   │   └── …
│   │   │
│   │   └── 25L_Night_Std
│   │       ├── 2012
│   │       │   ├── 25L_az3415011088320120614.tif
│   │       │   └── …
│   │       └── …
│   │
│   ├── Topography
│   │   ├── 2012
│   │   │   ├── 3L_az3415011088320120614.tif
│   │   │   └── …
│   │   └── …
│   │
│   └── Vegetation Condition and Greenness
│       ├── EVC
│       │   ├── 2012
│       │   │   ├── 1L_az3415011088320120614.tif
│       │   │   └── …
│       │   └── …
│       │
│       ├── EVH
│       │   ├── 2012
│       │   │   ├── 1L_az3415011088320120614.tif
│       │   │   └── …
│       │   └── …
│       │
│       ├── EVI
│       │   ├── 2012
│       │   │   ├── 25L_az3415011088320120614.tif
│       │   │   └── …
│       │   └── …
│       │
│       └── NDVI
│           ├── 2012
│           │   ├── 25L_az3415011088320120614.tif
│           │   └── …
│           └── …
│
├── Soil Characteristics
│   ├── 2012
│   │   ├── 25L_az3415011088320120614.tif
│   │   └── …
│   └── …
│
├── Weather and Climate
│   ├── Climate Normal (30 Year Averages)
│   │   ├── 2012
│   │   │   ├── 7L_az3415011088320120614.tif
│   │   │   └── …
│   │   └── …
│   │
│   └── Event Centered Climate
│       ├── Pr
│       │   ├── 2012
│       │   │   ├── 25L_az3415011088320120614.tif
│       │   │   └── …
│       │   └── …
│       │
│       ├── Tmmn
│       │   ├── 2012
│       │   │   ├── 25L_az3415011088320120614.tif
│       │   │   └── …
│       │   └── …
│       │
│       └── Tmmx
│           ├── 2012
│           │   ├── 25L_az3415011088320120614.tif
│           │   └── …
│           └── …
│
└── Daily Fire Progression Attributes
    ├── VIIRS based Data
    │   ├── 2012
    │   │   ├── 192L_az3415011088320120614.tif
    │   │   └── …
    │   └── …
    │
    └── FIRED Data
        ├── 2012
        │   ├── 8L_az3415011088320120614.tif
        │   └── …
        └── …

Table of Contents

BurnSAVe Stacking App

Stack fire-related raster features (burn severity, fire intensity, climate, vegetation, topography, and daily fire-progression variables) into per-fire-event, multi-band GeoTIFFs — with real variable names and definitions on every band, not generic placeholders.

You download the public BurnSAVe dataset yourself from HydroShare (no account or login required), then give the app the path to the zip file or the extracted folder. The app takes it from there.

Contents

Requirements

• Conda (Miniconda or Anaconda) — https://docs.conda.io/en/latest/miniconda.html
• A web browser, to download the public dataset from HydroShare

No extra Python packages beyond environment.yml are needed — there's no API client involved.

Quick Start

1. Set up the environment

Linux/macOS:

``` chmod +x setup_env.sh run.sh

./setup_env.sh ```

conda activate sbs_app

Windows PowerShell:

.\setup_env.ps1

conda activate sbs_app

2. Download the dataset

Download the dataset from its public HydroShare page using your web browser. Save the downloaded .zip file to a location of your choice.

3. Run the application

Run the application and specify the path to the downloaded dataset:

python app.py --data-root "C:/Downloads/BurnSAVe.zip" --features VBS,NDVI --years 2020 --out-dir ./outputs

The app unzips the file automatically (next to where it already is), finds the BurnSAVe folder inside, and produces stacked GeoTIFFs in ./outputs. Re-running the same command later skips re-unzipping, since it detects the data is already extracted.

Step-by-Step Setup

1. Install Conda

Download Miniconda for your OS, install with default options, then reopen your terminal. Confirm it worked: bash conda --version

2. Get the app files

Put this whole folder somewhere convenient and open a terminal in it: bash cd sbs_app ls

3. Create the environment (one-time)

Linux/macOS: bash chmod +x setup_env.sh run.sh ./setup_env.sh conda activate sbs_app

Windows (PowerShell): powershell .\setup_env.ps1 conda activate sbs_app Your prompt should now start with (sbs_app). This creates the environment from environment.yml (Python 3.11, numpy, rasterio). You only need to do this once per computer; re-run setup_env any time environment.yml changes.

4. Download the dataset yourself

Open the dataset's public HydroShare page in a browser and download it as a zip — no account or login required, since it's public. Save it anywhere convenient; you don't need to unzip it yourself.

Pointing the App at Your Data

--data-root (or the SBS_DATA_ROOT environment variable) accepts either:

• A .zip file — the app unzips it automatically, into a new folder named after the zip, right next to it. For example, C:/Downloads/BurnSAVe.zip extracts to C:/Downloads/BurnSAVe/.
• An already-extracted folder — used directly (or searched one level in, if the BurnSAVe folder is nested a level or two deeper, e.g. inside a folder HydroShare added around it).

Either way, the app automatically finds the folder literally named BurnSAVe and uses that as the dataset root. This never requires internet access — it only touches files already on your disk.

One-off, per run

bash python app.py --data-root "C:/Downloads/BurnSAVe.zip" --features VBS,NDVI --out-dir ./outputs

Set once for the whole terminal session

bash export SBS_DATA_ROOT=/full/path/to/BurnSAVe # Linux/macOS, already extracted $env:SBS_DATA_ROOT = "C:\full\path\to\BurnSAVe" # Windows PowerShell, already extracted

Note: SBS_DATA_ROOT expects an already-extracted folder, not a zip. Use --data-root if you want to point directly at a .zip file.

Sanity-check before a real run

bash python app.py --data-root "C:/Downloads/BurnSAVe.zip" --list-features This unzips/locates the data (if needed) and runs the same path-existence check the stacker uses, warning immediately if anything's missing instead of failing partway through a run.

Extract/locate only, without stacking anything

bash python local_data.py --path "C:/Downloads/BurnSAVe.zip" Prints the resolved BurnSAVe folder path and the exact commands to use it, without running the stacker.

If nothing is set

If you don't pass --data-root, don't set SBS_DATA_ROOT, and you're running non-interactively, the app falls back to the built-in default path in app.py (DEFAULT_DATA_ROOT). On a new computer this usually won't exist, and the app fails fast with a clear error instead of silently producing zero outputs: [ERROR] The SBS reference folder does not exist: <path> Fix it with one of: --data-root "C:/path/to/BurnSAVe.zip" --data-root /path/to/already/extracted/BurnSAVe export SBS_DATA_ROOT=/path/to/your/BurnSAVe

Running the App

Interactive mode

Run with no arguments at all: bash python app.py You'll be prompted in order for: the path to your BurnSAVe data (a .zip or an extracted folder — skipped if --data-root/SBS_DATA_ROOT is already set), output folder, years, months, MTBS IDs, features (the full feature list with descriptions is printed first), whether to include SBS, strict mode, and debug logging. Press Enter at any prompt to accept its default.

Non-interactive / scripted mode

Pass any of --out-dir, --years, --months, --mtbs-ids, --features, --include-sbs, --strict, --debug, or -y, and the app skips the prompts and runs directly — useful for batch/HPC jobs: bash python app.py --data-root "C:/Downloads/BurnSAVe.zip" --years 2019,2020 --features VBS,NDVI --out-dir ./outputs --strict run.sh/run.ps1 forward any arguments, so ./run.sh --list-features works the same way.

Exploring Features and Bands

These need no data on disk — they just read the built-in metadata catalog:

List all available features

python app.py --list-features

Describe a specific feature

python app.py --describe-feature VBS

Available features

VIIRS_daily and FIRED were previously named Daily_zach/Daily_Jennifer. Both old names still work (auto-mapped internally) if you have older scripts referencing them.

Band naming in the output

Every band in a stacked GeoTIFF is named <feature>__<variable>, e.g. VBS__dNBR6, Pr__pr_m-12 (12 months pre-fire), Pr__pr_m+00 (fire month). This is stamped as the band description in the GeoTIFF itself (visible in QGIS/ArcGIS/gdalinfo), along with tags for DEFINITION, UNITS, SOURCE, and CLASSES where applicable.

CLI Reference

Run python app.py --help any time for the full, current list.

Output Structure

outputs/ STACK_<mtbs_id>.tif <- stacked, multi-band GeoTIFF for one fire event STACK_<mtbs_id>_bands.csv <- plain-English legend: variable, definition, units, source, classes, per band logs/ stack_log_<timestamp>.log <- full run log stack_report_<timestamp>.csv <- FOUND / MISSING / ERROR, per feature per fire

Always check the _bands.csv first to know exactly what each band in the GeoTIFF represents.

Troubleshooting

Notes

• Nothing in this app ever connects to the internet or any API — all it does is read a .zip file or folder you already downloaded yourself.
• find_data_root() searches case-insensitively for BurnSAVe, so variations in capitalization in the extracted folder name won't break auto-discovery.
• Re-running the same --data-root <zip> command is safe — it detects the zip is already extracted and skips redoing it.