diff --git a/NAMESPACE b/NAMESPACE index 9c34859..51cb84e 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -36,8 +36,9 @@ export(ch_get_ECDE_metadata) export(ch_get_peaks) export(ch_get_url_data) export(ch_get_wscstation) +export(ch_gg_hydrographs) export(ch_high_Grubbs_test) -export(ch_hydrograph_plot) +export(ch_model_hydrograph) export(ch_polar_plot) export(ch_polar_plot_peaks) export(ch_polar_plot_prep) @@ -73,6 +74,9 @@ export(ch_wbt_removesinks) export(ch_wtr_yr) import(TeachingDemos) import(circular) +import(dplyr) +import(ggplot2) +import(tidyhydat) importFrom(Kendall,MannKendall) importFrom(MGBT,MGBT) importFrom(dplyr,left_join) diff --git a/R/Visualization_functions.R b/R/Visualization_functions.R index 99e3a10..163530a 100644 --- a/R/Visualization_functions.R +++ b/R/Visualization_functions.R @@ -4,11 +4,14 @@ #' some analyses may also be done. #' \describe{ #' \item{ch_booth_plot}{Plot of peaks over a threshold} +#' \item{ch_ffa_screen_plot}{FFA screening plot} #' \item{ch_flow_raster}{Raster plot of streamflows} #' \item{ch_flow_raster_qa}{Raster plot of streamflows with WSC quality flags} +#' \item{ch_gg_hydrographs}{ggplot2 hydrographs of WSC flows} #' \item{ch_flow_raster_trend}{Raster plot and simple trends of observed streamflows} -#' \item{ch_hydrograph_plot}{Plots hydrographs and/or precipitation} +#' \item{ch_model_hydrograph}{Plots hydrographs and/or precipitation} #' \item{ch_polar_plot}{Polar plot of daily streamflows} +#' \item{ch_qa_hydrograph}{Plots a hydrograph with the data quality symbols} #' \item{ch_regime_plot}{Plots the regime of daily streamflows} #' } NULL \ No newline at end of file diff --git a/R/ch_gg_hydrographs.R b/R/ch_gg_hydrographs.R new file mode 100644 index 0000000..87526e7 --- /dev/null +++ b/R/ch_gg_hydrographs.R @@ -0,0 +1,205 @@ +#' Hydrographs for WSC stations using \pkg{ggplot2} +#' +#' @description +#' Acquires and plots values for WSC streamflows, using \pkg{ggplot2}. The existing +#' functions \code{ch_qa_hydrograph} and +#' \code{ch_model_hydrograph} use basic \R plotting, require other functions to +#' assemble the values, and only plot +#' values for a single station. This function is +#' able to plot hydrographs for more than one station, which may be useful, particularly +#' when comparing responses for several streams in the same region. +#' @param WSC_stations Required. A vector of WSC station numbers. +#' @param daily Optional. If TRUE, mean daily streamflows are plotted as stair-steps. +#' @param instantaneous Optional. If TRUE, annual instantaneous peak flows are plotted as points. +#' @param facets Optional. If TRUE, the plot is faceted by station number. +#' @param common_dates Optional. If TRUE, a common date range is used for all +#' time series. +#' @param start_date Optional. If specified (format = yyyy-mm-dd), only values on +#' or following the date are plotted. +#' @param end_date Optional. If specified (format = yyyy-mm-dd), only values on or +#' before the date are plotted. +#' @param hydat_path Optional. Path to the HYDAT database. Usually omitted unless +#' you want to use a specific database file. +#' @param inst_colour Optional. Colour to be used for annual instantaneous peaks, +#' if either facetted or only a single station is plotted. Default is "black". +#' @param daily_colour Optional. Colour to be used for daily flows, +#' if either facetted or only a single station is plotted. Default is "black". +#' @param ... Other parameters for the \pkg{ggplot} facets, if specified. +#' @author Kevin Shook +#' @seealso \code{\link{ch_qa_hydrograph}} \code{\link{ch_model_hydrograph}} +#' @returns Returns a \code{ggplot2} object of the hydrographs. +#' @export +#' @import ggplot2 dplyr tidyhydat +#' +#' @examples { +#' # plot a single station +#' stations <- c("05HH003") +#' p <- ch_gg_hydrographs(stations, daily = TRUE, instantaneous = TRUE) +#' +#' # plot a group of stations in a region, as all appear to be responding to the same event +#' stations <- c("05CC001", "05CC011", "05CD006", "05CD007", "05CE002", "05CE006", +#' "05CE010", "05CE012", "05CE018", "05CE020", "05CG004", "05CG006") +#' +#' p <- ch_gg_hydrographs(stations, daily = TRUE, instantaneous = FALSE, +#' common_dates = FALSE, start_date = "2011-06-01", end_date = "2011-06-30", +#' facets = TRUE, scales = "free_y", ncol= 3) +#' } + +ch_gg_hydrographs <- function(WSC_stations, + daily = TRUE, + instantaneous = FALSE, + facets = TRUE, + common_dates = FALSE, + start_date = NULL, + end_date = NULL, + hydat_path = NULL, + inst_colour = "black", + daily_colour = "black", + ...) { + # set up plot values + Datetime <- NULL + Value <- NULL + start_year <- NULL + end_year <- NULL + STATION_NUMBER <- NULL + + if (is.null(daily_colour)) + daily_colour <- "black" + + if (is.null(inst_colour)) + inst_colour <- "black" + + + # check parameter values + if (!daily & !instantaneous) + stop("No plots selected") + + if (is.null(WSC_stations) | length(WSC_stations) == 0 ) + stop("No stations selected") + + if (!is.null(start_date)) { + start_date_val <- as.Date(start_date, format = "%Y-%m-%d") + start_year <- as.numeric(format(start_date_val, format = "%Y")) + } + + if (!is.null(end_date)) { + end_date_val <- as.Date(end_date, format = "%Y-%m-%d") + end_year <- as.numeric(format(end_date_val, format = "%Y")) + } + + # get number of stations + num_stations <- length(WSC_stations) + + # get WSC data for plotting and find min and max dates + if (daily) { + wsc_daily <- hy_daily_flows(WSC_stations, + start_date = start_date, + end_date = end_date) + + wsc_daily$Datetime <- as.POSIXct(wsc_daily$Date, format = "%Y-%m-%d") + daily_min_max_dates <- wsc_daily %>% group_by(STATION_NUMBER) %>% + summarise(min_Datetime = min(Datetime), max_Datetime = max(Datetime)) + + common_daily_min_Datetime <- max(daily_min_max_dates$min_Datetime) + common_daily_max_Datetime <- min(daily_min_max_dates$max_Datetime) + } + + if (instantaneous) { + wsc_inst <- hy_annual_instant_peaks(WSC_stations, + start_year = start_year, + end_year = end_year) + + wsc_inst <- wsc_inst[wsc_inst$Parameter == "Flow" & wsc_inst$PEAK_CODE == "MAX",] + + # remove wsc_inst values with missing datetimes + wsc_inst <- wsc_inst[!is.na(wsc_inst$Datetime),] + + inst_min_max_dates <- wsc_inst %>% group_by(STATION_NUMBER) %>% + summarise(min_Datetime = min(Datetime), max_Datetime = max(Datetime)) + common_inst_min_Datetime <- max(inst_min_max_dates$min_Datetime) + common_inst_max_Datetime <- min(inst_min_max_dates$max_Datetime) + } + + if (common_dates) { + if (daily & !instantaneous) { + common_min_Datetime <- common_daily_min_Datetime + common_max_Datetime <- common_daily_max_Datetime + wsc_daily <- wsc_daily[wsc_daily$Datetime >= common_min_Datetime,] + wsc_daily <- wsc_daily[wsc_daily$Datetime <= common_max_Datetime,] + } else if (!daily & instantaneous) { + + common_min_Datetime <- as.POSIXct(paste0(format.Date(common_inst_min_Datetime, "%Y"), "-01-01 00:00:00"), + format = "%Y-%m-%d %H:%M:%S") + common_max_Datetime <- as.POSIXct(paste0(format.Date(common_inst_max_Datetime, "%Y"), "-12-31 23:45:00"), + format = "%Y-%m-%d %H:%M:%S") + + wsc_inst <- wsc_inst[wsc_inst$Datetime >= common_min_Datetime,] + wsc_inst <- wsc_inst[wsc_inst$Datetime <= common_max_Datetime,] + + } else { + common_min_Datetime <- common_daily_min_Datetime + common_max_Datetime <- common_daily_max_Datetime + + wsc_daily <- wsc_daily[wsc_daily$Datetime >= common_min_Datetime,] + wsc_daily <- wsc_daily[wsc_daily$Datetime <= common_max_Datetime,] + + wsc_inst <- wsc_inst[wsc_inst$Datetime >= common_min_Datetime,] + wsc_inst <- wsc_inst[wsc_inst$Datetime <= common_max_Datetime,] + } + } + # plot + if (daily & !instantaneous) { + if (!facets) + if(num_stations > 1) + p <- ggplot(wsc_daily, aes(Datetime, Value, colour = STATION_NUMBER)) + + geom_step(direction = "hv") + else + p <- ggplot(wsc_daily, aes(Datetime, Value)) + + geom_step(direction = "hv", colour = daily_colour) + else + p <- ggplot(wsc_daily, aes(Datetime, Value)) + + geom_step(direction = "hv", colour = daily_colour) + + facet_wrap(~STATION_NUMBER, ...) + + } else if (!daily & instantaneous) { + if (!facets) { + if (num_stations == 1 ){ + p <- ggplot(wsc_inst, aes(Datetime, Value)) + + geom_point(colour = inst_colour) + } else { + p <- ggplot(wsc_inst, aes(Datetime, Value, colour = STATION_NUMBER)) + + geom_point() + } + } else { + # facets + p <- ggplot(wsc_inst, aes(Datetime, Value)) + + geom_point(colour = inst_colour) + + facet_wrap(~STATION_NUMBER, ...) + + } + + } else { + # daily and instantaneous + if (!facets){ + if (num_stations == 1){ + p <- ggplot(wsc_daily, aes(Datetime, Value)) + + geom_step(direction = "hv", colour = daily_colour) + + geom_point(data = wsc_inst, aes(Datetime, Value),colour = inst_colour, ...) + } else { + p <- ggplot(wsc_daily, aes(Datetime, Value, colour = STATION_NUMBER)) + + geom_step(direction = "hv") + + geom_point(data = wsc_inst, aes(Datetime, Value), ...) + } + } + else + p <- ggplot(wsc_daily, aes(Datetime, Value)) + + geom_step(direction = "hv", colour = daily_colour) + + geom_point(data = wsc_inst, aes(Datetime, Value), colour = inst_colour) + + facet_wrap(~STATION_NUMBER, ...) + } + + # add labels + p <- p + xlab("") + ylab(expression(paste("Discharge (m", ""^{ 3 }, "/s)", sep = ""))) + + return(p) +} \ No newline at end of file diff --git a/R/ch_hydrograph_plot.R b/R/ch_model_hydrograph.R similarity index 93% rename from R/ch_hydrograph_plot.R rename to R/ch_model_hydrograph.R index 23763bc..2ef679d 100644 --- a/R/ch_hydrograph_plot.R +++ b/R/ch_model_hydrograph.R @@ -1,9 +1,9 @@ -#' @title Hydrograph plot +#' @title Hydrograph plot for model outputs and gauged flows #' #' @description -#' Creates a hydrograph plot for simulated, observed, and inflow -#' hydrograph series, including precipitation if provided. The secondary y axis -#' will be used to plot the precip time series. +#' Creates a hydrograph plot for simulated and observed flows, including +#' precipitation if provided. The secondary y axis +#' is used to plot the precipitation time series. #' #' @details #' Assumes that the supplied time series have the same length and @@ -40,12 +40,13 @@ #' small buffer for presentation. Be warned that if this option is set to #' TRUE, the minimum value is set to zero without checking if any flow values #' are less than zero. This option should not be used for reservoir stage plotting, since -#' most reservoir stage is typically reported as an elevation. +#' most reservoir stages are typically reported as geodetic elevations, where the +#' minimum values are much greater than zero. #' #' @return Returns \code{TRUE} if the function is executed properly. #' #' @author Robert Chlumsky -#' +#' @seealso \code{\link{ch_qa_hydrograph}} \code{\link{ch_gg_hydrographs}} #' @examples #' # example with synthetic random data #' dd <- seq.Date(as.Date("2010-10-01"), as.Date("2013-09-30"),by = 1) @@ -57,21 +58,21 @@ #' precip <- data.frame("Date" = dd," precip" = abs(rnorm(length(dd))) * 10) #' #' # basic hydrograph plot -#' ch_hydrograph_plot(flows = df, winter_shading = FALSE) +#' ch_model_hydrograph(flows = df, winter_shading = FALSE) #' #' # with different labels and winter shading -#' ch_hydrograph_plot(flows = df, winter_shading = TRUE, +#' ch_model_hydrograph(flows = df, winter_shading = TRUE, #' flow_labels = c("simulated", "observed")) #' #' # add precipitation, increase the plot ranges to separate flows and precip, and add a legend box -#' ch_hydrograph_plot(flows = df, precip = precip, range_mult_flow = 1.7, +#' ch_model_hydrograph(flows = df, precip = precip, range_mult_flow = 1.7, #' range_mult_precip = 2, leg_box = TRUE) #' #' @importFrom lubridate year month day date #' @importFrom graphics grid lines #' @export #' -ch_hydrograph_plot <- function(flows = NULL, +ch_model_hydrograph <- function(flows = NULL, precip = NULL, prd = NULL, winter_shading = FALSE, diff --git a/R/ch_qa_hydrograph.R b/R/ch_qa_hydrograph.R index 41aed92..ae8c2de 100644 --- a/R/ch_qa_hydrograph.R +++ b/R/ch_qa_hydrograph.R @@ -1,112 +1,112 @@ -#' Plots a hydrograph with the data quality symbols and returns a report on qa symbols and missing data. -#' -#' @description Plots a hydrograph of a WSC daily data file read from from ECDataExplorer (ECDE). -#' The hydrograph shows individual days with data quality symbols [SYM] -#' in colour and counts cases of each and reports them in the legend. The colours and symbols -#' are those produced by ECDataExplorer. -#' -#' There is an option is to provide start and end dates to show -#' only part of the time period for which data exists and the plot is annotated to indicate this. -#' Counts of missing observations is also provided in the legend. -#' -#' @param DF Data frame retrieved from ECDataExplorer as returned by the function -#' \code{ch_read_ECDE_flows}. -#' @param st_date Optional start date in the form \option{yyyy-mm-dd}. Default is \code{NULL}. -#' @param end_date Optional end date in the form \option{yyyy-mm-dd}. Default is \code{NULL}. -#' @param rescale If \code{FALSE} (the default), the y-axis scaling is determined by the time -#' period. If \code{TRUE} then determined by the whole dataset. -#' @param sym_col Colours used for SYM; default is those used in ECDE ("black", -#' "green", "cyan","yellow", "red", "white"). The final "white" can be changed to highlight -#' missing data points. -#' @param cts If \code{TRUE} (the default) shows the counts of SYM in the legend. If \code{FALSE} -#' the counts are omitted as in ECDE. -#' @param metadata a dataframe of station metadata, default is \code{HYDAT_list}. -#' -#' -#' @author Paul Whitfield -#' -#' @return Produces a plot and returns a list that contains: -#' \item{station name or title used}{} -#' \item{st_date}{starting date} -#' \item{end_date}{ending data} -#' \item{n}{the number of data points} -#' \item{sym_count}{summary of the SYM counts} -#' \item{missing}{number of missing data} -#' -#' -#' @export -#' -#' @importFrom graphics text -#' -#' @examples -#' m_test <- ch_qa_hydrograph(CAN05AA008) -# using a date range -#' m_test <- ch_qa_hydrograph(CAN05AA008, st_date="1980-01-01", end_date="1999-12-31") -# - -ch_qa_hydrograph <- function(DF, st_date = NULL, end_date = NULL, cts = TRUE, rescale = FALSE, - sym_col = c("black", "green", "cyan", "yellow", "red", "white"), - metadata = NULL) { - - - disch <- expression(paste("Mean Daily Discharge m"^{3}, "/sec")) - - m_station <- ch_get_wscstation(DF[1, 1], metadata = metadata) - title <- paste(m_station$Station, " ", m_station$StationName) - - sym_count <- array(0, dim = 6) - DF$dcol <- array(1, dim = length(DF[ , 1])) - - - ylims <- c(min(DF[ , 4]),max(DF[,4])) - - if (!is.null(st_date)) - { - st_date <- as.Date(st_date, "%Y-%m-%d") - end_date <- as.Date(end_date, "%Y-%m-%d") - - DF <- DF[DF$Date >= st_date, ] - DF <- DF[DF$Date <= end_date, ] - } - - if (!rescale) ylims <- c(min(DF[ , 4]), max(DF[ , 4])) - - for (k in 1:length(DF$dcol)) - { - if (!is.na(DF$SYM[k]) && DF$SYM[k] == "A") {DF$dcol[k] <- 2; sym_count[2] <- sym_count[2] + 1} - if (!is.na(DF$SYM[k]) && DF$SYM[k] == "B") {DF$dcol[k] <- 3; sym_count[3] <- sym_count[3] + 1} - if (!is.na(DF$SYM[k]) && DF$SYM[k] == "C") {DF$dcol[k] <- 4; sym_count[4] <- sym_count[4] + 1} - if (!is.na(DF$SYM[k]) && DF$SYM[k] == "D") {DF$dcol[k] <- 5; sym_count[5] <- sym_count[5] + 1} - if (!is.na(DF$SYM[k]) && DF$SYM[k] == "E") {DF$dcol[k] <- 6; sym_count[6] <- sym_count[6] + 1} - } - - par(mar = c(2.5, 4.5, 3, 1)) - plot(DF$Date, DF[ , 4], - col = "black", type = "l", ylim = ylims, ylab = disch, xlab = "", main = title, lwd = 0.2, las = 1) - points(DF$Date, DF[ , 4], col = sym_col[DF$dcol], type = "p", pch = 19, cex = 0.6) - - sym_count[1] <- length(DF[,4]) - sum(sym_count) - missdays <- as.numeric(1 + DF[length(DF[,1]), 3] - DF[1,3] - length(DF[, 1])) - - ltexta <- c("Default ","(A) - Partial ","(B) - Backwater ","(D) - Dry ","(E) - Estimate ") - ltextb <- c(paste("Default ", sym_count[1]), - paste("(A) - Partial ", sym_count[2]), - paste("(B) - Backwater ", sym_count[3]), - paste("(D) - Dry ", sym_count[5]), - paste("(E) - Estimate ", sym_count[6]), - paste("Missing", missdays)) - - - - if (!cts) legend("topleft", ltexta, pch = 19, col = sym_col, cex = 0.7, bg = "transparent") - if (cts) legend("topleft", ltextb, pch = 19, col = sym_col, cex = 0.7, bg = "transparent") - - if (!is.null(st_date)) text(DF$Date[as.integer(0.75 * length(DF$Date))], max(DF[ , 4]), - "Selected Date Range", col = "gray50", cex = 0.7) - - names(sym_count) <- c("Default", "A", "B", "C", "D", "E") - - result <- list(title, st_date, end_date, length(DF[,4]), sym_count, missdays) - names(result) <- c("Station", "start_date", "end_date", "points", "SYM_count","missing_observations") - return(result) -} +#' Plots a hydrograph with the data quality symbols and returns a report on qa symbols and missing data. +#' +#' @description Plots a hydrograph of a WSC daily data file read from from ECDataExplorer (ECDE). +#' The hydrograph shows individual days with data quality symbols [SYM] +#' in colour and counts cases of each and reports them in the legend. The colours and symbols +#' are those produced by ECDataExplorer. +#' +#' There is an option is to provide start and end dates to show +#' only part of the time period for which data exists and the plot is annotated to indicate this. +#' Counts of missing observations is also provided in the legend. +#' +#' @param DF Data frame retrieved from ECDataExplorer as returned by the function +#' \code{ch_read_ECDE_flows}. +#' @param st_date Optional start date in the form \option{yyyy-mm-dd}. Default is \code{NULL}. +#' @param end_date Optional end date in the form \option{yyyy-mm-dd}. Default is \code{NULL}. +#' @param rescale If \code{FALSE} (the default), the y-axis scaling is determined by the time +#' period. If \code{TRUE} then determined by the whole dataset. +#' @param sym_col Colours used for SYM; default is those used in ECDE ("black", +#' "green", "cyan","yellow", "red", "white"). The final "white" can be changed to highlight +#' missing data points. +#' @param cts If \code{TRUE} (the default) shows the counts of SYM in the legend. If \code{FALSE} +#' the counts are omitted as in ECDE. +#' @param metadata a dataframe of station metadata, default is \code{HYDAT_list}. +#' +#' +#' @author Paul Whitfield +#' @seealso \code{\link{ch_gg_hydrographs}} \code{\link{ch_model_hydrograph}} +#' @return Produces a plot and returns a list that contains: +#' \item{station name or title used}{} +#' \item{st_date}{starting date} +#' \item{end_date}{ending data} +#' \item{n}{the number of data points} +#' \item{sym_count}{summary of the SYM counts} +#' \item{missing}{number of missing data} +#' +#' +#' @export +#' +#' @importFrom graphics text +#' +#' @examples +#' m_test <- ch_qa_hydrograph(CAN05AA008) +# using a date range +#' m_test <- ch_qa_hydrograph(CAN05AA008, st_date="1980-01-01", end_date="1999-12-31") +# + +ch_qa_hydrograph <- function(DF, st_date = NULL, end_date = NULL, cts = TRUE, rescale = FALSE, + sym_col = c("black", "green", "cyan", "yellow", "red", "white"), + metadata = NULL) { + + + disch <- expression(paste("Mean Daily Discharge m"^{3}, "/sec")) + + m_station <- ch_get_wscstation(DF[1, 1], metadata = metadata) + title <- paste(m_station$Station, " ", m_station$StationName) + + sym_count <- array(0, dim = 6) + DF$dcol <- array(1, dim = length(DF[ , 1])) + + + ylims <- c(min(DF[ , 4]),max(DF[,4])) + + if (!is.null(st_date)) + { + st_date <- as.Date(st_date, "%Y-%m-%d") + end_date <- as.Date(end_date, "%Y-%m-%d") + + DF <- DF[DF$Date >= st_date, ] + DF <- DF[DF$Date <= end_date, ] + } + + if (!rescale) ylims <- c(min(DF[ , 4]), max(DF[ , 4])) + + for (k in 1:length(DF$dcol)) + { + if (!is.na(DF$SYM[k]) && DF$SYM[k] == "A") {DF$dcol[k] <- 2; sym_count[2] <- sym_count[2] + 1} + if (!is.na(DF$SYM[k]) && DF$SYM[k] == "B") {DF$dcol[k] <- 3; sym_count[3] <- sym_count[3] + 1} + if (!is.na(DF$SYM[k]) && DF$SYM[k] == "C") {DF$dcol[k] <- 4; sym_count[4] <- sym_count[4] + 1} + if (!is.na(DF$SYM[k]) && DF$SYM[k] == "D") {DF$dcol[k] <- 5; sym_count[5] <- sym_count[5] + 1} + if (!is.na(DF$SYM[k]) && DF$SYM[k] == "E") {DF$dcol[k] <- 6; sym_count[6] <- sym_count[6] + 1} + } + + par(mar = c(2.5, 4.5, 3, 1)) + plot(DF$Date, DF[ , 4], + col = "black", type = "l", ylim = ylims, ylab = disch, xlab = "", main = title, lwd = 0.2, las = 1) + points(DF$Date, DF[ , 4], col = sym_col[DF$dcol], type = "p", pch = 19, cex = 0.6) + + sym_count[1] <- length(DF[,4]) - sum(sym_count) + missdays <- as.numeric(1 + DF[length(DF[,1]), 3] - DF[1,3] - length(DF[, 1])) + + ltexta <- c("Default ","(A) - Partial ","(B) - Backwater ","(D) - Dry ","(E) - Estimate ") + ltextb <- c(paste("Default ", sym_count[1]), + paste("(A) - Partial ", sym_count[2]), + paste("(B) - Backwater ", sym_count[3]), + paste("(D) - Dry ", sym_count[5]), + paste("(E) - Estimate ", sym_count[6]), + paste("Missing", missdays)) + + + + if (!cts) legend("topleft", ltexta, pch = 19, col = sym_col, cex = 0.7, bg = "transparent") + if (cts) legend("topleft", ltextb, pch = 19, col = sym_col, cex = 0.7, bg = "transparent") + + if (!is.null(st_date)) text(DF$Date[as.integer(0.75 * length(DF$Date))], max(DF[ , 4]), + "Selected Date Range", col = "gray50", cex = 0.7) + + names(sym_count) <- c("Default", "A", "B", "C", "D", "E") + + result <- list(title, st_date, end_date, length(DF[,4]), sym_count, missdays) + names(result) <- c("Station", "start_date", "end_date", "points", "SYM_count","missing_observations") + return(result) +} diff --git a/man/Visualization-functions.Rd b/man/Visualization-functions.Rd index ed96644..b718a40 100644 --- a/man/Visualization-functions.Rd +++ b/man/Visualization-functions.Rd @@ -8,11 +8,14 @@ These functions are primarily intended for graphing, although some analyses may also be done. \describe{ \item{ch_booth_plot}{Plot of peaks over a threshold} + \item{ch_ffa_screen_plot}{FFA screening plot} \item{ch_flow_raster}{Raster plot of streamflows} \item{ch_flow_raster_qa}{Raster plot of streamflows with WSC quality flags} + \item{ch_gg_hydrographs}{ggplot2 hydrographs of WSC flows} \item{ch_flow_raster_trend}{Raster plot and simple trends of observed streamflows} - \item{ch_hydrograph_plot}{Plots hydrographs and/or precipitation} + \item{ch_model_hydrograph}{Plots hydrographs and/or precipitation} \item{ch_polar_plot}{Polar plot of daily streamflows} + \item{ch_qa_hydrograph}{Plots a hydrograph with the data quality symbols} \item{ch_regime_plot}{Plots the regime of daily streamflows} } } diff --git a/man/ch_gg_hydrographs.Rd b/man/ch_gg_hydrographs.Rd new file mode 100644 index 0000000..97d7820 --- /dev/null +++ b/man/ch_gg_hydrographs.Rd @@ -0,0 +1,70 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/ch_gg_hydrographs.R +\name{ch_gg_hydrographs} +\alias{ch_gg_hydrographs} +\title{Hydrographs for WSC stations using \pkg{ggplot2}} +\usage{ +ch_gg_hydrographs( + WSC_stations, + daily = TRUE, + instantaneous = FALSE, + facets = TRUE, + common_dates = FALSE, + start_date = NULL, + end_date = NULL, + hydat_path = NULL, + ... +) +} +\arguments{ +\item{WSC_stations}{Required. A vector of WSC station numbers.} + +\item{daily}{Optional. If TRUE, mean daily streamflows are plotted as stair-steps.} + +\item{instantaneous}{Optional. If TRUE, annual instantaneous peak flows are plotted as points.} + +\item{facets}{Optional. If TRUE, the plot is faceted by station number.} + +\item{common_dates}{Optional. If TRUE, a common date range is used for all time series.} + +\item{start_date}{Optional. If specified (format = yyyy-mm-dd), only values on or following the date are plotted.} + +\item{end_date}{Optional. If specified (format = yyyy-mm-dd), only values on or before the date are plotted.} + +\item{hydat_path}{Optional. Path to the HYDAT database. Usually omitted unless you want to use a specific database file.} + +\item{...}{Other parameters for the \pkg{ggplot} facets, if specified.} +} +\value{ +Returns a \code{ggplot2} object of the hydrographs. +} +\description{ +Acquires and plots values for WSC streamflows, using \pkg{ggplot2}. The existing +functions \code{ch_qa_hydrograph} and +\code{ch_model_hydrograph} use basic \R plotting, require other functions to +assemble the values, and only plot +values for a single station. This function is +able to plot hydrographs for more than one station, which may be useful, particularly +when comparing responses for several streams in the same region. +} +\examples{ +{ +# plot a single station +stations <- c("05HH003") +p <- ch_gg_hydrographs(stations, daily = TRUE, instantaneous = TRUE) + +# plot a group of stations in a region, as all appear to be responding to the same event +stations <- c("05CC001", "05CC011", "05CD006", "05CD007", "05CE002", "05CE006", +"05CE010", "05CE012", "05CE018", "05CE020", "05CG004", "05CG006") + +p <- ch_gg_hydrographs(stations, daily = TRUE, instantaneous = FALSE, +common_dates = FALSE, start_date = "2011-06-01", end_date = "2011-06-30", +facets = TRUE, scales = "free_y", ncol= 3) +} +} +\seealso{ +\code{\link{ch_qa_hydrograph}} \code{\link{ch_model_hydrograph}} +} +\author{ +Kevin Shook +} diff --git a/man/ch_hydrograph_plot.Rd b/man/ch_model_hydrograph.Rd similarity index 81% rename from man/ch_hydrograph_plot.Rd rename to man/ch_model_hydrograph.Rd index b362211..6b4358f 100644 --- a/man/ch_hydrograph_plot.Rd +++ b/man/ch_model_hydrograph.Rd @@ -1,10 +1,10 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/ch_hydrograph_plot.R -\name{ch_hydrograph_plot} -\alias{ch_hydrograph_plot} -\title{Hydrograph plot} +% Please edit documentation in R/ch_model_hydrograph.R +\name{ch_model_hydrograph} +\alias{ch_model_hydrograph} +\title{Hydrograph plot for model outputs and gauged flows} \usage{ -ch_hydrograph_plot( +ch_model_hydrograph( flows = NULL, precip = NULL, prd = NULL, @@ -60,15 +60,16 @@ By default, R will plot the values with a small buffer for presentation. Be warned that if this option is set to TRUE, the minimum value is set to zero without checking if any flow values are less than zero. This option should not be used for reservoir stage plotting, since -most reservoir stage is typically reported as an elevation.} +most reservoir stages are typically reported as geodetic elevations, where the +minimum values are much greater than zero.} } \value{ Returns \code{TRUE} if the function is executed properly. } \description{ -Creates a hydrograph plot for simulated, observed, and inflow -hydrograph series, including precipitation if provided. The secondary y axis -will be used to plot the precip time series. +Creates a hydrograph plot for simulated and observed flows, including +precipitation if provided. The secondary y axis +is used to plot the precipitation time series. } \details{ Assumes that the supplied time series have the same length and @@ -89,16 +90,19 @@ myprd <- "2011-10-01/2012-09-30" precip <- data.frame("Date" = dd," precip" = abs(rnorm(length(dd))) * 10) # basic hydrograph plot -ch_hydrograph_plot(flows = df, winter_shading = FALSE) +ch_model_hydrograph(flows = df, winter_shading = FALSE) # with different labels and winter shading -ch_hydrograph_plot(flows = df, winter_shading = TRUE, +ch_model_hydrograph(flows = df, winter_shading = TRUE, flow_labels = c("simulated", "observed")) # add precipitation, increase the plot ranges to separate flows and precip, and add a legend box -ch_hydrograph_plot(flows = df, precip = precip, range_mult_flow = 1.7, +ch_model_hydrograph(flows = df, precip = precip, range_mult_flow = 1.7, range_mult_precip = 2, leg_box = TRUE) +} +\seealso{ +\code{\link{ch_qa_hydrograph}} \code{\link{ch_gg_hydrographs}} } \author{ Robert Chlumsky diff --git a/man/ch_qa_hydrograph.Rd b/man/ch_qa_hydrograph.Rd index 8762240..b4a1069 100644 --- a/man/ch_qa_hydrograph.Rd +++ b/man/ch_qa_hydrograph.Rd @@ -57,6 +57,9 @@ Counts of missing observations is also provided in the legend. m_test <- ch_qa_hydrograph(CAN05AA008) m_test <- ch_qa_hydrograph(CAN05AA008, st_date="1980-01-01", end_date="1999-12-31") } +\seealso{ +\code{\link{ch_gg_hydrographs}} \code{\link{ch_model_hydrograph}} +} \author{ Paul Whitfield } diff --git a/vignettes/hydrograph_plot.R b/vignettes/ch_model_hydrograph.R similarity index 81% rename from vignettes/hydrograph_plot.R rename to vignettes/ch_model_hydrograph.R index 9c77ab6..6829a65 100644 --- a/vignettes/hydrograph_plot.R +++ b/vignettes/ch_model_hydrograph.R @@ -9,53 +9,53 @@ CAN05AA008 <- CAN05AA008 ## ----------------------------------------------------------------------------- daily_flows <- CAN05AA008[, c(3, 4)] -result1 <- ch_hydrograph_plot(flows = daily_flows, winter_shading = FALSE) -result2 <- ch_hydrograph_plot(flows = daily_flows, winter_shading = TRUE) +result1 <- ch_model_hydrograph(flows = daily_flows, winter_shading = FALSE) +result2 <- ch_model_hydrograph(flows = daily_flows, winter_shading = TRUE) ## ----------------------------------------------------------------------------- myprd <- "2000-01-01/2000-12-31" -result3 <- ch_hydrograph_plot( +result3 <- ch_model_hydrograph( flows = daily_flows, winter_shading = TRUE, prd = myprd ) ## ----------------------------------------------------------------------------- precip <- data.frame("Date" = daily_flows$Date, "precip" = abs(rnorm(nrow(daily_flows))) * 10) -result4 <- ch_hydrograph_plot( +result4 <- ch_model_hydrograph( flows = daily_flows, precip = precip, winter_shading = TRUE, prd = myprd ) ## ----------------------------------------------------------------------------- -result5 <- ch_hydrograph_plot( +result5 <- ch_model_hydrograph( flows = daily_flows, precip = precip, winter_shading = TRUE, prd = myprd, range_mult_precip = 2, range_mult_flow = 1.8 ) ## ----------------------------------------------------------------------------- ylab <- expression(paste("Discharge [m"^"3", "/s]")) -result6 <- ch_hydrograph_plot( +result6 <- ch_model_hydrograph( flows = daily_flows, precip = precip, prd = myprd, ylabel = ylab ) ## ----------------------------------------------------------------------------- ylab_precip <- "Rainfall [mm]" -result7 <- ch_hydrograph_plot( +result7 <- ch_model_hydrograph( flows = daily_flows, precip = precip, prd = myprd, precip_label = ylab_precip ) ## ----------------------------------------------------------------------------- -result8 <- ch_hydrograph_plot( +result8 <- ch_model_hydrograph( flows = daily_flows, precip = precip, prd = myprd, leg_pos = "right" ) # change legend to the right side -result9 <- ch_hydrograph_plot( +result9 <- ch_model_hydrograph( flows = daily_flows, precip = precip, prd = myprd, leg_box = TRUE ) # add legend fill and outline -result10 <- ch_hydrograph_plot( +result10 <- ch_model_hydrograph( flows = daily_flows, precip = precip, prd = myprd, zero_axis = F ) # default plot outside of function with buffer around axis diff --git a/vignettes/hydrograph_plot.Rmd b/vignettes/ch_model_hydrograph.Rmd similarity index 70% rename from vignettes/hydrograph_plot.Rmd rename to vignettes/ch_model_hydrograph.Rmd index b14d923..9bcdb30 100644 --- a/vignettes/hydrograph_plot.Rmd +++ b/vignettes/ch_model_hydrograph.Rmd @@ -1,12 +1,12 @@ --- -title: "ch_hydrograph_plot" +title: "ch_model_hydrograph" author: "R. Chlumsky" contributor: "K. Shook" date: "June 13, 2018" output: rmarkdown::html_vignette vignette: > - %\VignetteIndexEntry{ch_hydrograph_plot} + %\VignetteIndexEntry{ch_model_hydrograph} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- @@ -21,13 +21,13 @@ library(CSHShydRology) CAN05AA008 <- CAN05AA008 ``` -## hydrograph_plot +## ch_model_hydrograph -This is a general-purpose hydrograph plotting function, which is useful for a wide variety of tasks. -Currently the function only uses base R plotting, but the addition of ggplot2 graphs is planned for the -future. -The function can plot any of: observed flows, simulated flows, inflows to a sub-basin, and precipitation on the same graph. -The plots can indicate the winter period (which is fixed), and options exist to change the scales and y-axis +This is a general-purpose hydrograph plotting function. Although it can be used for a wide variety of tasks, +it is most useful for plotting the outputs of models and gauged discharges. +Note that this function uses base **R** plotting; **ggplot2** plots can be done using the function `ch_gghydrographs`. + +The function `ch_model_hydrograph` can plot any of: observed flows, simulated flows, inflows to a sub-basin, and precipitation on the same graph. The plots can indicate the winter period (which is fixed), and options exist to change the scales and y-axis label. ## Plotting daily streamflows, without and with winter shading @@ -36,8 +36,8 @@ Note that the value returned by the function, if successful, is TRUE ```{r} daily_flows <- CAN05AA008[, c(3, 4)] -result1 <- ch_hydrograph_plot(flows = daily_flows, winter_shading = FALSE) -result2 <- ch_hydrograph_plot(flows = daily_flows, winter_shading = TRUE) +result1 <- ch_model_hydrograph(flows = daily_flows, winter_shading = FALSE) +result2 <- ch_model_hydrograph(flows = daily_flows, winter_shading = TRUE) ``` The period of the plot can be restricted by setting the option prd, nwhich is a string like “2011-10- @@ -45,7 +45,7 @@ The period of the plot can be restricted by setting the option prd, nwhich is a ```{r} myprd <- "2000-01-01/2000-12-31" -result3 <- ch_hydrograph_plot( +result3 <- ch_model_hydrograph( flows = daily_flows, winter_shading = TRUE, prd = myprd ) @@ -57,7 +57,7 @@ You can also plot precipitation data. In this example fake precipitation data ar ```{r} precip <- data.frame("Date" = daily_flows$Date, "precip" = abs(rnorm(nrow(daily_flows))) * 10) -result4 <- ch_hydrograph_plot( +result4 <- ch_model_hydrograph( flows = daily_flows, precip = precip, winter_shading = TRUE, prd = myprd ) @@ -68,7 +68,7 @@ if desired. The default is to multiply the precipitation range by 1.5 of the max the range can be multiplied by any positive value to prevent this. ```{r} -result5 <- ch_hydrograph_plot( +result5 <- ch_model_hydrograph( flows = daily_flows, precip = precip, winter_shading = TRUE, prd = myprd, range_mult_precip = 2, range_mult_flow = 1.8 ) @@ -82,7 +82,7 @@ expression to get a superscripted 3. ```{r} ylab <- expression(paste("Discharge [m"^"3", "/s]")) -result6 <- ch_hydrograph_plot( +result6 <- ch_model_hydrograph( flows = daily_flows, precip = precip, prd = myprd, ylabel = ylab ) @@ -91,7 +91,7 @@ result6 <- ch_hydrograph_plot( The precipitation label can also be adjusted. ```{r} ylab_precip <- "Rainfall [mm]" -result7 <- ch_hydrograph_plot( +result7 <- ch_model_hydrograph( flows = daily_flows, precip = precip, prd = myprd, precip_label = ylab_precip ) @@ -108,15 +108,15 @@ Many other formatting options exist, such as: For example: ```{r} -result8 <- ch_hydrograph_plot( +result8 <- ch_model_hydrograph( flows = daily_flows, precip = precip, prd = myprd, leg_pos = "right" ) # change legend to the right side -result9 <- ch_hydrograph_plot( +result9 <- ch_model_hydrograph( flows = daily_flows, precip = precip, prd = myprd, leg_box = TRUE ) # add legend fill and outline -result10 <- ch_hydrograph_plot( +result10 <- ch_model_hydrograph( flows = daily_flows, precip = precip, prd = myprd, zero_axis = F ) # default plot outside of function with buffer around axis diff --git a/vignettes/ch_model_hydrograph.html b/vignettes/ch_model_hydrograph.html new file mode 100644 index 0000000..7045036 --- /dev/null +++ b/vignettes/ch_model_hydrograph.html @@ -0,0 +1,460 @@ + + + + + + + + + + + + + + + + +ch_model_hydrograph + + + + + + + + + + + + + + + + + + + + + + + + + + +

ch_model_hydrograph

+

R. Chlumsky

+

June 13, 2018

+ + + +
+

ch_model_hydrograph

+

This is a general-purpose hydrograph plotting function. Although it +can be used for a wide variety of tasks, it is most useful for plotting +the outputs of models and gauged discharges. Note that this function +uses base R plotting; ggplot2 plots +can be done using the function ch_gghydrographs.

+

The function ch_model_hydrograph can plot any of: +observed flows, simulated flows, inflows to a sub-basin, and +precipitation on the same graph. The plots can indicate the winter +period (which is fixed), and options exist to change the scales and +y-axis label.

+
+
+

Plotting daily streamflows, without and with winter shading

+

Note that the value returned by the function, if successful, is +TRUE

+
daily_flows <- CAN05AA008[, c(3, 4)]
+result1 <- ch_model_hydrograph(flows = daily_flows, winter_shading = FALSE)
+

+
result2 <- ch_model_hydrograph(flows = daily_flows, winter_shading = TRUE)
+

+

The period of the plot can be restricted by setting the option prd, +nwhich is a string like “2011-10- 01/2012-09-30” indicating the +beginning and end dates of the plot.

+
myprd <- "2000-01-01/2000-12-31"
+result3 <- ch_model_hydrograph(
+  flows = daily_flows, winter_shading = TRUE,
+  prd = myprd
+)
+

+
+
+

Adding Precipitation

+

You can also plot precipitation data. In this example fake +precipitation data are used.

+
precip <- data.frame("Date" = daily_flows$Date, "precip" = abs(rnorm(nrow(daily_flows))) * 10)
+result4 <- ch_model_hydrograph(
+  flows = daily_flows, precip = precip, winter_shading = TRUE,
+  prd = myprd
+)
+

+

The axes of the precipitation and flow can be modified as needed to +prevent overlap of the two series, if desired. The default is to +multiply the precipitation range by 1.5 of the maximum value, however +the range can be multiplied by any positive value to prevent this.

+
result5 <- ch_model_hydrograph(
+  flows = daily_flows, precip = precip, winter_shading = TRUE,
+  prd = myprd, range_mult_precip = 2, range_mult_flow = 1.8
+)
+

+
+
+

Changing Axis Labels

+

Only the default y-axis label can be over-ridden. Note that you can +use a Unicode character or an expression to get a superscripted 3.

+
ylab <- expression(paste("Discharge [m"^"3", "/s]"))
+result6 <- ch_model_hydrograph(
+  flows = daily_flows, precip = precip,
+  prd = myprd, ylabel = ylab
+)
+

+

The precipitation label can also be adjusted.

+
ylab_precip <- "Rainfall [mm]"
+result7 <- ch_model_hydrograph(
+  flows = daily_flows, precip = precip,
+  prd = myprd, precip_label = ylab_precip
+)
+

+
+
+

Other format options

+

Many other formatting options exist, such as:

+ +

For example:

+
result8 <- ch_model_hydrograph(
+  flows = daily_flows, precip = precip,
+  prd = myprd, leg_pos = "right"
+) # change legend to the right side
+

+
result9 <- ch_model_hydrograph(
+  flows = daily_flows, precip = precip,
+  prd = myprd, leg_box = TRUE
+) # add legend fill and outline
+

+
result10 <- ch_model_hydrograph(
+  flows = daily_flows, precip = precip,
+  prd = myprd, zero_axis = F
+) # default plot outside of function with buffer around axis
+

+
+ + + + + + + + + + + diff --git a/vignettes/hydrograph_plot.html b/vignettes/hydrograph_plot.html deleted file mode 100644 index 0d5017f..0000000 --- a/vignettes/hydrograph_plot.html +++ /dev/null @@ -1,243 +0,0 @@ - - - - - - - - - - - - - - - - -ch_hydrograph_plot - - - - - - - - - - - - - - - - - - - - - - - - - -

ch_hydrograph_plot

-

R. Chlumsky

-

June 13, 2018

- - - -
-

hydrograph_plot

-

This is a general-purpose hydrograph plotting function, which is useful for a wide variety of tasks. Currently the function only uses base R plotting, but the addition of ggplot2 graphs is planned for the future. The function can plot any of: observed flows, simulated flows, inflows to a sub-basin, and precipitation on the same graph. The plots can indicate the winter period (which is fixed), and options exist to change the scales and y-axis label.

-
-
-

Plotting daily streamflows, without and with winter shading

-

Note that the value returned by the function, if successful, is TRUE

-
daily_flows <- CAN05AA008[, c(3, 4)]
-result1 <- ch_hydrograph_plot(flows = daily_flows, winter_shading = FALSE)
-

-
result2 <- ch_hydrograph_plot(flows = daily_flows, winter_shading = TRUE)
-

-

The period of the plot can be restricted by setting the option prd, nwhich is a string like “2011-10- 01/2012-09-30” indicating the beginning and end dates of the plot.

-
myprd <- "2000-01-01/2000-12-31"
-result3 <- ch_hydrograph_plot(
-  flows = daily_flows, winter_shading = TRUE,
-  prd = myprd
-)
-

-
-
-

Adding Precipitation

-

You can also plot precipitation data. In this example fake precipitation data are used.

-
precip <- data.frame("Date" = daily_flows$Date, "precip" = abs(rnorm(nrow(daily_flows))) * 10)
-result4 <- ch_hydrograph_plot(
-  flows = daily_flows, precip = precip, winter_shading = TRUE,
-  prd = myprd
-)
-

-

The axes of the precipitation and flow can be modified as needed to prevent overlap of the two series, if desired. The default is to multiply the precipitation range by 1.5 of the maximum value, however the range can be multiplied by any positive value to prevent this.

-
result5 <- ch_hydrograph_plot(
-  flows = daily_flows, precip = precip, winter_shading = TRUE,
-  prd = myprd, range_mult_precip = 2, range_mult_flow = 1.8
-)
-

-
-
-

Changing Axis Labels

-

Only the default y-axis label can be over-ridden. Note that you can use a Unicode character or an expression to get a superscripted 3.

-
ylab <- expression(paste("Discharge [m"^"3", "/s]"))
-result6 <- ch_hydrograph_plot(
-  flows = daily_flows, precip = precip,
-  prd = myprd, ylabel = ylab
-)
-

-

The precipitation label can also be adjusted.

-
ylab_precip <- "Rainfall [mm]"
-result7 <- ch_hydrograph_plot(
-  flows = daily_flows, precip = precip,
-  prd = myprd, precip_label = ylab_precip
-)
-

-
-
-

Other format options

-

Many other formatting options exist, such as:

- -

For example:

-
result8 <- ch_hydrograph_plot(
-  flows = daily_flows, precip = precip,
-  prd = myprd, leg_pos = "right"
-) # change legend to the right side
-

-
result9 <- ch_hydrograph_plot(
-  flows = daily_flows, precip = precip,
-  prd = myprd, leg_box = TRUE
-) # add legend fill and outline
-

-
result10 <- ch_hydrograph_plot(
-  flows = daily_flows, precip = precip,
-  prd = myprd, zero_axis = F
-) # default plot outside of function with buffer around axis
-

-
- - - - - - - - - - -