Transition (version 1.0.1)

Transitions: 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
)

Value

add_transitions()

A data.frame based on object, with an added column of type integer containing the values of the test result transitions.

get_transitions()

An integer vector of length nrow(object), containing the values of the test result transitions ordered in the exact sequence of the subject and timepoint in object.

Arguments

object

a data.frame (or object coercible by as.data.frame() to a data frame) containing the data to be analysed.

subject

character, name of the column (of type integer or factor) identifying individual study subjects; default "subject".

timepoint

character, name of the column recording time points (as Dates) of testing of subjects; default "timepoint".

result

character, name of the column (of type ordered factor, or binary, see Details) recording test results; default "result".

transition

character, name to be used for a new column (of type integer) to record transitions; default "transition".

cap

integer, required for calculating transitions; default 0L.

modulate

integer, required for calculating transitions; default 0L.

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 either be semi-quantitiative, formatted as an ordered factor (see Note), or binary data formatted as an integer (or numeric) vector with values of either 1 or 0, and included in object in the data frame column specified by argument result.

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.

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)