Help for package OmopStudyBuilder

Type:

Package

Title:

Build Reproducible Network Studies for OMOP Common Data Model

Version:

0.1.0

Description:

Streamlines the setup and execution of network studies using the Observational Medical Outcomes Partnership (OMOP) Common Data Model (CDM). Creates standardised project structures with template code, manages dependencies with 'renv', provides code review utilities, and supports containerised execution with 'Docker' for reproducible multi-site studies. Includes 'GitHub' integration for collaboration and version control.

License:

Apache License (≥ 2)

URL:

https://oxford-pharmacoepi.github.io/OmopStudyBuilder/

Depends:

R (≥ 4.1.0)

Imports:

cli, jsonlite, omopgenerics, rlang, whisker

Suggests:

dplyr, gert, getPass, gh, here, knitr, processx, purrr, renv, rmarkdown, scales, stringr, testthat

VignetteBuilder:

knitr

Encoding:

UTF-8

BugReports:

https://github.com/oxford-pharmacoepi/OmopStudyBuilder/issues

RoxygenNote:

7.3.3

NeedsCompilation:

Packaged:

2026-04-24 15:39:42 UTC; foluwa

Author:

Folu Akintola

[aut, cre], Edward Burn

[aut], Martí Català

[aut], Marta Alcalde-Herraiz

[ctb]

Maintainer:

Folu Akintola <folu.akintola@ndorms.ox.ac.uk>

Repository:

CRAN

Date/Publication:

2026-04-28 19:10:08 UTC

OmopStudyBuilder: Build Reproducible Network Studies for OMOP Common Data Model

Description

Author(s)

Maintainer: Folu Akintola folu.akintola@ndorms.ox.ac.uk (ORCID)

Authors:

Edward Burn edward.burn@ndorms.ox.ac.uk (ORCID)
Martí Català marti.catalasabate@ndorms.ox.ac.uk (ORCID)

Other contributors:

Marta Alcalde-Herraiz marta.alcaldeherraiz@ndorms.ox.ac.uk (ORCID) [contributor]

Auto-detect image name from current directory

Description

Auto-detect image name from current directory

Usage

autoDetectImageName(image_name = NULL)

Arguments

image_name

Existing image name (if provided)

Value

Image name (lowercased directory basename)

Build Docker labels for OmopStudyBuilder containers

Description

Build Docker labels for OmopStudyBuilder containers

Usage

buildDockerLabels(image_name, mode)

Arguments

image_name

Docker image name

mode

Execute a Docker command

Usage

dockerExec(args, error_message = "Docker command failed")

Arguments

args

Character vector of Docker command arguments

error_message

Custom error message if command fails

Value

Command output as character vector (returned invisibly to avoid console clutter)

Run a Docker query command and return cleaned output

Description

Run a Docker query command and return cleaned output

Usage

dockerQuery(args)

Arguments

args

Character vector of Docker command arguments

Value

Output lines, or empty if the command fails

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)

Check if Docker daemon is running

Description

Check if Docker daemon is running

Usage

ensureDocker()

Value

TRUE if Docker is available, throws error otherwise

Ensure Git identity is configured

Description

Checks if Git user.name and user.email are configured for commits. If not configured, automatically sets them using GitHub account info provided by the caller. This allows seamless Git operations without requiring manual 'git config' setup.

Usage

ensureGitIdentity(directory, user_info = NULL)

Find next available port starting from a given port

Description

Find next available port starting from a given port

Usage

findAvailablePort(start_port = 8787, max_tries = 10)

Arguments

start_port

Starting port number to check

max_tries

Maximum number of ports to try

Value

Available port number

Generate unique Docker container name

Description

Generate unique Docker container name

Usage

generateContainerName(base_name, suffix = NULL, max_tries = 100)

Arguments

base_name

Base name for container

suffix

Optional suffix (e.g., "-run")

max_tries

Maximum attempts to find unique name

Value

Unique container name

Create git commit

Description

Create git commit

Usage

gitCommit(
  directory,
  message,
  allow_nothing_to_commit = FALSE,
  error_message = "Failed to commit"
)

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)

Initialize local git repository

Description

Initialize local git repository

Usage

initializeGitRepo(directory)

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):

Visit https://github.com/settings/tokens
Generate a token with repo scope
Set for current session: Sys.setenv(GITHUB_PAT = "your_token_here")
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)

Process environment file argument

Description

Process environment file argument

Usage

processEnvFile(env_file, default_env_file = ".env")

Arguments

env_file

Path to .env file or NULL

default_env_file

Default env file path to use when env_file is NULL

Value

Character vector of Docker env-file arguments (empty if no file)

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)

Setup git remote and push

Description

Setup git remote and push

Usage

setupGitRemote(directory, clone_url, user_info = NULL, created_repo = FALSE)

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)

Validate repository name for GitHub

Description

Checks if a repository name follows GitHub naming rules. Throws an error with helpful suggestions if invalid.

Usage

validateRepoName(name)

Arguments

name

Repository name to validate

Value

TRUE if valid, throws error otherwise

Verify Docker image exists and provide helpful error

Description

Verify Docker image exists and provide helpful error

Usage

verifyImageExists(image_name, check_rstudio = FALSE)

Arguments

image_name

Name of Docker image

check_rstudio

If TRUE, also verify RStudio Server is present

Value

TRUE (invisibly) if checks pass, otherwise throws error

OmopStudyBuilder: Build Reproducible Network Studies for OMOP Common Data Model

Description

Author(s)

See Also

Auto-detect image name from current directory

Description

Usage

Arguments

Value

Build Docker labels for OmopStudyBuilder containers

Description

Usage

Arguments

Value

Check GitHub authentication

Description

Usage

Check if repository name is available

Description

Usage

Create GitHub repository via API

Description

Usage

Create .gitignore for OMOP studies

Description

Usage

Execute a Docker command

Description

Usage

Arguments

Value

Run a Docker query command and return cleaned output

Description

Usage

Arguments

Value

Build a Docker image for an OMOP study

Description

Usage

Arguments

Value

Check if Docker daemon is running

Description

Usage

Value

Ensure Git identity is configured

Description

Usage

Find next available port starting from a given port

Description

Usage

Arguments

Value

Generate unique Docker container name

Description

Usage

Arguments

Value

Create git commit

Description

Usage

Creates initial directory for an OMOP CDM network study

Description

Usage

Arguments

Value

Examples

Initialize local git repository

Description

Usage

Link study directory to GitHub repository

Description

Usage

Arguments

Value

Requirements

Authentication

Examples

Process environment file argument

Description