,
Luke Shaw [aut] (Luke developped the code to handle the missing and gap
periods for Peaks over threshold records.)| Title: | Interact with Peak Flow Data in the United Kingdom |
|---|---|
| Description: | Obtain information on peak flow data from the National River Flow Archive (NRFA) in the United Kingdom, either from the Peak Flow Dataset files <https://nrfa.ceh.ac.uk/peak-flow-dataset> once these have been downloaded to the user's computer or using the NRFA's API. These files are in a format suitable for direct use in the 'WINFAP' software, hence the name of the package. |
| Authors: | Ilaria Prosdocimi [aut, cre] ,
Luke Shaw [aut] (Luke developped the code to handle the missing and gap
periods for Peaks over threshold records.) |
| Maintainer: | Ilaria Prosdocimi <[email protected]> |
| License: | GPL-3 |
| Version: | 0.1-5.1 |
| Built: | 2025-02-14 03:11:12 UTC |
| Source: | https://github.com/ilapros/winfapreader |
The function queries the NRFA API for the .AM file similar to the WINFAP file for a given stations. It then processes the file in a fashion similar to read_amax.
get_amax(station)get_amax(station)
station |
the NRFA station number for which the annual maxima records should be obtained. Can also be a vector of station numbers. |
a data.frame with information on the annual maxima for the station with the following columns
NRFA station number (can be a vector of station numbers)
the correct water year for the peak flow
date of maximum flow
the maximum flow in m3/s
the stage (height) reached by the river - this information is used to derive the flow via a rating curve
logical, if TRUE the water year has been flagged as rejected by the NRFA
read_amax. Information on river flow gauging in the UK and the annual maxima can be found at the National River Flow Archive website https://nrfa.ceh.ac.uk
a40003 <- get_amax(40003) # the Medway at Teston / East Farleigh multipleStations <- get_amax(c(40003, 42003)) names(multipleStations) summary(multipleStations$`42003`)a40003 <- get_amax(40003) # the Medway at Teston / East Farleigh multipleStations <- get_amax(c(40003, 42003)) names(multipleStations) summary(multipleStations$`42003`)
The function queries the NRFA API for for information of a given station. Unlike get_amax and get_pot, the output of this function is not exactly the same from the output of the read_cd3 function due to differences in the information made available by the NRFA API
get_cd(station, fields = "feh")get_cd(station, fields = "feh")
station |
the NRFA station(s) number for which the the information is required |
fields |
the type of information which is required. Can be "feh" (default), which outputs a subset of information typically used when applying the flood estimation handbook methods, or "all", which output all information made available in the NRFA API. |
a data.frame of one row with different columns depending on whether fields = "all" or fields = "feh" was selected.
read_cd3. Information on catchment descriptors river flow gauging in the UK can be found at the National River Flow Archive website https://nrfa.ceh.ac.uk
cdMult <- get_cd(c(40003,42003), fields = "all") ### lots of information on the catchment/station ### including information on rejected annual maxima cdMult$`40003`$`peak-flow-rejected-amax-years` ## no rejections cdMult$`42003`$`peak-flow-rejected-amax-years` ## several rejections cd40003 <- get_cd(40003, fields = "feh") # less information, mostly the FEH descriptors dim(cd40003) sapply(cdMult, ncol)cdMult <- get_cd(c(40003,42003), fields = "all") ### lots of information on the catchment/station ### including information on rejected annual maxima cdMult$`40003`$`peak-flow-rejected-amax-years` ## no rejections cdMult$`42003`$`peak-flow-rejected-amax-years` ## several rejections cd40003 <- get_cd(40003, fields = "feh") # less information, mostly the FEH descriptors dim(cd40003) sapply(cdMult, ncol)
The function queries the NRFA API for the .PT file similar to the WINFAP file for a given stations. It then processes the file in a fashion similar to read_pot.
get_pot(station, getAmax = FALSE)get_pot(station, getAmax = FALSE)
station |
the NRFA station number for which peaks over threshold information should be obtained. It can also be a vector of station numbers |
getAmax |
logical. If |
Like read_pot a list of three objects tablePOT, WaterYearInfo and dateRange.
tablePOT contains a table with all the peaks above the threshold present in the record
WaterYearInfo a table containing the information on the percentage of missing values
in any water year for which some data is available in the POT record. This is useful to assess
whether the lack of exceedances is genuine or the result of missing data and to assess whether the threshold
exceedances present in tablePOT can be deemed to be representative of the whole year
dateRange a vector with the first and last date of recording for the POT record as provided in the [POT Details] field.
Note that this period might be different than the period for which annual maxima records are available
read_pot. Information on the peaks over threshold records and river flow gauging in the UK can be found at the National River Flow Archive website https://nrfa.ceh.ac.uk
### the example take longer than 5 seconds to run p40003 <- get_pot(40003) # the Medway at Teston / East Farleigh p40003$tablePOT[p40003$tablePOT$WaterYear > 1969 & p40003$tablePOT$WaterYear < 1977,] ### no events in 1971 nor 1975 p40003$WaterYearInfo[p40003$WaterYearInfo$WaterYear > 1969 & p40003$WaterYearInfo$WaterYear < 1977,] # in 1971 all records are valid, # in 1975 no exceedances # might be due to the fact that almost no valid record are available p40003 <- get_pot(40003, getAmax = TRUE) p40003$WaterYearInfo[p40003$WaterYearInfo$WaterYear > 1969 & p40003$WaterYearInfo$WaterYear < 1977,] # the annual maximum in 1971 and 1975 was below the threshold # no events exceeded the threshold### the example take longer than 5 seconds to run p40003 <- get_pot(40003) # the Medway at Teston / East Farleigh p40003$tablePOT[p40003$tablePOT$WaterYear > 1969 & p40003$tablePOT$WaterYear < 1977,] ### no events in 1971 nor 1975 p40003$WaterYearInfo[p40003$WaterYearInfo$WaterYear > 1969 & p40003$WaterYearInfo$WaterYear < 1977,] # in 1971 all records are valid, # in 1975 no exceedances # might be due to the fact that almost no valid record are available p40003 <- get_pot(40003, getAmax = TRUE) p40003$WaterYearInfo[p40003$WaterYearInfo$WaterYear > 1969 & p40003$WaterYearInfo$WaterYear < 1977,] # the annual maximum in 1971 and 1975 was below the threshold # no events exceeded the threshold
The Water Year in the UK runs from 9am of the 1st October of a given year
to 8:59am of the 1st October of the next year. Since the WINFAP files contain
information only on the date of the annual maximum (and not time) it is possible that an event is
mis-classified when using the water_year function. This dataset lists the events which are
known to have happened to October 1st before 9am. This is used to correct the WaterYear
information in these known cases in the read_amax and get_amax functions. For some stations
events on October 1st have been deemed as annual maxima only in some winfap releases. They are
maintained in the dataset in the event that somebody read old winfap files.
known_Oct1known_Oct1
A data frame with 36 rows and 3 variables:
NRFA station number
date of maximum flow (always the 1st October)
the correct water year for the peak flow
Derived manually by identifying events which happened on Oct. 1st and comparing it with information on https://nrfa.ceh.ac.uk
The function reads .AM files once these are in a local folder: these files contain information on annual maxima (AMAX) records extracted from the instantaneous river flow measurements. The function checks for the presence of any [AM Rejected] information and includes it in the output.
read_amax(station, loc_WinFapFiles = getwd())read_amax(station, loc_WinFapFiles = getwd())
station |
NRFA station number(s) for which the .AM file (named |
loc_WinFapFiles |
the file.path of the WINFAP files, i.e. the location in which the
|
a data.frame with information on the annual maxima for the station with the following columns
NRFA station number (can be a vector of station numbers)
the correct water year for the peak flow
date of maximum flow
the maximum flow in m3/s
the stage (height) reached by the river - this information is used to derive the flow via a rating curve
logical, if TRUE the water year has been flagged as rejected by the NRFA
Information on the .AM files and river flow gauging in the UK can be found at the National River Flow Archive website https://nrfa.ceh.ac.uk
The function reads .CD3 files once these are in a local folder: these files contain information on the gauging station and on the catchment upstream the station.
read_cd3(station, loc_WinFapFiles = getwd())read_cd3(station, loc_WinFapFiles = getwd())
station |
the NRFA station number(s) for which the .CD3 file (names |
loc_WinFapFiles |
the file.path of the WINFAP files, i.e. the location in which the
|
a data.frame with information on the catchment descriptors for the station
Information on the .CD3 files and river flow gauging in the UK can be found at the National River Flow Archive website https://nrfa.ceh.ac.uk. Specific information on the catchment descriptors can be found at https://nrfa.ceh.ac.uk/feh-catchment-descriptors
The function reads .PT files once these are in a local folder: these files contain information on Peaks-Over-Threshold (POT) records from the instantaneous river flow measurements. The function checks for the presence of any [POT GAPS] and [POT REJECTED] periods. If these are present, they are merged and information on the proportion of days with missing records in each water year is provided.
read_pot(station, loc_WinFapFiles = getwd(), getAmax = FALSE)read_pot(station, loc_WinFapFiles = getwd(), getAmax = FALSE)
station |
NRFA station number(s) for which the .PT file (names |
loc_WinFapFiles |
the file.path of the WINFAP files, i.e. the location in which the
|
getAmax |
logical. If |
a list of three objects tablePOT, WaterYearInfo and dateRange.
tablePOT contains a table with all the peaks above the threshold present in the .PT file
WaterYearInfo a table containing the information on the percentage of missing values
in any water year for which some data is available in the POT record. This is useful to assess
whether the lack of exceedances is genuine or the result of missing data and to assess whether the threshold
exceedances present in tablePOT can be deemed to be representative of the whole year
dateRange a vector with the first and last date of recording for the POT record as provided in the [POT Details] field.
Note that this period might be different than the period for which annual maxima records are available
Information on the .PT files and river flow gauging in the UK can be found at the National River Flow Archive website https://nrfa.ceh.ac.uk
Derive water year value for a date
water_year(date, start_month = 10)water_year(date, start_month = 10)
date |
the (vector of) dates for which the water year will be calculated |
start_month |
the month in which the water year starts, default is October |
The water year value
water_year(as.Date(c("2010-11-03", "2013-02-03")))water_year(as.Date(c("2010-11-03", "2013-02-03")))