Package 'OmopStudyBuilder'

Build a Docker image for an OMOP study

Description

Build a Docker image for an OMOP study

Usage

dockeriseStudy(
  image_name = NULL,
  path = ".",
  useRStudio = FALSE,
  r_version = NULL,
  snapshot = TRUE,
  github_token = NULL
)

Arguments

image_name	Name for the Docker image (default: auto-detected from directory)
path	Path to study directory (default: current directory)
useRStudio	Use RStudio Server base (TRUE) or r-ver base (FALSE, default)
r_version	R version override (default: auto-detected from renv.lock)
snapshot	Update renv.lock before building (default: TRUE)
github_token	Optional GitHub token for installing GitHub packages during build

Value

Image name (invisibly - already printed to console)

---

Creates initial directory for an OMOP CDM network study

Description

Creates initial directory for an OMOP CDM network study

Usage

initStudy(
  directory,
  diagnostics = TRUE,
  study = TRUE,
  studyTitle = NULL,
  studyLeads = NULL,
  studyDescription = NULL,
  repository = NULL,
  organisation = NULL,
  private = TRUE
)

Arguments

directory	Path to a directory that will be used as the root folder for the study. If it does not exist, it will be created. The directory must be empty if it already exists.
diagnostics	A single TRUE or FALSE value. If TRUE (the default), the function creates the 'diagnosticsCode/' and 'diagnosticsShiny/' folders using the package templates. If FALSE, these diagnostics folders are not created.
study	A single TRUE or FALSE value. If TRUE (the default), the function creates the 'studyCode/' and 'studyShiny/' folders using the package templates. If FALSE, these study folders are not created.
studyTitle	Character string with the study title. If NULL (default), uses the directory basename.
studyLeads	Character string with study leads. If NULL (default), leaves a placeholder.
studyDescription	Character string with study description. If NULL (default), leaves a placeholder.
repository	Optional GitHub repository name. If provided, creates a GitHub repository and links it to the study. Requires the gh and gert packages and GitHub authentication (for example via GITHUB_PAT).
organisation	Optional GitHub organisation name. If NULL (default), creates repository under your personal account. Only used when repository is provided.
private	Logical. If TRUE (default), creates a private GitHub repository. Only used when repository is provided.

Value

Project directory will be created

Examples

# Create a study called "SampleStudy" in a temporary directory
study_root <- file.path(tempdir(), "SampleStudy")
initStudy(study_root)

# Inspect the top-level contents
list.files(study_root)

# Create another study with custom metadata
study_root2 <- file.path(tempdir(), "DiabetesStudy")
initStudy(study_root2,
          studyTitle = "Diabetes Prevalence Study",
          studyLeads = "Dr. Smith, Dr. Jones")

## Not run: 
# Create study with GitHub integration (requires GITHUB_PAT)
# Set PAT for current session:
Sys.setenv(GITHUB_PAT = "your_token_here")

study_root3 <- file.path(tempdir(), "GitHubStudy")
initStudy(
  directory = study_root3,
  repository = "my-omop-study",
  organisation = "oxford-pharmacoepi",
  private = TRUE
)

## End(Not run)

---

Link study directory to GitHub repository

Description

Creates a new GitHub repository and connects it to an existing study directory. Initializes git, creates .gitignore, commits all files, and pushes to GitHub.

Usage

linkGitHub(
  directory,
  repository,
  organisation = NULL,
  private = TRUE,
  description = NULL
)

Arguments

directory	Path to study directory
repository	GitHub repository name (will be sanitised if needed)
organisation	GitHub organisation name. If NULL (default), creates repo under your personal account
private	Logical. If TRUE (default), creates a private repository
description	Repository description. If NULL, auto-generated from directory name

Value

GitHub repository URL (invisibly)

Requirements

• GitHub authentication: Set up via GITHUB_PAT, gh CLI, or git credentials

• R package 'gh': Install with install.packages("gh")

• R package 'gert': Install with install.packages("gert")

Authentication

This function needs credentials for both:

• GitHub API access: used by gh to check your account and create the repository

• Git transport authentication: used by gert to push the local repository to GitHub

Recommended setup:

• GITHUB_PAT environment variable: recommended for HTTPS authentication and works for both GitHub API calls and Git pushes to GitHub

• Stored Git credentials: credentials in your OS credential store or Git credential helper can also work for both the API and push steps

• gh CLI: may help set up GitHub authentication, but you may still need Git credentials available for the final push

• SSH: supported when your remote/auth setup is configured accordingly

To create a Personal Access Token (PAT):

1. Visit https://github.com/settings/tokens

2. Generate a token with repo scope

3. Set for current session: Sys.setenv(GITHUB_PAT = "your_token_here")

4. Or add to .Renviron: GITHUB_PAT='your_token_here' and restart R

Examples

## Not run: 
library(OmopStudyBuilder)
library(here)

# Authenticate (choose one method):
# 1. Set GITHUB_PAT for current session
Sys.setenv(GITHUB_PAT = "your_token_here")
# 2. Or use gh CLI: gh auth login

# Create repo under personal account
linkGitHub(
  directory = here::here(),
  repository = "my-omop-study"
)

# Create repo under organisation
linkGitHub(
  directory = here::here(),
  repository = "diabetes-study",
  organisation = "oxford-pharmacoepi",
  private = TRUE
)

## End(Not run)

---

Push a Docker image to Docker Hub

Description

Push a Docker image to Docker Hub

Usage

pushDockerImage(
  image_name = NULL,
  repo,
  tag = "latest",
  username = NULL,
  password = NULL,
  logout = TRUE
)

Arguments

image_name	Name of Docker image to push (default: auto-detected from directory)
repo	Docker Hub repository (e.g., "username/repo" or "repo")
tag	Tag to push (default: "latest")
username	Docker Hub username (prompted if NULL)
password	Docker Hub password or token (prompted if NULL, hidden input)
logout	If TRUE, logs out after pushing

Value

Pushed image reference (invisibly)

---

Review a study directory

Description

Summarises the code and/or renv dependencies in a study directory.

Usage

reviewStudy(dir, code = TRUE, dependencies = TRUE, type = "analysis")

Arguments

dir	Path to the study directory.
code	If 'TRUE', summarises R, JSON, CSV, and Excel files found in the directory.
dependencies	If 'TRUE', summarises the renv.lock dependencies.
type	Whether the R project is for analysis code or study reporting. Only used when 'dependencies = TRUE'.

Value

Invisibly returns 'NULL'. Called for its side effects of printing summaries to the console.

---

Run RStudio Server for interactive study execution

Description

Note: The Docker image must include RStudio Server (i.e., be built with 'dockeriseStudy(useRStudio = TRUE)' which uses a 'rocker/rstudio' base image).

Usage

runRStudio(
  image_name = NULL,
  results_path = "./results",
  env_file = NULL,
  port = 8787,
  password = NULL
)

Arguments

image_name	Name of Docker image to run (default: auto-detected from directory)
results_path	Path to save results (default: "./results")
env_file	Optional path to a .env file (passed to Docker via –env-file). If NULL and a '.env' file exists in the current working directory, it will be used automatically.
port	Port for RStudio Server (default: 8787, auto-finds next available if busy)
password	RStudio password (default: auto-generated and displayed)

Value

Container ID (invisibly)

---

Run study in automated mode with real-time log streaming

Description

Run study in automated mode with real-time log streaming

Usage

runStudy(
  image_name = NULL,
  results_path = "./results",
  env_file = NULL,
  data_path = NULL,
  script_path = "codeToRun.R"
)

Arguments

image_name	Name of Docker image to run (default: auto-detected from directory)
results_path	Path to save results (default: "./results")
env_file	Optional path to a .env file (passed to Docker via –env-file). If NULL and a '.env' file exists in the current working directory, it will be used automatically.
data_path	Optional path to data directory (mounted at /data)
script_path	Path to R script to execute (default: "codeToRun.R")

Value

Exit status (0 = success, non-zero = failure)

---

Stop a running OmopStudyBuilder container (automated or RStudio)

Description

Stops containers started by runStudy() and/or runRStudio(). By default it stops containers for the image inferred from the current directory name.

Usage

stopStudy(
  container = NULL,
  image_name = NULL,
  mode = c("any", "rstudio", "run"),
  all = FALSE
)

Arguments

container	Optional container name or ID to stop directly.
image_name	Optional Docker image name. Defaults to current directory name.
mode	Which container(s) to stop: "any" (default), "rstudio", or "run".
all	If TRUE, stops all running containers started by OmopStudyBuilder.

Value

TRUE if at least one container was stopped (invisibly)

---