Transitions: Identify Temporal Transitions in Longitudinal Study Data

In Transition: Characterise Transitions in Test Result Status in Longitudinal Studies

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 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.

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.

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. See vignette Converting numeric values to class "Date" for examples.

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)

Transition documentation built on Feb. 11, 2026, 5:07 p.m.