| Title: | UK National River Flow Archive Data from R |
| Version: | 2.1.0.7 |
| Description: | Utility functions to retrieve data from the UK National River Flow Archive (https://nrfa.ceh.ac.uk/, terms and conditions:https://nrfa.ceh.ac.uk/help/costs-terms-and-conditions). The package contains R wrappers to the UK NRFA data temporary-API. There are functions to retrieve stations falling in a bounding box, to generate a map and extracting time series and general information. The package is fully described in Vitolo et al (2016) "rnrfa: An R package to Retrieve, Filter and Visualize Data from the UK National River Flow Archive"https://journal.r-project.org/archive/2016/RJ-2016-036/RJ-2016-036.pdf. |
| License: | GPL-3 |
| URL: | https://ilapros.github.io/rnrfa/ |
| BugReports: | https://github.com/ilapros/rnrfa/issues |
| Depends: | R (≥ 3.5) |
| Imports: | curl, ggmap (≥ 4.0.0), ggplot2, graphics, httr, jsonlite,lubridate, parallel, sf, stats, tibble, utils, zoo |
| Suggests: | DT, dygraphs, knitr, leaflet, rmarkdown, spelling, testthat |
| VignetteBuilder: | knitr |
| Encoding: | UTF-8 |
| Repository: | CRAN |
| RoxygenNote: | 7.3.2 |
| Language: | en-US |
| NeedsCompilation: | no |
| Packaged: | 2025-08-25 14:06:25 UTC; ilari |
| Author: | Ilaria Prosdocimi [ctb, cre], Claudia Vitolo [aut] (Claudia is the original creator of the package), Matthew Fry [ctb] (Matthew supervised the unofficial API integration.), Wouter Buytaert [ctb] (This package is part of Claudia Vitolo's PhD work and Wouter is the supervisor.), Michael Spencer [ctb] (Michael updated the function osg_parse to work with grid references of different lengths.), Tobias Gauster [ctb] (Tobias improved the function osg_parse introducing vectorisation) |
| Maintainer: | Ilaria Prosdocimi <prosdocimi.ilaria@gmail.com> |
| Date/Publication: | 2025-08-25 14:30:08 UTC |
UK National River Flow Archive data from R
Description
rnrfa: UK National River Flow Archive Data from R.
Details
Utility functions to retrieve data from the UK National River Flow Archive(https://nrfa.ceh.ac.uk/). The package contains R wrappers to the UK NRFA datatemporary-API. There are functions to retrieve stations falling in a boundingbox, to generate a map and extracting time series and general information.
List of stations from UK NRFA
Description
This function pulls the list of stations (and related metadata),falling within a given bounding box, from the CEH National River Flow Archivewebsite.
Usage
catalogue( bbox = NULL, column_name = NULL, column_value = NULL, min_rec = NULL, all = TRUE)Arguments
bbox | this is a geographical bounding box (e.g. list(lon_min = -3.82,lon_max = -3.63, lat_min = 52.43, lat_max = 52.52)) |
column_name | name of column to filter |
column_value | string to search in column_name |
min_rec | minimum number of recording years |
all | if TRUE it returns all the available metadata. If FALSE, itreturns only the following columns: id, name, river, hydrometricArea,catchmentArea, lat, lon, selected feh catchment descriptors. |
Details
coordinates of bounding box are required in WGS84 (EPSG: 4326).If BB coordinates are missing, the function returns the list corresponding tothe maximum extent of the network.
Value
tibble table containing the list of stations and related metadata
Author(s)
Claudia Vitolo
Examples
## Not run: # Retrieve all the stations in the network x <- catalogue() # Define a bounding box: bbox <- list(lon_min=-3.82, lon_max=-3.63, lat_min=52.43, lat_max=52.52) # Get stations within the bounding box x <- catalogue(bbox) # Get stations based on minimum catchment area x <- catalogue(column_name = "catchment-area", column_value = 2000) # Get stations based on minimum number of recording years x <- catalogue(min_rec=30)## End(Not run)This function retrieves Catchment Mean Rainfall (cmr).
Description
Given the station ID number(s), this function retrieves data(time series in zoo format with accompanying metadata) from the WaterML2service on the NRFA database. Catchment Mean Rainfall is measured inmm/month.
Usage
cmr(id, metadata = FALSE, cl = NULL, verbose = FALSE)Arguments
id | station ID number(s), each number should be in the range[3002,236051]. |
metadata | Logical, FALSE by default. If metadata = TRUE means that theresult for a single station is a list with two elements:data (the time series) and meta (metadata). |
cl | (optional) This is a cluster object, created by the parallelpackage. This is set to NULL by default, which sends sequential calls to theserver. |
verbose | (FALSE by default). If set to TRUE prints GET request on theconsole. |
Value
list composed of as many objects as in the list of station IDnumbers. Each object can be accessed using their names or index(e.g. x[[1]], x[[2]], and so forth). Each object contains a zoo time series.
Author(s)
Claudia Vitolo
Examples
## Not run: cmr(18019) cmr(c(54022,54090,54091))## End(Not run)Convert flow from cumecs to mm/d
Description
This function converts flow time series from cumecs (m3/s) tomm/d by dividing the flow by the catchment area and converting it to mm/day.
Usage
convert_flow(flow_cumecs, catchment_area)Arguments
flow_cumecs | This is the flow time series in cumecs (m3/s) |
catchment_area | This is the catchment are in Km2. |
Value
Flow time series in mm/d
Examples
## Not run: convert_flow(30, 2)## End(Not run)This function retrieves Gauged Daily Flow (gdf).
Description
Given the station ID number(s), this function retrieves data(time series in zoo format with accompanying metadata) from the WaterML2service on the NRFA database. Gauged Daily Flow is measured inm^3/s.
Usage
gdf(id, metadata = FALSE, cl = NULL)Arguments
id | station ID number(s), each number should be in the range[3002,236051]. |
metadata | Logical, FALSE by default. If metadata = TRUE means that theresult for a single station is a list with two elements:data (the time series) and meta (metadata). |
cl | (optional) This is a cluster object, created by the parallelpackage. This is set to NULL by default, which sends sequential calls to theserver. |
Value
list composed of as many objects as in the list of station IDnumbers. Each object can be accessed using their names or index(e.g. x[[1]], x[[2]], and so forth). Each object contains a zoo time series.
Author(s)
Claudia Vitolo
Examples
## Not run: gdf(18019) gdf(c(54022,54090,54091))## End(Not run)This function retrieves time series data.
Description
Given the station identification number(s), this functionretrieves data (time series in zoo format with accompanying metadata) fromthe WaterML2 service on the NRFA database. The time series can be of twotypes:cmr (catchment mean rainfall, monthly) orgdf(gauged daily flows, daily).
Usage
get_ts(id, type, metadata = FALSE, cl = NULL, full_info = FALSE)Arguments
id | station identification number(s), each number should be in therange [3002,236051]. |
type | The following data-types are available:
|
metadata | Logical, FALSE by default. When metadata = TRUE theresult for a single station is a list with two elements: data (the timeseries) and meta (metadata). |
cl | (optional) This is a cluster object, created by the parallelpackage. This is set to NULL by default, which sends sequential calls to theserver. |
full_info | Logical, FALSE by default. If full_info = TRUE, the functionwill retrieve information on rejected periods. |
Value
list composed of as many objects as in the list of stationidentification numbers. Each object can be accessed using their names orindexes (e.g. x[[1]], x[[2]], and so forth). Each object contains a timeseries of classzoo/xts.
Author(s)
Claudia Vitolo
Examples
## Not run: get_ts(18019, type = "cmr") get_ts(c(54022,54090,54091), type = "cmr") get_ts(18019, type = "gdf") get_ts(c(54022,54090,54091), type = "gdf") plot(get_ts(id = 23001, type = "ndf")) plot(get_ts(id = 23001, type = "nmf"))## End(Not run)Converts OS Grid Reference to BNG/WGS coordinates.
Description
This function converts an Ordnance Survey (OS) grid reference toeasting/northing or latitude/longitude coordinates.
Usage
osg_parse(grid_refs, coord_system = c("BNG", "WGS84"))Arguments
grid_refs | This is a string (or a character vector) that contains theOS grid Reference. |
coord_system | By default, this is "BNG" which stands for BritishNational Grids. The other option is to set coord_system = "WGS84", whichreturns latitude/longitude coordinates (more info can be found herehttps://www.epsg-registry.org/). |
Value
vector made of two elements: the easting and northing (by default) orlatitude and longitude coordinates.
Author(s)
Claudia Vitolo (Ilaria Prosdocimi ported to sf)
Examples
## Not run: # single entry osg_parse(grid_refs = "TQ722213") # multiple entries osg_parse(grid_refs = c("SN831869","SN829838")) # multiple entries with missing values, NA will be returned osg_parse(grid_refs = c("SN831869",NA, "SN829838", NA))## End(Not run)Plot rainfall and flow for a given station
Description
This function retrieves rainfall and flow time series for agiven catchment, divides the flow by the catchment area and converts it tomm/day to that it can be comparable with the rainfall (mm/month). Finally itgenerates a plots combining rainfall and flow information.
Usage
plot_rain_flow(id = NULL, rain = NULL, flow = NULL, area = NULL, title = "")Arguments
id | Station identification number |
rain | Rainfall time series, measured in mm/month |
flow | Flow time series, measured in m3/s |
area | Catchment area in Km2 |
title | (optional) Plot title |
Value
Plot rainfall and flow for a given station
Examples
## Not run: plot_rain_flow(id = 54090)## End(Not run)Plot trend
Description
This function plots a previously calculated trend.
Usage
plot_trend(df, column_name, maptype = "stamen_toner_lite", showmap = TRUE)Arguments
df | Data frame containing at least 4 column:lat (latitude), lon (longitude), slope and an additional user-defined column |
column_name | name of the column to use for grouping the results. |
maptype | maptype, was need to choose the stamenmap type, now useless sincestamenmap are no longer reachable |
showmap | set to FALSE to avoid plotting the map when running the function |
Details
The function relies on the 'ggmap' package for the map, and this package has in time gone through many changes due to changes in API of map providers. Currently to be able to create the map one needs to register to the stadiamapsservice. More information at ?ggmap::register_stadiamaps().
Value
Two plots, the first showing the distribution of thetrend over a map, based on the slope of the linear model that describes thetrend. The second plot shows a boxplot of the slope grouped based on thecolumncolumn_name and slope can be user-defined (notice that in the plot the very extreme slope values are not displayed to avoid skewed visualisations).
Examples
## Not run: # some fake data around London df <- data.frame(lat = 51.5+runif(40,-0.3,0.3), lon = 0+runif(40, -0.3,0.3), slope = rnorm(40, c(rep(-0.4,20),rep(0.4,20))), g = factor(c(rep("a",20), rep("b",20)))) theplots <- plot_trend(df, "g", maptype = "terrain-background") theplots$A # map theplots$B + labs(subtitle = "Use ggplot usual commands to modify the plots") # boxplots ## End(Not run)print.nrfa_api
Description
Not to be used by user. Internal function used to print error in nrfaapi.
Usage
## S3 method for class 'nrfa_api'print(x, ...)Arguments
x | an nrfa call |
... | additional items, not really used |
Calculate seasonal averages
Description
This calculates the seasonal averages from a time series.
Usage
seasonal_averages(timeseries, season = "Spring")Arguments
timeseries | Time series (zoo class). |
season | Name of the season, which corresponds to a quarter:Winter (Q1), Spring (Q2), Summer (Q3), Autumn (Q4) |
Value
A vector containing the seasonal average and significance level(p-value) for each time series.
Examples
## Not run: seasonal_averages(timeseries = cmr(18019), season = "Spring") seasonal_averages(list(cmr(18019), cmr(18019)), season = "Spring")## End(Not run)List of stations identification numbers from UK NRFA
Description
This function pulls the list of station identification numbers.
Usage
station_ids()Value
vector integer identification numbers (one for each station)
Author(s)
Claudia Vitolo
Examples
## Not run: # Retrieve all the stations ids x <- station_ids()## End(Not run)