PISCO_ARNOVIC v1.1 - README

============================================================
DESCRIPTION
============================================================
PISCO_ARNOVIC v1.1 is a national-scale hydrological dataset
providing simulated daily streamflow across Peru.

The dataset was developed using:
- PISCO gridded precipitation and temperature datasets
- ARNO/VIC rainfall-runoff model
- RAPID river routing model

It provides continuous daily discharge estimates for 11,913
river reaches (COMIDs), covering Peru and transboundary basins.

============================================================
DATA COMPONENTS
============================================================

1) NetCDF file
   - PISCO_ARNOVIC_v1.1.nc

2) River network (vector)
   - riv_pisco_arnovic_v1.1.gpkg

3) Catchments (vector)
   - cat_pisco_arnovic_v1.1.gpkg

============================================================
NETCDF DATA STRUCTURE
============================================================

Format: NetCDF (.nc)
Temporal resolution: Daily
Units: m3/s

Variables:

- comid
  Unique identifier of river reaches (COMID)

- time
  Time dimension (days since 1970-01-01, UTC)

- flow
  Simulated daily streamflow (m3/s)
  Dimensions: [time x comid]

Notes:
- Flow values correspond to routed discharge using RAPID
- Time is stored as UNIX time (seconds since 1970-01-01)

============================================================
SPATIAL DATA STRUCTURE
============================================================

All spatial data are provided in GeoPackage (.gpkg) format.

------------------------------------------------------------
1) River Network (riv_pisco_arnovic_v1.1.gpkg)
------------------------------------------------------------

Geometry: Line (river reaches)

Main attributes typically include:

- COMID
  Unique river reach identifier (links with NetCDF)

- Length / Length_km
  River reach length

- Upstream / Downstream IDs
  Connectivity within the river network

- Other hydraulic/topologic attributes may be included

Purpose:
- Defines the routing network used by RAPID
- Enables visualization and mapping of streamflow

------------------------------------------------------------
2) Catchments (cat_pisco_arnovic_v1.1.gpkg)
------------------------------------------------------------

Geometry: Polygon (subbasins)

Main attributes typically include:

- COMID
  Unique identifier matching the river reach outlet

- Area / Area_km2
  Catchment area

- Other physiographic attributes (if included)

Purpose:
- Defines contributing areas for each river reach
- Used for spatial aggregation and analysis

============================================================
LINK BETWEEN DATASETS
============================================================

The key linkage across all datasets is:

COMID

- NetCDF: identifies time series of streamflow
- River network: spatial location of flow
- Catchments: contributing drainage area

============================================================
ABBREVIATIONS
============================================================

PISCO    : Peruvian Interpolated data of SENAMHI observations
ARNOVIC  : ARNO/VIC hydrological model implementation
RAPID    : Routing Application for Parallel Computation of Discharge
COMID    : Unique identifier for river reaches

============================================================
NOTES AND LIMITATIONS
============================================================

- Streamflow values are simulated, not direct observations
- Model calibrated using 43 gauging stations (1981–2020)
- Suitable for regional and national-scale applications
- Local-scale use requires validation with observed data
- Uncertainty may increase in small catchments or ungauged regions

============================================================
EXAMPLE: READING DATA IN R
============================================================

# Load library
library(ncdf4)

# Inputs
nc_file <- "PISCO_ARNOVIC_v1.1.nc"
myCOMID <- 9072683

# Read NetCDF
nc    <- nc_open(nc_file)
comid <- ncvar_get(nc, "comid")
time  <- as.Date(as.POSIXct(ncvar_get(nc, "time"),
                            origin = "1970-01-01", tz = "UTC"))
flow  <- round(t(ncvar_get(nc, "flow")), 1)
nc_close(nc)

# Extract COMID
ind <- which(comid == myCOMID)
if (length(ind) == 0) stop("COMID not found")

df <- data.frame(Time = time, FLOW = flow[, ind])

# Plot
plot(df$Time, df$FLOW, type = "l", col = "blue",
     main = paste("COMID:", myCOMID),
     xlab = "Date",
     ylab = "Discharge (m3/s)")
grid()

# Export
write.csv(df, paste0("flow_", myCOMID, ".csv"),
          row.names = FALSE)

============================================================
ADDITIONAL RESOURCES
============================================================

COMID finder:
https://hllauca.github.io/PISCO_HyD_ARNOVIC_map/Identificar_COMID.html

HydroShare resource:
https://www.hydroshare.org/resource/f723d6c762ca45b6936dd9489bc44842/

============================================================
AUTHOR
============================================================

Harold Llauca
SENAMHI - Peru
hllauca@senamhi.gob.pe

============================================================