Get or Replace the Timezone of an xts Object's Index

Generic functions to get or replace the timezone of an xts object's index.

Usage

indexTZ(x, ...)

tzone(x, ...)

indexTZ(x) <- value

tzone(x) <- value

Arguments

x: An xts object.
...: Arguments passed to other methods.
value: A valid timezone value (see OlsonNames()).

Value

A one element named vector containing the timezone of the object's index.

Details

Internally, an xts object's index is a numeric value corresponding to seconds since the epoch in the UTC timezone. When an xts object is created, all time index values are converted internally to POSIXct() (which is also in seconds since the UNIX epoch), using the underlying OS conventions and the TZ environment variable. The xts() function manages timezone information as transparently as possible.

The tzone<- function does not change the internal index values (i.e. the index will remain the same time in the UTC timezone).

Note

Both indexTZ() and indexTZ<- are deprecated in favor of tzone() and tzone<-, respectively.

Problems may arise when an object that had been created under one timezone are used in a session using another timezone. This isn't usually a issue, but when it is a warning is given upon printing or subsetting. This warning may be suppressed by setting options(xts_check_TZ = FALSE).

Author

Jeffrey A. Ryan

Examples


# Date indexes always have a "UTC" timezone
x <- xts(1, Sys.Date())
tzone(x)
#> [1] "UTC"
str(x)
#> An xts object on 2026-03-05 / 2026-03-05 containing: 
#>   Data:    double [1, 1]
#>   Index:   Date [1] (TZ: "UTC")
print(x)
#>            [,1]
#> 2026-03-05    1

# The default 'tzone' is blank -- your machine's local timezone,
# determined by the 'TZ' environment variable.
x <- xts(1, Sys.time())
tzone(x)
#> [1] ""
str(x)
#> An xts object on 2026-03-05 20:17:49.679045 / 2026-03-05 20:17:49.679045 containing: 
#>   Data:    double [1, 1]
#>   Index:   POSIXct,POSIXt [1] (TZ: "")

# now set 'tzone' to different values
tzone(x) <- "UTC"
str(x)
#> An xts object on 2026-03-05 20:17:49.679045 / 2026-03-05 20:17:49.679045 containing: 
#>   Data:    double [1, 1]
#>   Index:   POSIXct,POSIXt [1] (TZ: "UTC")

tzone(x) <- "America/Chicago"
str(x)
#> An xts object on 2026-03-05 14:17:49.679045 / 2026-03-05 14:17:49.679045 containing: 
#>   Data:    double [1, 1]
#>   Index:   POSIXct,POSIXt [1] (TZ: "America/Chicago")

y <- timeBasedSeq('2010-01-01/2010-01-03 12:00/H')
y <- xts(seq_along(y), y, tzone = "America/New_York")

# Changing the tzone does not change the internal index values, but it
# does change how the index is printed!
head(y)
#> Warning: object timezone ('America/New_York') is different from system timezone ('')
#>                     [,1]
#> 2009-12-31 19:00:00    1
#> 2009-12-31 20:00:00    2
#> 2009-12-31 21:00:00    3
#> 2009-12-31 22:00:00    4
#> 2009-12-31 23:00:00    5
#> 2010-01-01 00:00:00    6
head(.index(y))
#> [1] 1262304000 1262307600 1262311200 1262314800 1262318400 1262322000
tzone(y) <- "Europe/London"
head(y)          # the index prints with hours, but
#> Warning: object timezone ('Europe/London') is different from system timezone ('')
#>                     [,1]
#> 2010-01-01 00:00:00    1
#> 2010-01-01 01:00:00    2
#> 2010-01-01 02:00:00    3
#> 2010-01-01 03:00:00    4
#> 2010-01-01 04:00:00    5
#> 2010-01-01 05:00:00    6
head(.index(y))  # the internal index is not changed!
#> [1] 1262304000 1262307600 1262311200 1262314800 1262318400 1262322000