format_time: Parse date-time data to numeric

Description Usage Arguments Details Value See Also Examples

View source: R/format_time.R

Description

A function to parse class POSIX.ct or text strings of date-time data to numeric time for use in respR functions.

Usage

1
format_time(x, time = 1, format = "ymdHMS", start = 0)

Arguments

x

vector or data frame containing strings or class POSIX.ct date-time data to be converted to numeric.

time

numeric value or vector of length 2. Identifies column(s) containing date-time data

format

string. Code describing structure of date-time data. See details. Directly relates to functions in the package lubridate

start

numeric. Default = 0. At what time (in seconds) should the formatted time data start?

Details

Input

Input can be a vector, or data frame. If a vector, output is a vector of equal length containing numeric time data. If a data frame, the column index of the date-time data can be specified using the time = input. If date-time data is split over two columns (e.g. date in one column, time in another), two columns can be specified. The function uses these to combine date and time strings together for conversion. If multiple columns are specified, the format setting should reflect the same order entered in time =. The output data frame will be identical, except a new column called time.num is added as the first column.

Date-time data can be unspaced or separated by any combination of spaces, forward slashes, hyphens, dots, commas, colons, semicolons, or underscores.

E.g. all these are parsed as the same date-time: "2010-02-28 13:10:23", "20100228131023", "2010,02/28 13.10;23", "2010 02 28 13_10-23".

Regardless of input, all data are parsed to numeric time data in seconds duration from the first entry, unless a start number is specified, in which case the series starts at that number (in seconds) and all subsequent times are shifted forward by the same amount.

Syntax

Simply identify the order which the year, month, day, and time appears in your date-time input.

d

Day of the month as decimal number (01–31 or 0–31).

m

Month of the year as decimal number (01–12 or 1–12).

y

Year (2010, 2001, 1989).

H

Hour, must be capitalised (H, not h). Decimal number (00–24 or 0–24).

M

Minute, must be capitalised (M, not m). Decimal number (00–59 or 0–59).

S

Second, must be capitalised (S, not s). Decimal number (00–59 or 0–59).

p

AM/PM indicator. Adding this will format the data as 12-h date-time format.

Print the order in the format string argument, using separators if you choose to (optional): "dmyHMS"; "dmy_HMS" and "d m y H M S" are all the same. Obviously, single experiments will not be conducted across different time zones, so if a time zone is present, it is ignored for the purposes of calculating numeric times. If multiple columns have been specified in the time argument, the format should reflect the same order.

Value

A vector or data frame, depending on input. If input is a vector, a vector of same length containing numeric time is returned. If input is a data frame, the output data frame is identical, except a new column, time.num,of numeric time data in seconds is added as the first column.

See Also

lubridate

Examples

 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
29
30
31
32
33
34
35
36
37
38
# convert year-month-day hour-min-sec
x <- c("09-02-03 01:11:11", "09-02-03 02:11:11","09-02-03 02:25:11")
format_time(x)
## [1]    0 3600 4440

# convert day-month-year hour-min
x <- c("03-02-09 01:11", "03-02-09 02:11","03-02-09 02:25")
format_time(x, format = "dmyHM")
## [1]    0 3600 4440

# convert when AM/PM is present
x <- c("09-02-03 11:11:11 AM", "09-02-03 12:11:11 PM","09-02-03 01:25:11 PM")
format_time(x, format = "dmyHMS") # this is wrong
format_time(x, format = "dmyHMSp")
## [1]    0 3600 8040

# convert dataframe with year-month-day hour-min-sec (ymdHMS default)
x <- data.frame(
  x = c("09-02-03 01:11:11", "09-02-03 02:11:11","09-02-03 02:25:11"),
  y = c(23, 34, 45))
format_time(x, time = 1)

# convert dataframe with time in different column and non-default format
x <- data.frame(
  x = c(23, 34, 45),
  y = c("09-02-2018 11:11:11 AM", "09-02-2018 12:11:11 PM","09-02-2018 01:25:11 PM"),
  z = c(56, 67, 78))
format_time(x, time = 2, format = "dmyHMSp")

# convert dataframe with separate date and time columns crossing midnight
x <- data.frame(
  w = c("09-02-18", "09-02-18","10-02-18"),
  x = c("22:11:11", "23:11:11","00:25:11"),
  y = c(23, 34, 45),
  z = c(56, 67, 78))
format_time(x, time = 2, format = "HMS") # WRONG! Crosses midnight
format_time(x, time = c(1,2), format = "dmyHMS") # Correct
format_time(x, time = c(2,1), format = "HMSdmy") # Different column order & format

januarharianto/respR documentation built on Nov. 13, 2018, 1:21 p.m.