Merge branch 'joshuaulrich:main' into 423_recycle_col_input

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: xts
 Type: Package
 Title: eXtensible Time Series
-Version: 0.13.2.2
+Version: 0.14.1
 Authors@R: c(
   person(given=c("Jeffrey","A."), family="Ryan", role=c("aut","cph")),
   person(given=c("Joshua","M."), family="Ulrich", role=c("cre","aut"), email="[email protected]"),
@@ -17,3 +17,5 @@ Description: Provide for uniform handling of R's different time-based data class
 License: GPL (>= 2)
 URL: https://joshuaulrich.github.io/xts/, https://github.com/joshuaulrich/xts
 BugReports: https://github.com/joshuaulrich/xts/issues
+Encoding: UTF-8
+Roxygen: list(markdown = TRUE)

NAMESPACE

@@ -161,7 +161,6 @@ export(axTicksByTime)
 export(plot.xts)
 export(addLegend)
 export(addEventLines)
-# export(addPoints)
 export(addSeries)
 export(addPanel)
 export(addPolygon)
@@ -172,16 +171,10 @@ S3method(print, replot_xts)
 S3method(plot, replot_xts)
 S3method(str, replot_xts)
 
-#export(lines.xts)
-#S3method(lines,xts)
-#S3method(points,xts)
-
-#export(Lag.xts, Next.xts) #, Diff.xts)
 
 export(lag.xts)
 export(diff.xts)
 export(merge.xts)
-#export(mergeXts)
 S3method(all.equal, xts)
 S3method(split, xts)
 S3method(lag,xts)
@@ -208,7 +201,6 @@ importFrom(zoo,'index<-')
 importFrom(zoo,'time<-')
 importFrom(zoo, na.locf)
 importFrom(zoo, as.zoo)
-#importFrom(zoo, lagts)
 importFrom(zoo, rollapply)
 importFrom(zoo, na.approx)
 importFrom(zoo, na.fill)
@@ -275,7 +267,6 @@ S3method(cumsum, xts)
 S3method(cumprod, xts)
 S3method(cummin, xts)
 S3method(cummax, xts)
-#S3method(lagts,xts)
 S3method(rollapply, xts)
 
 # list specific methods
@@ -286,7 +277,6 @@ S3method(as.xts, ts)
 S3method(as.ts, xts)
 
 # zoo specific methods
-#importFrom(zoo,as.zoo)  # now in zoo
 S3method(as.xts,zoo)
 if (getRversion() >= "3.6.0" && utils::packageVersion("zoo") < "1.8.5") {
   # xts:::as.zoo.xts was copied to zoo:::as.zoo.xts in zoo 1.8-5
@@ -302,7 +292,6 @@ S3method(as.xts,matrix)
 S3method(as.matrix,xts)
 
 # environment specific methods
-#S3method(as.xts,environment)
 S3method(as.environment,xts)
 
 # timeSeries (package:timeSeries) specific methods
@@ -327,5 +316,3 @@ S3method(as.xts,yearqtr)
 # timeDate specific methods
 S3method(as.xts,timeDate)
 ## currently unexported functions that _may_ be exported at some point
-
-#export(startof,endof,firstof,lastof)

NEWS.md

@@ -1,3 +1,24 @@
+# xts 0.14.0 (2024-06-05)
+
+* `addEventLines()` and `addLegend()` now draw on multiple panels when `on` is
+  a vector. Thanks to Ethan Smith for the report.
+  ([#420](https://github.com/joshuaulrich/xts/issues/420))
+
+* Replace `SET_TYPEOF()` in merge.c because it will error when it tries to
+  convert a REAL to an INTEGER. Thanks to Kurt Hornik for the report!
+  ([#419](https://github.com/joshuaulrich/xts/issues/419))
+
+* Fix crash when 'j' is not an integer and in [0, 1) (e.g. `j = 0.1`). Also
+  throw a warning when 'j' is not an integer.
+  ([#413](https://github.com/joshuaulrich/xts/issues/413))
+  ([#415](https://github.com/joshuaulrich/xts/issues/415))
+
+* Fix plot header when `layout()` is used to draw multiple plots on a single
+  device. Thanks to Dirk Eddelbuettel for the report and testing!
+  ([#412](https://github.com/joshuaulrich/xts/issues/412))
+
+* Fix plot legend location when the y-axis is log scale.
+  ([#407](https://github.com/joshuaulrich/xts/issues/407))
 
 # xts 0.13.2 (2024-01-21)
 

R/Date.R

@@ -1,5 +1,5 @@
 #
-#   xts: eXtensible time-series 
+#   xts: eXtensible time-series
 #
 #   Copyright (C) 2008  Jeffrey A. Ryan jeff.a.ryan @ gmail.com
 #
@@ -19,6 +19,7 @@
 #   along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 
+#' @rdname as.xts
 `as.xts.Date` <- function(x,...) {
   xts(x=NULL,order.by=x,...)
 }

R/Math.xts.R

@@ -1,5 +1,5 @@
 #
-#   xts: eXtensible time-series 
+#   xts: eXtensible time-series
 #
 #   Copyright (C) 2008  Jeffrey A. Ryan jeff.a.ryan @ gmail.com
 #
@@ -64,4 +64,4 @@ sd.xts <- function(x,na.rm=FALSE) {
         x<-as.numeric(x)
         sd(x,na.rm=na.rm)
     } else apply(x,2,sd,na.rm=na.rm)
-}
+}

R/OHLC.R

@@ -1,5 +1,5 @@
 #
-#   xts: eXtensible time-series 
+#   xts: eXtensible time-series
 #
 #   Copyright (C) 2008  Jeffrey A. Ryan jeff.a.ryan @ gmail.com
 #

R/Ops.xts.R

@@ -1,5 +1,5 @@
 #
-#   xts: eXtensible time-series 
+#   xts: eXtensible time-series
 #
 #   Copyright (C) 2008  Jeffrey A. Ryan jeff.a.ryan @ gmail.com
 #

R/POSIX.R

@@ -1,5 +1,5 @@
 #
-#   xts: eXtensible time-series 
+#   xts: eXtensible time-series
 #
 #   Copyright (C) 2008  Jeffrey A. Ryan jeff.a.ryan @ gmail.com
 #
@@ -19,6 +19,7 @@
 #   along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 
+#' @rdname as.xts
 as.xts.POSIXt <- function(x, ...)
 {
   xts(NULL, order.by=x)

R/adj.time.R

@@ -19,6 +19,7 @@
 #   along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 
+#' @rdname align.time
 adj.time <-
 function(x, ...) {
   tr <- match.call(expand.dots=FALSE)$...

R/align.time.R

@@ -19,10 +19,43 @@
 #   along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 
+#' Align seconds, minutes, and hours to beginning of next period.
+#' 
+#' Change timestamps to the start of the next period, specified in multiples of
+#' seconds.
+#' 
+#' This function is an S3 generic. The result is to round up to the next period
+#' determined by 'n modulo x'.
+#' 
+#' @param x Object containing timestamps to align.
+#' @param n Number of seconds to adjust by.
+#' @param \dots Additional arguments. See details.
+#' 
+#' @return A new object with the same class as `x`.
+#' 
+#' @author Jeffrey A. Ryan with input from Brian Peterson
+#' 
+#' @seealso [`to.period()`]
+#' 
+#' @keywords chron manip ts misc
+#' @examples
+#' 
+#' x <- Sys.time() + 1:1000
+#' 
+#' # every 10 seconds
+#' align.time(x, 10)
+#' 
+#' # align to next whole minute
+#' align.time(x, 60)
+#' 
+#' # align to next whole 10 min interval
+#' align.time(x, 10 * 60)
+#' 
 align.time <- function(x, ...) {
   UseMethod("align.time")
 }
 
+#' @rdname align.time
 align.time.xts <- function(x, n=60, ...) {
   if(n <= 0) stop("'n' must be positive")
   .xts(x, .index(x) + (n-.index(x) %% n), tzone=tzone(x), tclass=tclass(x))
@@ -38,6 +71,7 @@ align.time.POSIXlt <- function(x, n=60, ...) {
   as.POSIXlt(align.time(as.POSIXct(x),n=n,...))
 }
 
+#' @rdname align.time
 shift.time <- function(x, n=60, ...) {
   UseMethod("shift.time")
 }
@@ -46,9 +80,12 @@ shift.time.xts <- function(x, n=60, ...) {
   .xts(x, .index(x) + n, tzone=tzone(x), tclass=tclass(x))
 }
 
-is.index.unique <- is.time.unique <- function(x) {
+#' @rdname make.index.unique
+is.index.unique <- function(x) {
   UseMethod("is.time.unique")
 }
+#' @rdname make.index.unique
+is.time.unique <- is.index.unique
 
 is.time.unique.xts <- function(x) {
   isOrdered(.index(x), strictly=TRUE)
@@ -58,10 +95,54 @@ is.time.unique.zoo <- function(x) {
   isOrdered(index(x), strictly=TRUE)
 }
 
-make.index.unique <- make.time.unique <- function(x, eps=0.000001, drop=FALSE, fromLast=FALSE, ...) {
+#' Force Time Values To Be Unique
+#' 
+#' A generic function to force sorted time vectors to be unique. Useful for
+#' high-frequency time-series where original time-stamps may have identical
+#' values. For the case of xts objects, the default `eps` is set to ten
+#' microseconds. In practice this advances each subsequent identical time by
+#' `eps` over the previous (possibly also advanced) value.
+#' 
+#' The returned time-series object will have new time-stamps so that
+#' `isOrdered(.index(x))` evaluates to `TRUE`.
+#' 
+#' @param x An xts object, or POSIXct vector.
+#' @param eps A value to add to force uniqueness.
+#' @param drop Should duplicates be dropped instead of adjusted by `eps`?
+#' @param fromLast When `drop = TRUE`, `fromLast` controls which duplicated
+#'   times are dropped. When `fromLast = FALSE`, the earliest observation with
+#'   an identical timestamp is kept and subsequent observations are dropped.
+#' @param \dots Unused.
+#' 
+#' @return A modified version of `x` with unique timestamps.
+#' 
+#' @note Incoming values must be pre-sorted, and no check is done to make sure
+#'   that this is the case.  \sQuote{integer} index value will be coerced to
+#'   \sQuote{double} when `drop = FALSE`.
+#' 
+#' @author Jeffrey A. Ryan
+#' 
+#' @seealso [`align.time()`]
+#' 
+#' @rdname make.index.unique
+#' @keywords ts
+#' @examples
+#' 
+#' ds <- options(digits.secs=6) # so we can see the change
+#' 
+#' x <- xts(1:10, as.POSIXct("2011-01-21") + c(1,1,1,2:8)/1e3)
+#' x
+#' make.index.unique(x)
+#' 
+#' options(ds)
+#' 
+make.index.unique <- function(x, eps=0.000001, drop=FALSE, fromLast=FALSE, ...) {
   UseMethod("make.index.unique")
 }
 
+#' @rdname make.index.unique
+make.time.unique <- make.index.unique
+
 make.index.unique.xts <- function(x, eps=0.000001, drop=FALSE, fromLast=FALSE, ...) {
   if( !drop) {
     .Call(C_make_index_unique, x, eps)

R/as.environment.xts.R

@@ -18,7 +18,36 @@
 #   You should have received a copy of the GNU General Public License
 #   along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-
+#' Coerce an xts Object to an Environment by Column
+#' 
+#' Method to automatically convert an xts object to an environment containing
+#' vectors representing each column of the original xts object. The name of
+#' each object in the resulting environment corresponds to the name of the
+#' column of the xts object.
+#' 
+#' @param x An xts object.
+#' 
+#' @return An environment containing `ncol(x)` vectors extracted by
+#'   column from `x`.
+#'
+#' @note Environments do not preserve (or have knowledge) of column order and
+#'   cannot be subset by an integer index.
+#' 
+#' @author Jeffrey A. Ryan
+#' 
+#' @keywords manip
+#' @examples
+#' 
+#' x <- xts(1:10, Sys.Date()+1:10)
+#' colnames(x) <- "X"
+#' y <- xts(1:10, Sys.Date()+1:10)
+#' colnames(x) <- "Y"
+#' xy <- cbind(x,y)
+#' colnames(xy)
+#' e <- as.environment(xy)    # currently using xts-style positive k 
+#' ls(xy)
+#' ls.str(xy)
+#' 
 as.environment.xts <- function(x) {
   e <- new.env()
   lapply(1:NCOL(x), function(.) assign(colnames(x)[.], x[,.],envir=e))

R/as.numeric.R

@@ -1,5 +1,5 @@
 #
-#   xts: eXtensible time-series 
+#   xts: eXtensible time-series
 #
 #   Copyright (C) 2008  Jeffrey A. Ryan jeff.a.ryan @ gmail.com
 #

R/axTicksByTime.R

@@ -1,5 +1,5 @@
 #
-#   xts: eXtensible time-series 
+#   xts: eXtensible time-series
 #
 #   Copyright (C) 2008  Jeffrey A. Ryan jeff.a.ryan @ gmail.com
 #
@@ -19,6 +19,48 @@
 #   along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 
+#' Compute x-Axis Tickmark Locations by Time
+#' 
+#' Compute x-axis tickmarks like [`axTicks()`] in base but with respect to
+#' time. This function is written for internal use, and documented for those
+#' wishing to use it for customized plots.
+#' 
+#' The default `ticks.on = "auto"` uses heuristics to compute sensible tick
+#' locations. Use a combination of `ticks.on` and `k` to create tick locations
+#' at specific intervals. For example, `ticks.on = "days"` and `k = 7` will
+#' create tick marks every 7 days.
+#' 
+#' When `format.labels` is a character string the possible values are the same
+#' as those listed in the Details section of [`strptime()`].
+#' 
+#' @param x An object indexed by time or a vector of times/dates.
+#' @param ticks.on Time unit for tick locations.
+#' @param k Frequency of tick locations.
+#' @param labels Should a labeled vector be returned?
+#' @param format.labels Either a logical value specifying whether labels should
+#'   be formatted, or a character string specifying the format to use.
+#' @param ends Should the ends be adjusted?
+#' @param gt Lower bound on number of tick locations.
+#' @param lt Upper bound on number of tick locations.
+#' 
+#' @return A numeric vector of index element locations where tick marks should
+#' be drawn. These are *locations* (e.g. 1, 2, 3, ...), *not* the
+#' index timestamps.
+#' 
+#' If possible, the result will be named using formatted values from the index
+#' timestamps. The names will be used for the tick mark labels.
+#' 
+#' @author Jeffrey A. Ryan
+#' 
+#' @seealso [`endpoints()`]
+#' @keywords utilities
+#' @examples
+#' 
+#' data(sample_matrix)
+#' axTicksByTime(as.xts(sample_matrix),'auto')
+#' axTicksByTime(as.xts(sample_matrix),'weeks')
+#' axTicksByTime(as.xts(sample_matrix),'months',7)
+#' 
 axTicksByTime <-
 function(x, ticks.on = "auto", k = 1, labels = TRUE, format.labels = TRUE,
          ends = TRUE, gt = 2, lt = 30)