Skip to contents

Import Fire Hotspot Data for Brazilian Municipalities

Source: R/sus_grid_fires.R
sus_grid_fires.Rd

sus_grid_fires() downloads fire hotspot (active fire) data from INPE Queimadas or NASA FIRMS, optionally aggregates counts and Fire Radiative Power (FRP) to Brazilian municipalities, and returns a climasus_df compatible with sus_mod_dlnm() and sus_climate_anomaly().

Fire data is critical for respiratory health analyses in Brazil: smoke from agricultural burning (cerrado, cana-de-acucar) and deforestation fires (Amazonia) are associated with acute respiratory outcomes in SIH/SINAN data.

Sources available:

  • "inpe" (default) — INPE Queimadas portal. No authentication. Historical data from 1998 to present. Brazil only. DOI: doi:10.2312/inpe.2022.009

  • "firms_modis" — NASA FIRMS MODIS Collection 6.1. Requires a free MAP KEY from https://firms.modaps.eosdis.nasa.gov/api/map_key/. Global, 1 km resolution, 2000 to present.

  • "firms_viirs" — NASA FIRMS VIIRS SNPP. Same key as FIRMS MODIS. 375 m resolution, 2012 to present.

Usage

sus_grid_fires(
  years,
  months = 1:12,
  uf = NULL,
  bbox = NULL,
  source = c("inpe", "firms_modis", "firms_viirs"),
  municipalities = NULL,
  agg_fun = "count",
  biome = NULL,
  use_cache = TRUE,
  cache_dir = "~/.climasus4r_cache/fires",
  firms_key = NULL,
  lang = "pt",
  verbose = TRUE
)

Arguments

years

Numeric vector of years. INPE: 1998–present. FIRMS MODIS: 2000–present. FIRMS VIIRS: 2012–present.

months

Integer vector (1–12). Default 1:12.

uf

Character vector of state codes (e.g., c("MT", "PA")). Case-insensitive. NULL = all Brazil. Used to filter INPE queries and as a shortcut to define bbox for FIRMS.

bbox

Numeric vector c(xmin, ymin, xmax, ymax) in WGS84 longitude/ latitude. Used by FIRMS for spatial subsetting. If NULL and uf is provided, the bbox is computed from Brazilian state centroids. If both are NULL, Brazil's bounding box is used.

source

Character. Data source: "inpe" (default), "firms_modis", or "firms_viirs".

municipalities

An sf POLYGON object (e.g., from geobr::read_municipality()). When provided, fire points are spatially joined to polygons and aggregated to daily municipality-level counts. If NULL, the raw fire point data are returned as a climasus_df.

agg_fun

Character. Aggregation strategy when municipalities is provided. Currently "count" is supported (count of fire hotspots per municipality per day). Future versions may support "frp_sum".

biome

Character vector. INPE biome filter. Allowed values: "Amazonia", "Cerrado", "Mata Atlantica", "Caatinga", "Pampa", "Pantanal". NULL = no filter.

use_cache

Logical. Reuse previously downloaded CSV/JSON files. Default TRUE.

cache_dir

Character. Root cache directory. Default "~/.climasus4r_cache/fires".

firms_key

Character. NASA FIRMS MAP KEY. Defaults to Sys.getenv("FIRMS_MAP_KEY"). Required when source %in% c("firms_modis", "firms_viirs").

lang

Character. Message language: "pt" (default), "en", "es".

verbose

Logical. Print progress. Default TRUE.

Value

  • If municipalities is provided: a climasus_df with columns date (Date), code_muni (character), n_fires (integer count of hotspots), and frp_mean (mean Fire Radiative Power in MW, NA when not available). Metadata: stage = "climate", type = "fires".

  • If municipalities = NULL: a climasus_df with raw fire point columns: date, lat, lon, frp, biome, estado, source.

INPE Queimadas API

Queries https://queimadas.dgi.inpe.br/api/focos/ monthly. Each monthly request is cached as a JSON file. Large states in fire-season months may return truncated results due to the API's record limit; use uf to narrow the query when needed.

NASA FIRMS API

Queries https://firms.modaps.eosdis.nasa.gov/api/area/csv/{key}/{product}/{bbox}/10/{date} in 10-day chunks (maximum allowed per request). A free MAP KEY is required and must be activated at https://firms.modaps.eosdis.nasa.gov/api/map_key/.

See also

sus_grid_pollution_cams(), sus_climate_anomaly(), sus_mod_dlnm()

Examples

if (FALSE) { # \dontrun{
library(geobr)
mt_mun <- read_municipality(code_muni = "MT", year = 2020)

# INPE fire count for Mato Grosso municipalities, fire season 2020
fires <- sus_grid_fires(
  years          = 2020,
  months         = 7:10,
  uf             = "MT",
  municipalities = mt_mun,
  lang           = "pt"
)
sus_meta(fires, "stage")  # "climate"
sus_meta(fires, "type")   # "fires"

# Raw fire points for Amazonia, no aggregation
fires_pts <- sus_grid_fires(
  years  = 2022,
  months = 8,
  biome  = "Amazonia",
  lang   = "en"
)

# FIRMS MODIS with API key
Sys.setenv(FIRMS_MAP_KEY = "my_key")
fires_firms <- sus_grid_fires(
  years          = 2023,
  months         = 9,
  uf             = "MT",
  source         = "firms_modis",
  municipalities = mt_mun
)
} # }