From 7e046defff71b38549b877fc094d6157686a488d Mon Sep 17 00:00:00 2001 From: Andrew Singleton Date: Wed, 29 Nov 2023 08:58:15 +0100 Subject: [PATCH] Add functions for generating time sequence character vectors --- DESCRIPTION | 2 +- NAMESPACE | 4 ++++ R/date_time.R | 57 ++++++++++++++++++++++++++++++++++++++++++++----- man/seq_dttm.Rd | 42 ++++++++++++++++++++++++++++++------ 4 files changed, 92 insertions(+), 13 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index d6bff86..37090ec 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,6 +1,6 @@ Package: harpCore Title: Core functions and methods for the harp ecosystem -Version: 0.2.0.9000 +Version: 0.2.0.9001 Authors@R: person("Andrew", "Singleton", , "andrewts@met.no", role = c("aut", "cre")) Description: harp is a collection of packages for reading, analysing and diff --git a/NAMESPACE b/NAMESPACE index 5ead049..7e04946 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -234,9 +234,13 @@ export(q_to_rh) export(rh_to_td) export(scale_param) export(select_members) +export(seq_days) export(seq_double) export(seq_dttm) +export(seq_hours) +export(seq_mins) export(seq_pwr2) +export(seq_secs) export(set_units) export(std_dev) export(to_seconds) diff --git a/R/date_time.R b/R/date_time.R index 43f919b..f950f1e 100644 --- a/R/date_time.R +++ b/R/date_time.R @@ -327,16 +327,23 @@ unixtime_to_str_dttm <- function(x) { ### -#' Generate a sequence of date-time strings +#' Generate a sequence of time strings #' -#' Given a start date-time, end date-time and time resolution a regular sequence -#' of date-time strings is generated. The start and end date-times must be a -#' string or numeric of the form YYYYMMDD, YYYYMMDDhh, YYYYMMDDhhmm, or -#' YYYYMMDDhhmmss. +#' @description Given a start date-time, end date-time and time resolution +#' `seq_dttm()` generates a regular sequence of date-time strings is generated. +#' The start and end date-times must be a string or numeric of the form +#' YYYYMMDD, YYYYMMDDhh, YYYYMMDDhhmm, or YYYYMMDDhhmmss. #' #' The output sequence is a vector of strings. Truncation of the strings is done #' so that the last zero values are removed. #' +#' `seq_secs()`, `seq_mins()`, `seq_hours()` and `seq_days()` generate regular +#' sequences of numbers as character vectors with a character specifying the +#' time unit. These vectors can be used to, for example, generate sequences of +#' lead times for input to functions such as +#' \code{\link[harpIO]{read_forecast}}. \code{\link{to_seconds}} can be used to +#' convert any of the +#' #' @param start_dttm The date-time at the start of the sequence. Must be a #' string or numeric of the form YYYYMMDD, YYYYMMDDhh, YYYYMMDDhhmm, or #' YYYYMMDDhhmmss. @@ -376,6 +383,46 @@ seq_dttm <- function(start_dttm, end_dttm, by = "1h") { as_str_dttm(seq(start_dttm, end_dttm, by_secs)) } +#' @inheritParams base::seq +#' +#' @rdname seq_dttm +#' @export +#' +#' @examples +#' seq_secs(0, 60, 5) +seq_secs <- function(from, to, by = 1) { + paste0(seq(from, to, by), "s") +} + +#' @rdname seq_dttm +#' @export +#' +#' @examples +#' seq_mins(0, 60, 15) +seq_mins <- function(from, to, by = 1) { + paste0(seq(from, to, by), "m") +} + +#' @rdname seq_dttm +#' @export +#' +#' @examples +#' seq_hours(0, 6) +#' seq_hours(0, 6, 3) +seq_hours <- function(from, to, by = 1) { + paste0(seq(from, to, by), "h") +} + +#' @rdname seq_dttm +#' @export +#' +#' @examples +#' seq_days(0, 7) +#' seq_days(0, 28, 7) +seq_days <- function(from, to, by = 1) { + paste0(seq(from, to, by), "d") +} + #' Convert a time period to seconds #' #' Convert number of minutes, hours, days or weeks into seconds. If \code{x} is diff --git a/man/seq_dttm.Rd b/man/seq_dttm.Rd index 328807d..9c07a9f 100644 --- a/man/seq_dttm.Rd +++ b/man/seq_dttm.Rd @@ -2,9 +2,21 @@ % Please edit documentation in R/date_time.R \name{seq_dttm} \alias{seq_dttm} -\title{Generate a sequence of date-time strings} +\alias{seq_secs} +\alias{seq_mins} +\alias{seq_hours} +\alias{seq_days} +\title{Generate a sequence of time strings} \usage{ seq_dttm(start_dttm, end_dttm, by = "1h") + +seq_secs(from, to, by = 1) + +seq_mins(from, to, by = 1) + +seq_hours(from, to, by = 1) + +seq_days(from, to, by = 1) } \arguments{ \item{start_dttm}{The date-time at the start of the sequence. Must be a @@ -17,23 +29,39 @@ numeric of the form YYYYMMDD, YYYYMMDDhh, YYYYMMDDhhmm, or YYYYMMDDhhmmss.} \item{by}{Increment of the sequence. If numeric, it is considered to be in hours, otherwise a string with a number followed by a unit. Units can be "s", for seconds; "m", for minutes; "h", for hours; or "d", for days.} + +\item{from, to}{the starting and (maximal) end values of the + sequence. Of length \code{1} unless just \code{from} is supplied as + an unnamed argument.} } \value{ A sequence of date-time strings } \description{ -Given a start date-time, end date-time and time resolution a regular sequence -of date-time strings is generated. The start and end date-times must be a -string or numeric of the form YYYYMMDD, YYYYMMDDhh, YYYYMMDDhhmm, or -YYYYMMDDhhmmss. -} -\details{ +Given a start date-time, end date-time and time resolution +\code{seq_dttm()} generates a regular sequence of date-time strings is generated. +The start and end date-times must be a string or numeric of the form +YYYYMMDD, YYYYMMDDhh, YYYYMMDDhhmm, or YYYYMMDDhhmmss. + The output sequence is a vector of strings. Truncation of the strings is done so that the last zero values are removed. + +\code{seq_secs()}, \code{seq_mins()}, \code{seq_hours()} and \code{seq_days()} generate regular +sequences of numbers as character vectors with a character specifying the +time unit. These vectors can be used to, for example, generate sequences of +lead times for input to functions such as +\code{\link[harpIO]{read_forecast}}. \code{\link{to_seconds}} can be used to +convert any of the } \examples{ seq_dttm(20220306, 20220307) seq_dttm(20220306, 20220307, by = "30m") seq_dttm(20220301, 20220331, by = "1d") seq_dttm(202203061030, 202203061045, by = "30s") +seq_secs(0, 60, 5) +seq_mins(0, 60, 15) +seq_hours(0, 6) +seq_hours(0, 6, 3) +seq_days(0, 7) +seq_days(0, 28, 7) }