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. 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.
Illustration of the event-level and daily-level output of FIREDpy for the 2013 Rim Fire in California. Figure is from Mahood et al. 2022.
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, see https://modis-land.gsfc.nasa.gov/MODLAND_grid.html. If you would like to use the MODIS sinusoidal grid IDs to identify FIREDpy study areas, see the visualization of this grid below.
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
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
Coming soon...
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 ([email protected]), University of Colorado Boulder.
- 10/14/2024 FIREDpy V2.0
- No longer using setup.py. See new instructions below for running it with Docker or installing it locally.
- Improved fire grouping
- Improved CLI
- Access to MODIS burn area product Version 6.1 with support up to at least December 2024
Many of the data products created in Fall 2021 may be shifted by a half pixel, and may lack a coordinate reference system.
The problem is now fixed, so this will not affect new iterations of firedpy.
Sometimes the server that houses the MCD64A1 product used by firedpy is down. If this happens, you just need to wait until it comes back up.
See the issues tab for more bugs, or to report a new bug!
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 [email protected] and Adam will be overjoyed to talk about firedpy.
Already-created products are linked 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.
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.
-
Step #1: Install the Geospatial Data Abstraction Library (GDAL) on your machine, if it is not installed already. The installation method depends on your operating system (OS) and package manager (for Linux and MacOS). Below are a subset of installation options (see the GDAL Documentation page for official downloads: https://gdal.org/en/stable/download.html).
MacOS (brew)
brew install gdal
Linux (Debian or Debian-derivatives such as Ubuntu):
sudo apt update sudo apt install gdal-bin libgdal-dev python3-gdal
Linux (Fedora, RHEL, CentOS, Rocky Linux, and other OSs that use dnf)
sudo dnf install gdal gdal-devel python3-gdal
Linux (Arch)
sudo pacman -Syu sudo pacman -S gdal python-gdal
Windows
The most commonly recommended approach for installing GDAL with Windows is to use the Conda method (described below), but you may also use the OSGeo4W network installer. Go to the OSGeo4W landing page and download and run the installer: https://trac.osgeo.org/osgeo4w/. More detailed installation instructions are available on that site.
-
Step 2: Create a Python environment and activate it. There are many options for doing this, one way is to use Python's virtual environment package as follows:
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: Now you may install FIREDpy from source using pip. Clone this repository, change directories into it, and install using the pip installation command:
git clone https://github.com/earthlab/firedpy.git cd firedpy pip install .
Anaconda and its package manager conda is a system-independent method and should work for MacOS, Linux, or Windows.
-
Step #1: Install Anaconda The installation method you use will depend on your operating system. Visit Conda's installation site, choose either
Miniconda,Anaconda Distribution, orMiniforge(all options should work well) and following the installation instructions there: https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html. The easiest way to find an installer is through this miniconda repository: https://repo.anaconda.com/miniconda/. -
Step #2: Clone this repository to a local folder and change directories into it:
git clone https://github.com/earthlab/firedpy.git cd firedpy -
Step 3: Use the
environment.ymlfile to create a conda environment with all dependencies, including the system-level GDAL libraries.conda env create -f environment.yml conda activate firedpy
-
Step 4: Install FIREDpy with pip.
pip install .
Note, the docker container has changed from earthlab/firedpy to earthlabcu/firedpy
-
Run the docker container in a detached state (-d) and bind it to an available port on localhost (-p 127.0.0.1:0:7681)
-
docker run -d -p 127.0.0.1:0:7681 earthlabcu/firedpy:latest -
Call
docker psto get the name of the docker container you just created and the port it is running on. -
Then get into the docker container by either running docker exec:
docker exec -it <silly_name> /bin/bash -
Or access the CLI from your browser. The output from docker ps will look like this:
| 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 |
In this example the container is running on the host machine at 127.0.0.1:32768. It may be different when you run it. Access this location in your browser by copy and pasting it into your browser's address bar
After creating a new fire product, it might be useful to get it out of the docker container in order to use it.
-
First, exit the docker container by typing
exit -
Second, copy the file out. Here we will use the example of a container with the name "unruffled_clarke". The
docker cpcommand uses the syntaxdocker cp <source> <destination>. Files inside of a docker container will have a prefix of the docker container name (or container ID) followed by a colon, then with a normal path.Here is an example command using the container name:
docker cp unruffled_clarke:/home/firedpy/proj/outputs/shapefiles/fired_events_s5_t11_2020153.gpkg /home/Documents/fired_events_s5_t11_2020153.gpkgAnother example command using the container ID:
docker cp fa73c6d3e007:/home/firedpy/proj/outputs/shapefiles/fired_events_s5_t11_2020153.gpkg /home/Documents/fired_events_s5_t11_2020153.gpkg
- Run the command line interface
firedpyorfiredpy --helpin your terminal for its help file:
firedpy --helpYou should see the help file with a description of the CLI and each of its options:
Usage: firedpy [OPTIONS]
firedpy command line interface.
Options:
--version Show the version and exit.
-i, --interactive Interactive Mode. Firedpy will prompt the user for all parameter
values and confirm selections before proceeding. Defaults to
False.
-p, --project_directory TEXT Interactive Mode. Firedpy will prompt the user for all parameter
values and confirm selections before proceeding. Defaults to
False. [required]
-n, --project_name TEXT A name used to identify the output files of this project. Defaults
to None, which will use the name of the parent run directory.
...Then you may either run the CLI with each non-default parameter you wish define. You must define the project directory to help avoid writing outputs in your current working directory. You must also define either a --tiles, --shape_file or --country option for your study area. Be careful, running with defaults and a fire-intensive study area can be a very resource intensive operation:
firedpy --project_directory ~/scratch/firedpy_finland --country FinlandYou may also run firedpy with the --interactive or -i flag to be prompted with input questions for each option:
firedpy -iIn this case, you will see a series of prompts starting with
Using interactive mode, please enter parameter values as prompted. Press enter to accept defaults if availabile (value in square brackets)
Project directory path. Inputs and outputs will all be written here. Required (Use "." for the present directory).: The following set of commands demonstrates how to run firedpy with increasingly detailed control over the run options:
-
Change the spatial and temporal parameters of the model run:
firedpy -project_directory ~/scratch/firedpy_finland --country Finland --spatial_param 6 --temporal_param 10 -
Specify specific MODIS tiles instead of a full country study area:
firedpy -p ~/scratch/firedpy_nw_brazil --tiles "h11v09 h12v09" -sp 6 -tp 10
-
Specify specific years to run (defaults to 2000 to 2025):
firedpy -p ~/scratch/firedpy_nw_brazil -t "h11v09 h12v09" -sp 6 -tp 10 --start_year 2020 --end_year 2024
-
Add the most common level 3 Ecoregion as an attribute to each event:
firedpy -p ~/scratch/firedpy_nw_brazil -t "h11v09 h12v09" -sp 6 -tp 10 -y1 2020 -y2 2024 --eco_region_type 3
-
Add landcover information and produce the daily burn file:
firedpy -p ~/scratch/firedpy_nw_brazil -t "h11v09 h12v09" -sp 6 -tp 10 -y1 2020 -y2 2024 --et 3 --land_cover_type 4 --daily
| 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. You will need to also make an account at https://urs.earthdata.nasa.gov/home |
| --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. The first year avalible is 2001 |
| --end_year | integer | -y2 2021 | Gets the HDF4 files from the MODIS tiles ending in this year. The last year avalible is 2021 |
- 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
- For example
firedpy -sf ~/firedpy/firedpy/data/us_states/colorado.gpkggets Colorado, USA. - If using the ineractive option, when prompted for the name of the country, spaces will be replaced with spaces and case does not matter.
- step 0.1. install docker (go to the docker website for OS-specific instructions.)
- step 0.2. get a dockerhub account
- step 1. login to docker hub via the command line
docker loginorsudo docker login
- step 2. get the existing docker image set up
- docker run -t -d earthlab/firedpy
- step 3. update from github
- git pull
- step 4. build the docker container
docker build -t earthlab/firedpy:latest .
- step 5. ENSURE THE SOFTWARE STILL WORKS BEFORE PUSHING
firedpy -aoi /home/firedpy/ref/individual_countries/samoa.gpkg
- step 6. push it up to dockerhub
docker push earthlab/firedpy:latest