search

earthlab / firedpy

A Python Command Line Interface for classifying fire events from the Collection 6 MODIS Burned Area Product.
MIT License
37 stars 20 forks source link

readme

DOI Docker Automated build GitHub contributors GitHub issues GitHub commit activity

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

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

North America

Carribean Sea

South America

Entire Western hemisphere from Jan 2017 to March 2020, intended for use in conjunction with GOES16 active fire detections.

Europe

Africa

Asia

Australia

Australia (state by state)

Oceania

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

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.

Method 2. Local Installation Instructions:

Use:

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/individual_countries/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.
-proj_dir character -proj_dir /home/firedpy/proj which directory should firedpy operate within? Defaults to a folder called "proj" within the current working directory.
-ecoregion_type character -ecoregion_type na type of ecoregion, either world or na
-ecoregion_level integer -ecoregion_level 3 if ecoregion type = na, the level (1-3) of North American ecoregions
-landcover_type integer and character -landcover_type 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.
-shp_type character -shp_type gpkg option to build a shapefile for the fired event in gpkg, ESRI shapefile (shp), both, or none
-file character -file fired_colorado 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 fired_colorado_to2021031_events.gpkg.
-daily character (yes or no) -daily yes creates daily polygons, if no just the event-level perimeters will be created. Defaults to no.
-start_yr integer -start_yr 2001 gets the hdf files from the MODIS tiles starting in this year. The first year avalible is 2001
-end_yr 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

How to update the docker container