Debug a function
A function is a small program inside your program. When it gives a wrong value, you want to stop inside it, see every variable, and go on line by line. The debugger does this. It works on the same R session as your runs, so the data of your session is there.
The debugger is in the Professional edition, free during Early Access until 17 February 2027. The keys are on the cheat sheet.
25.1 Which tool when
Section titled “25.1 Which tool when”You know four tools now. They work together. Choose by the question:
| Your question | The tool | Chapter |
|---|---|---|
| Where does this value go wrong, and what is in each frame? | the debugger | this chapter |
| What is the data at this point of the real run, for this subject? | pry() |
24 |
| Why does this function return this value? | trace | 23.8 |
| Which step of the pipeline loses or copies the records? | the pipe debugger | 23 |
| Which lines ran at all? | coverage | 26 |
25.2 The keys
Section titled “25.2 The keys”| Key or action | What it does |
|---|---|
| a click in the margin, Ctrl+F9 | a breakpoint on the line (F9 is Show Keys in R files) |
| F5 in an R file | Debug R File: run the file in the debugger, no launch.json needed |
| F5 at a stop | continue to the next breakpoint |
| F10 | step over: the next line of this function |
| F11 | step into a function of the project that this line calls |
| Shift+F11 | step out: back to the caller |
| Stop at Line (Ctrl/Cmd+Alt+F9) | run and stop at the cursor line, also inside a function |
| right-click a later line, Run to Cursor | go on to that line |
At a stop, three views show the state:
- Call Stack: the frames, each with its file and line. A frame is one function call while it runs.
- Variables: the objects of the frame you choose in the Call Stack. A data frame opens to its columns, with their labels.
- Debug Console: R code that runs in that frame. Rest the mouse on a variable in the code to see its value.
In a terminal, a stop of the debugger is the same as a --stop-at stop of chapter 24: dsr pry next, step, finish and continue do what F10, F11, Shift+F11 and F5 do. This chapter shows that output.
25.3 Session 1: why do four subjects get no age group?
Section titled “25.3 Session 1: why do four subjects get no age group?”The function and the program that uses it:
# Chapter 25: a function that puts each age into a group (program 25_2 uses it)age_group <- function(age) { grp <- rep(NA_character_, length(age)) grp[age < 65] <- "<65" grp[age > 65 & age <= 80] <- "65-80" grp[age > 80] <- ">80" grp}# Chapter 25: age groups for the safety population, and four subjects get no grouplibrary(dplyr)source("25_1_age_group.R")
adsl <- pharmaverseadam::adsl |> filter(SAFFL == "Y") |> select(USUBJID, TRT01A, AGE)adsl <- adsl |> mutate(AGEGR = age_group(AGE))
adsl |> count(AGEGR)#> # A tibble: 4 x 2#> AGEGR n#> <chr> <int>#> 1 65-80 140#> 2 <65 33#> 3 >80 77#> 4 <NA> 4The log of the run says it too: NOTE: adsl has 254 rows and 4 columns (was 254 x 3). New: AGEGR (4 missing). Every subject has an age, so every subject should get a group.
-
Open
25_1_age_group.R. Click in the margin of line 5 to set a breakpoint. Right-click the red dot, Edit Condition, and typeany(age == 65). The run stops there only when an age is exactly 65. -
Open
25_2_adsl_agegr.Rand press F5. What you should see: the run stops in the function. The terminal form of the same stop:$ dsr run programs/25_2_adsl_agegr.R --stop-at 'programs/25_1_age_group.R:5 if any(age == 65)'5 NOTE: adsl has 254 rows and 3 columns.=> age_group programs/25_1_age_group.R:53 grp <- rep(NA_character_, length(age))4 grp[age < 65] <- "<65"=> 5 grp[age > 65 & age <= 80] <- "65-80"6 grp[age > 80] <- ">80"7 grpRESULT: PRY | AT: programs/25_1_age_group.R:5: stopped at the breakpoint: where any(age == 65) (0.02 s) (live: dsr pry next | step | finish | continue | quit) -
Look at the Call Stack. What you should see: your program at the top level, line 8, the frames of dplyr in between, and
age_groupat line 5:$ dsr pry stackPRY at stop[1] <top level> programs/25_2_adsl_agegr.R:8[2-8] 7 frames of dplyr, base=> [9] age_group programs/25_1_age_group.R:5 -
In the Debug Console, type
table(grp, useNA = "always"). What you should see: 33 subjects are in<65; 221 have no group yet. Line 5 has not run.$ dsr pry eval 'table(grp, useNA = "always")'grp<65 <NA>33 221RESULT: CLEAN (0 s) -
Press F10: line 5 runs, and the run stops at line 6. In the Debug Console, compare the ages near 65 with their groups:
$ dsr pry eval 'age[age %in% 64:66]'[1] 64 64 66 64 65 65 64 65 65 64RESULT: CLEAN (0 s)$ dsr pry eval 'grp[age %in% 64:66]'[1] "<65" "<65" "65-80" "<65" NA NA "<65" NA NA[10] "<65"RESULT: CLEAN (0 s)Each age 65 has
NA. Line 4 takes ages below 65; line 5 takes ages above 65. Nobody takes 65 itself. The rule is “65 to 80”, so line 5 must sayage >= 65. -
Press F5: the run ends with
AGEGR (4 missing). Fix line 5, run again: exercise 25-4.
25.4 Session 2: into a function, and back
Section titled “25.4 Session 2: into a function, and back”You do not have to know where a function is. Stop at the line that calls it, and go in.
-
Set a breakpoint on line 8 of
25_2_adsl_agegr.R, themutate()that callsage_group(). Press F5. -
Press F11. What you should see: the editor opens
25_1_age_group.Rat the first line of the function:$ dsr run programs/25_2_adsl_agegr.R --stop-at 8...$ dsr pry step=> age_group programs/25_1_age_group.R:31 # Chapter 25: a function that puts each age into a group (program 25_2 uses it)2 age_group <- function(age) {=> 3 grp <- rep(NA_character_, length(age))4 grp[age < 65] <- "<65"5 grp[age > 65 & age <= 80] <- "65-80"RESULT: PRY | AT: programs/25_1_age_group.R:3: stopped (step) (0.06 s) (live: dsr pry next | step | finish | continue | quit) -
Press Shift+F11 to step out, back to the program.
F11 goes into functions of the project, not into the functions of a package such as mutate(). That is what you want: the bug is almost always in your own code.
25.5 Break on Value Change: who changed this value?
Section titled “25.5 Break on Value Change: who changed this value?”In the Variables view, right-click a variable and choose Break on Value Change. The run stops at the line after the value changes, and the stop says which line changed it. In a terminal, dsr pry watch takes any expression. Stopped at line 4 of age_group(), watch how many ages have no group:
$ dsr pry watch 'sum(is.na(grp))'Watching sum(is.na(grp)) (now 254): the run stops at the line after it changes. dsr pry continue.$ dsr pry continue...RESULT: PRY | AT: programs/25_1_age_group.R:5: stopped: a watched value changed: sum(is.na(grp)) changed by 25_1_age_group.R:4: 254 -> 221 (0.23 s) (live: dsr pry next | step | finish | continue | quit)$ dsr pry continue...RESULT: PRY | AT: programs/25_1_age_group.R:6: stopped: a watched value changed: sum(is.na(grp)) changed by 25_1_age_group.R:5: 221 -> 81 (0.3 s) (live: dsr pry next | step | finish | continue | quit)$ dsr pry continue...RESULT: PRY | AT: programs/25_1_age_group.R:7: stopped: a watched value changed: sum(is.na(grp)) changed by 25_1_age_group.R:6: 81 -> 4 (0.36 s) (live: dsr pry next | step | finish | continue | quit)254 ages without a group, then 221, 81 and 4. After the last line of the rules, 4 are left: the four subjects aged 65. Each stop also shows the code around the line; it is cut here.
25.6 Hit counts and log messages
Section titled “25.6 Hit counts and log messages”Right-click a breakpoint and choose Edit Breakpoint. Two more choices:
- A hit count:
3,>= 3or% 10. The breakpoint stops only on the third hit, from the third hit on, or on every tenth hit. In the loop of24_1_by_sev.R, a hit count3on line 14 stops in round 3, the SEVERE round, without a condition. - A log message: for example
round {i}: {sev}. The breakpoint does not stop. It writes the message to the log, with the values in{ }. This is aprint()that you never have to remove from the file.
A condition (25.3) decides with the values of the frame. A hit count decides with the number of times the line ran. Use a condition when you know the subject or the value, and a hit count when you know the round.
25.7 Stop on a warning
Section titled “25.7 Stop on a warning”A warning lets a run go on with a wrong result. Tick R warnings in the Breakpoints view, and the run stops where a warning happens, with its frames alive. In a terminal, --stop-on-warning. On the program of chapter 20:
$ dsr run programs/20_2_bili.R --stop-on-warning 4 NOTE: adsl has 254 rows and 2 columns. 8 WARNING: There was 1 warning in `mutate()`.ℹ In argument: `BILI = as.numeric(LBORRES)`.Caused by warning:! NAs introduced by coercion=> <top level> programs/20_2_bili.R:8 6 select(USUBJID, TRT01A) 7=> 8 bili <- pharmaversesdtm::lb |> 9 filter(LBTESTCD == "BILI") |> 10 mutate(BILI = as.numeric(LBORRES)) |>RESULT: PRY | AT: programs/20_2_bili.R:8: stopped at a warning: There was 1 warning in `mutate()`.ℹ In argument: `BILI = as.numeric(LBORRES)`.Caused by warning:! NAs introduced by coercion (0.04 s) (live: dsr pry next | step | finish | continue | quit)The stop is at the start of the pipeline, line 8. Which step warned? Debug the Pipeline at the Stop (dsr pry pipe) runs that pipeline step by step on the data of the frame, and names the step:
$ dsr pry pipePipeline at programs/20_2_bili.R:8 (bili <- ...): 3 steps 0 pharmaversesdtm::lb 59580 rows 1 filter(LBTESTCD == "BILI") 59580 -> 1814... 2 mutate(BILI = as.numeric(LBORRES)) 1814 -> 1814 +BILI WARNING: There was 1 warning in `mutate()`.ℹ In argument: `BILI = as.numeric(LBORRES)`.Caused by warning:! NAs introduced by coercion 3 select(USUBJID, VISIT, BILI) 1814 -> 1814 -STUDYID -DOMAIN -LBSEQ ...RESULT: CHECK | FIRST CAUSE: programs/20_2_bili.R:10: step 2: There was 1 warning in `mutate()`.ℹ In argument: `BILI = as.numeric(LBORRES)`.Caused by warning:! NAs introduced by coercion (data after step k: @pipe[k]; rows step k dropped: @pipe[k]:dropped)Step 2, line 10. The data after that step is @pipe[2]: dsr query '@pipe[2]' --where 'is.na(BILI)' lists the rows that became NA. End with dsr pry quit.
25.8 More from the manual
Section titled “25.8 More from the manual”- Call a Function with a Form. Right-click a function name: a form with its arguments, their defaults and their help. Debug starts a run that stops at the first line of the function; Trace shows every line (chapter 23).
- Debug the Run That Waits at Its Stop. When a run of an AI agent waits at a stop, the status bar says so. This command opens that run in the debugger (chapter 26).
- No Pause. R runs one thing at a time, so the debugger cannot pause in the middle of a line. Use a breakpoint, or Stop the Running Code.
25.9 Summary
Section titled “25.9 Summary”- A click in the margin (or Ctrl+F9) sets a breakpoint; F5 runs the file in the debugger.
- F10, F11, Shift+F11 and F5 step over, into, out and continue. The Call Stack, Variables and Debug Console show each frame.
- Edit Condition stops only for the case you want:
any(age == 65). Edit Breakpoint adds a hit count or a log message. - Break on Value Change (
dsr pry watch) stops after the line that changed a value, and names it. - R warnings in the Breakpoints view (
--stop-on-warning) stops where a warning happens; Debug the Pipeline at the Stop names the step. - Each debugger stop has a terminal form:
dsr run --stop-atanddsr pry.
25.10 Exercises
Section titled “25.10 Exercises”Exercise 25-1. In 25.5, how many ages have no group after line 5 has run? Which ages are they, roughly?
Exercise 25-2. Which four subjects have no age group in 25_2_adsl_agegr.R, and in which arms are they? Use the data viewer or dsr query.
Exercise 25-3. In 25.7, at which line and in which step of the pipeline does the warning happen? Which values became NA (exercise 20-2)?
Exercise 25-4. Fix line 5 of 25_1_age_group.R and run 25_2_adsl_agegr.R again. How many subjects are in the group 65-80 now? Then put the bug back: chapter 26 uses it.
The answers are in Answers, Part VI.
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.