initStudy

Introduction

initStudy() is the starting point for building a study project with the OMOP Common Data Model (CDM) using the OmopStudyBuilder package.

It generates a fully structured project folder containing:

• Templates for study diagnostics
• Templates for analysis code
• Shiny apps for diagnostics and reporting
• A project README
• A reproducible, opinionated layout aligned with OxInfer conventions

This allows you to immediately focus on writing study-specific code instead of manually assembling the surrounding infrastructure.

In this vignette you will learn how to:

• Create a new study project using initStudy()
• Explore the folder structure that is generated
• Control whether diagnostics and/or study analysis templates are included
• Understand next steps after project creation

Basic usage

The simplest way to use initStudy() is to provide a directory path. If the directory:

• Does not exist: it will be created
• Exists but is empty: it will be used
• Exists and contains files: an error will be thrown

To avoid modifying your real project directories, this vignette uses a temporary folder.

# Create a temporary root for this vignette
study_root <- file.path(tempdir(), "SampleStudy")

initStudy(study_root)

# Show top-level contents created by initStudy()
list.files(study_root)
#> [1] "INSTRUCTIONS.md"  "README.md"        "diagnosticsCode"  "diagnosticsShiny"
#> [5] "studyCode"        "studyShiny"

You should see something like:

• diagnosticsCode/ – diagnostic scripts and helpers
• diagnosticsShiny/ – skeleton diagnostics Shiny app
• studyCode/ – scripts for running the main analyses
• studyShiny/ – skeleton reporting Shiny app
• README.md – overview of the study project

To inspect the full structure:

list.files(study_root, recursive = TRUE)
#>  [1] "INSTRUCTIONS.md"                             
#>  [2] "README.md"                                   
#>  [3] "diagnosticsCode/README.md"                   
#>  [4] "diagnosticsCode/codeToRun.R"                 
#>  [5] "diagnosticsCode/cohorts/instantiateCohorts.R"
#>  [6] "diagnosticsCode/diagnosticsCode.Rproj"       
#>  [7] "diagnosticsCode/results/README.md"           
#>  [8] "diagnosticsCode/runStudy.R"                  
#>  [9] "diagnosticsShiny/README.md"                  
#> [10] "diagnosticsShiny/diagnosticsShiny.Rproj"     
#> [11] "studyCode/README.md"                         
#> [12] "studyCode/analyses/cohortCharacteristics.R"  
#> [13] "studyCode/analyses/cohortSurvival.R"         
#> [14] "studyCode/analyses/drugUtilisation.R"        
#> [15] "studyCode/analyses/incidencePrevalence.R"    
#> [16] "studyCode/codeToRun.R"                       
#> [17] "studyCode/codelist/codelistCreation.R"       
#> [18] "studyCode/cohorts/instantiateCohorts.R"      
#> [19] "studyCode/results/README.md"                 
#> [20] "studyCode/runStudy.R"                        
#> [21] "studyCode/studyCode.Rproj"                   
#> [22] "studyShiny/README.md"                        
#> [23] "studyShiny/studyShiny.Rproj"

Diagnostics-only and study-only setups

You can control which parts of the template are created with the diagnostics and study arguments.

diag_root <- file.path(tempdir(), "DiagnosticsOnly")

initStudy(
  directory   = diag_root,
  diagnostics = TRUE,
  study       = FALSE
)

list.files(diag_root)
#> [1] "INSTRUCTIONS.md"  "README.md"        "diagnosticsCode"  "diagnosticsShiny"

study_only_root <- file.path(tempdir(), "StudyOnly")

initStudy(
  directory   = study_only_root,
  diagnostics = FALSE,
  study       = TRUE
)

list.files(study_only_root)
#> [1] "INSTRUCTIONS.md" "README.md"       "studyCode"       "studyShiny"

What to do after initStudy()

After generating the project structure, you will mainly work with these folders and files:

• studyCode/
  • studyCode.Rproj: open this in RStudio to work on the main analysis code. It sets the working directory so all relative paths behave correctly.
    
  • codeToRun.R: where you add database connection details, schemas, and global settings
  • cohorts/instantiateCohorts.R: defines the study cohorts using your codelists and cohort-building functions. You customise this to match your phenotype definitions.
    
  • runStudy.R: orchestrates the analysis steps (cohort creation, summaries, analyses, export).
• diagnosticsCode/
  • diagnosticsCode.Rproj: open this project to work on diagnostics. It keeps diagnostics code separate from the main analysis project.
    
  • codeToRun.R: similar to the study version, but dedicated to diagnostics. You set connection details and schemas used for running phenotype diagnostics.
    
  • cohorts/instantiateCohorts.R: defines cohorts for diagnostic checking, often mirroring or simplifying the main study cohorts.
    
  • runStudy.R: runs the PhenotypeDiagnostics workflow and exports diagnostic results. You might tweak options, but the overall flow is usually left intact.
• studyShiny/
  • For a shiny app to explore study results. You extend this with plots, tables, and filters built on top of your exported outputs.
• diagnosticsShiny/
  • Contains a minimal Shiny app for exploring diagnostic outputs. Use it to review cohort characteristics and diagnostic results interactively across data partners.

Building and Distributing Your Study

Once your study code is ready, OmopStudyBuilder provides functions to package it into a Docker image and distribute it to data partners.

# Build a Docker image containing your study code
dockeriseStudy(
  image_name = "omop-study-study-code",
  path = file.path(study_root, "studyCode")
)
#> Building Docker image: omop-study-study-code
#> This may take some minutes on first build...
#> ✔ Image built successfully: omop-study-study-code

pushDockerImage(
  image_name = "omop-study-study-code",
  repo = "yourusername/myomopstudy"
)
#> ✔ Image pushed to Docker Hub!

library(OmopStudyBuilder)

# Interactive (requires image built with dockeriseStudy(useRStudio = TRUE)):
runRStudio(
  image_name = "yourusername/myomopstudy:latest",
  results_path = "./results"
)

# Requires image built with dockeriseStudy(useRStudio = TRUE)
runRStudio(
  image_name = "omop-study-study-code",
  results_path = "./results"
)

runStudy(
  image_name = "omop-study-study-code",
  results_path = "./results",
  data_path = "path/to/data"
)

stopStudy(image_name = "omop-study-study-code")