Package {climateBR}

Type:	Package
Title:	Download Rainfall, Temperature, and Wind Data from Brazil
Version:	0.2.0
Description:	Provides functions to download and import meteorological data from Brazil's National Institute of Meteorology (INMET) https://portal.inmet.gov.br.
License:	MIT + file LICENSE
Encoding:	UTF-8
LazyData:	true
LazyDataCompression:	xz
RoxygenNote:	7.3.3
Imports:	glue, arrow, dplyr, tidyr, janitor, data.table, pracma, purrr, tibble
Suggests:	knitr, rmarkdown, ggplot2, patchwork, geobr
Depends:	R (≥ 4.1.0), rlang, sf, gstat
VignetteBuilder:	knitr
URL:	https://github.com/kaiorb52/climateBR
BugReports:	https://github.com/kaiorb52/climateBR/issues
NeedsCompilation:	no
Packaged:	2026-08-19 11:03:01 UTC; kaio
Author:	Kaio Bárbara [aut, cre, cph]
Maintainer:	Kaio Bárbara <kaio.rbarbara@ufpe.br>
Repository:	CRAN
Date/Publication:	2026-08-19 13:40:09 UTC

Build a partitioned Arrow dataset from INMET CSV files

Description

Converts the raw CSV files downloaded from INMET into a partitioned Arrow/Parquet dataset optimized for fast querying with [read_inmet()].

Usage

build_inmet_dataset(
  input,
  output,
  years = 2000:2026,
  partitioning_by = c("ano", "codigo_wmo"),
  progress = TRUE
)

Arguments

Details

During the conversion, metadata are extracted from each file, column names are standardized, numeric variables are converted to numeric format, and the resulting dataset is partitioned by year ('ano') and WMO station code ('codigo_wmo').

This function only needs to be executed once for a collection of downloaded INMET files. After the dataset has been created, it can be accessed efficiently using [read_inmet()] without repeatedly parsing the original CSV files.

The resulting dataset is partitioned by year ('ano') and weather station ('codigo_wmo'), allowing Arrow to read only the files required by a query.

Value

Invisibly returns the output directory.

See Also

[download_inmet()], [read_inmet()]

Examples

build_inmet_dataset(
  input = file.path(tempdir(), "inmet_raw"),
  output = file.path(tempdir(), "inmet_arrow"),
  progress = FALSE
)

Download historical meteorological data from INMET

Description

Downloads historical weather station data from the Brazilian National Institute of Meteorology (INMET) and extracts the downloaded ZIP files into a user-specified directory.

Usage

download_inmet(years = 2008, unzip_to = tempdir(), progress = TRUE)

Arguments

Details

INMET provides historical observations dating back to 2000. However, only a small number of weather stations were operating in the early years of the dataset. For most applications, we recommend using data from **2008 onwards**, when the monitoring network became substantially more comprehensive.

Existing directories containing extracted files are skipped to avoid downloading the same data multiple times.

The downloaded files can subsequently be processed with [build_inmet_dataset()].

Value

This function is called for its side effects. ZIP files are downloaded, extracted into 'unzip_to', and the extracted files are stored on disk.

See Also

[build_inmet_dataset()], [read_inmet()]

Examples

## Download a single year
download_inmet(
  years = 2000,
  unzip_to = tempdir()
)

## Download multiple years
download_inmet(
  years = 2004:2006,
  unzip_to = tempdir()
)

Rainfall during the 2024 Rio Grande do Sul floods

Description

Dataset containing accumulated rainfall observed at meteorological stations operated by the Brazilian National Institute of Meteorology (INMET) during the extreme flooding event that affected Rio Grande do Sul, Brazil, in 2024.

Usage

floods_rs

Format

A data frame with 545 rows and 4 variables:

code_wmo

Character. World Meteorological Organization (WMO) identifier of the INMET weather station.

lat

Numeric. Latitude of the station in decimal degrees (WGS84).

lon

Numeric. Longitude of the station in decimal degrees (WGS84).

total_rainfall

Numeric. Total accumulated rainfall (mm) during the study period.

Details

The dataset contains 545 monitoring stations distributed across Brazil. Each row corresponds to a single INMET weather station and includes its identification code, geographic coordinates, and the total accumulated rainfall (in millimeters) recorded between April 27 and May 5, 2024.

Source

Brazilian National Institute of Meteorology (INMET).

Examples

head(floods_rs)
summary(floods_rs$total_rainfall)

INMET rainfall monitoring stations

Description

Dataset containing metadata for rainfall monitoring stations operated by the Brazilian National Institute of Meteorology (INMET). Each row represents a specific meteorological station collect based on data from 2000 to 2026.

Usage

inmet_stations

Format

A data frame with 700 rows and 6 variables:

state_station

Brazilian state abbreviation.

code_wmo

WMO station identifier.

lat

Station Latitude in decimal degrees (WGS84).

lon

Station Longitude in decimal degrees (WGS84).

creation_year

First year with available observations for the station.

last_used_year

Last year with available observations for the station.

Details

The dataset includes station identifiers, location information, state, municipality codes, and the first and last years in which data are available for each station.

Source

Instituto Nacional de Meteorologia (INMET).

Examples

data(inmet_stations)
head(inmet_stations)

Perform ordinary kriging interpolation of INMET observations

Description

Interpolates meteorological observations from INMET weather stations using ordinary kriging and predicts values for a set of target geometries, such as Brazilian municipalities.

Usage

kriging_inmet(stations_df, mun_geo, var = "total_rainfall")

Arguments

Details

The empirical variogram is estimated with [gstat::variogram()] and a spherical variogram model is fitted using [gstat::fit.variogram()]. Ordinary kriging is then performed with [gstat::krige()].

Both 'stations_df' and 'mun_geo' must use the same projected coordinate reference system (CRS). Using geographic coordinates (longitude/latitude) is not recommended for kriging because distance calculations are performed in map units.

Value

An 'sf' object containing the geometries from 'mun_geo' together with the kriging predictions:

* 'var1.pred' - Predicted values. * 'var1.var' - Prediction variance.

See Also

[gstat::krige()], [gstat::variogram()], [gstat::fit.variogram()]

Examples

# Requires spatial data (e.g., municipal boundaries) together with
# INMET stations observations. The example dataset `floods_rs`
# illustrates the required input format for the `stations_df` parameter. 
# See the vignette "Spatial Interpolation Using Ordinary Kriging" 
# for the complete workflow of this function.

## Not run: 

krig_df <- kriging_inmet(
  stations_df = inmet_data,
  mun_geo = municipalities_sf,
  var = "total_rainfall"
)

head(krig_df)

## End(Not run)

Nearest INMET Weather Stations for Brazilian Municipalities

Description

A dataset containing the five nearest INMET weather stations for each Brazilian municipality based on the distance between the municipality centroid and the station location.

Usage

mun_stations

Format

A tibble with 27,850 rows and 4 variables:

state_muni

Brazilian state abbreviation.

code_ibge7

Seven-digit IBGE municipality code.

code_wmo

World Meteorological Organization (WMO) identifier of the INMET weather station.

distance

Distance between the municipality centroid and the station, in kilometers.

station_order

Rank of the station by proximity, where 1 indicates the nearest station.

Details

Distances were calculated using the Haversine formula. Each municipality is associated with its five closest INMET stations, ordered by increasing distance.

The dataset was generated using the 'nearest_stations()' function from the climateBR package, matching municipality centroids to the five closest INMET weather stations available in the package's 'inmet_stations' dataset.

This dataset is based on the most recent version of the INMET station network available in the package. It is intended for analyses using recent observations. Because the INMET network changes over time (stations may be added or removed), this dataset should not be used to match historical data from earlier years. For historical analyses, users should create a year-specific municipality-to-station mapping using the corresponding historical INMET station

Source

Distances were computed from municipality centroid coordinates and INMET station coordinates using the Haversine formula.

Examples

data(mun_stations)
head(mun_stations)

Distance Between Brazilian Municipal Centroids and INMET Rainfall Stations

Description

A dataset containing the distances between the centroids of Brazilian municipalities and rainfall stations operated by the Brazilian National Institute of Meteorology (INMET). Distances were computed using the Haversine formula.

Usage

mun_stations_distance

Format

A data frame with the following variables:

code_muni

Seven-digit IBGE municipality code.

codigo_wmo

WMO identifier of the INMET rainfall station.

distance

Distance between the municipality centroid and the station, in kilometers.

i

Rank of the station by distance, where 1 indicates the nearest station.

ano

Reference year (2008, 2010, ..., 2024).

Details

The dataset covers the period from 2008 to 2024. Because the INMET station network changes over time, distances were calculated for snapshots taken every two years (2008, 2010, 2012, 2014, 2016, 2018, 2020, 2022, 2024).

Each municipality is associated with all available INMET stations for the corresponding year, ordered by increasing distance. The variable 'i' indicates the rank of the station according to its proximity to the municipality centroid.

Source

Distances computed from municipality centroids and INMET rainfall station coordinates using the Haversine formula.

Examples

data(mun_stations_distance)
head(mun_stations_distance)

Municipality Database

Description

Municipality Database

Usage

municipality

Format

A data frame with the following variables:

state_muni

Brazilian state abbreviation.

code_ibge7

Seven-digit IBGE municipality code.

code_ibge6

Six-digit IBGE municipality code.

code_tse

Six-digit IBGE municipality code.

lat

Municipality Centroid Latitude in decimal degrees (WGS84).

lon

Municipality Centroid Longitude in decimal degrees (WGS84).

Examples

data(municipality)
head(municipality)

Find the nearest INMET stations for each municipality

Description

Computes the great-circle distance between each municipality and all INMET stations, returning the 'n' nearest stations for every municipality.

Usage

nearest_stations(municipality, inmet_stations, n = 5)

Arguments

Value

A tibble with the columns:

state_muni

Brazilian state abbreviation.

code_ibge7

Municipality code.

code_wmo

INMET station code.

distance

Distance (in meters) between the municipality and station.

station_order

Rank of the station by distance, where 1 indicates the nearest station.

Examples

data("municipality")
data("inmet_stations")

mun_rs <- municipality[municipality$state_muni == "RS", ]

mun_stations1 <- nearest_stations(
  municipality = mun_rs,
  inmet_stations = inmet_stations,
  n = 1
)

# It is fine to include stations from other states. This is expected,
# as stations from neighboring states may be closer to municipalities
# near state borders.

mun_stations2 <- nearest_stations(
  municipality = mun_rs,
  inmet_stations = inmet_stations,
  n = 5
)

INMET rainfall monitoring stations by year

Description

Dataset containing metadata for rainfall monitoring stations operated by the Brazilian National Institute of Meteorology (INMET). Each row represents a meteorological station in a specific year between 2000 and 2024.

Usage

rain_stations

Format

A data frame with 9,459 rows and 11 variables:

uf

Brazilian state abbreviation.

estacao

Name of the meteorological station.

codigo_wmo

WMO station identifier.

ano

Reference year.

nome_formatado

Standardized station name.

frist_year

First year with available observations for the station.

last_year

Last year with available observations for the station.

id_ibge7

Seven-digit IBGE municipality code.

id_tse

Municipality code used by the Brazilian Electoral Court (TSE).

latitude

Latitude in decimal degrees (WGS84).

longitude

Longitude in decimal degrees (WGS84).

Details

The dataset includes station identifiers, location information, state, municipality codes, and the first and last years in which data are available for each station.

Source

Instituto Nacional de Meteorologia (INMET).

Examples

head(rain_stations)
unique(rain_stations$ano)

Read INMET meteorological observations

Description

Reads an INMET dataset previously created with [build_inmet_dataset()]. The dataset is accessed through the Arrow Dataset interface, allowing efficient filtering without loading all observations into memory.

Usage

read_inmet(
  path = NULL,
  years = NULL,
  stations = NULL,
  variables = NULL,
  collect = FALSE
)

Arguments

Details

The function performs filtering directly on disk whenever possible, making it suitable for working with large datasets.

Setting 'collect = TRUE' loads the selected observations into memory. This may require a large amount of RAM when reading many years or stations simultaneously. Consider filtering by year, station, or variables before collecting the data.

Value

If 'collect = FALSE', returns an Arrow Dataset query. If 'collect = TRUE', returns a data frame containing the selected observations.

See Also

[download_inmet()], [build_inmet_dataset()]

Examples

# Requires INMET data downloaded with download_inmet() and
# processed into an Arrow dataset with build_inmet_dataset().
# See the vignette "climateBR: An R package to download meteorological data from Brazil".
# for the complete workflow of this function.

## Not run: 

## Read a single year without loading the data into memory
rainfall_df1 <- read_inmet(
  path = dataset_dir,
  years = 2000,
  collect = FALSE
)

## Read multiple years and collect the results into memory
rainfall_df2 <- read_inmet(
  path = dataset_dir,
  years = 2000:2005,
  collect = TRUE
)

## For large datasets, keeping collect = FALSE is generally
## recommended to avoid excessive memory usage.

## End(Not run)