Skip to contents

Identify Temporal Transitions in Longitudinal Study Data

Transitions.Rd

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

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.

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.

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()
#> 'data.frame':	945 obs. of  4 variables:
#>  $ subject : Factor w/ 231 levels "100","101","102",..: 1 1 1 1 1 2 2 2 2 2 ...
#>  $ age     : num  8 10 12 14 15.9 ...
#>  $ exercise: num  2.71 1.94 2.36 1.54 8.63 0.14 0.14 0 0 5.08 ...
#>  $ group   : Factor w/ 2 levels "control","patient": 2 2 2 2 2 2 2 2 2 2 ...

  # {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]
#> $breaks
#>  [1]  0  2  4  6  8 10 12 14 16 18 20 22 24 26 28 30
#> 
#> $counts
#>  [1] 594 166  75  43  20  19  11   5   3   5   1   1   1   0   1
#> 

  # 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()
#> 'data.frame':	945 obs. of  6 variables:
#>  $ subject  : Factor w/ 231 levels "100","101","102",..: 1 1 1 1 1 2 2 2 2 2 ...
#>  $ age      : num  8 10 12 14 15.9 ...
#>  $ exercise : num  2.71 1.94 2.36 1.54 8.63 0.14 0.14 0 0 5.08 ...
#>  $ group    : Factor w/ 2 levels "control","patient": 2 2 2 2 2 2 2 2 2 2 ...
#>  $ timepoint: Date, format: "2008-01-01" "2009-12-31" ...
#>  $ result   : Ord.factor w/ 15 levels "<=2"<"<=4"<"<=6"<..: 2 1 2 1 5 1 1 1 1 3 ...

  # Integer vector of test result transitions (defaults: cap = modulate = 0)
get_transitions(Blackmore)
#>   [1] NA -1  1 -1  4 NA  0  0  0  2 NA  0  2 10 NA  1  0  2 NA  2 -3  6 NA  0  0
#>  [26]  0  0 NA  0  0  0  2 NA  0  0  2 -2 NA  1  0  8 -7 NA -1  9 NA  0  0  6 -5
#>  [51] NA  0  2  5 NA  0  0  0  0 NA  0  1  8 NA  0  0  0 NA  0  1 -1 NA  0  0  1
#>  [76]  2 NA  0  0  1  4 NA  0  0  1 NA  0  0  0  4 NA  0  0  0  0 NA  0  5 -3 NA
#> [101]  0  0  3 -1 NA  0  0  0 NA  0  1  1 NA  1  2 -2 NA  0  0  1 NA  0  0  1  1
#> [126] NA  0  0 NA  0  0  5 NA  0  1  0  4 NA  0  2 NA  1  0 -1  6 NA  2  3  4 -1
#> [151] NA  0  0  0  0 NA  0  1  0  0 NA  0  0  0 NA  0  0  0 NA  0  4 -2  1 NA  1
#> [176]  0  0  0 NA  0  0  0  2 NA -3  0  5 NA  1  2 -3  2 NA  0  0  2 -2 NA  0  0
#> [201]  2 NA  0  0  2 NA  0  1 NA  0  0  0  4 NA  0  1 NA  1  0  2  3 NA  0  0  0
#> [226]  0 NA  2  0  0  1 NA  0  1 -1 NA  1  0  0 NA  0  1 NA  0  0  3 NA  0  0  9
#> [251] -6 NA  0  0 NA  0  0  0 NA  5  1  2 -1 NA  0  0  0  0 NA  0  0 NA -2  0 12
#> [276] NA  0  1 -1  2 NA  0  0  2 NA  1  0  2  2 NA  1  1  4 NA  0 NA  2  5 NA  0
#> [301]  0  0  1 NA  0  0  1 NA  0  2  1 NA  0  0  1 NA  0  1 NA  0  1 -1  0 NA  0
#> [326]  0  0  0 NA  0  0  1 NA  0  0  6 NA  0  0  0  0 NA  1  0  4 NA  0  0  0  2
#> [351] NA  0 -1  5 NA  0  0  0 NA  1  0 NA  0  0  0  1 NA  1  2  3 NA  1  0  2 NA
#> [376] -1  5  0 NA  0  1  0  0 NA  0  1  1 NA  0  0  2 NA  1  4 NA  0  0  0 NA  0
#> [401]  0  0 NA  1  0 NA  0  1  4 NA  0  1  3 NA  0  0  0  3 NA  0  0  0  0 NA  0
#> [426]  0  2  3 NA  2 -2  0  0 NA  1  2  2  2 NA  1 -2  0  4 NA  0  0  0  1 NA  0
#> [451]  0  1 NA  0  0  4 NA  0  0  2 NA  0  1 -1  1 NA  0  0  0  5 NA  0  0  0  1
#> [476] NA  0  0  1 NA  1  1  1 NA  1 -1 NA  0 -1 NA  0  0  0 NA  0  1  2  0 NA  0
#> [501]  0 -2 NA  0  0  1 -1 NA  1  4 NA  0  1 NA  0  0  0  0 NA  1  3 NA  0  0  0
#> [526] NA  0  0  1 NA  0  1 -1  1 NA  0  0  0  0 NA -1  1 NA  2 -1  3 NA  0  0  0
#> [551] NA  1  0  1 NA  1  0  7 NA  0  0  0  0 NA  0  2 -2 NA  0  0  0 NA -1  4 NA
#> [576]  0  0  0 NA  0  3  0  0 NA  0  0 NA  1 -2  3 -2 NA  0  0 NA  0  0 NA  0  0
#> [601]  0 NA  2  0  1 NA  0  0  0  0 NA  0  0 NA  0  0  0  1 NA  0  0  0 NA  0  0
#> [626] NA  0  0  0 NA  1  0 -1 NA  0  1 NA  1 -1  3  0 NA  0  0 -1 NA  0  0  1 NA
#> [651]  1  0  2 NA  1 -1 NA  0  0 NA  0  0  0  0 NA  0  0  0  0 NA  0  0  2 NA  2
#> [676]  1 NA  0 NA  2 -2 NA  1  0  0 NA  1 -1  1 NA  0  0 NA -2  0 NA  0  0  0  1
#> [701] NA  0  0  0 NA  0  0  0  1 NA  0  0 NA  0  1  0 NA  0  0  0  0 NA  1 -1  0
#> [726]  1 NA  0  0 NA -1  1 NA  0  0  1  2 NA  1  0 -1  1 NA  3  0  0 -2 NA  0  1
#> [751] NA  0  0 NA  0  4 NA  1  0 NA  2 -2  0 NA  0  0  0  0 NA  0  0  0  0 NA  0
#> [776]  0  0 NA  0  0  0 NA -2  0 NA  0  0  1  0 NA  1  0  1 NA  0  0  0 NA  0  1
#> [801] NA  0  0  1  0 NA  0  0 NA  0  0  0 NA -1  1 -1  1 NA  0  0  1 NA  0  1  0
#> [826] NA  0  0 NA  0  0  0 NA  0  0 NA  0  0 NA  0  0 NA  0  0 NA  0  0 NA  0 -1
#> [851] NA  0  0 NA  0  0  0 NA  0  0  0 NA  0  1 NA  1  0 -1 NA  0  0  0 NA  1  0
#> [876] NA  0  0  0 NA  0  0  0  0 NA  0  1 NA  0  0  0  0 NA  0  0  0 NA  0  0  0
#> [901] NA -2  0 NA  0  0 NA  0  0  0 NA  0  0  1 NA  0  0  1 -1 NA  0  1  0  0 NA
#> [926]  0  0  0  0 NA  0  1 NA  0  0  0  0 NA  0  0 NA  0  0  0  0

  # Tabulate values of transitions
get_transitions(Blackmore) |> table()
#> 
#>  -7  -6  -5  -3  -2  -1   0   1   2   3   4   5   6   7   8   9  10  12 
#>   1   1   1   4  17  34 444 116  46  14  16   9   4   1   2   2   1   1 

  # Effect of cap argument
get_transitions(Blackmore, cap = 6) |> table()
#> 
#>  -6  -5  -3  -2  -1   0   1   2   3   4   5   6 
#>   2   1   4  17  34 444 116  46  14  16   9  11 

  # Effect of modulate argument
get_transitions(Blackmore, modulate = 2) |> table()
#> 
#>  -4  -3  -2  -1   0   1   2   3   4   5   6 
#>   1   2   4  51 444 162  30  13   3   3   1 

  # Add column of test result transitions to data frame
add_transitions(Blackmore) |> head(22)
#>    subject   age exercise   group  timepoint result transition
#> 1      100  8.00     2.71 patient 2008-01-01    <=4         NA
#> 2      100 10.00     1.94 patient 2009-12-31    <=2         -1
#> 3      100 12.00     2.36 patient 2012-01-01    <=4          1
#> 4      100 14.00     1.54 patient 2014-01-01    <=2         -1
#> 5      100 15.92     8.63 patient 2015-12-03   <=10          4
#> 6      101  8.00     0.14 patient 2008-01-01    <=2         NA
#> 7      101 10.00     0.14 patient 2009-12-31    <=2          0
#> 8      101 12.00     0.00 patient 2012-01-01    <=2          0
#> 9      101 14.00     0.00 patient 2014-01-01    <=2          0
#> 10     101 16.67     5.08 patient 2016-09-02    <=6          2
#> 11     102  8.00     0.92 patient 2008-01-01    <=2         NA
#> 12     102 10.00     1.82 patient 2009-12-31    <=2          0
#> 13     102 12.00     4.75 patient 2012-01-01    <=6          2
#> 14     102 15.08    24.72 patient 2015-01-30   <=26         10
#> 15     103  8.00     1.04 patient 2008-01-01    <=2         NA
#> 16     103 10.00     2.90 patient 2009-12-31    <=4          1
#> 17     103 12.00     2.65 patient 2012-01-01    <=4          0
#> 18     103 14.08     6.86 patient 2014-01-30    <=8          2
#> 19     104  8.00     2.75 patient 2008-01-01    <=4         NA
#> 20     104 10.00     6.62 patient 2009-12-31    <=8          2
#> 21     104 12.00     0.29 patient 2012-01-01    <=2         -3
#> 22     104 15.42    12.37 patient 2015-06-03   <=14          6

  # Showing transitions as either positive (1) or negative (-1)
  #   (defaults to modulate = 0)
add_transitions(Blackmore, cap = 1) |> head(14)
#>    subject   age exercise   group  timepoint result transition
#> 1      100  8.00     2.71 patient 2008-01-01    <=4         NA
#> 2      100 10.00     1.94 patient 2009-12-31    <=2         -1
#> 3      100 12.00     2.36 patient 2012-01-01    <=4          1
#> 4      100 14.00     1.54 patient 2014-01-01    <=2         -1
#> 5      100 15.92     8.63 patient 2015-12-03   <=10          1
#> 6      101  8.00     0.14 patient 2008-01-01    <=2         NA
#> 7      101 10.00     0.14 patient 2009-12-31    <=2          0
#> 8      101 12.00     0.00 patient 2012-01-01    <=2          0
#> 9      101 14.00     0.00 patient 2014-01-01    <=2          0
#> 10     101 16.67     5.08 patient 2016-09-02    <=6          1
#> 11     102  8.00     0.92 patient 2008-01-01    <=2         NA
#> 12     102 10.00     1.82 patient 2009-12-31    <=2          0
#> 13     102 12.00     4.75 patient 2012-01-01    <=6          1
#> 14     102 15.08    24.72 patient 2015-01-30   <=26          1

rm(Blackmore)