FIREDpy - FIRe Event Delineation for python

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. Shapefiles include full event polygons 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.

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.

More methodological information is at:

Balch, J. K., St. Denis, L. A., Mahood, A. L., Mietkiewicz, N. P., Williams, T. P., 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 country-level data sets is at:

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

Changes

• 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 2024

BUG ALERT:

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. We created a script, R/posthoc_fixes.R that contains a function to fix either or both of these problems.

Sometimes the server (fuoco.geog.umd.edu) 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!

Have you used firedpy?

The algorithm and derived data products are under active development. Please take this survey to help us improve firedpy. Or just email admahood@gmail.com and Adam will be overjoyed to talk about firedpy.

Current status of created products

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. Many countries also have the daily-level shapefile, but these were not created for most countries in Africa and Asia due to computational restrictions.

Click on a link below to download a fire perimeter dataset for your favorite country

|| Firedpy version| 1.0|2.0|2.0| |-------|---------|----------------------------------------|----------------------------------------|---------------------------| | Region | Country | V2022 (variable space-time parameters) | V2024 (1 pixel 5 days for everything) | V2024 (variable ST-params) | | North America ||||| || Belize || Nov 2000 - July 2024 || || Canada| 2001-2021 | 2001-2024 || || Costa Rica || Nov 2000 - July 2024 || || El Salvador || Nov 2000 - July 2024|| || Guatemala || Nov 2000 - July 2024|| || Honduras || Nov 2000 - July 2024|| || Mexico || November 2000 - July 2024|| || Nicaragua || November 2000 - July 2024|| || Panama || November 2000 - July 2024|| || USA plus Canada | 2001-2021| November 2000 - July 2024|| || USA (Coterminous) + Alaska | 2001-2021 | 2001-2024|| || Hawaii | 2001-2021||| |Mexico and Central America |Belize, Guatemala, Honduras, El Salvador, Nicaragua, Costa Rica, Panama| 2001-2021|| |Carribean Sea ||||| |Whole region |Barbados, Bahamas, Cayman Islands, Cuba, Dominican Republic, Haiti, Jamaica, Montserrat, Puerto Rico, Saint Kitts And Nevis, Trinidad And Tobago, British Virgin Islands, Guadeloupe, Saint Barthelemy| 2001-2021 || || Aruba|| Nov 2000 - July 2024|| || Antigua and Barbuda|| Nov 2000 - July 2024|| || The Bahamas|| Nov 2000 - July 2024|| || Barbados|| Nov 2000 - July 2024|| || British Virgin Islands|| Nov 2000 - July 2024|| || Cayman Islands|| Nov 2000 - July 2024|| || Cuba|| Nov 2000 - July 2024|| || Curacao|| Nov 2000 - July 2024|| || Dominica|| Nov 2000 - July 2024|| || Dominican Republic|| Nov 2000 - July 2024|| || Grenada|| Nov 2000 - July 2024|| || Haiti|| Nov 2000 - July 2024|| || Jamaica|| Nov 2000 - July 2024|| || Montserrat|| Nov 2000 - July 2024|| || Puerto Rico|| November 2000 - July 2024|| || Saint Barthelemy|| November 2000 - July 2024|| || Saint Kitts and Nevis|| November 2000 - July 2024|| || Saint Martin|| November 2000 - July 2024|| || Trinidad and Tobago|| November 2000 - July 2024|| || Turks and Caicos|| November 2000 - July 2024|| || US Virgin Islands|| November 2000 - July 2024|| |South America ||||| || Argentina| 2001-2021| Nov 2000 - July 2024|| || Brazil| 2001-2021 |November 2000 - July 2024|| || Bolivia| 2001-2021||| || Chile| 2001-2021 |Nov 2000 - July 2024|| || Colombia| 2001-2021 |Nov 2000 - July 2024|| || Ecuador| 2001-2021| Nov 2000 - July 2024|| || Guyana|| Nov 2000 - July 2024|| || Paraguay| 2001-2021| Nov 2000 - July 2024|| || Peru| 2001-2021| November 2000 - July 2024|| || Suriname|| Nov 2000 - July 2024|| || Uruguay| 2001-2021 |November 2000 - July 2024|| || Venezuela| 2001-2021 |November 2000 - July 2024|| | Northern South America |Suriname, French Guiana, Guyana| 2001-2021||| |Entire Western hemisphere, intended for use in conjunction with GOES16 active fire detections. || Jan 2017 to March 2020||| | Europe ||||| || Aland|| Nov 2000 - July 2024|| || Albania|| Nov 2000 - July 2024|| || Andorra|| Nov 2000 - July 2024|| || Belarus|| Nov 2000 - July 2024|| || Belgium||Nov 2000 - July 2024|| || Bosnia and Herzegovina|| Nov 2000 - July 2024|| || Croatia|| Nov 2000 - July 2024|| || Cyprus|| Nov 2000 - July 2024|| || Czechia|| Nov 2000 - July 2024|| || Estonia|| Nov 2000 - July 2024|| || Finland| 2001-2021| Nov 2000 - July 2024|| || Germany|| Nov 2000 - July 2024|| || Greece| 2001-2021| Nov 2000 - July 2024|| || Greenland|| Nov 2000 - July 2024|| || Guernsey|| Nov 2000 - July 2024|| || Italy|2001-2021| Nov 2000 - July 2024|| || Kosovo|| Nov 2000 - July 2024|| || Latvia||Nov 2000 - July 2024|| || Liechtenstein|| Nov 2000 - July 2024|| || Lithuania|| Nov 2000 - July 2024|| || Macedonia|| Nov 2000 - July 2024|| || Malta|| November 2000 - July 2024|| || Moldova|| November 2000 - July 2024|| || Monaco|| November 2000 - July 2024|| || Montenegro|| November 2000 - July 2024|| || Netherlands|| November 2000 - July 2024|| || Northern Cyprus|| November 2000 - July 2024|| || Norway|| November 2000 - July 2024|| || Poland| 2001-2021| November 2000 - July 2024|| || Portugal|| November 2000 - July 2024|| || Romania|| November 2000 - July 2024|| || San Marino|| November 2000 - July 2024|| || Serbia|| November 2000 - July 2024|| || Slovakia|| November 2000 - July 2024|| || Slovenia|| November 2000 - July 2024|| || Spain|| November 2000 - July 2024|| || Sweden|| November 2000 - July 2024|| || Switzerland|| November 2000 - July 2024|| || Ukraine|| November 2000 - July 2024|| || United Kingdom|| November 2000 - July 2024|| |The British Isles|UK and Ireland| 2001-2021||| |The Iberian Peninsula| Spain & Portugal| 2001-2021||| | Western Europe |France, Germany, Poland, Switzerland, Belgium, Netherlands, Luxembourg and Austria| 2001-2021||| | Central to Southern Europe |Estonia, Latvia, Lithuania, Belarus, Ukraine, Czech Republic, Slovakia, Hungary, Romania, Bulgaria, Montenegro, Bosnia, Turkey, Republic Of Moldova, Serbia, Albania, Slovenia, and North Macedonia| 2001-2021||| | Northern Europe |Iceland, Sweden, Norway, and Denmark| 2001-2021||| | Africa||||| || Algeria:|| Nov 2000 - July 2024|| || Angola:| 2001-2021 |Nov 2000 - July 2024|| || Benin:| 2001-2021 |Nov 2000 - July 2024|| || Botswana:| 2001-2021| Nov 2000 - July 2024|| || Burundi:| 2001-2021 |Nov 2000 - July 2024|| || Burkina Faso:| 2001-2021| Nov 2000 - July 2024|| || Cabo Verde: ||Nov 2000 - July 2024|| || Cameroon:| 2001-2021| November 2000 - July 2024|| || Central African Republic: |2001-2021 |November 2000 - July 2024|| || Chad:| 2001-2021| November 2000 - July 2024|| || Comoros: ||Nov 2000 - July 2024|| || Democratic Republic of the Congo:| 2001-2021||| || Djibouti:| 2001-2021| Nov 2000 - July 2024|| || Egypt: ||Nov 2000 - July 2024|| || Equatorial Guinea:| 2001-2021 | Nov 2000 - July 2024|| || Eritrea:| 2001-2021 | Nov 2000 - July 2024|| || eSwatini:| 2001-2021| Nov 2000 - July 2024|| || Ethiopia:| 2001-2021||| || Gabon: |2001-2021| Nov 2000 - July 2024|| || The Gambia:| 2001-2021||| || Ghana: |2001-2021||| || Guinea: |2001-2021| Nov 2000 - July 2024|| || Guinea-Bissau:| 2001-2021||| || Ivory Coast: |2001-2021||| || Kenya:| 2001-2021 |Nov 2000 - July 2024|| || Lesotho:| 2001-2021 | Nov 2000 - July 2024|| || Liberia: |2001-2021 |Nov 2000 - July 2024|| || Libya: ||Nov 2000 - July 2024|| || Madagascar:| 2001-2021 |November 2000 - July 2024|| || Malawi: |2001-2021 |November 2000 - July 2024|| || Mali: |2001-2021| November 2000 - July 2024|| || Mauritania: |2001-2021| November 2000 - July 2024|| || Mauritius:|| Nov 2000 - July 2024|| || Morocco:| 2001-2021| Nov 2000 - July 2024|| || Mozambique: |2001-2021| Nov 2000 - July 2024|| || Namibia: |2001-2021| Nov 2000 - July 2024|| || Niger:| 2001-2021 |Nov 2000 - July 2024|| || Nigeria: |2001-2021||| || Republic of the Congo: |2001-2021| Nov 2000 - July 2024|| || Rwanda:| 2001-2021| Nov 2000 - July 2024|| || Sao Tome and Principe: ||Nov 2000 - July 2024|| || Senegal:| 2001-2021 |Nov 2000 - July 2024|| || Sierra Leone: |2001-2021 |Nov 2000 - July 2024|| || Somalia:| 2001-2021 |Nov 2000 - July 2024|| || Somaliland:| 2001-2021 |Nov 2000 - July 2024|| || South Africa:| 2001-2021 |Nov 2000 - July 2024|| || South Sudan:| 2001-2021 |Nov 2000 - July 2024|| || Sudan:| 2001-2021 |Nov 2000 - July 2024|| || Tanzania:| 2001-2021 |Nov 2000 - July 2024|| || Togo: |2001-2021 |Nov 2000 - July 2024|| || Tunisia:|| Nov 2000 - July 2024|| || Uganda:| 2001-2021| Nov 2000 - July 2024|| || Zambia:| 2001-2021 |Nov 2000 - July 2024|| || Zimbabwe| 2001-2021| Nov 2000 - July 2024|| | Central North Africa |Libya, Algeria, Tunisia| 2001-2021||| | Asia ||||| || Afghanistan || Nov 2000 - July 2024 || || Armenia ||Nov 2000 - July 2024|| || Azerbaijan|| Nov 2000 - July 2024|| || Bhutan| 2001-2021 |Nov 2000 - July 2024|| || Bangladesh|2001-2021 |Nov 2000 - July 2024|| || Bahrain|| Nov 2000 - July 2024|| || Cambodia|| Nov 2000 - July 2024|| || China| 2001-2021 | Nov 2000 - July 2024|| || India| 2001-2021||| || Israel|| Nov 2000 - July 2024|| || Iraq |||| || Iran|| Nov 2000 - July 2024|| || Japan|2001-2021||| || Kazakhstan|| Nov 2000 - July 2024|| || Kuwait|| Nov 2000 - July 2024|| || Kyrgyzstan|| Nov 2000 - July 2024|| || Lebanon|| Nov 2000 - July 2024 || Laos| 2001-2021| Nov 2000 - July 2024|| || Macao|| November 2000 - July 2024|| || Mongolia| 2001-2021 |November 2000 - July 2024|| || Myanmar| 2001-2021| November 2000 - July 2024|| || Nepal| 2001-2021| November 2000 - July 2024|| || North Korea| 2001-2021 |November 2000 - July 2024|| || Oman|| November 2000 - July 2024|| || Pakistan|| November 2000 - July 2024|| || Palestine|| November 2000 - July 2024|| || Qatar|| November 2000 - July 2024|| || Russia| 2001-2021 |November 2000 - July 2024|| || Saudi Arabia|| November 2000 - July 2024|| || South Korea| 2001-2021| November 2000 - July 2024|| || Sri Lanka| 2001-2021| November 2000 - July 2024|| || Syria|| November 2000 - July 2024|| || Taiwan| 2001-2021 |November 2000 - July 2024|| || Tajikistan|| November 2000 - July 2024|| || Thailand| 2001-2021 |November 2000 - July 2024|| || Turkmenistan|| November 2000 - July 2024|| || United Arab Emirates|| November 2000 - July 2024|| || Uzbekistan|| November 2000 - July 2024|| || Vietnam| 2001-2021| November 2000 - July 2024|| || Yemen|| November 2000 - July 2024|| | Caucasus |Armenia, Azerbaijan, Georgia| 2001-2021||| | Central Asia |Turkmenistan, Kazakhstan, Uzbekistan, Kyrgystan, Tajikistan, Afghanistan, and Pakistan| 2001-2021||| | Middle East |Saudi Arabia, Qatar, Oman, Yemen, United Arab Emirates, Iraq, Jordan, Syria, Israel, Palestine, Lebanon, Egypt| 2001-2021||| | Australia||||| || Whole Country || Nov 2000 - July 2024 || || (state by state) |||| ||Tasmania| 2001-2021||| || Victoria| 2001-2021||| || New South Wales + Capital Territory| 2001-2021||| || Queensland| 2001-2021||| || South Australia| 2001-2021||| || Western Australia| 2001-2021||| || Northern Territory| 2001-2021||| | Oceania || ||Philippines| 2001-2021 |Nov 2000 - July 2024|| || Papua New Guinea| 2001-2021 |Nov 2000 - July 2024|| || East Timor| 2001-2021 |Nov 2000 - July 2024|| || New Caledonia|| Nov 2000 - July 2024|| || New Zealand| 2001-2021| Nov 2000 - July 2024|| || Malaysia| 2001-2021| Nov 2000 - July 2024|| || Brunei| 2001-2021| Nov 2000 - July 2024|| || Indonesia| 2001-2021||| || Samoa|| November 2000 - July 2024|| || Singapore|| November 2000 - July 2024|| || Solomon Islands|| November 2000 - July 2024|| || Vanuatu|| November 2000 - July 2024||

Installation

There are two ways to install firedpy. Method one is to run it out of a docker container, Method 2 is to install locally.

Method 1. Run from a Docker Container:

1.1 Get the docker container running:

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 ps to 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

1.2 Copy firedpy outputs to your local machine

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 cp command uses the syntax docker 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.gpkg

  Another 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

Method 2. Local Installation Instructions:

• Clone this repository to a local folder and change directories into it:

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

  cd firedpy

• Ensure your anaconda setup has conda-forge, channel_priority set to strict, and update your conda.

  conda update conda --yes conda config --add channels conda-forge conda config --set channel_priority strict

• You must have all packages listed in the environment.yaml installed using 'conda install -c conda-forge '

• Create and activate a conda environment:

  conda env create -f environment.yml

  conda activate firedpy

Use:

• Run firedpy with no options to be prompted with input questions for each option/attribute

  python bin/firedpy.py or if running from Docker container, simply firedpy

• Or use the following commands in your command line to specify the options/attributes you would like:

• In your terminal use this command to print out the available options and their descriptions:

  python bin/firedpy.py --help

• Run firedpy with the default option to download required data and write a data table of classified fire events to a temporary directory. This uses CONUS as the default area of interest with a spatial parameter of 5 pixels (~2.3 km) and 11 days:

  python bin/firedpy.py --default

• Change the spatial and temporal parameters of the model run:

  python bin/firedpy.py -spatial 6 -temporal 10

• Specify specific tiles and a local project_directory for required data and model outputs:

  python bin/firedpy.py -spatial 6 -temporal 10 -aoi h11v09 h12v09 -proj_dir /home/<user>/fired_project

• Write shapefiles as outputs in addition to the data table:

  python bin/firedpy.py -spatial 6 -temporal 10 -aoi h11v09 h12v09 -proj_dir /home/<user>/fired_project --shapefile

• Add the most common level 3 Ecoregion as an attribute to each event:

  python bin/firedpy.py bin/firedpy.py -spatial 6 -temporal 10 -aoi h11v09 h12v09 -proj_dir /home/<user>/fired_project --shapefile -ecoregion_level 3

• Add landcover information and produce the daily burn file

  python bin/firedpy.py -spatial 6 -temporal 10 -aoi h11v09 h12v09 -proj_dir /home/<user>/fired_project --shapefile -ecoregion_level 3 -landcover_type 1 -daily yes

For more information about each parameter, use:

'python bin/firedpy.py --help'

Parameter table (under construction)

| parameter | value(s)| example | description| |:--------------|:----------|:-----|:---------| | -spatial | integer | -spatial 5 | pixel radius for moving window, defaults to 5| | -temporal | integer | -temporal 11 | day radius for moving window, defaults to 11| | -aoi | character (MODIS tile) | -aoi h11v09 | which modis tiles should be used | | -aoi | character (shapefile) | -aoi /home/firedpy/individualcountries/canada.gpkg | figures out which modis tiles to download based on the polygon -- polygon must be in the same projection as MODIS MCD64 -- all the polygons in the ref folder are correctly projected and can be used as crs templates to prepare other polygons. | | -projdir| character| -projdir /home/firedpy/proj | which directory should firedpy operate within? Defaults to a folder called "proj" within the current working directory.| | -ecoregiontype | character | -ecoregiontype na | type of ecoregion, either world or na| | -ecoregionlevel | integer | -ecoregionlevel 3 | if ecoregion type = na, the level (1-3) of North American ecoregions | | -landcovertype | integer and character | -landcovertype 2:username:password | 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 and include your login information within the argument. | | -shptype | character | -shptype gpkg | option to build a shapefile for the fired event in gpkg, ESRI shapefile (shp), both, or none | | -file | character | -file firedcolorado | specifies the base of the file name for the tables and shapefile outputs, defaults to "fired", in the format: "(-file aruguement)toYYYYDDD(either events or daily).gpkg", with YYYY being the year, and DDD being the julian day of the last month in the time series. The example would output firedcoloradoto2021031events.gpkg.| | -daily | character (yes or no) | -daily yes | creates daily polygons, if no just the event-level perimeters will be created. Defaults to no. | | -startyr |integer | -startyr 2001 | gets the hdf files from the MODIS tiles starting in this year. The first year avalible is 2001 | | -endyr |integer | -end_yr 2021 | gets the hdf files from the MODIS tiles ending in this year. The last year avalible is 2021 |

Boundary files are available for use as areas of interest

• Country boundaries are in ref/individual_countries
• Continent boundaries are in ref/continents
• United States state boundaries for the United States of America are in ref/us_states
• Australian state boundaries are in ref/australian_states
• For example python bin/firedpy.py -aoi /home/firedpy/ref/us_states/colorado.gpkg, and so on. Every space is a '_'.
• If using the user input option, when prompted for the name of the continent, country, or state use "_" for spaces.
• Ensure that the input shapefiles are in the modis sinusiodal projection

How to update the docker container

• 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 login or sudo 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