The dsr commands

Every dsr tool, with the help text the tool itself prints (dsr tools, dsr help <tool>), version 0.10.3. The editor puts dsr on the PATH of its terminals; elsewhere it is node <extension folder>/bin/dsr.js. The MCP server (bin/dsr-mcp.js) gives the same tools with the same arguments.

Every tool also takes --json (one JSON object), --max-lines N (the rest: dsr more) and --root DIR (that folder's session).

The session

Usage: dsr start [--root DIR]

Usage: dsr stop [--session]

Usage: dsr status

Usage: dsr wait [--timeout 600]

Usage: dsr sessions [--dir DIR]

Usage: dsr doctor [--root DIR]

Usage: dsr history [--n 20]

Running programs

Usage: dsr run <file.R | -> [--from-line N] [--to-line M] [--stop-at LINE | FILE:LINE ['if <condition>'] (repeat it)] [--stop-when '<R condition>'] [--stop-on-warning] [--coverage] [--echo] [--timeout S]

The log names the line of every message. A data frame a step creates or changes gets a NOTE:
  NOTE: adae has 1191 rows and 57 columns (was 1191 x 55). New: ASTDT (11 missing), ASTDTF (1180 missing).
  NOTE: Empty columns in adae (missing on every row): AEACN.      <- a bug until you know why
  WARNING: adae: rows went from 1191 to 1205 in a join ...        <- duplicate keys on the other side
--from-line/--to-line run a part (whole expressions); the objects of the session stay between runs, so after one
full run, run only what you changed. --stop-at stops before that line (also a line inside a function, in this or
another file the session sourced); repeat it for several stops; 'R/f.R:8 if x > 3' or --stop-when (for all) only
when the condition is TRUE there. The run WAITS at the stop (live): dsr pry ls | eval look there, then
dsr pry next | step | finish | continue | quit go on (each answers at the next stop or at the end of the run).
--stop-on-warning stops where a warning happens. --coverage: how often each line ran (dsr coverage).
An ERROR keeps the frames where it happened open: dsr pry stack, dsr pry ls, dsr pry eval.
pry() in the code stops there (pry(when = <condition>)); pry(stop = FALSE) keeps a snapshot and goes on (dsr pry points).
The last line before the verdict says what the run changed in the workspace (new, changed, removed objects).
A program runs in its own folder (as Rscript started there): its relative paths start at the program's folder;
dsr eval and dsr run - run in the project folder. A program elsewhere in the project can find the project folder
with rprojroot (rprojroot::find_root(rprojroot::has_file("<a file of the project root>"))).
--timeout S: come back after S seconds while the run goes on (exit 3); dsr wait, then dsr log.

Usage: dsr eval '<code>' | dsr eval - <<'R' ... R  [--timeout S]

Usage: dsr log [--filter errors|warnings|notes|output|suspicious|rules] [--from 1] [--n 200]

Usage: dsr output [--from 1] [--n 200]

Usage: dsr more [--from 1] [--n 200]

Usage: dsr reload

Usage: dsr outline <file.R>

Usage: dsr batch <file.R> [more.R ...] [--vanilla] [--timeout S]

Each program runs in its own new R session, in the project folder, with the log of dsr run (program.log next to it).
--vanilla (anywhere on the line): R --vanilla, so no .Rprofile (neither the project's nor yours), no .Renviron and no site
profile, and no startup file (triallens.R); the library paths are the session's (.libPaths(), passed as R_LIBS), so the
packages are there but nothing of the project is loaded: the proof that a program needs only R and its packages.

Debugging: when a value is wrong and the log does not say why

Usage: dsr pry [whereami | stack | ls | eval '<code>' | up | down | frame <k> | next [n] | step | finish | continue | quit | break 'FILE:LINE [if <cond>]' | watch '<expr>' | unwatch | source <function> | run <file.R> | pipe | vars | points | point <k> | help]

whereami     the frame, its code around the line, its objects
stack (bt)   the frames from the top level down to where it stopped (=> the current one)
ls           the objects of the current frame
eval <code>  run code IN the frame (its local variables), e.g. dsr pry eval 'table(grp, useNA = "always")'
up / down / frame <k>   move between frames
At a LIVE stop (dsr run --stop-at, a breakpoint of the editor, pry() in the code) the run waits; each of these answers
at the next stop or at the end of the run, with the log since the last answer:
next [n] (n) the next line of this frame (or of the frame it returns to); n 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 (its verdict)
quit (q)     end the run here: RESULT: STOPPED, the lines after the stop do not run (a new dsr run quits too)
break 'R/f.R:12 if x > 3'   one more stop;  watch 'x'   stop at the line after x changes;  unwatch
source <fn>  the function's code with its file and line;  run <file.R>  a program file run in the frame
pipe         the pipeline at this line, step by step, on the frame's data (as dsr pipe)
points       the snapshots that pry(stop = FALSE) kept (e.g. one per loop pass), point <k> opens one
The data tools take @pry:<object> (and @point[k]:<object>): dsr query @pry:adsl --where 'is.na(BMIBL)'

Usage: dsr trace [file.R] --call '<f(args)>' [--into g,h] [--steps 300]

The R counterpart of the DATA step trace: use it when a value is wrong and the log does not say why.
file.R (optional) defines the functions without running the rest of it; --into also traces the functions it calls.
  dsr trace R/derive.R --call 'bmi_group(c(22, 30, NA))'
  R/derive.R:8   grp[bmi > 30] <- ">=30"          grp = [3] "<25", "", ""     <- 30 is in no group
An error in the call keeps its frames open for dsr pry.

Usage: dsr pipe <file.R>:<line> [--no-prepare]

Usage: dsr coverage [file.R]

Data (a data frame of the session, a file .xpt/.rds/.sas7bdat/.csv, @pry:<obj>, @pipe[k])

Usage: dsr datasets

Usage: dsr describe <data> [--find <text>]

Usage: dsr profile <data> [--vars 'A B'] [--where '<R condition>']

Usage: dsr query <data> [--where '<R condition>'] [--search <text>] [--vars 'A B'] [--sort 'A -B'] [--n 20] [--offset 0] [--raw] [--code]

--code: the query as R code to paste into a program (dplyr and base R), checked to give the same rows: the
data viewer's "View as R code". --search: rows where any column contains the text (case not counted).
--raw: the stored values, not the formatted ones: a factor's code, a labelled value's number (haven), a date's days
since 1970-01-01. Formatted (the default): a factor's level, a labelled value's label, a SAS w.d format's decimals.

Usage: dsr freq <data> <VAR | 'A*B'> (or --vars) [--by TRTA] [--where '<R condition>'] [--subjects] [--n 50]

Usage: dsr means <data> <'A B'> (or --vars) [--by TRTA] [--where '<R condition>']

Usage: dsr dups <data> --key 'USUBJID AESEQ' (or --by) [--where '<R condition>']

Usage: dsr compare <base> <compare> [--key 'USUBJID AESEQ'] [--vars 'A B'] [--tolerance 1e-8] [--n 5]

Usage: dsr data <data> [--where '<R condition>'] [--n 10] [--vars A,B]

Usage: dsr ls

The R language

Usage: dsr syntax <pkg::fn | fn> [--full]

Usage: dsr complete <file.R>:<line>:<col> [--n 40]

Usage: dsr index

Writing code, tests and packages

Usage: dsr lint [file.R | folder ...]   (default: R/, programs/ and the .R files of the project)

Usage: dsr format <file.R | folder ...> [--check | --write] [--scope spaces|indention|line_breaks|tokens] [--indent-by 2] [--strict true|false]

The proof, per file: the code's tokens (every token but the comments: its kind and its text, in order) are the
same before and after, the comments are the same word for word, and the parsed program is the same. A file is
written only when its tokens and comments are the same; with --scope tokens (styler may change ' to ", = to <-,
braces) when its program and comments are the same. Else it stays as it is and the first difference is named.
--scope: how much styler may change: spaces < indention < line_breaks (the default: the layout only) < tokens.
--check: write nothing, say which files would change (exit 1 when one would); --write: write (the default).
The style: options(dsr.format = list(scope = "line_breaks", indent_by = 4, strict = FALSE)) in the project's .Rprofile,
else styler's defaults (indent 2); the verdict line names where it came from.
--indent-by N: spaces per level (styler's indent_by); --strict false: keep the spaces and line breaks styler would
only tidy (fewer changes). Both override options(dsr.format) of the project, as the editor's settings do.

Usage: dsr load

Usage: dsr check [--cran] [--timeout S]

Usage: dsr test [dir | test-file.R] [--filter <part of a file name>] [--verbose] [--coverage] [--timeout S]

--coverage: after the clean run, the same test files run once more in the session with the debugger's counters
(failures do not stop it), then COVERAGE per file of the project's functions: the lines the tests ran and those
they never ran; dsr coverage <file> lists each line with its count. A test file that sources a file of R/ is fine:
the functions it defines are counted from the next line on.

Clinical data: subjects, specifications, conformance

Usage: dsr subject <USUBJID | subject number> [--vars 'A B'] [--n 30]

Usage: dsr spec <dataset> [VARIABLE] [--data <data>]

Usage: dsr cdisc <data> [--dataset ADSL] [--key 'USUBJID PARAMCD AVISIT'] [--spec specs/adam/advs.json]

Usage: dsr numbers <output.txt> <reference.txt | .pdf> [--table 14-3.01] [--only '<block regex>'] [--rows 'ref row = out row; ...'] [--label '<regex>'] [--round r|sas] [--page 49] [--n 30]

Each line of a table is a label and its numbers; a line of words only is a block heading (Baseline, Week 24).
Reference rows pair with output rows by block + label; numbers by position, each rounded to the reference's decimals.
  --only 'Week 24|Baseline'   compare only these blocks of the reference; the other rows are "not compared", not differences
  --rows 'Week 24 / Median (Range) = Week 24 / Median + Week 24 / Min, Max; n = Week 24 / n'
                              pair rows whose labels differ; + joins several output rows to one reference row
  --label '^Week \d+( \(Windowed\))?'   where a label ends, for pages with no gap of two blanks before the numbers
  --round sas                 round half away from zero (SAS ROUND: 42.65 -> 42.7), as a CSR made with SAS prints
  --page 49                   read a PDF page with its layout (pdftotext); a text file needs no option

Checks of the dashboard and the study (the clinical add-on)

Usage: dsr app start|stop|status|logs|check [--dir apps/dashboard] [--port 3150 | --ports 3100-3199] [--timeout 120] [--width 1400] [--height 1000] [--set 'input=value' ...] [--wait '<CSS selector | js:condition>'] [--key data-rid]

start      the app in a background R process (the session stays free); --port, or a free port of --ports
check      a headless browser opens the app, visits every tab, and keeps for each page its errors, a screenshot and
           its text (.triallens/check/). --timeout: seconds for the app to load (also the browser's own commands);
           --width/--height: the browser window; --set 'f_SEX="F"' (repeat it) sets inputs before the visits, so the
           check runs on another view; --wait '.page-meta[data-view]' (a CSS selector) or 'js:<condition>' waits on
           each page; --key data-rid keeps the text and data-raw of every element with that attribute for dsr gate.
--dir      the app's folder when it is not the project folder (apps/dashboard).

Usage: dsr gate

Usage: dsr adam check <dataset|all>

The guide for agents

dsr guide prints the way of working on one page; an agent reads it once.

How to work in the programmer's R session through DataStep Studio for R (dsr)

The tools work in the user's live R session: the user sees every run, log and stop in the editor.
Find things out with the tools; never guess what R did. Run R only through dsr (no Rscript, no R -e).

THE LOOP
1. Goal: "Done when ..." is a fact in the data or the output (254 subjects; the gate passes), not a clean log.
   The specifications and contracts (specs/, dashboard.yml) belong to people: report what is wrong in them.
2. Look: dsr describe | profile | query <data> (also a file, @pry:x, @pipe[k]); dsr outline <program>.
   Before a call you are not sure of: dsr syntax pkg::fn (the installed version's arguments).
3. Write a small piece, dsr lint <file>, then dsr run <file> (or dsr run - for code on stdin).
   A program runs in its own folder (its relative paths start there); dsr eval and dsr run - in the project folder.
4. Read the verdict line, then every NOTE:
   RESULT: CLEAN  look at the result         CHECK  a warning or an error in disguise: fix it, or say why it is right
   RESULT: ERROR  fix the FIRST CAUSE only   NOTEs  empty columns, new columns with missing values, rows that grow in a join
   dsr log --filter suspicious: the messages that matter, each with its rule, why and fix (dsr log --filter rules)
5. A wrong value: find the cause with the tools before you change code, and say what you saw.
   an ERROR leaves its frames open: dsr pry stack | ls | eval '<code>'
   stop anywhere: dsr run <file> --stop-at 'R/f.R:42 if USUBJID == "01-701-1015"' (repeat it; --stop-on-warning);
   the run WAITS there: dsr pry ls | eval look, dsr pry next | step | finish | continue | quit go on (each answers at
   the next stop or the end); dsr pry watch x, break, pipe (the pipeline at the stop, on its data); a new run quits it
   dsr trace --call 'f(x)' (each line, what it changed, each if)    dsr pipe <file>:<line> (each pipeline step)
   dsr freq | means | dups --key | compare on the data
6. The smallest fix; run again (--from-line/--to-line runs a part; the objects stay). Three failed tries: report.
   Which lines ran at all: dsr run <file> --coverage, or dsr test --coverage (the lines the tests run), then
   dsr coverage <file> (a line run 0 times never ran).
   A refactor that must not change results: keep the old function (git show HEAD:R/f.R > old.R, sys.source into
   its own environment) and compare identical(old(x), new(x)) on many inputs: factor, Date and NA groups, empty
   data, one row. for() walks a factor as text and a Date as numbers; rbind() and c() decide the result's type.
7. Finish: dsr lint, dsr format (it writes only when it proves that only the layout changed), dsr batch <program>
   (alone, in a new session; it writes <program>.log next to it), dsr test, and the checks that fit the project:
   an output table with a reference (a CSR page, a double-programmed table): dsr numbers <output> <reference>
   ADaM with specs/adam/<ds>.yml: dsr adam check <ds>      a dashboard: dsr app check, then dsr gate
   data for a submission: dsr cdisc <data>
   A test that fails outside your task: report it, and run yours with dsr test <file> or --filter.
   A specification and a reference that disagree: follow the specification, say where they differ; never match
   the reference silently.

FOR A PROGRAM THAT CALLS dsr (an agent, a harness)
- --json on every tool: one object {schema "dsr/1", tool, exit, ok, verdict, summary, fix, text, truncated,
  more, data}. MCP: the same as structuredContent (node <extension>/bin/dsr-mcp.js; docs/agents.md).
- Exit codes: 0 good; 1 the tool says not good (ERROR, FAIL, PROBLEMS); 2 a wrong call or no session (fix: names
  what to do); 3 still running after --timeout S (dsr wait, then dsr log; dsr stop cancels, the objects stay).
- Long output: --max-lines N keeps the head and the verdict; dsr more --from N gives the rest.
- Writing code: dsr complete <file>:<line>:<col> (what fits there: columns with labels, arguments, exports, the
  signature), dsr query <data> ... --code (a view as R code to paste), dsr syntax pkg::fn.
- Sessions: dsr status, dsr sessions, --root DIR; it cannot start: dsr start says why; dsr doctor checks all.

dsr guide --full: which tool answers which question, in detail. dsr tools: every tool. dsr help <tool>: one.