Skip to content

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.

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.
programs/24_1_by_sev.R
# Chapter 24: count the subjects with a treatment-emergent adverse event, one severity at a time
library(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 29

The loop makes one subset per severity and counts its subjects.

  1. Replace the comment on line 13 with pry(when = sev == "SEVERE") and press F4. when is a condition: the run stops only when it is TRUE, here in the third round.

    $ dsr run programs/24_1_by_sev.R
    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:13
    11 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.

  2. Type ls (or dsr pry ls): the objects of the frame.

    $ dsr pry ls
    adae tbl_df 1122 rows x 107 columns
    i integer 3
    nsub integer [2] 186, 129
    sev character "SEVERE"
    sevs character [3] "MILD", "MODERATE", "SEVERE"
    sub tbl_df 41 rows x 107 columns

    i is 3 and sev is SEVERE. nsub has only two values: the count of round 3 has not run yet.

  3. 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 × 2
    TRT01A n
    <chr> <int>
    1 Placebo 6
    2 Xanomeline High Dose 10
    3 Xanomeline Low Dose 25
    RESULT: 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 opens sub from the Pry panel.

  4. Type next (or n): the run goes one line on.

    $ dsr pry next
    => <top level> programs/24_1_by_sev.R:14
    12 filter(AESEV == sev)
    13 pry(when = sev == "SEVERE")
    => 14 nsub[sev] <- n_distinct(sub$USUBJID)
    15 }
    16
    RESULT: 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 next runs it.

  5. Type continue (or c): the run goes to its end, or to the next stop.

    $ dsr pry continue
    9 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 SEVERE
    186 129 29
    Workspace: 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.

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 }
16
RESULT: 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 353
RESULT: 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.

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:

programs/24_3_error.R
# Chapter 24: an error inside a function, and its frames stay open to look at
summarise_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::advs
summarise_param(advs, "WEIGHT")
#> n mean
#> 4289.0 66.6
summarise_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 stack
PRY 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.

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] 4289
RESULT: 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.

programs/24_2_baseline.R
# Chapter 24: baseline weight, the last value on or before the first dose, taken from the wrong visit
library(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.0

The 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.0
RESULT: 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-1015
Follow 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.98
FOLLOW: 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.43

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

  • pry() belongs to DataStep Studio for R. A pry() step stops in a live run (F4, dsr run). In dsr batch it only passes its data on. In plain R without DataStep Studio, the function pry() 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 points lists the snapshots, for example one per round of a loop.
  • The snippet pry-when writes a pry(when = ...) line for one subject (chapter 22).
  • A walk with pstep runs 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 continue or quit. A run that waits holds the session.
  • 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: ls and eval look; next, step, finish, continue and quit go on; watch stops where a value changes.
  • An error keeps its frames open: stack, ls, eval after RESULT: ERROR.
  • pry() in a pipeline gives ., the data at that point; pstep, follow and try work on that pipeline.
  • A bug can leave every count right. Look at the values of one subject.

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.