Variables that behave
A column in R has a type, and it can have a label. Most silent errors in a clinical program come from a wrong type: a number that is text, a text that became NA, a date that is a number. This chapter shows how R decides the type and how you change it on purpose. Then it shows the functions you use every day for text, dates and numbers.
3.1 Types and class()
Section titled “3.1 Types and class()”# Chapter 3: every value has a type, and one vector holds one type onlylibrary(dplyr)
class("01-701-1015")#> [1] "character"class(63)#> [1] "numeric"class(63L)#> [1] "integer"class(TRUE)#> [1] "logical"class(as.Date("2014-01-02"))#> [1] "Date"
c(63, "<65")#> [1] "63" "<65"c(63, TRUE)#> [1] 63 1
pharmaverseadam::adsl |> filter(USUBJID == "01-701-1015") |> select(USUBJID, AGE, TRTSDT, TRTSDTM) |> glimpse()#> Rows: 1#> Columns: 4#> $ USUBJID <chr> "01-701-1015"#> $ AGE <dbl> 63#> $ TRTSDT <date> 2014-01-02#> $ TRTSDTM <dttm> 2014-01-02Every value has a type. class() tells you which one. These five types hold almost all clinical data:
| Type | class() |
Example | glimpse() shows |
|---|---|---|---|
| text | "character" |
"01-701-1015" |
<chr> |
| number with decimals | "numeric" |
63, 54.43 |
<dbl> |
| whole number | "integer" |
63L, the result of n() |
<int> |
| true or false | "logical" |
TRUE, FALSE, NA |
<lgl> |
| date | "Date" |
as.Date("2014-01-02") |
<date> |
A date and a time together (such as TRTSDTM) is a datetime. glimpse() shows it as <dttm>. A number without L is always a double (dbl), also when it has no decimals. glimpse() prints one line per column, with its type and its first values.
A vector holds one type only. If you combine types, R changes all values to the type that can hold them all. c(63, "<65") gives two texts: "63" and "<65". c(63, TRUE) gives two numbers: 63 and 1. R gives no message. This happens to a whole column too: one text value in a column of numbers makes the column text.
3.2 Convert between types
Section titled “3.2 Convert between types”A column keeps its type until you change it. Two functions do most of the work:
as.character(x)makes text from a number.as.numeric(x)makes a number from text. Text that is not a number becomesNA.
# Chapter 3: as.character() makes text and as.numeric() makes numbers. Text that is no number gives NAlibrary(dplyr)library(stringr)
pharmaversesdtm::dm |> filter(USUBJID %in% c("01-701-1015", "01-701-1023", "01-701-1028")) |> select(USUBJID, SITEID, AGE) |> mutate( AGE_C = as.character(AGE), SUBJ = str_split_i(USUBJID, "-", 3), TXT = str_c(USUBJID, " / ", AGE), SITE_N = as.numeric(SITEID) )#> # A tibble: 3 x 7#> USUBJID SITEID AGE AGE_C SUBJ TXT SITE_N#> <chr> <chr> <dbl> <chr> <chr> <chr> <dbl>#> 1 01-701-1015 701 63 63 1015 01-701-1015 / 63 701#> 2 01-701-1023 701 64 64 1023 01-701-1023 / 64 701#> 3 01-701-1028 701 71 71 1028 01-701-1028 / 71 701
bili <- pharmaversesdtm::lb |> filter(LBTESTCD == "BILI") |> mutate(VALUE = as.numeric(LBSTRESC))#> Warning:#> There was 1 warning in `mutate()`.#> i In argument: `VALUE = as.numeric(LBSTRESC)`.#> Caused by warning:#> ! NAs introduced by coercion
bili |> filter(is.na(VALUE)) |> select(USUBJID, VISIT, LBSTRESC, VALUE)#> # A tibble: 5 x 4#> USUBJID VISIT LBSTRESC VALUE#> <chr> <chr> <chr> <dbl>#> 1 01-701-1363 WEEK 24 <3.42 NA#> 2 01-704-1323 WEEK 4 <3.42 NA#> 3 01-705-1031 WEEK 24 <3.42 NA#> 4 01-705-1393 WEEK 2 <3.42 NA#> 5 01-711-1036 WEEK 24 <3.42 NAThe first part works on three subjects. SITEID is text in SDTM, so as.numeric(SITEID) makes the number 701. str_split_i(USUBJID, "-", 3) cuts the text at each - and takes the third piece: the subject number 1015. str_c() joins texts. It changes the number AGE to text by itself.
The second part is a real trap. Lab results come as text (LBSTRESC) and as numbers (LBSTRESN). as.numeric(LBSTRESC) for bilirubin gives the warning NAs introduced by coercion. The filter finds the 5 values: <3.42, a result below the lower limit of the lab. The value is not missing: the lab measured it. The SAP must say what to do with it, for example to use the limit, or half the limit.
3.3 Labels
Section titled “3.3 Labels”A label is a short description of a column, such as “Age”. The specification of an ADaM data set gives every variable a label. In R, a label is an attribute of the column: extra information that travels with the values.
# Chapter 3: a label is an attribute of a column. Some steps copy it, some drop itlibrary(dplyr)
adsl <- pharmaverseadam::adsl |> filter(USUBJID == "01-701-1015") |> select(USUBJID, AGE, SEX)
attr(adsl$AGE, "label")#> [1] "Age"sapply(adsl, attr, "label")#> USUBJID AGE#> "Unique Subject Identifier" "Age"#> SEX#> "Sex"
adsl <- adsl |> mutate( AGE_MONTHS = AGE * 12, AGE_C = as.character(AGE) )attr(adsl$AGE_MONTHS, "label")#> [1] "Age"attr(adsl$AGE_C, "label")#> NULL
attr(adsl$AGE_MONTHS, "label") <- "Age (months)"attr(adsl$AGE_C, "label") <- "Age as text"sapply(adsl, attr, "label")#> USUBJID AGE#> "Unique Subject Identifier" "Age"#> SEX AGE_MONTHS#> "Sex" "Age (months)"#> AGE_C#> "Age as text"attr(x, "label")reads the label.sapply(adsl, attr, "label")reads the label of every column.AGE_MONTHS = AGE * 12copied the label ofAGE. The new column says “Age”, but it holds months. That label is wrong, and R gives no message.as.character(AGE)dropped the label:NULLmeans “nothing”.attr(x, "label") <- "..."sets a label.
Data sets from pharmaverseadam and from haven::read_xpt() have labels, and data viewers such as RStudio’s show them under the column names. When you write a data set for a submission, the labels must match the specification. The package xportr can set all labels from the specification in one step.
3.4 Text functions you use every day
Section titled “3.4 Text functions you use every day”The package stringr has one function for each job on text. All its functions start with str_.
# Chapter 3: the stringr functions you use every day, on the adverse eventslibrary(dplyr)library(stringr)
ae <- pharmaversesdtm::ae |> select(USUBJID, AEDECOD) |> mutate( SITE = str_sub(USUBJID, 4, 6), SUBJ = str_sub(USUBJID, 8, 11), PAIN = str_detect(AEDECOD, regex("pain", ignore_case = TRUE)), SHORT = str_replace(AEDECOD, "APPLICATION SITE", "APPL. SITE"), LABEL = str_c(USUBJID, " | ", str_to_lower(AEDECOD)) )
sum(ae$PAIN)#> [1] 33nrow(ae)#> [1] 1191
ae |> filter(USUBJID == "01-701-1015") |> select(SITE, SUBJ, PAIN, SHORT, LABEL)#> # A tibble: 3 x 5#> SITE SUBJ PAIN SHORT LABEL#> <chr> <chr> <lgl> <chr> <chr>#> 1 701 1015 FALSE APPL. SITE ERYTHEMA 01-701-1015 | application site erythema#> 2 701 1015 FALSE APPL. SITE PRURITUS 01-701-1015 | application site pruritus#> 3 701 1015 FALSE DIARRHOEA 01-701-1015 | diarrhoea33 of the 1191 adverse events have “pain” in AEDECOD. Subject 01-701-1015 has none.
| Function | What it does here |
|---|---|
str_sub(USUBJID, 4, 6) |
the characters 4 to 6: the site |
str_detect(AEDECOD, regex("pain", ignore_case = TRUE)) |
TRUE when the text has “pain”, in upper or lower case |
str_replace(AEDECOD, "APPLICATION SITE", "APPL. SITE") |
replaces the first match with another text |
str_to_lower(AEDECOD) |
the text in lower case; str_to_upper() is the opposite |
str_c(USUBJID, " | ", ...) |
joins the texts |
str_detect() gives TRUE or FALSE, so sum() counts the TRUE values: each TRUE counts as 1.
Exercise 3-1. Search the verbatim term AETERM instead of AEDECOD. How many records have “pain”?
3.5 Clean text before you use it
Section titled “3.5 Clean text before you use it”Free text can hold blanks at the start and the end, double blanks, and line breaks from the data entry system: \r\n, a carriage return and a line feed. You cannot see them in a listing, but they change the sort order and break a join.
# Chapter 3: clean free text before you sort, join or print itlibrary(stringr)
raw <- " Mild headache\r\nafter dosing "raw#> [1] " Mild headache\r\nafter dosing "str_length(raw)#> [1] 31
str_trim(raw)#> [1] "Mild headache\r\nafter dosing"clean <- str_squish(raw)clean#> [1] "Mild headache after dosing"str_length(clean)#> [1] 26
str_to_upper(clean)#> [1] "MILD HEADACHE AFTER DOSING"str_sub(clean, 1, 8)#> [1] "Mild hea"str_pad("1015", width = 6, pad = "0")#> [1] "001015"str_length()counts the characters: 31 in the raw text.str_trim()removes the blanks at the start and the end only.str_squish()also changes every run of blanks, tabs and line breaks inside the text to one blank. The result has 26 characters.str_pad("1015", width = 6, pad = "0")fills the text from the left to 6 characters:"001015".
Clean a text column in the step that reads it from SDTM, before you sort, join or count with it.
3.6 Numbers and dates as text for display
Section titled “3.6 Numbers and dates as text for display”A table shows numbers as text with a fixed layout: one decimal for a mean, a percent in brackets. sprintf() and format() make that text.
# Chapter 3: sprintf() and format() turn numbers and dates into text for a table or a listinglibrary(dplyr)
ages <- pharmaversesdtm::dm |> filter(ARMCD != "Scrnfail") |> summarise(n = n(), n_old = sum(AGE > 80), mean = mean(AGE), sd = sd(AGE))ages#> # A tibble: 1 x 4#> n n_old mean sd#> <int> <int> <dbl> <dbl>#> 1 254 77 75.1 8.25
sprintf("%.1f (%.2f)", ages$mean, ages$sd)#> [1] "75.1 (8.25)"sprintf("%d (%.1f%%)", ages$n_old, 100 * ages$n_old / ages$n)#> [1] "77 (30.3%)"sprintf("%3d", c(5, 77, 254))#> [1] " 5" " 77" "254"format(1234567.891, big.mark = ",", nsmall = 2)#> [1] "1,234,567.89"
trtsdt <- as.Date("2014-01-02")format(trtsdt, "%d%b%Y")#> [1] "02Jan2014"toupper(format(trtsdt, "%d%b%Y"))#> [1] "02JAN2014"sprintf() takes a template and the values. Each % in the template is a place for one value:
| Template | Means | Result here |
|---|---|---|
%.1f |
a number with 1 decimal | 75.1 |
%.2f |
a number with 2 decimals | 8.25 |
%d |
a whole number | 77 |
%3d |
a whole number, 3 characters wide | " 5" |
%% |
the character % |
(30.3%) |
format(x, big.mark = ",", nsmall = 2) adds a comma for the thousands. format(date, "%d%b%Y") writes a date in another layout: %d is the day, %b the short month name, %Y the year. toupper() gives 02JAN2014.
3.7 Date functions
Section titled “3.7 Date functions”lubridate has the functions for dates. Because a date is a number of days, you can also subtract two dates directly.
# Chapter 3: date functions. Duration, study day (there is no day 0) and age in whole yearslibrary(dplyr)library(lubridate)
trtsdt <- ymd("2014-01-02")year(trtsdt)#> [1] 2014month(trtsdt)#> [1] 1
tibble(ADT = ymd(c("2013-12-31", "2014-01-01", "2014-01-02", "2014-01-03"))) |> mutate( DIFF = as.numeric(ADT - trtsdt), ADY = if_else(ADT >= trtsdt, DIFF + 1, DIFF) )#> # A tibble: 4 x 3#> ADT DIFF ADY#> <date> <dbl> <dbl>#> 1 2013-12-31 -2 -2#> 2 2014-01-01 -1 -1#> 3 2014-01-02 0 1#> 4 2014-01-03 1 2
pharmaversesdtm::ae |> filter(USUBJID == "01-701-1015") |> mutate( ASTDT = ymd(AESTDTC), AENDT = ymd(AEENDTC), ADURN = as.numeric(AENDT - ASTDT) + 1, ASTDY = if_else(ASTDT >= trtsdt, as.numeric(ASTDT - trtsdt) + 1, as.numeric(ASTDT - trtsdt)) ) |> select(AEDECOD, ASTDT, AENDT, ADURN, ASTDY, AESTDY)#> # A tibble: 3 x 6#> AEDECOD ASTDT AENDT ADURN ASTDY AESTDY#> <chr> <date> <date> <dbl> <dbl> <dbl>#> 1 APPLICATION SITE ERYTHEMA 2014-01-03 NA NA 2 2#> 2 APPLICATION SITE PRURITUS 2014-01-03 NA NA 2 2#> 3 DIARRHOEA 2014-01-09 2014-01-11 3 8 8
brthdt <- ymd("1950-12-26")time_length(interval(brthdt, trtsdt), "years")#> [1] 63.01918floor(time_length(interval(brthdt, trtsdt), "years"))#> [1] 63year()andmonth()take the year and the month out of a date.- Duration.
AENDT - ASTDT + 1counts both the first and the last day. The DIARRHOEA of subject 01-701-1015, from 9 to 11 January 2014, lasts 3 days. - Study day. The day of the first dose is day 1, and the day before it is day -1. There is no day 0. So you add 1 only for dates on or after the first dose. The small table shows it: 2014-01-02 is day 1 and 2014-01-01 is day -1. The computed
ASTDY(8 for the DIARRHOEA) agrees withAESTDYof SDTM. - Age.
interval(brthdt, trtsdt)is the time from one date to another.time_length(..., "years")gives it in years: 63.01918.floor()cuts it down to whole years: 63.
3.8 Numbers: three traps
Section titled “3.8 Numbers: three traps”# Chapter 3: three traps with numbers. Decimal fractions, NA in a sum, and round() to even0.1 * 3 == 0.3#> [1] FALSEisTRUE(all.equal(0.1 * 3, 0.3))#> [1] TRUE
p <- NAq <- 4p + q#> [1] NAsum(p, q)#> [1] NAsum(p, q, na.rm = TRUE)#> [1] 4
round(c(0.5, 1.5, 2.5, 3.5, -2.5))#> [1] 0 2 2 4 -2sprintf("%.0f", c(0.5, 1.5, 2.5))#> [1] "0" "2" "2"
round_half_up <- function(x, digits = 0) { scale <- 10^digits sign(x) * floor(abs(x) * scale + 0.5 + 1e-9) / scale}round_half_up(c(0.5, 1.5, 2.5, 3.5, -2.5))#> [1] 1 2 3 4 -3round(12.45, 1)#> [1] 12.4round_half_up(12.45, 1)#> [1] 12.5Decimal fractions. A computer stores 0.1 as a binary fraction that is a little wrong. So 0.1 * 3 == 0.3 is FALSE. Never compare computed decimals with ==. Use isTRUE(all.equal(a, b)): it allows a very small difference.
NA in a sum. p + q is NA when one value is NA, and so is sum(p, q). sum(p, q, na.rm = TRUE) removes the NA first and gives 4. Choose on purpose. A total score must often be missing when one item is missing: then keep the NA. A count of events ignores missing values: then use na.rm = TRUE.
round() goes to the even number. A value exactly halfway goes to the nearest even number: round(0.5) is 0, round(2.5) is 2, round(-2.5) is -2. This is the IEC 60559 standard, and it is not what a clinical table expects. sprintf() does the same. A table rounds halfway values away from zero.
round_half_up() does that. It is a small function: a named set of steps that you can use many times. Chapter 8 explains how to write one. It adds 0.5 and cuts the decimals off. The extra 1e-9 (0.000000001) corrects the trap of decimal fractions: 12.45 is stored a little below 12.45, so round(12.45, 1) gives 12.4. round_half_up(12.45, 1) gives 12.5.
Exercise 3-2. a <- 1, b <- NA, c <- 3. What do (a + b + c) / 3, mean(c(a, b, c)) and mean(c(a, b, c), na.rm = TRUE) give?
Exercise 3-3. 1 subject of 8 is 12.5%. A table shows it with no decimals. What do round(), sprintf("%.0f", ...) and round_half_up() give?
3.9 Patterns: regular expressions
Section titled “3.9 Patterns: regular expressions”A regular expression describes a pattern of text. str_detect(x, pattern) is TRUE when the text matches the pattern. Here it sorts the AE start dates by how complete they are.
# Chapter 3: regular expressions. Sort the AE start dates by how complete they arelibrary(dplyr)library(stringr)
ae <- pharmaversesdtm::ae |> select(USUBJID, AESTDTC) |> mutate( DTC_TYPE = case_when( str_detect(AESTDTC, "^\\d{4}-\\d{2}-\\d{2}$") ~ "complete", str_detect(AESTDTC, "^\\d{4}-\\d{2}$") ~ "year-month", str_detect(AESTDTC, "^\\d{4}$") ~ "year", .default = "other" ), YEAR = str_extract(AESTDTC, "^\\d{4}") )
ae |> count(DTC_TYPE)#> # A tibble: 3 x 2#> DTC_TYPE n#> <chr> <int>#> 1 complete 1165#> 2 year 11#> 3 year-month 15
ae |> filter(DTC_TYPE != "complete") |> print(n = 3)#> # A tibble: 26 x 4#> USUBJID AESTDTC DTC_TYPE YEAR#> <chr> <chr> <chr> <chr>#> 1 01-701-1118 2003 year 2003#> 2 01-701-1148 2012-02 year-month 2012#> 3 01-701-1180 2002 year 2002#> # i 23 more rows1165 start dates are complete, 15 have only the year and the month, and 11 have only the year. How to read the pattern "^\\d{4}-\\d{2}$":
^is the start of the text and$is the end.\\dis one digit. In R you write the backslash twice inside quotes.{4}means “four times”. So\\d{4}is four digits.-is the character itself.
So the pattern means: four digits, a dash, two digits, and nothing more. str_extract(x, "^\\d{4}") gives the part of the text that matches: the year. These are the 26 partial dates of chapter 2: ymd() failed on 19 of them and misread 7.
Exercise 3-4. How many subjects have an AE start date with only the year?
3.10 Summary
Section titled “3.10 Summary”class()andglimpse()show the type of a column. One text value makes a whole column text.as.numeric()turns text into numbers. EveryNAthat it makes needs a reason and a rule.- A label is an attribute. A computed column can inherit a wrong label.
stringrdoes the text work:str_sub(),str_detect(),str_replace(),str_c(),str_squish(),str_pad().sprintf()andformat()make text for display.- Dates subtract. Study day has no day 0.
time_length(interval(a, b), "years")gives an age. - Never compare decimals with
==.round()goes to the even number: use a round-half-up function for tables. - A regular expression describes a pattern:
^,$,\\d,{n}.
3.11 Exercises
Section titled “3.11 Exercises”Exercises 3-1 to 3-4 are in the sections above. One more:
Exercise 3-5. In DM, compute each randomised subject’s age at first treatment from BRTHDTC and RFXSTDTC, in whole years. For how many subjects does it agree with AGE?
The answers are in Answers, Part I.
Found an error or have a question? Write to datastep.studio@gmail.com· Every program runs in DataStep Studio for R, the R extension for VS Code and Positron.
Data: the CDISC pilot study (cdiscpilot01), from the R packagespharmaversesdtm andpharmaverseadam (Apache License 2.0).
R is a project of the R Foundation. SAS and all other SAS Institute Inc. product or service names are registered trademarks or trademarks of SAS Institute Inc. This book is not affiliated with or endorsed by SAS Institute Inc. or the R Foundation. CDISC, SDTM and ADaM are trademarks of the Clinical Data Interchange Standards Consortium.
© 2026 DataStep Labs. All rights reserved.