From b734f816e4c178094461f093566e707b9319eb8d Mon Sep 17 00:00:00 2001
From: Dorchies David <david.dorchies@inrae.fr>
Date: Thu, 4 Feb 2021 11:48:20 +0100
Subject: [PATCH] doc: clean up doc and warning at doc compilation
---
R/plot_isofrequency.R | 26 ++++++++++++--------------
R/vgest_add_leap.R | 9 ++++-----
R/vgest_cost.R | 1 -
R/vgest_read_chrono.R | 41 ++++++++++++++++++-----------------------
R/vgest_run.R | 4 ++--
R/vgest_run_store.R | 19 +++++++------------
6 files changed, 43 insertions(+), 57 deletions(-)
diff --git a/R/plot_isofrequency.R b/R/plot_isofrequency.R
index 8b8ad9d..8b4d744 100644
--- a/R/plot_isofrequency.R
+++ b/R/plot_isofrequency.R
@@ -1,13 +1,12 @@
#' Plot one lake isofrequency annual curves for one objective at one station
#'
-#' @param x
-#' @param freq
-#' @param result.dir
+#' @param x [list] containing one [data.frame] per lake
+#' @param freq [numeric] vector of frequencies to plot
+#' @param result.dir [character] The path to the result database (default: "database")
#'
-#' @return
+#' @return [NULL]
#' @export
#'
-#' @examples
plot_isofrequency <- function(x, freq, result.dir = "database") {
lObj <- vgest_read_all(x, result.dir)
nLakes <- nrow(x$lakes[[1]])
@@ -17,13 +16,13 @@ plot_isofrequency <- function(x, freq, result.dir = "database") {
lapply(1:nLakes, function(i) {plot_isofrequency_lake(lObj[[i]], freq, x$lakes[[1]][i,], ceiling(i/2))})
sLowHigh <- c("low", "high")
mtext(
- paste("Objective", x$threshold, "m3/s", sLowHigh[x$flood + 1], "flows threshold at", x$station),
+ paste("Objective", x$threshold, "m3/s", sLowHigh[x$flood + 1], "flows threshold at", x$station),
side = 3, col = "black", line = -2, cex = 1.2, font = 2, outer = TRUE
)
}
#' Plot one lake isofrequency annual curves for one objective at one station
-#'
+#'
#' This function is mainly called by [plot_isofrequency()].
#'
#' @param vObj dataframe produced by [vgest_read_one()] and stored in a list by [vgest_read_all()]
@@ -31,10 +30,9 @@ plot_isofrequency <- function(x, freq, result.dir = "database") {
#' @param lake lake data extract from column `lakes` of objective data given by [get_objectives()]
#' @param top.margin top margin applied on the plot for the title
#'
-#' @return Nil
+#' @return [NULL]
#' @export
#'
-#' @examples
plot_isofrequency_lake <- function(vObj, frequencies, lake, top.margin) {
frequencies <- paste0("F", format(frequencies, digits = 5, nsmall = 5))
vObj[,-1] <- (vObj[,-1]) / 1E6 + lake$min
@@ -42,13 +40,13 @@ plot_isofrequency_lake <- function(vObj, frequencies, lake, top.margin) {
sColors <- c("#003A80", "#f58231", "#3cb44b", "#e6194B", "#911eb4", "#ffe119", "#f032e6", "#9A6324", "#000075", "#808000", "#42d4f4", "#a9a9a9", "#bfef45", "#469990")
par(mgp=c(2,0.5,0), mar = c(2.5,3.5,5.5 - 2.2*top.margin,0.5))
plot(
- rep(lake$min, 365),
+ rep(lake$min, 365),
type = "l", lwd = 1.5, col = "grey", lty = 2,
xaxt="n",
- main = NULL,
+ main = NULL,
ylab = "Reservoir Storage (mcm)",
xlab = NULL,
- ylim = c(0, lake$max),
+ ylim = c(0, lake$max),
cex.lab = 0.6, cex.axis = 0.6
)
lines(rep(lake$max, 365), lwd = 1.5, col = "grey", lty = 2)
@@ -58,10 +56,10 @@ plot_isofrequency_lake <- function(vObj, frequencies, lake, top.margin) {
lines(vObj[,frequency], lwd = 2, col = sColors[i])
}
mtext(
- paste(lake$name, "reservoir (Active cap.", lake$max - lake$min, "mcm)"),
+ paste(lake$name, "reservoir (Active cap.", lake$max - lake$min, "mcm)"),
side = 3, font = 2, cex = 0.75
)
xtick <- c(0, 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31)
xtick <- sapply(1:13, function(x) {sum(xtick[1:x])})
axis(side=1, at=xtick, labels = unlist(strsplit("JFMAMJJASONDJ", NULL)), cex.axis = 0.6)
-}
\ No newline at end of file
+}
diff --git a/R/vgest_add_leap.R b/R/vgest_add_leap.R
index 600e232..3ff6366 100644
--- a/R/vgest_add_leap.R
+++ b/R/vgest_add_leap.R
@@ -1,5 +1,5 @@
#' Add missing leap year data to naturalised flow file
-#'
+#'
#' Update the file with missing leap year data
#'
#' @param Qfile Name of the file
@@ -8,23 +8,22 @@
#' @return
#' @export
#'
-#' @examples
vgest_add_leap <- function(Qfile, vgest_location = "../vgest") {
file <- file.path(vgest_location, "DONNEES", Qfile)
Qnat <- read.delim(file)
Qnat$Dates <- as.Date(as.character(Qnat$Dates), format = "%Y%m%d")
allDates <- seq(Qnat$Dates[1], tail(Qnat$Dates, 1), by="days")
missingDates <- allDates[!allDates %in% Qnat$Dates]
- missingData <- cbind(data.frame(Dates = missingDates),
+ missingData <- cbind(data.frame(Dates = missingDates),
matrix(data = NA, nrow = length(missingDates), ncol = ncol(Qnat) - 1))
colnames(missingData) <- names(Qnat)
- Qnat <- rbind(Qnat,
+ Qnat <- rbind(Qnat,
missingData)
Qnat <- dplyr::arrange(Qnat, Dates)
Qnat[,-1] <- zoo::na.approx(Qnat[,-1])
Qnat$Dates <- format(Qnat$Dates, "%Y%m%d")
columnNames <- gsub(pattern = "\\.", replacement = "-", names(Qnat))
-
+
write.table(x = Qnat, file = file, quote = FALSE,
sep = "\t", row.names = FALSE, col.names = columnNames)
}
\ No newline at end of file
diff --git a/R/vgest_cost.R b/R/vgest_cost.R
index 536efe7..cf178ff 100644
--- a/R/vgest_cost.R
+++ b/R/vgest_cost.R
@@ -10,7 +10,6 @@
#' @return
#' @export
#'
-#' @examples
vgest_cost <- function(data, ...) {
UseMethod("vgest_cost", data)
}
diff --git a/R/vgest_read_chrono.R b/R/vgest_read_chrono.R
index a08a13d..36d73ae 100644
--- a/R/vgest_read_chrono.R
+++ b/R/vgest_read_chrono.R
@@ -1,23 +1,9 @@
#' Read Chrono.txt or PaChrono.txt
#'
-#' See [vgest_read_chrono.default] for details.
-#'
-#' @param x
-#' @param ...
-#'
-#' @return
-#' @export
-#'
-#' @examples
-vgest_read_chrono <- function(x, ...) {
- UseMethod("vgest_read_chrono", x)
-}
-
-
-#' Read Chrono.txt or PaChrono.txt
-#'
+#' @description
#' Read the time series provided by VGEST for the forward calculation (Chrono.txt) and backward calculation (PaChrono.txt)
#'
+#' @details
#' The format of the file is has follow. Headers are in line 53 followed by the complete time series which is backward in time for PaChrono.txt. The columns and respected widths are:
#' - Downstream date (10)
#' - QXsous (22)
@@ -36,14 +22,24 @@ vgest_read_chrono <- function(x, ...) {
#' The file is saved in RDS format for quicker reading the next time.
#'
#' @param x file to read with txt extension
-#' @param nLakes number of lakes in the file
-#' @param distributionType Distribution type. See [vgest_write_batch] details
-#'
+#' @param ... further arguments passed to or from other methods
#'
#' @return
#' @export
+#' @rdname vgest_read_chrono
+#'
+vgest_read_chrono <- function(x, ...) {
+ UseMethod("vgest_read_chrono", x)
+}
+
+
+#'
+#' @param nLakes number of lakes in the file
+#' @param distributionType Distribution type. See [vgest_write_batch] details
+#' @return [data.frame] with the content of the file
+#' @export
+#' @rdname vgest_read_chrono
#'
-#' @examples
vgest_read_chrono.default <- function(x, nLakes, distributionType) {
# Reading cached file if exists
rdsFile <- paste0(sub('\\..[^\\.]*$', '', x), ".rds")
@@ -82,15 +78,14 @@ vgest_read_chrono.default <- function(x, nLakes, distributionType) {
return(df)
}
-#' Read Chrono.txt or PaChrono.txt
#'
-#' @param x
#' @param result.dir path for storing the result of vgest run. The result is stored in a subfolder named high or low (depending on \code{bFlood}) followed by the threshold
#' @param distributionType Distribution type. See [vgest_write_batch] details
#' @param backward boolean `TRUE` for reading "PaChrono.txt", `FALSE` for reading "Chrono.txt"
#'
-#' @return A list with items named [station]_[high/low]_[threshold] containing [data.frame] with the content of each file
+#' @return A list with items named \[station\]_\[high/low\]_\[threshold\] containing [data.frame] with the content of each file
#' @export
+#' @rdname vgest_read_chrono
#'
#' @examples
#' \donttest{
diff --git a/R/vgest_run.R b/R/vgest_run.R
index 166ade7..9beb991 100644
--- a/R/vgest_run.R
+++ b/R/vgest_run.R
@@ -1,5 +1,5 @@
#' Run VGEST and stop execution if an error is encountered during execution
-#'
+#'
#' @details
#' Delete the content of the `RESULTAT` folder before running
#'
@@ -10,7 +10,7 @@
#'
#' @examples
#' \donttest{
-#' # Run vgest with the current
+#' # Run vgest with the current configuration
#' vgest_run()
#' }
vgest_run <- function(vgest_location = "../vgest") {
diff --git a/R/vgest_run_store.R b/R/vgest_run_store.R
index 586ff6a..c4ff32d 100644
--- a/R/vgest_run_store.R
+++ b/R/vgest_run_store.R
@@ -1,11 +1,11 @@
#' Prepare, run and store results of one or several VGEST instances
-#'
+#'
#' @param ... other parameter passed to the method [vgest_run_store.default]
#'
#' @return [NULL]
#' @export
#' @rdname vgest_run_store
-#'
+#'
vgest_run_store <- function(x, ...) {
UseMethod("vgest_run_store", x)
}
@@ -26,7 +26,6 @@ vgest_run_store <- function(x, ...) {
#' @param objective_file name of the file used for storing the threshold hydrograph
#' @param result.dir path for storing the result of vgest run. The result is stored in a subfolder named high or low (depending on \code{bFlood}) followed by the threshold
#'
-#' @return
#' @export
#' @rdname vgest_run_store
#'
@@ -36,7 +35,7 @@ vgest_run_store.default <- function(reservoirRuleSet, networkSet,
distributionType, distributionOption = NULL,
vgest_location = "../vgest",
objective_file = "BATCH",
- formatResult = 1,
+ formatResult = 1,
result.dir = "database") {
sLowHigh <- c("low", "high")
cat("Run VGEST for configuration: ", station, Qfile, sLowHigh[bFlood + 1], threshold, "...")
@@ -55,12 +54,8 @@ vgest_run_store.default <- function(reservoirRuleSet, networkSet,
cat(" - OK\n")
}
-#' Prepare, run and store results of multiple VGEST runs
-#'
-#'
#' @param x row(s) of a [data.frame] provided by [get_objectives()]
#'
-#' @return [NULL]
#' @export
#' @rdname vgest_run_store
#'
@@ -74,10 +69,10 @@ vgest_run_store.default <- function(reservoirRuleSet, networkSet,
#' # - the naturalized hydrological flows of the file located in DONNEES/Q_NAT_1900-2009.txt
#' # - doing the optimization on the period between 01/01/1900 and 31/12/2009
#' # - a task distribution function of present volumes and maximum usable volume replenishment times from the start of time steps
-#' vgest_run_store(get_objectives()[1,],
-#' 1, 1, "Q_NAT_1900-2009.txt",
+#' vgest_run_store(get_objectives()[1,],
+#' 1, 1, "Q_NAT_1900-2009.txt",
#' "01/01/1900", "31/12/2009", 2)
-#'
+#'
#' # Example with `vgest_run_store.default`
#' # Running vgest for:
#' # - the first configuration of reservoir rules
@@ -94,7 +89,7 @@ vgest_run_store.Objectives <- function(x, reservoirRuleSet, networkSet,
Qfile, startDate, endDate, ...) {
nothing <- apply(x, 1, function(y) {
vgest_run_store.default(reservoirRuleSet, networkSet,
- Qfile, startDate, endDate,
+ Qfile, startDate, endDate,
y$station, y$flood, y$threshold, ...)
})
}
\ No newline at end of file
--
GitLab