| Title: | Download Rainfall, Temperature, and Wind Data from Brazil |
|---|---|
| Description: | Provides functions to download and import meteorological data from Brazil's National Institute of Meteorology (INMET) <https://portal.inmet.gov.br>. |
| Authors: | Kaio Bárbara [aut, cre, cph] (ORCID: <https://orcid.org/0009-0003-4884-7980>) |
| Maintainer: | Kaio Bárbara <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.2.5 |
| Built: | 2026-10-12 16:13:50 UTC |
| Source: | https://github.com/kaiorb52/climatebr |
Converts the raw CSV files downloaded from INMET into a partitioned Arrow/Parquet dataset optimized for fast querying with [read_inmet()].
build_inmet_dataset( input, output, years = 2000:2026, partitioning_by = c("ano", "codigo_wmo"), region = "all", state = "all", progress = TRUE )build_inmet_dataset( input, output, years = 2000:2026, partitioning_by = c("ano", "codigo_wmo"), region = "all", state = "all", progress = TRUE )
input |
Character. Directory containing the raw CSV files downloaded with [download_inmet()]. |
output |
Character. Directory where the partitioned Arrow/Parquet dataset will be written. |
years |
Integer vector. Years of INMET data in 'input' to convert into the Arrow/Parquet dataset. Defaults to '2000:2026'. |
partitioning_by |
Character vector. Variable(s) used to partition the dataset; each variable creates one level of Parquet folders. Defaults to 'c("ano", "codigo_wmo")'. |
region |
Character vector. INMET region abbreviation(s) to filter (e.g. '"NE"', '"SE"'). Defaults to '"all"', which applies no filter. |
state |
Character vector. Brazilian state abbreviation(s) ('uf') to filter (e.g. '"BA"', '"SP"'). Defaults to '"all"', which applies no filter. |
progress |
Logical. If 'TRUE' (default), displays a progress bar while processing the INMET files. |
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 default) 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.
With the default partitioning by year ('ano') and weather station ('codigo_wmo'), Arrow reads only the files required by a query.
Invisibly returns the output directory.
[download_inmet()], [read_inmet()]
## Not run: build_inmet_dataset( input = file.path(tempdir(), "inmet_raw"), output = file.path(tempdir(), "inmet_arrow"), progress = FALSE ) ## End(Not run)## Not run: build_inmet_dataset( input = file.path(tempdir(), "inmet_raw"), output = file.path(tempdir(), "inmet_arrow"), progress = FALSE ) ## End(Not run)
Downloads historical weather station data from the Brazilian National Institute of Meteorology (INMET) and extracts the downloaded ZIP files into a user-specified directory.
download_inmet(years = 2008, unzip_to = tempdir(), progress = TRUE)download_inmet(years = 2008, unzip_to = tempdir(), progress = TRUE)
years |
Integer vector specifying the years to download. Historical data are available from 2000 onwards. The default is '2008'. |
unzip_to |
Character. Directory where the downloaded files will be extracted. |
progress |
Logical. If 'TRUE' (default), displays a progress bar while downloading the INMET files. |
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()].
This function is called for its side effects. ZIP files are downloaded, extracted into 'unzip_to', and the extracted files are stored on disk.
[build_inmet_dataset()], [read_inmet()]
## Not run: ## Download a single year download_inmet( years = 2000, unzip_to = tempdir() ) ## Download multiple years download_inmet( years = 2004:2006, unzip_to = tempdir() ) ## End(Not run)## Not run: ## Download a single year download_inmet( years = 2000, unzip_to = tempdir() ) ## Download multiple years download_inmet( years = 2004:2006, unzip_to = tempdir() ) ## End(Not run)
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.
floods_rsfloods_rs
A data frame with 565 rows and 4 variables:
Character. World Meteorological Organization (WMO) identifier of the INMET weather station.
Numeric. Latitude of the station in decimal degrees (WGS84).
Numeric. Longitude of the station in decimal degrees (WGS84).
Numeric. Total accumulated rainfall (mm) during the study period.
The dataset contains 565 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.
Brazilian National Institute of Meteorology (INMET).
head(floods_rs) summary(floods_rs$total_rainfall)head(floods_rs) summary(floods_rs$total_rainfall)
Dataset containing metadata for rainfall monitoring stations operated by the Brazilian National Institute of Meteorology (INMET). Each row is one station, compiled from INMET data from 2000 to 2026.
inmet_stationsinmet_stations
A data frame with 700 rows and 6 variables:
Brazilian state abbreviation.
WMO station identifier.
Station latitude in decimal degrees (WGS84).
Station longitude in decimal degrees (WGS84).
First year with available observations for the station.
Last year with available observations for the station. 'NA' if the station is still active.
The dataset includes the station identifier, state, location, and the first and last years with available data for each station.
Instituto Nacional de Meteorologia (INMET).
data(inmet_stations) head(inmet_stations)data(inmet_stations) head(inmet_stations)
Interpolates meteorological observations from INMET weather stations using ordinary kriging and predicts values for a set of target geometries, such as Brazilian municipalities.
kriging_inmet(stations_df, mun_geo, var = "total_rainfall")kriging_inmet(stations_df, mun_geo, var = "total_rainfall")
stations_df |
An 'sf' object containing weather station observations. The object must include point geometries and a numeric column corresponding to the variable specified in 'var'. |
mun_geo |
An 'sf' object containing the target geometries where predictions will be generated. |
var |
Character. Name of the numeric variable to interpolate. Defaults to '"total_rainfall"'. |
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.
An 'sf' object containing the geometries from 'mun_geo' together with the kriging predictions:
* 'var1.pred' - Predicted values. * 'var1.var' - Prediction variance.
[gstat::krige()], [gstat::variogram()], [gstat::fit.variogram()]
# Requires spatial data (e.g., municipal boundaries) together with # INMET station observations. The example dataset `floods_rs` # shows the input format required by `stations_df`. # See the vignette "Spatial Interpolation Using Ordinary Kriging" # for the complete workflow. ## Not run: krig_df <- kriging_inmet( stations_df = inmet_data, mun_geo = municipalities_sf, var = "total_rainfall" ) head(krig_df) ## End(Not run)# Requires spatial data (e.g., municipal boundaries) together with # INMET station observations. The example dataset `floods_rs` # shows the input format required by `stations_df`. # See the vignette "Spatial Interpolation Using Ordinary Kriging" # for the complete workflow. ## Not run: krig_df <- kriging_inmet( stations_df = inmet_data, mun_geo = municipalities_sf, var = "total_rainfall" ) head(krig_df) ## End(Not run)
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.
mun_stationsmun_stations
A tibble with 27,850 rows and 5 variables:
Brazilian state abbreviation.
Seven-digit IBGE municipality code.
World Meteorological Organization (WMO) identifier of the INMET weather station.
Distance between the municipality centroid and the station, in kilometers.
Rank of the station by proximity, where 1 indicates the nearest station.
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 with [nearest_stations()], matching each municipality centroid to the five closest stations in the 'inmet_stations' dataset.
It reflects the most recent INMET station network and is intended for analyses of recent observations. Because stations are added and removed over time, do not use it to match data from earlier years. For historical analyses, use 'mun_stations_distance' or build a year-specific mapping with [nearest_stations()] and the station network of that year.
Distances were computed from municipality centroid coordinates and INMET station coordinates using the Haversine formula.
data(mun_stations) head(mun_stations)data(mun_stations) head(mun_stations)
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.
mun_stations_distancemun_stations_distance
A data frame with 501,390 rows and 5 variables:
Seven-digit IBGE municipality code.
WMO identifier of the INMET rainfall station.
Distance between the municipality centroid and the station, in kilometers.
Rank of the station by distance, where 1 indicates the nearest station.
Reference year (2008, 2010, ..., 2024).
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).
For each year, each municipality is matched to its 10 nearest INMET stations within the same Brazilian macro-region, ordered by increasing distance. The variable 'i' is the rank of the station by proximity to the municipality centroid.
Distances computed from municipality centroids and INMET rainfall station coordinates using the Haversine formula.
data(mun_stations_distance) head(mun_stations_distance)data(mun_stations_distance) head(mun_stations_distance)
Dataset with the IBGE and TSE codes, state, and centroid coordinates of each Brazilian municipality.
municipalitymunicipality
A data frame with 5,570 rows and 6 variables:
Brazilian state abbreviation.
Seven-digit IBGE municipality code.
Six-digit IBGE municipality code.
Municipality code used by the Brazilian Superior Electoral Court (TSE).
Latitude of the municipality centroid in decimal degrees (WGS84).
Longitude of the municipality centroid in decimal degrees (WGS84).
data(municipality) head(municipality)data(municipality) head(municipality)
Computes the great-circle distance between each municipality and all INMET stations, returning the 'n' nearest stations for every municipality.
nearest_stations(municipality, inmet_stations, n = 5)nearest_stations(municipality, inmet_stations, n = 5)
municipality |
A data frame containing the municipality coordinates. Must include the columns 'code_ibge7', 'lat', and 'lon'. |
inmet_stations |
A data frame containing the INMET station coordinates. Must include the columns 'code_wmo', 'lat', and 'lon'. |
n |
Number of nearest stations to return for each municipality. |
A tibble with the columns:
Brazilian state abbreviation.
Seven-digit IBGE municipality code.
WMO identifier of the INMET station.
Distance (in kilometers) between the municipality and the station.
Rank of the station by distance, where 1 indicates the nearest station.
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 ) # Stations from other states may be returned. This is expected: # municipalities near state borders may be closer to a station in a # neighboring state. mun_stations2 <- nearest_stations( municipality = mun_rs, inmet_stations = inmet_stations, n = 5 )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 ) # Stations from other states may be returned. This is expected: # municipalities near state borders may be closer to a station in a # neighboring state. mun_stations2 <- nearest_stations( municipality = mun_rs, inmet_stations = inmet_stations, n = 5 )
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.
rain_stationsrain_stations
A data frame with 9,459 rows and 11 variables:
Brazilian state abbreviation.
Name of the meteorological station.
WMO station identifier.
Reference year.
Standardized station name.
First year with available observations for the station.
Last year with available observations for the station.
Seven-digit IBGE municipality code.
Municipality code used by the Brazilian Electoral Court (TSE).
Latitude in decimal degrees (WGS84).
Longitude in decimal degrees (WGS84).
The dataset includes the station identifier, name, state, location, municipality codes, and the first and last years with available data for each station.
Instituto Nacional de Meteorologia (INMET).
head(rain_stations) unique(rain_stations$ano)head(rain_stations) unique(rain_stations$ano)
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.
read_inmet( path = NULL, years = NULL, stations = NULL, variables = NULL, collect = FALSE )read_inmet( path = NULL, years = NULL, stations = NULL, variables = NULL, collect = FALSE )
path |
Character. Path to the directory containing the processed INMET dataset. |
years |
Integer vector of years to read. If 'NULL', all available years are returned. |
stations |
Character vector of WMO station codes. If 'NULL', all stations are returned. |
variables |
Character vector of variables (columns) to return. If 'NULL', all variables are returned. |
collect |
Logical. If 'TRUE', the filtered dataset is collected into memory as a data frame. If 'FALSE' (default), an Arrow Dataset query is returned. |
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 at once. Filter by year, station, or variable before collecting the data.
If 'collect = FALSE', returns an Arrow Dataset query. If 'collect = TRUE', returns a data frame containing the selected observations.
[download_inmet()], [build_inmet_dataset()]
# 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. ## 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)# 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. ## 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)