A Python Command-Line Interface for classifying fire events from the Collection 6 MODIS Burned Area Product.

This package uses a space-time window to classify individual burn detections from late 2001 to near-present into discrete events and return both a data table and shapefiles of these events.

Methodological information for FIREDpy 1.0:

Balch, J. K., St. Denis, L. A., Mahood, A. L., Mietkiewicz, N. P., Williams, T. W., McGlinchy J, and Cook, M. C. 2020. FIRED (Fire Events Delineation): An open, flexible algorithm & database of U.S. fire events derived from the MODIS burned area product (2001-19). Remote Sensing, 12(21), 3498; https://doi.org/10.3390/rs12213498.

Description of the 2000 - 2021 data sets:

Mahood, A.L. Lindrooth, E.J., Cook, M.C. and Balch, J.K. 2022. Country-level fire perimeter datasets (2001-2021). Nature Scientific Data, 9(458). https://doi.org/10.1038/s41597-022-01572-3

Methodological information for FIREDpy 2.0, description of 2000-2024 datasets:

Coming soon...

Data Sharing Agreement

FIREDpy is currently in active development, and newer versions of the algorithm and data products are shared on an individual basis. All data products generated from unpublished versions of FIREDpy require permission from PI Jennifer K. Balch prior to use in publications, presentations, or public dissemination. These conversations ensure appropriate acknowledgment of the development team's contributions and proper context for the algorithm's current capabilities and limitations. Please use the above citation for attributing credit. For data requests or collaboration inquiries, please contact Nate Hofford, University of Colorado Boulder.

Proccessed Countries

Already-created products are displayed below. They are housed in the CU Scholar data repository in the Earth Lab Data collection, or here. All of the created products have an event-level shapefile in .gpkg and .shp formats. Most countries also have the daily-level shapefile for the V2024 products, but for the V2022 products these were not created for most countries in Africa and Asia due to computational restrictions.

Click on, or search for, your favorite country to view avaliable fire perimeter datasets:

Run your own analysis!

The user is able to specify the spatial and temporal parameters of the window, as well as the spatial and temporal extent, using either a shapefile or a list of MODIS Sinusoidal Projection tile IDs. Countries, continents and US states are included. Any area from the world may be selected.

However, in the current version, memory constraints may limit the extent available for a single model run. Equatorial regions have much more fire activity, and may require much more RAM to process than a normal laptop will have.

The algorithm outputs shapefiles of delineated fire events in either .shp or .gpkg format. In addition to the full event polygons created by default, and the user has the option of having firedpy produce daily-level perimeters, providing a representation of both final and expanding event perimeters.

The MODIS Sinusioidal Project

You may specify study areas for FIREDpy using individual MODIS tiles. This product uses a Sinusoidal, Lambert Azimuthal Equal-Area projection. There are several spatial resolutions available for this data, but FIREDpy uses the 500m resolution (actual distances depend on location). For more information about this projection, click here. If you would like to use the MODIS sinusoidal grid IDs to identify FIREDpy study areas, see the visualization of this grid below.

Avaliable Parameters

parameter	value(s)	example	description
--spatial_param, -sp	integer	-sp 5	Pixel radius for moving window, defaults to 5
--temporal_param, -tp	integer	-tp 11	Day radius for moving window, defaults to 11
--tiles, -t	character (MODIS tile)	-t h11v09	Which MODIS tiles should be used
--shape_file, -sf	character (shapefile)	-sf ~/firedpy/data/individual_countries/canada.gpkg	Finds MODIS tiles to download based on the polygon and clips output by the shapefile boundaries
--project_directory, -p	character	-p /home/firedpy/proj	Sets the output directory. Will also download all input data to this path
--eco_region_type, -et	character	-et na	Type of ecoregion, either 'world' or 'na'
--eco_region_level, -el	integer	-el 3	If ecoregion type = na, the level (1-3) of North American ecoregions
--land_cover_type, -lt	integer and character	-lt 2	Number (1-3) corresponding with a MODIS/Terra+Aqua Land Cover (MCD12Q1) category. Requires an Earthdata account
--shape_type, -st	character	-st gpkg	Option to build a shapefile for the fired event as a GeoPackage (gpkg), ESRI shapefile (shp), or both
--project_name, -n	character	-n fired_colorado	Specifies a base name for output files for the tables and shapefile outputs
--daily, -d	character (yes or no)	-d	Creates daily polygons; if not provided, only event-level perimeters will be created
--start_year, -y1	integer	-y1 2001	Gets the HDF4 files from the MODIS tiles starting in this year. Earliest available is 2001
--end_year, -y2	integer	-y2 2021	Gets the HDF4 files from the MODIS tiles ending in this year. Latest available is 2021

Boundary files are available for use as areas of interest

For example, using the -sf option to select fire data for Colorado, USA.:

firedpy -sf ~/firedpy/firedpy/data/us_states/colorado.gpkg

Country boundaries are in data/individual_countries
Continent boundaries are in data/continents
United States state boundaries for the United States of America are in dat/us_states
Australian state boundaries are in data/australian_states
If using the ineractive option, when prompted for the name of the country, spaces will be replaced with spaces and case does not matter.

Have you used FIREDpy?

The algorithm and derived data products are under active development. Please raise an issue with any suggestions to help us improve firedpy. Or just email Adam and he will be overjoyed to talk about firedpy. If you'd like to contribute, check out the GitHub

Installation

There are two main ways to install firedpy. Method 1 is to install locally from source and method 2 is to run it out of a Docker container.

Method 1 - Install from source

1.1 Package Installer for Python (pip)

Step #1: Install the Geospatial Data Abstraction Library (GDAL). Installation depends on your OS.

macOS (brew)

brew install gdal

Linux (Debian/Ubuntu)

sudo apt update

sudo apt install gdal-bin libgdal-dev python3-gdal

Linux (Fedora/RHEL/CentOS/Rocky)

sudo dnf install gdal gdal-devel python3-gdal

Linux (Arch)

sudo pacman -Syu

sudo pacman -S gdal python-gdal

Windows
Recommended: install GDAL via Conda. Alternatively, use the OSGeo4W installer.

Step #2: Create and activate a Python environment.

macOS or Linux

mkdir ~/envs

python3 -m venv ~/envs/firedpy

source ~/envs/firedpy/bin/activate

Windows (CMD)

mkdir ~/envs

python3 -m venv ~/envs/firedpy

~/envs/firedpy/Scripts/activate.bat

Step #3: Install FIREDpy from source.

git clone https://github.com/earthlab/firedpy.git

cd firedpy

pip install .

1.2 Conda

Anaconda and its package manager conda work on macOS, Linux, and Windows.

Step #1: Install Anaconda or Miniconda.

Step #2: Clone the repository.

git clone https://github.com/earthlab/firedpy.git

cd firedpy

Step #3: Create the environment.

conda env create -f environment.yml

conda activate firedpy

Optional explicit environment path:

conda env create -f environment.yml --prefix /path/to/firedenv

conda activate /path/to/firedenv

Step #4: Install FIREDpy.

pip install .

Method 2 - Run from a Docker Container

2.1 Get the Docker container running

The container name changed from earthlab/firedpy to earthlabcu/firedpy.

docker run -d -p 127.0.0.1:0:7681 earthlabcu/firedpy:latest

Check running containers:

docker ps

Enter the container:

docker exec -it <container_name> /bin/bash

Example output:

CONTAINER ID	IMAGE	COMMAND	CREATED	STATUS	PORTS	NAMES
58a8a6ed926a	earthlabcu/firedpy:latest	"/bin/entry.sh ttyd …"	2 minutes ago	Up 2 minutes	127.0.0.1:32768→7681/tcp	stupefied_hypatia

2.2 Copy firedpy outputs to your local machine

Exit the container:

exit

Copy files out:

docker cp unruffled_clarke:/home/firedpy/proj/outputs/shapefiles/fired_events_s5_t11_2020153.gpkg /home/Documents/

Use

Create a .netrc file to avoid repeated authentication:

Earthdata .netrc instructions

Run the CLI:

firedpy --help

Example run:

firedpy --project_directory ~/scratch/firedpy_finland --country Finland

Interactive mode:

firedpy -i

More examples:

firedpy -p ~/scratch/firedpy_finland --country Finland --spatial_param 6 --temporal_param 10

firedpy -p ~/scratch/firedpy_nw_brazil --tiles "h11v09 h12v09" -sp 6 -tp 10

firedpy -p ~/scratch/firedpy_nw_brazil -t "h11v09 h12v09" -sp 6 -tp 10 --start_year 2020 --end_year 2024

firedpy -p ~/scratch/firedpy_nw_brazil -t "h11v09 h12v09" -sp 6 -tp 10 -y1 2020 -y2 2024 --eco_region_type 3

firedpy -p ~/scratch/firedpy_nw_brazil -t "h11v09 h12v09" -sp 6 -tp 10 -y1 2020 -y2 2024 --et 3 --land_cover_type 4 --daily

Firedpy by EarthLab