vignettes/format_time.Rmd
format_time.RmdTo prepare data and extract rates the functions in respR
require data be put into a very simple structure - numeric time against
oxygen in any common units in a data.frame. In other words,
the time data must be as numeric timestamps or time-elapsed values in
seconds, minutes, hours or days, each with a paired oxygen value.
If you have imported data (see vignette("importing"))
but it does not contain a numeric time or timestamp column, the
format_time() function can parse date-time columns to
numeric time-elapsed values. Internally, it uses functionality in the
package lubridate.
format_time()
The date-times can either be passed as a vector (for
example, so it can be appended to the original data frame), or as a
data.frame. If the input is a vector, the output is a
vector of the same length. If it is a data frame, the time
input indicates the column number (or numbers, if they is split across
several) containing the date-times, the default being
time = 1. The resulting data frame will be identical, with
a new column named time.num containing the converted
numeric time added as the last column.
We also need to specify the format of the date-times in
the correct order. See help(format_time) for further
info.
Note: numeric time data will always output in
seconds regardless of the input format. These can easily be
converted to other units using simple arithmetic (e.g. to hours:
time.num/60/60).
Here’s an example of a 2-column data frame with date-time data and oxygen.
head(data, n = 5)
#> Date_Time O2_mg/L
#> <char> <num>
#> 1: 5/11/2017 9:24:04 AM 10.056
#> 2: 5/11/2017 9:24:05 AM 10.015
#> 3: 5/11/2017 9:24:06 AM 10.012
#> 4: 5/11/2017 9:24:07 AM 10.027
#> 5: 5/11/2017 9:24:08 AM 10.032We will convert these as both vector and
data.frame inputs.
## Pass as vector
data_2 <- format_time(data[[1]], format = "dmyHMSp")
head(data_2)
#> [1] 1 2 3 4 5 6
## Pass as data frame
data_3 <- format_time(data, time = 1, format = "dmyHMSp")
head(data_3)
#> Date_Time O2_mg/L time_num
#> <char> <num> <num>
#> 1: 5/11/2017 9:24:04 AM 10.056 1
#> 2: 5/11/2017 9:24:05 AM 10.015 2
#> 3: 5/11/2017 9:24:06 AM 10.012 3
#> 4: 5/11/2017 9:24:07 AM 10.027 4
#> 5: 5/11/2017 9:24:08 AM 10.032 5
#> 6: 5/11/2017 9:24:09 AM 10.073 6By default, the numeric time data will start at 1, but we can override this. This could be useful if data are split into separate files, and you want to append the start of one onto the end of another, or you simply want to link a specific numeric time value to the start of the experiment.
## as data frame
data_4 <- format_time(data, time = 1, format = "dmyHMSp", start = 1000)
head(data_4)
#> Date_Time O2_mg/L time_num
#> <char> <num> <num>
#> 1: 5/11/2017 9:24:04 AM 10.056 1000
#> 2: 5/11/2017 9:24:05 AM 10.015 1001
#> 3: 5/11/2017 9:24:06 AM 10.012 1002
#> 4: 5/11/2017 9:24:07 AM 10.027 1003
#> 5: 5/11/2017 9:24:08 AM 10.032 1004
#> 6: 5/11/2017 9:24:09 AM 10.073 1005In some oxygen probe system output files, the date and times are
split across multiple columns. In these cases, formatting the time only
data usually works, however the more careful and robust approach is to
use both. This can be done by specifying multiple columns as the
time input. Note, the format should reflect
the correct order.
These data have dates and times in different columns.
data
#> date time oxy
#> 1 5/11/2017 23:00 10.056
#> 2 5/11/2017 23:30 10.015
#> 3 6/11/2017 00:00 10.012
#> 4 6/11/2017 00:30 10.027
#> 5 6/11/2017 01:00 10.032
#> 6 6/11/2017 01:30 10.073We use time to specify both columns, and have
format in the same order.
format_time(data, time = 1:2, format = "dmyHM")
#> date time oxy time_num
#> 1 5/11/2017 23:00 10.056 1
#> 2 5/11/2017 23:30 10.015 1801
#> 3 6/11/2017 00:00 10.012 3601
#> 4 6/11/2017 00:30 10.027 5401
#> 5 6/11/2017 01:00 10.032 7201
#> 6 6/11/2017 01:30 10.073 9001Some oxygen probe system files have time values, but no dates. These
can also be parsed. This even works if the time values cross midnight.
Note time data with AM/PM should have a p appended to the
format.
format_time(data, time = 1, format = "HMSp")
#> Times cross midnight, attempting to parse correctly...
#> time oxy time_num
#> 1 11:00:00 PM 10.056 1
#> 2 11:30:00 PM 10.015 1801
#> 3 00:00:00 AM 10.012 3601
#> 4 00:30:00 AM 10.027 5401
#> 5 01:00:00 AM 10.032 7201
#> 6 01:30:00 AM 10.073 9001What if there are important notes or events associated with specific times in your experiment? For example, flushing of chambers, imposing a treatment, changing the temperature, noting a response, etc. Resetting the times via formatting the time data may make these notes difficult to associate to certain stages of the analysis. This is easily dealt with by formatting the times of the events in the same way you formatted the data. You only need to make sure at least one event is associated with the same start time used for the experimental data.
Here’s an example of some experimental notes (in some systems such notes can be entered in the software, and so may be included in output files, or they could be copied from a lab book into a csv file and imported).
exp_notes
#> times events
#> 1 8/17/2016 9:42:02 Experiment start
#> 2 8/17/2016 9:52:02 Flush period start
#> 3 8/17/2016 9:54:34 Flush period end
#> 4 8/17/2016 10:19:02 Specimen acting normally
#> 5 8/17/2016 12:04:54 Went to lunch
#> 6 8/17/2016 14:31:22 Swim speed set to 20 cm/s
format_time(exp_notes, format = "mdyHMS")
#> times events time_num
#> 1 8/17/2016 9:42:02 Experiment start 1
#> 2 8/17/2016 9:52:02 Flush period start 601
#> 3 8/17/2016 9:54:34 Flush period end 753
#> 4 8/17/2016 10:19:02 Specimen acting normally 2221
#> 5 8/17/2016 12:04:54 Went to lunch 8573
#> 6 8/17/2016 14:31:22 Swim speed set to 20 cm/s 17361These do not have to be in the same date-time format, or even at the
same precision, depending on how accurately you need to know when events
occurred. The important factors are associating at least one event with
the same start time used to format the experimental time data,
and using the correct format setting.
format_time(exp_notes, format = "HM")
#> times events time_num
#> 1 9:42 Experiment start 1
#> 2 9:52 Flush period start 601
#> 3 9:54 Flush period end 721
#> 4 10:19 Specimen acting normally 2221
#> 5 12:04 Went to lunch 8521
#> 6 14:31 Swim speed set to 20 cm/s 17341After your data is in a paired, numeric oxygen~time structure, it can
be passed to inspect() to check the importing or time
formatting has worked, look for common errors, and visualise the
dataset. See vignette("inspecting").