Package {climateBR}

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)

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")
)

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())

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:

id_who

Character. INMET weather station identifier.

lat

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

long

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)

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)

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)

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 "Downloading meteorological data from Brazil with climateBR".
# 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)