Skip to contents

Start here

John Ehrlinger

Source: vignettes/start-here.qmd

If you are new to the HVTI R family, or new to a study, read this page first. The work comes in two parts, and the order matters. hvtiR gets the study ready, once. The hvtiRtemplates tutorials then take you through the analysis, every day after that.

What you need

You need a session on the server, the study’s directory, and its title and ID from Study Tracker. On Posit Workbench, start a new RStudio Pro session and pick the latest R version listed. The family requires R 4.4.0 or newer, and setup() stops on anything older.

A study that already has a renv.lock is the exception: pick the R version its R Version entry records. setup() only warns about a different one, and its snapshot then records the R you are running. upgrade = FALSE keeps package versions from moving, not R.

Where to type

Every R command on this page goes in RStudio’s Console pane, at the > prompt, one command at a time. Press Enter to run it. The Terminal tab beside the Console is a shell, not R, and an R command typed there fails. The page has one shell command, study-setup --verify, and it says so where it comes.

  • Text after a # is a comment. R ignores it, so you can paste it or leave it out.
  • EDIT: marks a value that is yours to fill in. Replace the words, and keep the quotation marks around them.
  • A command can run over several lines. Paste it whole: R waits, showing + instead of >, until the closing parenthesis arrives.
  • hvtiR::setup() means “the setup() function from the hvtiR package”. The page writes every call that way so that it works in a fresh session. Common errors explains why.

Has the study been set up already?

Look in the study’s directory. If it holds both _study.yml and renv.lock, someone has probably set it up: open its .Rproj, then go to Check the study. Those two files can also come from an older renv::init(), which brings neither the family nor the standard packages. If hvtiR::status() there shows members missing, adopt the study from outside the project, as If it says to run from outside the project describes.

A new study may have been set up when its directory was made, because the study-setup command in qhsprograms runs hvtiR::setup() for you. Otherwise, carry on here.

Set up the study

Most studies already have a directory, with folders and files of their own. Set one of those up from inside it, as an RStudio project. A study whose directory does not exist yet is set up from outside; A new directory covers that case.

What adopting deletes

Setting up an existing directory is called adopting it. Adopting deletes three kinds of file anywhere in the study, and makes no backup:

  • every file whose name starts with tp., matched by name alone, so an edited or study-specific tp.* file goes too;
  • every binder.summaries.doc;
  • every other file whose name and exact content match one in the template corpus.

Before you adopt, look through the study for tp.* files that hold work of your own, and rename or copy any you need. To adopt without deleting anything, add cleanup = FALSE to the call below.

Open the study as a project

If the study’s top directory holds a .Rproj file, open it (File > Open Project). If it has none, make one: File > New Project > Existing Directory, then browse to the study’s top directory and click Create Project.

Choose the top directory, the one that holds the study’s folders, not one of those folders. setup() refuses a folder named like a study folder, such as datasets or 30_analyses, and names the directory above it to open instead.

Run it

In the Console, install the installer, then set the study up:

install.packages("pak")  # once per machine
pak::pak("ehrlinger/hvtiR")

hvtiR::setup(
  study = "EDIT: the Study Tracker title",
  study_tracker_id = 0L,  # EDIT: the Study Tracker ID
  identity_source = "manual"
)

The call names no directory: setup() takes the project you have open. Because that directory has no _study.yml yet, it asks before changing anything:

/path/to/study has no _study.yml. Adopt it as study "..." (Study Tracker ...)?
Adopting deletes the tp.* files, binder.summaries.doc and exact template copies
it holds; pass cleanup = FALSE to keep them. (yes/No/cancel)

Check the directory, title and ID in the question, then type yes and press Enter. The answer it shows in capitals, No, is what pressing Enter alone gives. No or cancel prints Not adopted. Nothing was changed., and nothing was.

identity_source = "manual" is there because you typed the title and ID. The default says they came from a Study Tracker record, and a new _study.yml would then record them as verified. A _study.yml the study already has is not rewritten.

A study in revision needs one more argument, upgrade = FALSE. By default, setup() moves a version the lockfile pins when the family needs a newer one, and lists each move. In revision those versions must not move, so with upgrade = FALSE a package the install would move stops the run instead, and renv.lock stays as it was.

If it says to run from outside the project

A study that already has a package library of its own, from an older renv::init(), loads that library when you open the project. setup() replaces packages in it, which it cannot do from a session that has them loaded. So it stops, after you answer yes if it asked, before installing anything, and prints the call to run instead:

Run it from a session started outside any project: hvtiR::setup(root = "...", ...)

Close the project (File > Close Project). Check that Sys.getenv("RENV_PROJECT") prints "", then paste the call it printed into the Console. That call names the directory with root. When the study already has a _study.yml, it asks before changing anything:

/path/to/study already has a _study.yml for this study. Adopt it, adding only
what is missing? (yes/No/cancel)

Type yes and press Enter. The question does not say so, but adopting deletes the files listed in What adopting deletes, as it does for a first setup. To keep them, add cleanup = FALSE to the call before you run it.

A new directory

For a study whose directory does not exist yet, close any open project, then name the directory with root:

hvtiR::setup(
  study = "EDIT: the Study Tracker title",
  study_tracker_id = 0L,  # EDIT: the Study Tracker ID
  root = "EDIT: the study directory",
  identity_source = "manual"
)

setup() creates the directory with the numbered folders (00_datasets, 10_descriptive and so on). An adopted study keeps the folder names it has.

What it does

In order, setup():

  • turns off RStudio’s .RData restore and save, for you rather than for the study (workspace_prefs = FALSE leaves them alone);
  • writes the study’s identity to _study.yml, adding a project file when there is none, and deletes the files listed above if you are adopting;
  • declares hvtiR, every family member and the standard analysis packages in the study’s DESCRIPTION;
  • installs them into the study’s own library and records them in renv.lock;
  • checks that every package’s dependencies resolve there;
  • restarts RStudio inside the project (outside RStudio, it tells you to restart R there).

It needs no data, so you can run it at kick-off. It needs no personal GitHub token to install, either, since pak carries a shared one. It warns when you have none, because restoring a package a lockfile already pins on GitHub may need your own GITHUB_PAT.

If it stops partway, fix what it names and run the same command again. Each step checks before it acts, so a rerun is safe.

When it worked

The last step restarts RStudio inside the study. The project name in RStudio’s top right corner is the study’s directory name, and the Files pane shows _study.yml and renv.lock beside the study’s folders. Go on to Check the study.

If R printed an error instead, read the message from its first line: it names what stopped the run. Fix that and run the same hvtiR::setup() command again.

What not to run

Do not run renv::init() on the study: setup() has already made the environment, and renv::init() starts the library over. Do not run organize_templates.sh: setup(adopt = TRUE) replaces it. When a study needs a package the family and the standard set do not bring, add it from inside the project:

hvtiRutilities::study_need("cmprsk")

That installs it, declares it and records it in renv.lock. A package already installed is only declared, so run renv::snapshot() after it. A study’s package environment covers updates, revisions and what to do when the environment misbehaves.

Check the study

Now you are inside the project. Ask the study what it still needs, and the family whether you are current:

hvtiRutilities::study_status()
hvtiR::status()

study_status() prints a checklist, one line per thing a study needs: [x] marks one that is in place, [ ] one that is not, and [~] one that is in place but not yet confirmed. On a study set up as above, renv.lock is ticked and _study.yml shows [~]. You typed the title and ID (identity_source = "manual"), so the line says they were entered by hand and to confirm them with study-setup --verify.

That is a shell command, so it goes in RStudio’s Terminal tab, not the Console. Run it from the study’s directory:

study-setup --verify

It looks the ID up in Study Tracker and compares the title you typed. When they match, it marks the identity verified, and study_status() then shows [x] for _study.yml. When they differ, it lists each difference and asks whether to take Study Tracker’s values; answer no and nothing changes. A study that the study-setup command created was read from Study Tracker in the first place, so its _study.yml shows [x] from the start.

The manifest.yaml and dataset lines are not ticked either, and each says to run register_data(). That is expected: registering the data is the next step, and it belongs to the tutorials. hvtiR::status() reports whether each family package in the study is current, and how to update any that are not.

Go on to the tutorials

From here the work moves to hvtiRtemplates.

  1. Register the data. For a new study, Start a new study. For an existing one, Adopt an existing study.
  2. Work a job. Work a job, from template to final report is the daily loop: pick a template, add it, fill in its EDIT: lines, render, and read the report.
  3. Choose the next template. The template gallery shows what each one produces on a synthetic study.

If you are coming from SAS, From SAS descriptive jobs to R sets the descriptive templates beside the tp.dc.* jobs they replace.

Common errors

R’s error messages are terse. These are the ones new users of the family meet most, word for word as R prints them, with what each means.

could not find function "read_built" 

Error in read_built() : could not find function "read_built"

R knows a function only once its package is attached, and a new session attaches none of the family. Either name the package in the call, as this page does:

d <- hvtiRutilities::read_built()

or attach the package once per session, then call the function by its name:

library(hvtiRutilities)
d <- read_built()

Attaching lasts until R restarts, and hvtiR::setup() restarts it, so attach again afterwards. The functions you will use most come from three packages:

Package Functions
hvtiR setup(), status(), update(), doctor()
hvtiRutilities register_data(), read_built(), study_status(), study_need()
hvtiRtemplates add_job(), job_status(), run_job(), upgrade_job()

'package' must be of length 1 

Error in library(c("hvtiRutilities", "hvtiRtemplates")) :
  'package' must be of length 1

library() attaches one package per call. To attach all three at once:

invisible(lapply(c("hvtiR", "hvtiRutilities", "hvtiRtemplates"), library, character.only = TRUE))

The following object is masked from ‘package:stats’: update

This is a note, not an error, printed when library(hvtiR) attaches. It means that update() now runs hvtiR::update(), which updates the family. To update a fitted model, write stats::update(fit, ...).

there is no package called ‘cmprsk’ 

Error in library(cmprsk) : there is no package called ‘cmprsk’

Each study has a library of its own, and that package is not in this one, even if another study or your own library has it. From inside the study’s project, install it into the study:

hvtiRutilities::study_need("cmprsk")

When the missing package is one of the family, run hvtiR::status() instead.

no _study.yml found 

Error: study_config(): no _study.yml found.

R is working outside the study. A study function finds its study by looking for _study.yml in the working directory and each folder above it, and the message lists every folder it looked in. Open the study’s .Rproj file, or run getwd() to see where R is, and try again.

When something goes wrong

Start with the doctor:

hvtiR::doctor()

It reports your R version, your platform, whether pak is available, the repositories R is configured to use and whether an renv project is active, and Install, update and check the family explains the failures we see most. If that does not settle it, tell the team. Send the code you ran, what you expected, what happened instead, and the doctor’s output. A failure you hit is usually a gap in the tools or in this page, so report it early.

Never send patient data. Column names and dim() are fine; rows are not.