Import UNIPLU-BR: Unified Brazilian Rainfall Dataset

sus_climate_uniplu() downloads, caches, and imports data from the Unified Brazilian Rainfall Dataset (UNIPLU-BR) — the most comprehensive national rainfall database for Brazil, covering 21,000+ gauges from five monitoring networks over 140 years (1885–2025).

The function implements a full processing pipeline:

Download: Single 1.6 GB ZIP from Zenodo (first call only)
Extraction: Two Parquet files cached locally for instant re-use
Standardization: Column names aligned with climasus4r conventions
Filtering: By year, state (UF), and/or monitoring network
Aggregation: Sub-daily data optionally aggregated to daily/monthly/yearly totals

Usage

sus_climate_uniplu(
  years = NULL,
  uf = NULL,
  network = NULL,
  aggregate_to = "day",
  use_cache = TRUE,
  cache_dir = "~/.climasus4r_cache/climate",
  lang = "pt",
  verbose = TRUE
)

Arguments

years

Integer vector of year(s) to import. Examples: 2020, 2020:2024, c(2015, 2020, 2024). Must be between 1885 and the current year. If NULL (default), imports the last 2 years.

uf

Character vector of Brazilian state codes (e.g., "RN", c("SP", "RJ", "MG")). Case insensitive. If NULL (default), all 27 states are returned.

network

Character vector of monitoring network(s) to include. One or more of: "Hidroweb", "INMET", "ICEA", "CEMADEN", "Telemetria". Case insensitive. If NULL (default), all networks are returned.

aggregate_to

Character. Temporal resolution for aggregating sub-daily observations into totals. One of:

"day" (default): Daily rainfall totals (sum(rain_mm))
"month": Monthly rainfall totals
"year": Annual rainfall totals
"none": Return raw observations at original resolution

When "none", rainfall_mm reflects the raw measurement interval (10 min to 1440 min depending on network). Use "day" for compatibility with sus_climate_aggregate().

use_cache

Logical. If TRUE (default), skips download when the two Parquet files already exist in cache_dir/uniplu/. The full ZIP (~1.6 GB) is only downloaded once. Use use_cache = FALSE to force a re-download (e.g., after a new dataset version is published on Zenodo).

cache_dir

Character. Directory path for the disk cache. Default: "~/.climasus4r_cache/climate". Created automatically if absent. Use unlink(file.path(cache_dir, "uniplu"), recursive = TRUE) to clear the UNIPLU cache.

lang

Character. Message language. One of:

"pt": Portuguese (default)
"en": English
"es": Spanish

verbose

Logical. If TRUE (default), prints progress messages including cache status, download progress, filtering counts, and aggregation summary.

Value

A climasus_df object (subclass of tibble) at stage = "climate", type = "uniplu". Columns:

station_code: Character. Unique gauge identifier (from gauge_code)
station_name: Character. City name of the gauge (from city)
uf: Character. State abbreviation (from state)
latitude: Numeric. Decimal latitude, WGS84 (from lat)
longitude: Numeric. Decimal longitude, WGS84 (from long)
altitude: Numeric. Elevation in metres above sea level (from elevation)
network: Character. Source monitoring network
time_step_min: Integer. Original temporal resolution in minutes (e.g., 10, 60, 1440). Only present when aggregate_to = "none".
utc_offset: Numeric. Timezone offset from UTC (from utc). Only present when aggregate_to = "none".
date: POSIXct or Date. Observation timestamp / aggregation period
rainfall_mm: Numeric. Precipitation in millimetres (sum over aggregation period, or raw value when aggregate_to = "none")

Metadata (accessible via sus_meta()):

stage: "climate"
type: "uniplu"
source: "UNIPLU-BR"
doi: "10.5281/zenodo.18883358"
years: Years retained after filtering
ufs: States retained after filtering
networks: Networks retained after filtering
n_stations: Number of unique gauges
n_observations: Total rows
temporal: List with start, end, unit (aggregate_to)

Note

Data quality: The dataset is strictly structurally standardized. No outlier removal or physical consistency checks were applied by the data producers. Extreme or implausible values from source agencies remain. Consider applying your own quality filters for scientific analyses.
Download size: ~1.6 GB compressed. Only performed once; subsequent calls read from cached Parquet files (typically a few seconds).
Rainfall only: UNIPLU-BR contains precipitation exclusively. For multi-variable climate data (temperature, humidity, radiation), use sus_climate_inmet().
License: CC-BY-4.0. Cite the dataset and paper when publishing.

Monitoring Networks

Network	Operator	Period	Resolution
Hidroweb	ANA	1885–2025	Daily (1440 min)
INMET daily	INMET	1889–2025	Daily (1440 min)
ICEA	ICEA	1951–2025	Various
CEMADEN	CEMADEN	2014–2025	10–15 min
Telemetria	Various	2014–2025	10–60 min
INMET sub-daily	INMET	2000–2025	60 min

References

Dataset: Das Neves Almeida, C., Bertrand, G. F., Lemos, F. C., et al. (2026). Unified Brazilian Rainfall Dataset (UNIPLU-BR): A Standardized National Database of Point Precipitation from Major Brazilian Monitoring Networks (1885–2025). Zenodo. doi:10.5281/zenodo.18883358

Related paper: Das Neves Almeida, C., Bertrand, G. F., Lemos, F. C., et al. (2025). The design of the Brazilian Sub-Daily Rainfall dataset (BR-SDR): two decades of high-time-resolution data in Brazil. Hydrological Sciences Journal, 70(11), 1850–1862. doi:10.1080/02626667.2025.2506193

GitHub repository: https://github.com/LARHENA/UNIPLU-BR

Examples

if (FALSE) { # \dontrun{
# Daily rainfall for Rio Grande do Norte, last 2 years (default)
rain_rn <- sus_climate_uniplu(uf = "RN")

# Multiple states, specific years, daily totals
rain_ne <- sus_climate_uniplu(
  years = 2015:2024,
  uf    = c("RN", "CE", "PB", "PE"),
  aggregate_to = "day"
)

# Only ANA/Hidroweb network, monthly totals
rain_hidroweb <- sus_climate_uniplu(
  years   = 2000:2020,
  network = "Hidroweb",
  aggregate_to = "month"
)

# Raw sub-daily data (no aggregation)
rain_raw <- sus_climate_uniplu(
  years        = 2023,
  uf           = "SP",
  network      = "CEMADEN",
  aggregate_to = "none"
)

# Check metadata
sus_meta(rain_rn)

# Inspect stations
dplyr::distinct(rain_rn, station_code, station_name, latitude, longitude)

# Integrate with health data (requires prior sus_spatial_join())
health_climate <- sus_climate_aggregate(
  health_data  = health_spatial,
  climate_data = rain_rn,
  climate_var  = "rainfall_mm",
  temporal_strategy = "moving_window",
  window_days  = 14
)
} # }