Transitions {Transition} | R Documentation |
Identify Temporal Transitions in Longitudinal Study Data
Description
get_transitions()
identifies temporal transitions in test results for individual
subjects in a longitudinal study.
add_transitions()
interpolates these transitions into a data frame for further analysis.
Usage
add_transitions(
object,
subject = "subject",
timepoint = "timepoint",
result = "result",
transition = "transition",
cap = 0L,
modulate = 0L
)
get_transitions(
object,
subject = "subject",
timepoint = "timepoint",
result = "result",
cap = 0L,
modulate = 0L
)
Arguments
object |
a |
subject |
|
timepoint |
|
result |
|
transition |
|
cap |
|
modulate |
|
Details
The data can be presented in any order e.g., ordered by subject
, by timepoint
,
forwards or backwards in time, or entirely at random, and may have unbalanced designs with different
time points or numbers of test results per subject. However, the user is responsible for
ensuring the data contain unique combinations of subject
, timepoint
and result
;
if not, outputs will be undefined.
Time points should be formatted as Dates
and included in data frame object
in
the column named as specified by argument timepoint
(see Note).
Test results should be semi-quantitiative, formatted as ordered factor
and included in data frame object
in the column named as specified by argument result
(see Note).
Temporal transitions in the test results
for each subject
within the object
data.frame
are characterised using methods governed by options cap
and
modulate
. If these two parameters are both zero (their defaults), a simple arithmetic
difference between the levels of the present and previous result is calculated. Otherwise, if
the value of modulate
is a positive, non-zero integer, the arithmetic difference is
subjected to integer division by that value. Finally, if cap
is a positive, non-zero
integer, the (possibly modulated) absolute arithmetic difference is capped at that value.
Value
add_transitions() |
A |
get_transitions() |
An |
Note
Time points represented by integer
or numeric
values can be converted
to R Dates
conveniently using as.Date()
. If only year information is
available, arbitrary values could be used consistently for month and day e.g., 1st of January of
each year; likewise, the first day of each month could be used arbitrary, if only the
year and month were known.
Quantitive results available as numeric
data can be converted to a semi-quantitative
ordered factor
conveniently using cut()
(see examples).
See Also
data.frame
, Dates
, and ordered factor
.
Other transitions:
PreviousDate
,
PreviousResult
,
uniques()
Examples
# Inspect Blackmore data frame using {base} str()
Blackmore |> str()
# {base} hist() gives insights into the "exercise" column,
# useful for choosing `breaks` and `labels` in cut() below
hist(Blackmore$exercise, include.lowest = TRUE, plot = FALSE)[1:2]
# Tweak Blackmore data frame by converting "age" to dates for the argument
# timepoint (using an arbitrary "origin" of 1-Jan-2000), and converting
# "exercise" to an ordered factor "result" with {base} cut()
Blackmore <- transform(Blackmore,
timepoint = as.Date("2000-01-01") + round(age * 365.25),
result = cut(
exercise,
breaks = seq(0, 30, 2),
labels = paste0("<=", seq(0, 30, 2)[-1]),
include.lowest = TRUE,
ordered_result = TRUE
)
)
# subject, timepoint and result arguments now defaults and required types
Blackmore |> str()
# Integer vector of test result transitions (defaults: cap = modulate = 0)
get_transitions(Blackmore)
# Tabulate values of transitions
get_transitions(Blackmore) |> table()
# Effect of cap argument
get_transitions(Blackmore, cap = 6) |> table()
# Effect of modulate argument
get_transitions(Blackmore, modulate = 2) |> table()
# Add column of test result transitions to data frame
add_transitions(Blackmore) |> head(22)
# Showing transitions as either positive (1) or negative (-1)
# (defaults to modulate = 0)
add_transitions(Blackmore, cap = 1) |> head(14)
rm(Blackmore)