pry, the complete guide
pry() is one line in your program. When the run reaches it, the run freezes. You ask: which value has sev now? What is in this data frame at this moment? Then you let the run go on. One run, one stop, no print() in ten places.
pry() and every stop of this chapter are in the Professional edition, free during Early Access until 17 February 2027. In the Community edition, pry() does not stop: the log gets one NOTE, and the run goes on. All commands are on the cheat sheet.
24.1 Why pry helps you learn
Section titled “24.1 Why pry helps you learn”A program makes objects in between: a subset in a loop, the data in the middle of a pipeline, the variables inside a function. Normally you see only the end. pry() stops at the moment in between. Three things become easy:
- Understand someone else’s code. Stop it inside its loop and look at what it built.
- Find a bug. Stop where the result goes wrong, for the one subject that is wrong.
- Try a fix where the bug is. Run the corrected code at the stop, on the data of that moment.
24.2 Your first stop in five steps
Section titled “24.2 Your first stop in five steps”# Chapter 24: count the subjects with a treatment-emergent adverse event, one severity at a timelibrary(dplyr)
adae <- pharmaverseadam::adae |> filter(TRTEMFL == "Y")sevs <- c("MILD", "MODERATE", "SEVERE")nsub <- integer(0)
for (i in seq_along(sevs)) { sev <- sevs[i] sub <- adae |> filter(AESEV == sev) # chapter 24 puts a pry() line here nsub[sev] <- n_distinct(sub$USUBJID)}
nsub#> MILD MODERATE SEVERE#> 186 129 29The loop makes one subset per severity and counts its subjects.
-
Replace the comment on line 13 with
pry(when = sev == "SEVERE")and press F4.whenis a condition: the run stops only when it is TRUE, here in the third round.$ dsr run programs/24_1_by_sev.R4 NOTE: adae has 1122 rows and 107 columns.4 NOTE: Empty columns in adae (missing on every row): SCRFDT, DTHA30FL, RFICDTC, DTHDTF, AEBDSYCD, AELLTCD, AEPTCD, AEHLTCD, AEHLGTCD, AESOCCD, AENDTF, AEACN. A bug until you know why.=> <top level> programs/24_1_by_sev.R:1311 sub <- adae |>12 filter(AESEV == sev)=> 13 pry(when = sev == "SEVERE")14 nsub[sev] <- n_distinct(sub$USUBJID)15 }RESULT: PRY | AT: programs/24_1_by_sev.R:13: stopped at pry() (0.08 s) (live: dsr pry next | step | finish | continue | quit)What you should see: the editor marks line 13. The prompt of the R Console changes to the pry prompt, with the place of the stop. What you type there runs in the frame of the stop. The Pry panel opens too (not in the RStudio layout; there, DataStep R: Open Pry opens it): the stack, the code around the line, the objects of the frame and an eval box.
-
Type
ls(ordsr pry ls): the objects of the frame.$ dsr pry lsadae tbl_df 1122 rows x 107 columnsi integer 3nsub integer [2] 186, 129sev character "SEVERE"sevs character [3] "MILD", "MODERATE", "SEVERE"sub tbl_df 41 rows x 107 columnsiis 3 andsevis SEVERE.nsubhas only two values: the count of round 3 has not run yet. -
Run R code in the frame. At the prompt, type the code. In a terminal,
dsr pry eval:$ dsr pry eval 'dplyr::count(sub, TRT01A)'# A tibble: 3 × 2TRT01A n<chr> <int>1 Placebo 62 Xanomeline High Dose 103 Xanomeline Low Dose 25RESULT: CLEAN (0 s)The 41 severe records of chapter 21. The data tools take the objects of a stop too:
dsr query @pry:sub, and the data viewer openssubfrom the Pry panel. -
Type
next(orn): the run goes one line on.$ dsr pry next=> <top level> programs/24_1_by_sev.R:1412 filter(AESEV == sev)13 pry(when = sev == "SEVERE")=> 14 nsub[sev] <- n_distinct(sub$USUBJID)15 }16RESULT: PRY | AT: programs/24_1_by_sev.R:14: stopped (next) (4.84 s) (live: dsr pry next | step | finish | continue | quit)The marked line has not run yet. One more
nextruns it. -
Type
continue(orc): the run goes to its end, or to the next stop.$ dsr pry continue9 NOTE: sub has 41 rows and 107 columns.9 NOTE: Empty columns in sub (missing on every row): ASTDTF. A bug until you know why.MILD MODERATE SEVERE186 129 29Workspace: new: adae (tbl_df 1122 x 107), i (integer 1), nsub (integer 3), sev (character 1), sevs (character 3), sub (tbl_df 41 x 107)RESULT: CLEAN (4.95 s)
That is the whole idea. Put the comment back on line 13 when you are done. The rest of the chapter lists the questions you can ask.
24.3 Where a run can stop
Section titled “24.3 Where a run can stop”| How | Where it stops |
|---|---|
pry() on its own line |
every time the run reaches it |
pry(when = <condition>) |
only when the condition is TRUE there |
x |> f() |> pry() |> g() |
in the middle of a pipeline; . is the data at that point (24.6) |
dsr run prog.R --stop-at 'FILE:LINE if <condition>' |
before that line, without a change of the file; also a line inside a function |
| a breakpoint in the margin, Stop at Line | as --stop-at, from the editor (chapter 25) |
--stop-on-drop, --stop-on-dup |
where a record leaves a pipeline, or a key stops being unique (chapter 23) |
--stop-on-warning |
where a warning happens |
| an error | the frames of the error stay open (24.4) |
--stop-at is the stop for a program you may not change, or do not want to change. The same stop as in 24.2, now in round 2 and on line 14:
$ dsr run programs/24_1_by_sev.R --stop-at 'programs/24_1_by_sev.R:14 if sev == "MODERATE"' 4 NOTE: adae has 1122 rows and 107 columns. 4 NOTE: Empty columns in adae (missing on every row): SCRFDT, DTHA30FL, RFICDTC, DTHDTF, AEBDSYCD, AELLTCD, AEPTCD, AEHLTCD, AEHLGTCD, AESOCCD, AENDTF, AEACN. A bug until you know why.=> <top level> programs/24_1_by_sev.R:14 12 filter(AESEV == sev) 13 # chapter 24 puts a pry() line here=> 14 nsub[sev] <- n_distinct(sub$USUBJID) 15 } 16RESULT: PRY | AT: programs/24_1_by_sev.R:14: stopped at the breakpoint: where sev == "MODERATE" (0.05 s) (live: dsr pry next | step | finish | continue | quit)$ dsr pry eval 'c(i = i, rows = nrow(sub))' i rows 2 353RESULT: CLEAN (0 s)The run waits at a stop until you go on. While it waits, dsr status says so, and the status bar of the editor shows the stop. A new dsr run ends the run that waits.
24.4 An error keeps its frames open
Section titled “24.4 An error keeps its frames open”A frame is the set of objects of one function call while it runs. When a program stops with an error, its frames stay open. You can look at the values where it failed, after the run. No new run, no stop to set:
# Chapter 24: an error inside a function, and its frames stay open to look atsummarise_param <- function(data, paramcd) { rows <- data[data$PARAMCD == paramcd, ] if (nrow(rows) == 0) stop("no records for ", paramcd) c(n = nrow(rows), mean = round(mean(rows$AVAL, na.rm = TRUE), 1))}
advs <- pharmaverseadam::advssummarise_param(advs, "WEIGHT")#> n mean#> 4289.0 66.6summarise_param(advs, "HR")#> Error in summarise_param(advs, "HR") : no records for HR$ dsr run programs/24_3_error.R 9 NOTE: advs has 65032 rows and 105 columns. 9 NOTE: Empty columns in advs (missing on every row): SCRFDT, DTHA30FL, RFICDTC, DTHDTF. A bug until you know why. n mean 4289.0 66.6 11 ERROR: no records for HR [in summarise_param(advs, "HR")] 11 PRY: The frames of the error stay open: dsr pry stack, dsr pry ls, dsr pry eval <code>.Workspace: new: advs (tbl_df 65032 x 105), summarise_param (function (data, paramcd))RESULT: ERROR | FIRST CAUSE: programs/24_3_error.R:5 (called at line 11): no records for HR [in summarise_param(advs, "HR")] (1 s)stack lists the frames from the top level down to the error. ls and eval work in the frame of the error, the call of summarise_param():
$ dsr pry stackPRY at the error: no records for HR [1] <top level> programs/24_3_error.R:11=> [2] summarise_param programs/24_3_error.R:5$ dsr pry ls data tbl_df 65032 rows x 105 columns paramcd character "HR" rows tbl_df 0 rows x 105 columns$ dsr pry eval 'unique(data$PARAMCD)' [1] "BMI" "BSA" "DIABP" "HEIGHT" "MAP" "PULSE" "SYSBP" "TEMP" [9] "WEIGHT"RESULT: CLEAN (0 s)rows has 0 rows, because ADVS has no parameter HR. The heart rate is PULSE. The frames of an error are only to look at: next and continue work at a live stop, not after an error.
24.5 The commands at a stop
Section titled “24.5 The commands at a stop”Type them at the pry prompt of the R Console (the short forms in brackets), click them in the Pry panel, or use dsr pry <command> in a terminal.
| Command | What it does |
|---|---|
whereami |
the frame, its code around the line, its objects |
stack (bt) |
the frames from the top level down to the stop |
up, down, frame k |
move to another frame |
ls |
the objects of the frame |
eval <code> |
R code in the frame (at the prompt: type the code) |
next [n] (n) |
the next line of this frame; next 3 goes three lines |
step (s) |
the next line anywhere: into a function of the project that this line calls |
finish (f) |
the first line after this frame returns |
continue (c) |
to the next stop, or to the end of the run |
quit (q) |
end the run here: RESULT: STOPPED; the lines after the stop do not run |
break 'FILE:LINE if <cond>' |
one more stop |
watch <expr> |
stop at the line after the value changes |
source <fn> |
the code of a function, with its file and line |
pipe, pnext, pback, pstep k, follow, try |
the pipeline at the line (24.6) |
step and finish. Stop on line 10 of 24_3_error.R, the first call of summarise_param(). step goes into the function, next goes one line on, finish comes back out:
$ dsr run programs/24_3_error.R --stop-at 10...RESULT: PRY | AT: programs/24_3_error.R:10: stopped at the breakpoint (0.11 s) (live: dsr pry next | step | finish | continue | quit)$ dsr pry step=> summarise_param programs/24_3_error.R:4 2 # Chapter 24: an error inside a function, and its frames stay open to look at 3 summarise_param <- function(data, paramcd) {=> 4 rows <- data[data$PARAMCD == paramcd, ] 5 if (nrow(rows) == 0) stop("no records for ", paramcd) 6 c(n = nrow(rows), mean = round(mean(rows$AVAL, na.rm = TRUE), 1))RESULT: PRY | AT: programs/24_3_error.R:4: stopped (step) (0.18 s) (live: dsr pry next | step | finish | continue | quit)$ dsr pry next...RESULT: PRY | AT: programs/24_3_error.R:5: stopped (next) (0.25 s) (live: dsr pry next | step | finish | continue | quit)$ dsr pry eval 'nrow(rows)' [1] 4289RESULT: CLEAN (0 s)$ dsr pry finish n mean 4289.0 66.6=> <top level> programs/24_3_error.R:11 9 advs <- pharmaverseadam::advs 10 summarise_param(advs, "WEIGHT")=> 11 summarise_param(advs, "HR")RESULT: PRY | AT: programs/24_3_error.R:11: stopped (finish) (0.37 s) (live: dsr pry next | step | finish | continue | quit)finish ran the rest of the function: the result for WEIGHT is printed, and the run waits at line 11. dsr pry quit ends the run there (RESULT: STOPPED), so the failing call of line 11 does not run.
watch. Back at the stop of 24.3 (round 2, line 14), watch stops each time nsub changes:
$ dsr pry watch 'nsub'Watching nsub (now 186): the run stops at the line after it changes. dsr pry continue.$ dsr pry continue=> <top level> programs/24_1_by_sev.R:10 8 9 for (i in seq_along(sevs)) {=> 10 sev <- sevs[i] 11 sub <- adae |> 12 filter(AESEV == sev)RESULT: PRY | AT: programs/24_1_by_sev.R:10: stopped: a watched value changed: nsub changed by 24_1_by_sev.R:14: 186 -> [2] 186, 129 (0.24 s) (live: dsr pry next | step | finish | continue | quit)The stop says which line changed the value, and from what to what.
24.6 pry() in a pipeline: the wrong baseline
Section titled “24.6 pry() in a pipeline: the wrong baseline”This program takes the baseline weight: the last weight on or before the first dose.
# Chapter 24: baseline weight, the last value on or before the first dose, taken from the wrong visitlibrary(dplyr)
adsl <- pharmaverseadam::adsl |> filter(SAFFL == "Y") |> select(USUBJID, TRTSDT)weight <- pharmaversesdtm::vs |> filter(VSTESTCD == "WEIGHT")
base <- weight |> inner_join(adsl, by = "USUBJID") |> filter(as.Date(VSDTC) <= TRTSDT) |> arrange(USUBJID, VISIT) |> group_by(USUBJID) |> slice_tail(n = 1) |> ungroup() |> select(USUBJID, VISIT, VSDTC, BASE = VSSTRESN)
base |> filter(USUBJID == "01-701-1015")#> # A tibble: 1 x 4#> USUBJID VISIT VSDTC BASE#> <chr> <chr> <chr> <dbl>#> 1 01-701-1015 SCREENING 1 2013-12-26 54.0The baseline of 01-701-1015 comes from SCREENING 1, with 54.0 kg. The study flags the BASELINE visit (2 January 2014) as the baseline. What went wrong? Add a line pry() |> after line 13, the arrange(), and run:
$ dsr run programs/24_2_baseline.R 4 NOTE: adsl has 254 rows and 2 columns. 7 NOTE: weight has 2050 rows and 24 columns. 7 NOTE: Empty columns in weight (missing on every row): VSPOS, VSSTAT, VSLOC, VSTPT, VSTPTNUM, VSELTM, VSTPTREF. A bug until you know why.=> pipeline programs/24_2_baseline.R:14 12 filter(as.Date(VSDTC) <= TRTSDT) |> 13 arrange(USUBJID, VISIT) |>=> 14 pry() |> 15 group_by(USUBJID) |> 16 slice_tail(n = 1) |>RESULT: PRY | AT: programs/24_2_baseline.R:14: stopped at pry(): . is 507 rows x 25 columns (0.04 s) (live: dsr pry next | step | finish | continue | quit)At a pry() step, . is the data at that point of the pipeline. Look at the running example:
$ dsr pry eval '.[.$USUBJID == "01-701-1015", c("USUBJID", "VISIT", "VSDTC", "VSSTRESN")]' # A tibble: 2 × 4 USUBJID VISIT VSDTC VSSTRESN <chr> <chr> <chr> <dbl> 1 01-701-1015 BASELINE 2014-01-02 54.4 2 01-701-1015 SCREENING 1 2013-12-26 54.0RESULT: CLEAN (0.01 s)There it is. arrange(USUBJID, VISIT) sorts the visit names as text, and "BASELINE" comes before "SCREENING 1". So slice_tail() takes SCREENING 1 as the last record. Walk the steps with pstep k, pnext and pback, and follow a subject with follow:
$ dsr pry follow 01-701-1015Follow USUBJID == "01-701-1015": 0 weight 11 rows: 01-701-1015 / 142, 01-701-1015 / 143, 01-701-1015 / 144, 01-701-1015 / 145, 01-701-1015 / 146, 01-701-1015 / 147, ... 1 inner_join(adsl, by = "USUBJID") 11 -> 11 +TRTSDT = "2014-01-02" 2 filter(as.Date(VSDTC) <= TRTSDT) 11 -> 2 left: 01-701-1015 / 144 (as.Date(VSDTC) <= TRTSDT is FALSE: VSDTC = "2014-01-16"; TRTSDT = "2014-01-02")... left: 01-701-1015 / 152 (as.Date(VSDTC) <= TRTSDT is FALSE: VSDTC = "2014-07-02"; TRTSDT = "2014-01-02") 3 arrange(USUBJID, VISIT) 2 -> 2 4 pry() 2 -> 2 5 group_by(USUBJID) 2 -> 2 6 slice_tail(n = 1) 2 -> 1 left: 01-701-1015 / 143 7 ungroup() 1 -> 1 8 select(USUBJID, VISIT, VSDTC, BASE = VSSTRES 1 -> 1 +BASE = 53.98FOLLOW: 11 rows of USUBJID == "01-701-1015" at the start, 1 at the end (left at step 2: 9, step 6: 1)(Seven lines of step 2 are cut here.) Record 143, the BASELINE visit, leaves at step 6. Try the fix at the stop, on the same data:
$ dsr pry try 3 'arrange(USUBJID, VISITNUM)'Try step 3: arrange(USUBJID, VISITNUM) instead of arrange(USUBJID, VISIT)... 6 slice_tail(n = 1) 507 -> 254 (was 254) [grouped by USUBJID]...TRY: CLEAN | step 3 tried: at the end 254 rows (was 254)$ dsr query '@try[8]' --where 'USUBJID == "01-701-1015"'@try[8]: 1 of 254 rows where USUBJID == "01-701-1015", rows 1-1 USUBJID VISIT VSDTC BASE 01-701-1015 BASELINE 2014-01-02 54.43Look at the counts: 254 rows with the bug, 254 rows with the fix. A count cannot find this bug. Only the values differ. This is why you look at the data of one subject. dsr pry continue ends the run; then remove the pry() line.
24.7 Good to know
Section titled “24.7 Good to know”pry()belongs to DataStep Studio for R. Apry()step stops in a live run (F4,dsr run). Indsr batchit only passes its data on. In plain R without DataStep Studio, the functionpry()does not exist, so run such a program in the session.pry(stop = FALSE)keeps a snapshot of the frame and goes on.dsr pry pointslists the snapshots, for example one per round of a loop.- The snippet
pry-whenwrites apry(when = ...)line for one subject (chapter 22). - A walk with
pstepruns the pipeline again on the data of the frame. A step that writes a file writes it again. - Remove the
pry()lines before a program goes to QC. They are a tool for you, not part of the deliverable. - Always end a live stop with
continueorquit. A run that waits holds the session.
24.8 Summary
Section titled “24.8 Summary”pry()stops a real run at its line;pry(when = <condition>)stops only when the condition is TRUE.--stop-at 'FILE:LINE if <condition>'stops without a change of the file, also inside a function.- At the stop:
lsandevallook;next,step,finish,continueandquitgo on;watchstops where a value changes. - An error keeps its frames open:
stack,ls,evalafterRESULT: ERROR. pry()in a pipeline gives., the data at that point;pstep,followandtrywork on that pipeline.- A bug can leave every count right. Look at the values of one subject.
24.9 Exercises
Section titled “24.9 Exercises”Exercise 24-1. In 24_1_by_sev.R, stop in round 2 with pry(when = sev == "MODERATE"). What does nsub hold at the stop? Go on with next until the loop starts round 3, and look again.
Exercise 24-2. At the pry() step of 24.6, how many rows does . have? Why are there more rows than subjects?
Exercise 24-3. After the error of 24_3_error.R, how many records of PULSE does ADVS have? Use dsr pry eval in the frame of the error. Then change the call so that the program runs to its end.
Exercise 24-4. In 24.6, the fix sorts by VISITNUM. Why is arrange(USUBJID, VSDTC) also right here, and when would it not be?
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.