Description Usage Arguments Value Note Author(s) References See Also Examples
Convert Coordinated Universal Time (UTC) base::as.POSIXct()
date-time values into various character-string representations for time zones. The UTC offset for individual time zones are determined from the globe-encompassing time-zone codes recognized by the U.S. Geological Survey National Water Information System (NWIS) (U.S. Geological Survey, 2019) (see Note). The time zones are tracked in a separate database slot than the UTC date-time.
The justification for this package is that the time-zone codes are not standard to the function
base::OlsonNames()
within base R, but the NWIS names are an ANSI SQL/92 time-zone offset string. American National Standards Institute (ANSI) SQL/92 was the third revision of the Structured Query Language (SQL) database query language. NWIS stores date-times exclusively in UTC, and certain data retrievals can be (purposefully) kept in UTC, though commonly NWIS or various data output methods (beyond the scope of this documentation) switches in output either to the user's local time zone or the USGS data-collection site, local time-zone code.
For some data operations external to NWIS, it is useful to retain UTC convention for the core date-time information and convert to local time on character-string output. Further, NWIS also retains a date-accuracy code, which is actively used to truncate character-string output of date-time values. The utc2nwislocal
function as a result relies on three separate parts that are the first three arguments. The basis of this function is to add respectively UTC offsets (in seconds) to the UTC as.POSIXct
date-times and convert the results into character strings.
Warning: The function for purposes of execution speed does not check that an UTC is assigned to the first argument dt
.
The core operation of this function for the ith value is to add or subtract the number of seconds from the UTC:
1 2 3 4 |
and really the rest of the logic in the function is error trapping, adding optional features, and support for vectorization.
1 2 |
dt |
A vector of |
tz |
A vector of NWIS time-zone codes (such as |
acy |
The NWIS date-time accuracy code (such as |
no.ending.ws |
A logical to strip trailing whitespace from the end of the converted values. This is provided as switch to superceed the results of the various default right-padding styles; |
addat |
A logical to trigger whether the “at” character is inserted instead of a space between the date and time component; |
nosec |
A logical to override the |
pad |
A logical to right-side pad a date-time stamp to 19 or 16 characters wide before the time-zone code is appended if it makes sense for the accuracy (codes \in |
secpad |
A logical controlling whether the date-time padding on the right-side is 19 ( |
tzpad |
A logical controlling whether the time-zone stamp is right-padded to 5 characters. |
A character vector of converted date and times from UTC to the time zones requested. The date-time stamp will be right-padded 16 or 19 characters wide, and the time-zone code is right-padded to 5 characters or not at all. This padding can be stripped by the no.ending.ws
argument.
A list of the globe-encompassing NWIS time-zone codes can be found at NWIS Time Zones (accessed on October 22, 2019) and the date-time accuracy codes can be found at
NWIS Time Accuracy Codes (accessed on October 22, 2019). The conversion of time-zone code to UTC offset is made by tabular lookup. The sysdata.rda
file (RData binary format) that comes with this package in ./R/sysdata.rda
contains the environment
named .NWIStzUTC
. Within this environment
are three other environments titled
TimeZone_Names
,
TimeZone_Offset
, and
TimeZone_Offset_seconds
.
The .NWIStzUTC
and these other three are not exported by the utc2nwislocal package but they can be accessed, by curious users, through “triple-colon insistance (notation).” The following code shows how to access these three tables:
1 2 3 4 5 6 7 8 9 10 11 12 13 | ls(utc2nwislocal:::.NWIStzUTC) # See the three table names
# "TimeZone_Names" "TimeZone_Offset" "TimeZone_Offset_seconds"
# The creation of a vector of all time-zone codes
all_tz_codes <- ls(utc2nwislocal:::.NWIStzUTC$TimeZone_Names)
# Demonstration of access for a given code.
utc2nwislocal:::.NWIStzUTC$TimeZone_Names$IDLE
# "International Date Line, East"
utc2nwislocal:::.NWIStzUTC$TimeZone_Offset$IDLE
# "+12:00"
utc2nwislocal:::.NWIStzUTC$TimeZone_Offset_seconds$IDLE
# 43200
|
The code, which was used the create the sysdata.rda
, is located in file buildSYSDATA(R).txt
that is located in the ./inst/doc
subdirectory of this package's sources. NWIS appears to use a 5 (five) character wide (max) time-zone code convention. It is important to state that the table-lookup herein is based on white space being stripped from time-zone code. All spaces are internally stripped from the tz
before processing commences—the pad is possible to return through the tzpad
argument.
W.H. Asquith
U.S. Geological Survey, 2019, USGS water data for the Nation: U.S. Geological Survey National Water Information System database, accessed August 9, 2019, at https://doi.org/10.5066/F7P55KJN.
nwislocal2utc_offset_hours
, nwislocal2utc_offset_seconds
,
utc_offset_hours2nwislocal
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 | # Australia Eastern Standard Time is +10:00 to UTC and NWIS code == "AESST"
# EST, CDT, and PST are obviously American time zones.
dt_va <- as.POSIXct(c("2012-10-06 12:00:00", "2016-12-17 16:00:00",
"2017-07-26 06:15:00", "2017-07-26 06:15:30"), tz="UTC")
# Let us look only at impact on the Australian "data point."
utc2nwislocal(dt_va, tz="AESST")[1] # tz vectored to length of dt_va
# "2012-10-06 23:00:00 AESST"
utc2nwislocal(dt_va, tz="AESST", "h")[1] # m means accurate down to the hour
# "2012-10-06 23 AESST"
utc2nwislocal(dt_va, tz="AESST", "s", nosec=TRUE)[1]
# "2012-10-06 23:00 AESST"
utc2nwislocal(dt_va, tz="AESST", "M")[1]
# "2012-10 "
utc2nwislocal(dt_va, tz="AESST", "Y")[1]
# "2012 "
utc2nwislocal(as.POSIXct("2011-03-14 15:30:00"), tz="MDT", "m", secpad=TRUE)
# "2011-03-14 09:30 MDT"
utc2nwislocal(as.POSIXct("2011-03-14 15:30:00"), tz="MDT", "m", secpad=FALSE)
# "2011-03-14 09:30 MDT"
tzs <- c("AESST", "EST", "CDT", "PST")
utc2nwislocal(dt_va, tz=tzs) # tz vectored to length of dt_va
utc2nwislocal(dt_va, tz=tzs, "h") # hour means accurate down to the hour
utc2nwislocal(dt_va, tz=tzs, "s", nosec=TRUE)
utc2nwislocal(dt_va, tz=tzs, c("D","h","m","s"))
|
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.