Skip to contents

Load CAMELS-PE daily timeseries data

Source: R/timeseries.R
load_pe_timeseries.Rd

Efficiently loads daily hydroclimatic timeseries for Peruvian catchments. Features an optimized dual-pathway execution engine using 'arrow' and 'collapse':

  • For selective requests, reads individual catchment files with column projection.

  • For global or multi-catchment requests, uses arrow::open_dataset() with predicate pushdown (filtering stations and date ranges directly at scan time) to minimize memory footprint and maximize throughput.

Usage

load_pe_timeseries(
  gauge_ids = NULL,
  variables = NULL,
  start_date = NULL,
  end_date = NULL,
  path = get_camels_pe_path(),
  parse_dates = TRUE,
  use_arrow = TRUE,
  global = FALSE
)

Arguments

gauge_ids

Character vector. Station/catchment identifiers (e.g. "PE_110139"). If NULL (default), loads timeseries for all available catchments.

variables

Character vector. Names of hydroclimatic variables to select. If NULL (default), all variables are loaded. Allowed variables: "prec", "prec_var", "flow_obs", "flow_sim", "pet", "tmin", "tmean", "tmax", "srad", "vprp".

start_date

Optional character string or Date object ("YYYY-MM-DD"). Start date for temporal filtering.

end_date

Optional character string or Date object ("YYYY-MM-DD"). End date for temporal filtering.

path

Character string. Path to the CAMELS-PE dataset directory. If NULL, retrieved automatically via get_camels_pe_path().

parse_dates

Logical. Should the date column be parsed into R Date objects? Default is TRUE.

use_arrow

Logical. Should the 'arrow' package be used for reading? Default is TRUE (recommended for high performance).

global

Logical. If TRUE, read the master CSV even for a small selection.

Value

A data.frame containing daily hydroclimatic timeseries data with at least date and gauge_id columns, plus the requested hydrometeorological variables.

Details

The common calendar is 1981-2025; unavailable observations remain NA. Streamflow is expressed in mm/day, precipitation variance (prec_var) in mm^2/day^2, solar radiation in MJ/m^2/day, and vapor pressure in hPa. Identifier columns date and gauge_id may also be requested in variables. Automatic routing compares selected CSV bytes plus a 4 MiB per-file opening cost estimate against the master CSV size. This heuristic avoids scanning the national file for small subsets while retaining it for large requests. Missing individual files fall back to the master when it is available. global = TRUE always forces the master. No data cache is created.

Examples

# Load timeseries for a specific station
ts_station <- load_pe_timeseries(gauge_ids = "PE_110139")
head(ts_station)
#>         date  gauge_id  prec prec_var flow_obs flow_sim   pet  tmin  tmean
#> 1 1981-01-01 PE_110139 0.265    0.011       NA    1.187 3.738 1.990  8.846
#> 2 1981-01-02 PE_110139 1.278    0.200       NA    1.089 3.522 3.623  9.562
#> 3 1981-01-03 PE_110139 3.587    0.628       NA    1.020 2.811 4.724  9.556
#> 4 1981-01-04 PE_110139 9.783    1.281       NA    1.132 2.895 5.903 10.837
#> 5 1981-01-05 PE_110139 2.322    0.107       NA    1.218 2.845 4.981  9.571
#> 6 1981-01-06 PE_110139 0.989    0.362       NA    1.271 2.573 3.683  8.743
#>     tmax   srad  vprp
#> 1 15.702 25.573 5.567
#> 2 15.501 23.722 5.686
#> 3 14.389 18.989 7.137
#> 4 15.772 17.982 7.841
#> 5 14.161 17.006 7.012
#> 6 13.804 15.851 7.179

# Load only precipitation and observed streamflow with date range filter
ts_sub <- load_pe_timeseries(
  gauge_ids = "PE_110139",
  variables = c("prec", "flow_obs"),
  start_date = "2000-01-01",
  end_date = "2000-03-31"
)
head(ts_sub)
#>         date  gauge_id  prec flow_obs
#> 1 2000-01-01 PE_110139 5.758       NA
#> 2 2000-01-02 PE_110139 3.417       NA
#> 3 2000-01-03 PE_110139 5.581       NA
#> 4 2000-01-04 PE_110139 5.377       NA
#> 5 2000-01-05 PE_110139 3.782       NA
#> 6 2000-01-06 PE_110139 7.771       NA