diff --git a/DESCRIPTION b/DESCRIPTION index 8174ef1..dc61c5b 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,6 +1,6 @@ Package: Ulysses Title: Automate OHDSI Study Setup -Version: 0.0.3 +Version: 0.0.4 Authors@R: person("Martin", "Lavallee", , "martin.lavallee@odysseusinc.com", role = c("aut", "cre")) Description: Automates setup of OHDSI study and provides functions to assist on improving organization diff --git a/NAMESPACE b/NAMESPACE index 45135b2..62ae95e 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -2,37 +2,54 @@ export("%>%") export(addConfig) +export(addDataSources) +export(addLinks) +export(addStudyMember) +export(addTags) export(buildStudyHub) export(checkConfig) export(checkDatabaseCredential) export(cohortManifest) export(defaultCredentials) +export(importCredentialsToConfig) +export(importImages) +export(initConfig) export(isOhdsiStudy) export(makeAnalysisPlan) export(makeAnalysisScript) export(makeCaprScript) export(makeCohortDetails) -export(makeConfig) export(makeContributionGuidelines) export(makeHowToRun) export(makeInternals) export(makeKeyringSetup) -export(makeMeetingMinutes) +export(makeMigrationScript) export(makeNews) -export(makeOhdsiProtocol) export(makeReadMe) export(makeResultsReport) -export(makeStudySettings) -export(makeTechSpecs) export(makeWebApiScript) export(moduleTable) export(newOhdsiStudy) export(previewStudyHub) export(publishStudyToRepository) -export(requestStudyRepository) +export(retrieveStudySettings) export(setCredential) export(setMultipleCredentials) +export(setStudyAuthors) +export(setStudyDescription) +export(setStudyInfo) export(setStudyKeyring) +export(setStudyLinks) +export(setStudyTags) +export(setStudyTimeline) +export(updateDeveloperInfo) +export(updateLeadInfo) +export(updateStudyDescription) +export(updateStudyEndDate) +export(updateStudyStatus) +export(updateStudyTitle) +export(updateStudyVersion) +export(updateTherapeuticArea) export(zipResults) import(fs) import(rlang) diff --git a/NEWS.md b/NEWS.md index 78af011..36f0c71 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,3 +1,15 @@ +Ulysses 0.0.4 +============= +* Finalize Directory +* Finalize meta fields for _study.yml +* Reconfigure `newOhdsiStudy()` with better meta inputs +* Add functions to interface with _study.yml +* Reroute makeFiles to directory and meta fields +* Add `makeMigrationsScript()` template +* Update study hub website format +* Update vignette + + Ulysses 0.0.3 ============= diff --git a/R/config.R b/R/config.R index d2e766b..46948c6 100644 --- a/R/config.R +++ b/R/config.R @@ -31,7 +31,7 @@ checkConfig <- function() { bullet = "warning", bullet_col = "yellow") txt <- glue::glue( - "`Ulysses::makeConfig(block = '[block_name]', database = '[database_name]')` " + "`Ulysses::initConfig()` " ) cli::cat_line("To create config.yml edit and run function:\n\n ", crayon::red(txt), "\n") cli::cat_line() @@ -40,6 +40,148 @@ checkConfig <- function() { } +#TODO keep this list up to date +knownDataSourceTable <- function() { + + dt <- tibble::tibble( + databaseName = c("Optum Clinformatics", "Optum Market Clarity", "Merative MarketScan", + "German DA", "CPRD Gold", "CPRD Aurum", "THIN Belgium", "JMDC", "MDV"), + blockId = c("optumClaims", "optumEHR", "mktscan", "da", "gold", "aurum", "thin", "jmdc", "mdv") + ) + return(dt) +} + + + +config_block_text <- function(block, database, title, dbms, user, + password, connectionString, cdmDatabaseSchema, resultsDatabaseSchema, + workDatabaseSchema, tempEmulationSchema, cohortTable) { + + txt <- glue::glue( + "\n\n# {title} Credentials\n +{block}: + databaseName: {database} + dbms: {dbms} + user: {user} + password: {password} + connectionString: {connectionString} + cdmDatabaseSchema: {cdmDatabaseSchema} + resultsDatabaseSchema: {resultsDatabaseSchema} + vocabDatabaseSchema: {cdmDatabaseSchema} + workDatabaseSchema: {workDatabaseSchema} + tempEmulationSchema: {tempEmulationSchema} + cohortTable: {cohortTable} + \n\n") + return(txt) +} +#' Function to import credentials in stored csv to study config.yml +#' @param credFile a credential.csv file stored in a secure location +#' @param projectPath the path to the project +#' @param open toggle on whether the file should be opened +#' @export +importCredentialsToConfig <- function(credFile, projectPath = here::here(), open = TRUE) { + + # import credentials + creds <- readr::read_csv(file = credFile, show_col_types = FALSE) + + # check _study.yml for loaded databases + studyMeta <- retrieveStudySettings(projectPath)$study + dataSources <- studyMeta$about$`data-sources` + + # subset creds with loaded Data Sources + dt <- creds %>% + dplyr::filter( + db_title %in% dataSources + ) + # make cred text for config file + config_txt <- purrr::pmap_chr( + dt, + ~config_block_text( + block = ..1, + database = ..2, + title = ..3, + dbms = ..4, + user = ..9, + password = ..10, + connectionString = ..5, + cdmDatabaseSchema = ..6, + resultsDatabaseSchema = ..8, + workDatabaseSchema = ..7, + tempEmulationSchema = ..7, + cohortTable = paste0("cohort_", ..1) + ) + ) + + header <- glue::glue(" # Config File for {studyMeta$title}\n +default: + projectName: {studyMeta$id} + ") + + full_txt <- c(header, config_txt) + readr::write_lines(full_txt, file = fs::path(projectPath, "config.yml")) + + cli::cat_bullet("Initializing config.yml using imported credentials", + bullet = "tick", bullet_col = "green") + + + if (open) { + + cli::cat_bullet("Check config.yml", + bullet = "bullet", bullet_col = "red") + + rstudioapi::navigateToFile(file = fs::path(projectPath, "config.yml")) + } + + invisible(full_txt) + +} + + +#' Function to create a config.yml file +#' @param block the name of the config block, defaults to BlockName +#' @param database the name of the database for the block, default to DatabaseName +#' @param withKeyring should the config file use keyring, default FALSE +#' @param projectPath the path to the project +#' @param open toggle on whether the file should be opened +#' @export +initConfig <- function(block = "BlockName", + database = "DatabaseName", + withKeyring = FALSE, + projectPath = here::here(), + open = TRUE) { + + # retrieve study meta + studyMeta <- retrieveStudySettings(projectPath = projectPath)$study + + + data <- rlang::list2( + 'Title' = studyMeta$title, + 'ID' = studyMeta$id, + 'Cohort' = paste(studyMeta$id, database, sep = "_"), + 'Block' = block, + 'Database' = database + ) + + if (withKeyring) { + template_file <- "config_keyring.yml" + } else { + template_file <- "config_raw.yml" + } + + usethis::use_template( + template = template_file, + save_as = fs::path("config.yml"), + data = data, + open = open, + package = "Ulysses") + + usethis::use_git_ignore(ignores = "config.yml") + + invisible(data) +} + + + #' Add a line to the config file #' @param block the name of the config block #' @param database the name of the database for the block, default to block name diff --git a/R/makeFiles.R b/R/makeFiles.R index 8a9b0cc..3b9ecd1 100644 --- a/R/makeFiles.R +++ b/R/makeFiles.R @@ -8,23 +8,30 @@ makeReadMe <- function(projectPath = here::here(), open = TRUE) { # retrieve study meta - studyMeta <- retrieveStudySettings(projectPath = projectPath) + studyMeta <- retrieveStudySettings(projectPath = projectPath)$study + + #prep author info as single line name(email) + leadAuthor <- glue::glue("{studyMeta$authors$lead$name} ({studyMeta$authors$lead$email})") + developerAuthor <- glue::glue("{studyMeta$authors$developer$name} ({studyMeta$authors$developer$email})") + + # prep data sources + dataSources <- paste(studyMeta$about$`data-sources`, collapse = ", ") + + # prep tags + tags <- paste(studyMeta$tags, collapse = ", ") - #create template vars data <- rlang::list2( - 'Project' = studyMeta$Title, - 'StudyType' = studyMeta$Description$StudyType, - 'Contact' = studyMeta$Contact$Name, - 'ContactEmail' = studyMeta$Contact$Email, - 'CdmVersion' = studyMeta$CDM$CdmVersion, - 'VocabVersion' = studyMeta$CDM$VocabVersion, - 'VocabRelease' = studyMeta$CDM$VocabRelease, - 'StudyStatus' = studyMeta$Milestones$Status, - 'ForumPost' = studyMeta$Links$Forum, - 'Protocol' = studyMeta$Links$Protocol, - 'Hub' = studyMeta$Links$StudyHub, - 'Dashboard' = studyMeta$Links$ResultsDashboard, - 'Report' = studyMeta$Links$Report + 'Title' = studyMeta$title, + 'ID' = studyMeta$id, + 'Type' = studyMeta$type, + 'Start' = studyMeta$timeline$`start-date`, + 'End' = studyMeta$timeline$`end-date`, + 'Lead' = leadAuthor, + 'Developer' = developerAuthor, + 'Tags' = tags, + 'TA' = studyMeta$about$`therapeutic-area`, + 'Description' = studyMeta$about$description, + 'DS' = dataSources ) #load template with vars @@ -45,10 +52,11 @@ makeReadMe <- function(projectPath = here::here(), open = TRUE) { makeNews <- function(projectPath = here::here(), open = TRUE) { # retrieve study meta - studyMeta <- retrieveStudySettings(projectPath = projectPath) + studyMeta <- retrieveStudySettings(projectPath = projectPath)$study data <- rlang::list2( - 'Project' = studyMeta$Title + 'ID' = studyMeta$id, + 'Version' = studyMeta$version ) usethis::use_template( @@ -61,40 +69,15 @@ makeNews <- function(projectPath = here::here(), open = TRUE) { } -#' Function to create a config.yml file -#' @param block the name of the config block -#' @param database the name of the database for the block, default to block name -#' @param projectPath the path to the project -#' @param open toggle on whether the file should be opened -#' @export -makeConfig <- function(block, database = block, projectPath = here::here(), open = TRUE) { - - projFile <- list.files(projectPath, pattern = ".Rproj", full.names = TRUE) - projName <- basename(tools::file_path_sans_ext(projFile)) - - data <- rlang::list2( - 'Project' = projName, - 'Cohort' = paste(projName, database, sep = "_"), - 'Block' = block, - 'Database' = database - ) - usethis::use_template( - template = "config.yml", - data = data, - open = open, - package = "Ulysses") - usethis::use_git_ignore(ignores = "config.yml") +# Documentation Files ----------------------- - invisible(data) +replaceTitleColon <- function(title){ + gsub("\\:", "-", title) } - - -# Documentation Files ----------------------- - #' Function to create a SAP #' @param projectPath the path to the project #' @param open toggle on whether the file should be opened @@ -103,17 +86,18 @@ makeAnalysisPlan <- function(projectPath = here::here(), open = TRUE) { # retrieve study meta - studyMeta <- retrieveStudySettings(projectPath = projectPath) + studyMeta <- retrieveStudySettings(projectPath = projectPath)$study # make list of vars for template data <- rlang::list2( - 'Study' = studyMeta$Title + 'Title' = replaceTitleColon(studyMeta$title), + 'Developer' = studyMeta$authors$developer$name ) #create templated output usethis::use_template( template = "AnalysisPlan.qmd", - save_as = fs::path("documentation", "AnalysisPlan.qmd"), + save_as = fs::path("documentation/hub", "AnalysisPlan.qmd"), data = data, open = open, package = "Ulysses") @@ -131,16 +115,16 @@ makeContributionGuidelines <- function(projectPath = here::here(), open = TRUE) { # retrieve study meta - studyMeta <- retrieveStudySettings(projectPath = projectPath) + studyMeta <- retrieveStudySettings(projectPath = projectPath)$study # make list of vars for template data <- rlang::list2( - 'Study' = studyMeta$Title + 'Title' = replaceTitleColon(studyMeta$title) ) usethis::use_template( template = "ContributionGuidelines.qmd", - save_as = fs::path("documentation", "ContributionGuidelines.qmd"), + save_as = fs::path("documentation/hub", "ContributionGuidelines.qmd"), data = data, open = open, package = "Ulysses") @@ -157,16 +141,17 @@ makeResultsReport <- function(projectPath = here::here(), open = TRUE) { # retrieve study meta - studyMeta <- retrieveStudySettings(projectPath = projectPath) + studyMeta <- retrieveStudySettings(projectPath = projectPath)$study # make list of vars for template data <- rlang::list2( - 'Study' = studyMeta$Title + 'Title' = replaceTitleColon(studyMeta$title), + 'Developer' = studyMeta$authors$developer$name ) usethis::use_template( template = "ResultsReport.qmd", - save_as = fs::path("documentation", "ResultsReport.qmd"), + save_as = fs::path("documentation/hub", "ResultsReport.qmd"), data = data, open = open, package = "Ulysses") @@ -185,17 +170,18 @@ makeHowToRun <- function(projectPath = here::here(), open = TRUE) { # retrieve study meta - studyMeta <- retrieveStudySettings(projectPath = projectPath) + studyMeta <- retrieveStudySettings(projectPath = projectPath)$study # make list of vars for template data <- rlang::list2( - 'Study' = studyMeta$Title + 'Title' = replaceTitleColon(studyMeta$title), + 'Developer' = studyMeta$authors$developer$name ) usethis::use_template( template = "HowToRun.qmd", - save_as = fs::path("documentation", "HowToRun.qmd"), + save_as = fs::path("documentation/hub", "HowToRun.qmd"), data = data, open = open, package = "Ulysses") @@ -204,67 +190,38 @@ makeHowToRun <- function(projectPath = here::here(), } -#' Function to create a HowToRun file -#' @param projectPath the path to the project -#' @param open toggle on whether the file should be opened -#' @export -makeTechSpecs <- function( - projectPath = here::here(), - open = TRUE) { - - # retrieve study meta - studyMeta <- retrieveStudySettings(projectPath = projectPath) - - # make list of vars for template - data <- rlang::list2( - 'Study' = studyMeta$Title - ) - - - usethis::use_template( - template = "TechSpecs.qmd", - save_as = fs::path("documentation", "TechSpecs.qmd"), - data = data, - open = open, - package = "Ulysses") - - invisible(data) -} # TODO update this to quarto -#' R Markdown file to make the ohdsi protocol -#' @param projectPath the path to the project -#' @param open toggle on whether the file should be opened -#' @export -makeOhdsiProtocol <- function(projectPath = here::here(), - open = TRUE) { - data <- rlang::list2( - 'Study' = getStudyDetails(item = "StudyTitle", projectPath = projectPath), - 'Date' = lubridate::today() - ) - - fileName <- snakecase::to_upper_camel_case(getStudyDetails(item = "StudyTitle", projectPath = projectPath)) %>% - paste0("Protocol") - - dir_path <- fs::path("documentation", "Protocol") %>% - fs::dir_create() - - usethis::use_template( - template = "OhdsiProtocol.Rmd", - save_as = fs::path(dir_path, fileName, ext = "Rmd"), - data = data, - open = open, - package = "Ulysses") - - #get Protocol Components and move to folder - fs::path_package("Ulysses", "templates/Protocol-Components") %>% - fs::dir_copy(new_path = dir_path, overwrite = TRUE) - - - invisible(data) -} +# makeOhdsiProtocol <- function(projectPath = here::here(), +# open = TRUE) { +# +# data <- rlang::list2( +# 'Study' = getStudyDetails(item = "StudyTitle", projectPath = projectPath), +# 'Date' = lubridate::today() +# ) +# +# fileName <- snakecase::to_upper_camel_case(getStudyDetails(item = "StudyTitle", projectPath = projectPath)) %>% +# paste0("Protocol") +# +# dir_path <- fs::path("documentation", "Protocol") %>% +# fs::dir_create() +# +# usethis::use_template( +# template = "OhdsiProtocol.Rmd", +# save_as = fs::path(dir_path, fileName, ext = "Rmd"), +# data = data, +# open = open, +# package = "Ulysses") +# +# #get Protocol Components and move to folder +# fs::path_package("Ulysses", "templates/Protocol-Components") %>% +# fs::dir_copy(new_path = dir_path, overwrite = TRUE) +# +# +# invisible(data) +# } @@ -320,97 +277,94 @@ makeKeyringSetup <- function(database = NULL, } -#' Email asking to initialize an ohdsi-studies repo -#' -#' @param senderName your name as the person sending the email -#' @param senderEmail your email address -#' @param githubUserName your github username. -#' @param recipientName the recipients name, defaults to Admin -#' @param recipientEmail the recipients email, defaults to a dummy email -#' @param projectPath the path to the Ulysses project -#' @param open toggle on whether the file should be opened -#' -#' @details -#' This function works best if you have properly setup a Github PAT. To configure the PAT -#' follow the \href{https://gh.r-lib.org/articles/managing-personal-access-tokens.html}{instructions} -#' from the gh package. -#' -#' -#' @export -requestStudyRepository <- function(senderName, - senderEmail, - githubUserName = NULL, - recipientName = NULL, - recipientEmail = NULL, - projectPath = here::here(), - open = TRUE) { - #get repo name - repoName <- basename(projectPath) %>% - snakecase::to_upper_camel_case() - - - if (is.null(recipientName)) { - recipientName <- "Admin" - } - - if (is.null(recipientEmail)) { - recipientEmail <- "adminEmail@ohdsi.org" - } - - - if (is.null(githubUserName)) { - githubUser <- getGithubUser() - } - - data <- rlang::list2( - 'RepoName' = repoName, - 'GithubUser' = githubUser, - 'SenderName' = senderName, - 'SenderEmail' = senderEmail, - 'RecipientName' = recipientName, - 'RecipientEmail' = recipientEmail - ) - - usethis::use_template( - template = "RequestRepositoryEmail.R", - save_as = fs::path("extras", "RequestRepositoryEmail.R"), - data = data, - open = open, - package = "Ulysses") - - - usethis::use_git_ignore(ignores = "extras/RequestRepositoryEmail.R") - - invisible(data) - -} - - -#' Function to create a meeting minutes file -#' @param projectPath the path to the project -#' @param open toggle on whether the file should be opened -#' @export -makeMeetingMinutes <- function(projectPath = here::here(), open = TRUE) { - - data <- rlang::list2( - 'Study' = getStudyDetails("StudyTitle", projectPath = projectPath), - 'Author' = getStudyDetails("StudyLead", projectPath = projectPath), - 'Date' = lubridate::today() - ) - - saveName <- glue::glue("minutes_{lubridate::today()}") %>% - snakecase::to_snake_case() - - usethis::use_template( - template = "MeetingMinutes.qmd", - save_as = fs::path("extras/minutes", saveName, ext = "qmd"), - data = data, - open = open, - package = "Ulysses") - - invisible(data) - -} +# Email asking to initialize an ohdsi-studies repo +# +# senderName your name as the person sending the email +# senderEmail your email address +# githubUserName your github username. +# recipientName the recipients name, defaults to Admin +# recipientEmail the recipients email, defaults to a dummy email +# projectPath the path to the Ulysses project +# open toggle on whether the file should be opened +# +# +# This function works best if you have properly setup a Github PAT. To configure the PAT +# follow the \href{https://gh.r-lib.org/articles/managing-personal-access-tokens.html}{instructions} +# from the gh package. +# + + +# requestStudyRepository <- function(senderName, +# senderEmail, +# githubUserName = NULL, +# recipientName = NULL, +# recipientEmail = NULL, +# projectPath = here::here(), +# open = TRUE) { +# #get repo name +# repoName <- basename(projectPath) %>% +# snakecase::to_upper_camel_case() +# +# +# if (is.null(recipientName)) { +# recipientName <- "Admin" +# } +# +# if (is.null(recipientEmail)) { +# recipientEmail <- "adminEmail@ohdsi.org" +# } +# +# +# if (is.null(githubUserName)) { +# githubUser <- getGithubUser() +# } +# +# data <- rlang::list2( +# 'RepoName' = repoName, +# 'GithubUser' = githubUser, +# 'SenderName' = senderName, +# 'SenderEmail' = senderEmail, +# 'RecipientName' = recipientName, +# 'RecipientEmail' = recipientEmail +# ) +# +# usethis::use_template( +# template = "RequestRepositoryEmail.R", +# save_as = fs::path("extras", "RequestRepositoryEmail.R"), +# data = data, +# open = open, +# package = "Ulysses") +# +# +# usethis::use_git_ignore(ignores = "extras/RequestRepositoryEmail.R") +# +# invisible(data) +# +# } + + + +# makeMeetingMinutes <- function(projectPath = here::here(), open = TRUE) { +# +# data <- rlang::list2( +# 'Study' = getStudyDetails("StudyTitle", projectPath = projectPath), +# 'Author' = getStudyDetails("StudyLead", projectPath = projectPath), +# 'Date' = lubridate::today() +# ) +# +# saveName <- glue::glue("minutes_{lubridate::today()}") %>% +# snakecase::to_snake_case() +# +# usethis::use_template( +# template = "MeetingMinutes.qmd", +# save_as = fs::path("extras/minutes", saveName, ext = "qmd"), +# data = data, +# open = open, +# package = "Ulysses") +# +# invisible(data) +# +# } # Analysis Files --------------------- @@ -418,12 +372,12 @@ makeMeetingMinutes <- function(projectPath = here::here(), open = TRUE) { #' Function to create a pipeline task as an R file #' @param scriptName The name of the capr file that is being created #' @param configBlock the name of the config block to use for the script +#' @param date the date the script was built, default to today's date #' @param projectPath the path to the project #' @param open toggle on whether the file should be opened #' @export makeCaprScript <- function(scriptName, configBlock = NULL, - author = NULL, date = lubridate::today(), projectPath = here::here(), open = TRUE) { @@ -435,20 +389,12 @@ makeCaprScript <- function(scriptName, } # retrieve study meta - studyMeta <- Ulysses:::retrieveStudySettings(projectPath = projectPath) - - # specify author - if (is.null(author)) { - authorName <- studyMeta$Authors %>% - dplyr::slice(1) %>% - dplyr::pull(name) - } else{ - authorName <- author - } + studyMeta <- Ulysses:::retrieveStudySettings(projectPath = projectPath)$study + data <- rlang::list2( - 'Study' = studyMeta$Title, - 'Author' = authorName, + 'Title' = replaceTitleColon(studyMeta$title), + 'Author' = studyMeta$authors$developer$name, 'Date' = date, 'FileName' = intFileName ) @@ -457,7 +403,7 @@ makeCaprScript <- function(scriptName, usethis::use_template( template = "Capr.R", - save_as = fs::path("analysis/R", intFileName, ext = "R"), + save_as = fs::path("analysis/src", intFileName, ext = "R"), data = data, open = open, package = "Ulysses") @@ -510,12 +456,12 @@ makeWebApiScript <- function(keyringName = NULL, #' Function to create a pipeline task as a Rmd file #' @param scriptName The name of the analysis script #' @param configBlock the name of the config block to use for the script +#' @param date the date the script was built, default to today's date #' @param projectPath the path to the project #' @param open toggle on whether the file should be opened #' @export makeAnalysisScript <- function(scriptName, configBlock = NULL, - author = NULL, date = lubridate::today(), projectPath = here::here(), open = TRUE) { @@ -527,20 +473,12 @@ makeAnalysisScript <- function(scriptName, # retrieve study meta - studyMeta <- retrieveStudySettings(projectPath = projectPath) - - # specify author - if (is.null(author)) { - authorName <- studyMeta$Authors %>% - dplyr::slice(1) %>% - dplyr::pull(name) - } else{ - authorName <- author - } + studyMeta <- retrieveStudySettings(projectPath = projectPath)$study + data <- rlang::list2( - 'Study' = studyMeta$Title, - 'Author' = authorName, + 'Title' = replaceTitleColon(studyMeta$title), + 'Author' = studyMeta$authors$developer$name, 'Date' = date, 'FileName' = scriptName, 'Block' = configBlock @@ -559,36 +497,65 @@ makeAnalysisScript <- function(scriptName, } + + +#' Function to create a migration script +#' @param scriptName The name of the analysis script +#' @param date the date the script was built, default to today's date +#' @param projectPath the path to the project +#' @param open toggle on whether the file should be opened +#' @export +makeMigrationScript <- function(scriptName, + date = lubridate::today(), + projectPath = here::here(), + open = TRUE) { + + + + # retrieve study meta + studyMeta <- retrieveStudySettings(projectPath = projectPath)$study + migrationScriptName <- glue::glue("migrate_{scriptName}") + + + data <- rlang::list2( + 'Title' = replaceTitleColon(studyMeta$title), + 'Author' = studyMeta$authors$developer$name, + 'Date' = date, + 'FileName' = migrationScriptName + ) + + usethis::use_template( + template = "MigrationScript.R", + save_as = fs::path("analysis/migration", migrationScriptName, ext = "R"), + data = data, + open = open, + package = "Ulysses") + + invisible(data) + + +} + + #' Function to create a pipeline task as an R file #' @param internalsName The name of the internals file that is being created +#' @param date the date the script was built, default to today's date #' @param projectPath the path to the project -#' @param author the author of the R file, defaults to first author in _study.yml -#' @param date the date the file was initialized, defaults to today #' @param open toggle on whether the file should be opened #' @export makeInternals <- function(internalsName, - projectPath = here::here(), - author = NULL, date = lubridate::today(), + projectPath = here::here(), open = TRUE) { intFileName <- paste0("_", internalsName) # retrieve study meta - studyMeta <- retrieveStudySettings(projectPath = projectPath) - - # specify author - if (is.null(author)) { - authorName <- studyMeta$Authors %>% - dplyr::slice(1) %>% - dplyr::pull(name) - } else{ - authorName <- author - } + studyMeta <- retrieveStudySettings(projectPath = projectPath)$study + data <- rlang::list2( - 'Study' = studyMeta$Title, - 'Author' = authorName, + 'Author' = studyMeta$authors$developer$name, 'Date' = date, 'FileName' = intFileName ) @@ -596,7 +563,7 @@ makeInternals <- function(internalsName, usethis::use_template( template = "Internals.R", - save_as = fs::path("analysis/R", intFileName, ext = "R"), + save_as = fs::path("analysis/src", intFileName, ext = "R"), data = data, open = open, package = "Ulysses") diff --git a/R/ohdsiStudy.R b/R/ohdsiStudy.R index 6443af2..4855f35 100644 --- a/R/ohdsiStudy.R +++ b/R/ohdsiStudy.R @@ -1,17 +1,46 @@ #' Function that initializes a new ohdsi study project environment #' @param path the path where the project sits #' @param projectName the name of the project -#' @param studySettings a list of study settings +#' @param studyInfo a list object identifying the title, type and study version, +#' defaults to `setStudyInfo`, see documentation +#' @param authors a list object identifying the lead and developer authors names and emails, +#' defaults to `setStudyAuthors`, see documentation. +#' @param timeline a list object identifying the study status, start and end date, +#' defaults to `setStudyTimeline`, see documentation +#' @param about a list object identifying the study description, therapeutic area and databases, +#' defaults to `setStudyDescription`, see documentation +#' @param links a list object identifying the linked resources of the study, +#' defaults to `setStudyLinks`, see documentation +#' @param tags a list object identifying tags to the study, +#' defauls to `setStudyTags`, see documentation #' @param verbose whether the function should provide steps, default TRUE #' @param openProject should the project be opened if created #' @import rlang usethis fs #' @export newOhdsiStudy <- function(path, projectName = basename(path), - studySettings = makeStudySettings(title = basename(path)), + studyInfo = setStudyInfo(id = basename(path)), + authors = setStudyAuthors(), + timeline = setStudyTimeline(), + about = setStudyDescription(), + links = setStudyLinks(), + tags = setStudyTags(), verbose = TRUE, openProject = TRUE) { + + # Step 0: Bind study meta + studyMeta <- studyInfo %>% + append(authors) %>% + append(timeline) %>% + append(about) %>% + append(links) %>% + append(tags) + + studyMeta2 <- list( + 'study' = studyMeta + ) + # Step 1: create project directory if (verbose) { cli::cat_bullet("Step 1: Creating R Project", @@ -33,12 +62,7 @@ newOhdsiStudy <- function(path, addDefaultFolders(projectPath = dir_path, verbose = verbose) # Step 3: create _study.yml file - convert_to_yml(studySettings = studySettings, savePath = dir_path) - # addStudyMeta(projectName = projectName, - # author = author, - # type = type, - # projectPath = dir_path, - # verbose = verbose) + convert_to_yml(studySettings = studyMeta2, savePath = dir_path) # Step 4: create gitignore @@ -70,7 +94,7 @@ isOhdsiStudy <- function(basePath) { check1 <- fs::file_exists("_study.yml") %>% unname() #check if has subfolders - folders <- c("analysis", "cohortsToCreate", "exec", "extras", "documentation") + folders <- c("analysis", "cohorts", "exec", "extras", "documentation") ff <- fs::dir_ls(basePath, type = "directory") %>% basename() @@ -100,14 +124,17 @@ addDefaultFolders <- function(projectPath, verbose = TRUE) { bullet_col = "yellow", bullet = "info") } - analysisFolders <- c("R", "tasks", "migrations") + analysisFolders <- c("src", "tasks", "migrations") execFolders <- c('logs', 'results', "export") + cohortFolders <- c("json", "sql") + documentationFolders <- c("hub", "misc") + folders <- c( - 'cohorts/json', + paste('cohorts', cohortFolders, sep = "/"), paste('analysis', analysisFolders, sep = "/"), paste('exec', execFolders, sep = "/"), - 'extras', - 'documentation' + paste('documentation', documentationFolders, sep = "/"), + 'extras' ) pp <- fs::path("./", folders) %>% @@ -118,36 +145,3 @@ addDefaultFolders <- function(projectPath, verbose = TRUE) { - -# addStudyMeta <- function(projectName, -# author, -# type = c("Characterization", "Population-Level Estimation", "Patient-Level Prediction"), -# projectPath, -# verbose = TRUE){ -# -# if (verbose) { -# cli::cat_bullet("Step 3: Adding _study.yml file", -# bullet_col = "yellow", bullet = "info") -# } -# -# -# -# # projName <- basename(projectPath) %>% -# # snakecase::to_title_case() -# date <- lubridate::today() -# -# data <- rlang::list2( -# 'Title' = projectName, -# 'Author' = author, -# 'Type' = type, -# 'Date' = date -# ) -# -# template_contents <- render_template("_study.yml", data = data) -# save_as <- fs::path(projectPath, "_study.yml") -# new <- write_utf8(save_as, template_contents) -# invisible(new) -# -# -# } - diff --git a/R/studySettings.R b/R/studySettings.R index cc805a1..de0b345 100644 --- a/R/studySettings.R +++ b/R/studySettings.R @@ -1,160 +1,125 @@ # Meta info ------------ -## Authors ----------- -setAuthors <- function(name, organization, role) { - tibble::tibble( - name = name, - organization = organization, - role = role +#' Function to set study info +#' @param id specify the study id +#' @param title specify the study title +#' @param type specify the type of study +#' @param version specify the study version +#' @return a list containing study info +#' @export +setStudyInfo <- function(id, + title = id, + type = c("Characterization"), + version = "0.0.0.999") { + ll <- list( + id = id, + title = title, + type = type, + version = version ) -} -defaultAuthors <- function() { - setAuthors( - name = c("Ulysses", "Eurylochus"), - organization = c("OHDSI", "OHDSI"), - role = c("Lead", "Developer") - ) -} + return(ll) -## Milestones ----------- -setMilestones <- function(status, startDate, endDate) { - list( - 'Status' = status, - 'StartDate' = startDate, - 'EndDate' = endDate - ) } -defaultMilestones <- function() { - setMilestones( - status = "Started", - startDate = "01-01-1960", - endDate = "31-12-2099" - ) -} +#' Function to set study authors +#' @param developer specify the study developer, default to system variable +#' @param developerEmail the email of the developer +#' @param lead specify the lead of the study +#' @param leadEmail specify the lead of the study email +#' @return a list containing study authors +#' @export +setStudyAuthors <- function(developer = Sys.getenv("USERNAME"), + developerEmail = glue::glue("{developer}@ohdsi.org"), + lead = "Ulysses", + leadEmail = "Ulysses@ohdsi.org") { -## Descriptions ----------- -setDescription <- function(studyType, tags) { - list( - 'StudyType' = studyType, - 'Tags' = as.list(tags) + ll <- list( + 'authors' = list( + 'developer' = list( + 'name' = developer, + 'email' = developerEmail + ), + 'lead' = list( + 'name' = lead, + 'email' = leadEmail + ) + ) ) -} -defaultDesc <- function() { - setDescription(studyType = "Characterization", - tags = c("Observational Study", "OMOP", "OHDSI")) -} + return(ll) -## Links ----------- -setLinks <- function(forumPostLink, - protocolLink, - studyHubLink, - resultsDashboardLink, - reportLink) { - list( - 'Forum' = forumPostLink, - 'Protocol' = protocolLink, - 'StudyHub' = studyHubLink, - 'ResultsDashboard' = resultsDashboardLink, - 'Report' = reportLink - ) } -defaultLinks <- function() { - setLinks( - forumPostLink = "TBA", - protocolLink = "TBA", - studyHubLink = "TBA", - resultsDashboardLink = "TBA", - reportLink = "TBA" +#' Function to set study timeline +#' @param status the study status, default is started +#' @param startDate the start of the study, defaults to todays date +#' @param endDate the date specifying the end (or expected end) of the study +#' @return a list containing study timeline +#' @export +setStudyTimeline <- function(status = "Started", + startDate = as.character(lubridate::today()), + endDate = as.character(lubridate::today() + (365 * 2))) { + + ll <- list( + 'timeline' = list( + 'status' = status, + 'start-date' = startDate, + 'end-date' = endDate + ) ) + + return(ll) + } -## Contact ----------- -setContact <- function(name, email) { - list( - 'Name' = name, - 'Email' = email +#' Function to set study description +#' @param desc a brief description of the study +#' @param ta a character string of the therapeutic area +#' @param dataSources a list of data sources +#' @return a list containing study description info +#' @export +setStudyDescription <- function(desc = "Provide a 1 to 2 sentence description of your study. Be concise.", + ta = "Specify the therapeutic area of the study", + dataSources = list("Truven MarketScan", "Optum Market Clarity")) { + + ll <- list( + 'about' = list( + 'description' = desc, + 'therapeutic-area' = ta, + 'data-sources' = dataSources + ) ) -} -defaultContact <- function() { - setContact(name = "Ulysses", email = "ulysses@ohdsi.org") + + return(ll) + } +#' Function to set study links +#' @param ... a series of resource links for the study +#' @return a list containing links to resources +#' @export +setStudyLinks <- function(...) { -## Cdm ----------- -setCdmDetails <- function(cdmVersion, vocabVersion, vocabRelease) { - list( - 'CdmVersion' = cdmVersion, - 'VocabVersion' = vocabVersion, - 'VocabRelease' = vocabRelease + ll <- list( + 'links' = rlang::list2(...) ) + + return(ll) + } -defaultCdmDetails <- function() { - setCdmDetails( - cdmVersion = "v5.3", - vocabVersion = "v5.0", - vocabRelease = "22-06-2022") -} - - -## Data ----------- -# setDataSources <- function(databaseName, location, type, persons, timeFrame) { -# tibble::tibble( -# databaseName = databaseName, -# location = location, -# type = type, -# persons = persons, -# timeFrame -# ) -# } -# -# defaultDataSources <- function() { -# setDataSources( -# databaseName = c("CMS Synpuf"), -# location = c("US"), -# type = c("Claims"), -# persons = c("110K"), -# timeFrame = c("2008-2010") -# ) -# } - -#' Function to initialize study settings -#' @param title the title of the study -#' @param authors the author list for the study -#' @param milestones list of milestone information including study status and timeframe for study -#' @param cdm list of info about the cdm -#' @param desc a list of attributes describing the study including the study type and tages -#' @param contact a list of contact information for study -#' @param links a list of links to files used in study -#' @return a list containing study settings -#' @export -makeStudySettings <- function(title, - authors = defaultAuthors(), - milestones = defaultMilestones(), - cdm = defaultCdmDetails(), - strategus = getLatestModules(), - desc = defaultDesc(), - contact = defaultContact(), - links = defaultLinks()) { - - - - - studySettings <- list( - 'Title' = snakecase::to_title_case(title), - 'Authors' = authors, - 'Description' = desc, - 'Milestones' = milestones, - 'CDM' = cdm, - 'Strategus' = strategus, - 'Links' = links, - 'Contact' = contact + +#' Function to set study tags +#' @param ... a series of tags for the study +#' @return a list containing study tags +#' @export +setStudyTags <- function(...) { + + ll <- list( + 'tags' = rlang::list2(...) ) - return(studySettings) + return(ll) } @@ -179,11 +144,308 @@ convert_to_yml <- function(studySettings, savePath) { } -#Function to convert yml into a specified list format +#' Function to convert yml into a specified list format +#' @param projectPath the path to the project +#' @return the study yml as an R object (list) +#' @export retrieveStudySettings <- function(projectPath){ ymlPath <- fs::path(projectPath, "_study.yml") studyYml <- yaml::read_yaml(ymlPath) - studyYml$Authors <- purrr::map_dfr(studyYml$Authors, ~.x) return(studyYml) } +getStudySettings <- function(projectPath, field) { + + studyYml <- retrieveStudySettings(projectPath = projectPath) + studyElement <- studyYml$study[[field]] + + return(studyElement) +} + +pushStudyUpdate <- function(newStudyYml, projectPath, update, value) { + + cli::cat_bullet( + "Updated _study.yml", + bullet = "tick", bullet_col = "green" + ) + + cli::cat_bullet( + glue::glue("Changed {update} to {crayon::green(value)}"), + bullet = "info", bullet_col = "blue" + ) + + #write _study.yml file + ymlPath <- fs::path(projectPath, "_study", ext = "yml") + yaml::write_yaml( + x = newStudyYml, + file = ymlPath, + column.major = FALSE) + + invisible(ymlPath) + +} + +pushStudyAdd <- function(newStudyYml, projectPath, update, value) { + + cli::cat_bullet( + "Updated _study.yml", + bullet = "tick", bullet_col = "green" + ) + + cli::cat_bullet( + glue::glue("Added {update}: {crayon::green(value)}"), + bullet = "info", bullet_col = "blue" + ) + + #write _study.yml file + ymlPath <- fs::path(projectPath, "_study", ext = "yml") + yaml::write_yaml( + x = newStudyYml, + file = ymlPath, + column.major = FALSE) + + invisible(ymlPath) + +} + +# Update Study settings functions ------------------------ + +#' Function to update study end date +#' @param newEndDate the new end date of the study, suggest format YYYY-MM-DD +#' @param projectPath the path to the project +#' @return invisible studyYml, prints specifying what changes happened +#' @export +updateStudyEndDate <- function(newEndDate, + projectPath = here::here()){ + + studyYml <- retrieveStudySettings(projectPath = projectPath) + studyYml$study$timeline$`end-date` <- as.character(newEndDate) + + pushStudyUpdate(studyYml, projectPath, update = "Study End Date", value = newEndDate) + + invisible(studyYml) + +} + +#' Function to update study status +#' @param newStudyStatus the new status of the study, accepts Started, In-Progress, Stopped, Completed +#' @param projectPath the path to the project +#' @return invisible studyYml, prints specifying what changes happened +#' @export +updateStudyStatus <- function(newStudyStatus = c("Started", "In-Progress", "Stopped", "Completed"), + projectPath = here::here()) { + + studyYml <- retrieveStudySettings(projectPath = projectPath) + studyYml$study$timeline$status <- newStudyStatus + + pushStudyUpdate(studyYml, projectPath, update = "Study Status", value = newStudyStatus) + + invisible(studyYml) + +} + +#' Function to update study title +#' @param newStudyTitle the new study title +#' @param projectPath the path to the project +#' @return invisible studyYml, prints specifying what changes happened +#' @export +updateStudyTitle <- function(newStudyTitle, + projectPath = here::here()) { + + studyYml <- retrieveStudySettings(projectPath = projectPath) + studyYml$study$title <- newStudyTitle + + pushStudyUpdate(studyYml, projectPath, update = "Study Title", value = newStudyTitle) + + invisible(studyYml) + +} + +#' Function to update study version +#' @param newStudyVersion the new study version +#' @param projectPath the path to the project +#' @return invisible studyYml, prints specifying what changes happened +#' @export +updateStudyVersion <- function(newStudyVersion, + projectPath = here::here()) { + + studyYml <- retrieveStudySettings(projectPath = projectPath) + studyYml$study$version <- newStudyVersion + + pushStudyUpdate(studyYml, projectPath, update = "Study Version", value = newStudyVersion) + + #TODO add cascade to add line to NEWS + + invisible(studyYml) + +} + +#' Function to update study description +#' @param newStudyVersion the new study description +#' @param projectPath the path to the project +#' @return invisible studyYml, prints specifying what changes happened +#' @export +updateStudyDescription <- function(newStudyDescription, + projectPath = here::here()) { + + studyYml <- retrieveStudySettings(projectPath = projectPath) + studyYml$study$about$description <- newStudyDescription + + pushStudyUpdate(studyYml, projectPath, update = "Study Description", value = newStudyDescription) + + invisible(studyYml) + +} + + +#' Function to update study therapeutic area +#' @param newTA the new study therapeutic area +#' @param projectPath the path to the project +#' @return invisible studyYml, prints specifying what changes happened +#' @export +updateTherapeuticArea <- function(newTA, + projectPath = here::here()) { + + studyYml <- retrieveStudySettings(projectPath = projectPath) + studyYml$study$about$`therapeutic-area` <- newTA + + pushStudyUpdate(studyYml, projectPath, update = "Therapeutic Area", value = newTA) + + invisible(studyYml) + +} + + +#' Function to update developer Infor +#' @param newName change the developer name +#' @param newEmail change the developer email +#' @return invisible studyYml, prints specifying what changes happened +#' @export +updateDeveloperInfo <- function(newName, + newEmail, + projectPath = here::here()) { + + studyYml <- retrieveStudySettings(projectPath = projectPath) + studyYml$study$authors$developer$name <- newName + studyYml$study$authors$developer$email <- newEmail + + + memberText <- glue::glue("name: {newName}, email: {newEmail}") %>% + paste(collapse = ", ") + + pushStudyUpdate(studyYml, projectPath, update = "Developer", value = memberText) + + invisible(studyYml) + +} + + +#' Function to update lead Infor +#' @param newName change the lead name +#' @param newEmail change the lead email +#' @return invisible studyYml, prints specifying what changes happened +#' @export +updateLeadInfo <- function(newName, + newEmail, + projectPath = here::here()) { + + studyYml <- retrieveStudySettings(projectPath = projectPath) + studyYml$study$authors$lead$name <- newName + studyYml$study$authors$lead$email <- newEmail + + + memberText <- glue::glue("name: {newName}, email: {newEmail}") %>% + paste(collapse = ", ") + + pushStudyUpdate(studyYml, projectPath, update = "Lead", value = memberText) + + invisible(studyYml) + +} + + +# Add to study settings Options ----------------------- +#' Function to add a study member +#' @param name the name of the study member +#' @param email the study member's email +#' @param projectPath the path to the project +#' @return invisible studyYml, prints specifying what changes happened +#' @export +addStudyMember <- function(name, email = NULL, + projectPath = here::here()) { + + + if (is.null(email)) { + email <- "author@email.com" + } + + + studyMember <- list( + 'member' = list( + name = name, + email = email + ) + ) + + + studyYml <- retrieveStudySettings(projectPath = projectPath) + studyYml$study$authors <- append(studyYml$study$authors, studyMember) + + memberText <- glue::glue("{names(studyMember[[1]])}: {studyMember[[1]]}") %>% + paste(collapse = ", ") + + pushStudyAdd(studyYml, projectPath, update = "Study Author", value = memberText) + invisible(studyYml) +} + +#' Function to add study tags +#' @param ... a list of study tags to add +#' @param projectPath the path to the project +#' @return invisible studyYml, prints specifying what changes happened +#' @export +addTags <- function(..., projectPath = here::here()) { + + tags <- list(...) + studyYml <- retrieveStudySettings(projectPath = projectPath) + studyYml$study$tags <- append(studyYml$study$tags, tags) + + tagsText <- paste(tags, collapse = ", ") + + pushStudyAdd(studyYml, projectPath, update = "Study Tags", value = tagsText) + invisible(studyYml) +} + +#' Function to add study data sources +#' @param ... a list of data sources to add +#' @param projectPath the path to the project +#' @return invisible studyYml, prints specifying what changes happened +#' @export +addDataSources <- function(..., projectPath = here::here()) { + + dataSources <- list(...) + studyYml <- retrieveStudySettings(projectPath = projectPath) + studyYml$study$about$`data-sources` <- append(studyYml$study$about$`data-sources`, dataSources) + + sdText <- paste(dataSources, collapse = ", ") + + pushStudyAdd(studyYml, projectPath, update = "Data Sources", value = sdText) + invisible(studyYml) +} + +#' Function to add study links +#' @param ... a list of links to add +#' @param projectPath the path to the project +#' @return invisible studyYml, prints specifying what changes happened +#' @export +addLinks <- function(..., projectPath = here::here()) { + + links <- rlang::list2(...) + studyYml <- retrieveStudySettings(projectPath = projectPath) + studyYml$study$links <- append(studyYml$study$links, links) + + linkText <- glue::glue("{names(links)}: {links}") %>% + paste(collapse = ", ") + + pushStudyAdd(studyYml, projectPath, update = "Links", value = linkText) + invisible(studyYml) +} diff --git a/R/website.R b/R/website.R index 974d568..a084969 100644 --- a/R/website.R +++ b/R/website.R @@ -2,7 +2,7 @@ checkWebsiteYml <- function(projectPath = here::here()) { #create yml path - ymlPath <- fs::path(projectPath, "documentation/_quarto.yml") + ymlPath <- fs::path(projectPath, "documentation/hub/_quarto.yml") check <- fs::file_exists(ymlPath) if (check) { cli::cat_bullet("_quarto.yml already exists for study hub", bullet = "pointer", bullet_col = "yellow") @@ -13,14 +13,35 @@ checkWebsiteYml <- function(projectPath = here::here()) { # Function to create quarto yml -makeWebsiteYaml <- function(projectPath = here::here()) { +makeWebsiteYaml <- function(footer = NULL, + logoPath = NULL, + backgroundColor = "#336B91", #OHDSI Blue + projectPath = here::here()) { # retrieve study meta - studyMeta <- retrieveStudySettings(projectPath = projectPath) + studyMeta <- retrieveStudySettings(projectPath = projectPath)$study + + if (is.null(footer)) { + footer <- "Produced using Ulysses Package" + } + + if (is.null(logoPath)) { + + logoPath <- fs::path_package("Ulysses", "images") + + importImages(imageFolder = logoPath, projectPath = here::here()) + + logo <- "images/ohdsi_logo.png" + + } + # make list of vars for template data <- rlang::list2( - 'Study' = studyMeta$Title + 'Title' = replaceTitleColon(studyMeta$title), + 'Footer' = footer, + 'Color' = backgroundColor, + 'Logo' = logo ) check <- checkWebsiteYml(projectPath = projectPath) @@ -28,7 +49,7 @@ makeWebsiteYaml <- function(projectPath = here::here()) { #build template usethis::use_template( template = "quartoWebsite.yml", - save_as = fs::path("documentation", "_quarto.yml"), + save_as = fs::path("documentation/hub", "_quarto.yml"), data = data, open = FALSE, package = "Ulysses") @@ -54,14 +75,14 @@ makeIndexQuarto <- function(projectPath = here::here()) { newReadMe <- lines[keepLines] #set path to documentation - docPath <- fs::path(projectPath, "documentation/index.qmd") + docPath <- fs::path(projectPath, "documentation/hub/index.qmd") #write new readme to index.qmd cli::cat_bullet("Convert README.md to index.qmd", bullet = "tick", bullet_col = "green") readr::write_lines(newReadMe, file = docPath) #ignore index.qmd as it is redundant to README.md - usethis::use_git_ignore(ignores = "documentation/index.qmd") + usethis::use_git_ignore(ignores = "documentation/hub/index.qmd") invisible(docPath) } @@ -74,14 +95,14 @@ makeNewsQuarto <- function(projectPath = here::here()) { lines <- readr::read_lines(readMePath) #set path to documentation - docPath <- fs::path(projectPath, "documentation/news.qmd") + docPath <- fs::path(projectPath, "documentation/hub/news.qmd") #write new readme to index.qmd cli::cat_bullet("Convert NEWS to news.qmd", bullet = "tick", bullet_col = "green") readr::write_lines(lines, file = docPath) #ignore index.qmd as it is redundant to README.md - usethis::use_git_ignore(ignores = "documentation/news.qmd") + usethis::use_git_ignore(ignores = "documentation/hub/news.qmd") invisible(docPath) } @@ -89,15 +110,14 @@ makeNewsQuarto <- function(projectPath = here::here()) { missingStandardDocs <- function(projectPath = here::here()) { # make path to documentation folder - docsPath <- fs::path(projectPath, "documentation") + docsPath <- fs::path(projectPath, "documentation/hub") # look up all qmd files resourceFiles <- fs::dir_ls(docsPath, glob = "*.qmd") %>% basename() %>% tools::file_path_sans_ext() - expectedFiles <- c("AnalysisPlan", "ContributionGuidelines", "HowToRun", - "ResultsReport", "TechSpecs") + expectedFiles <- c("AnalysisPlan", "ResultsReport") `%notin%` <- Negate("%in%") @@ -124,7 +144,7 @@ makeMissingDocs <- function(missingDocs, projectPath = here::here()) { previewStudyHub <- function(projectPath = here::here()) { # make index path and check that it exists - indexFilePath <- fs::path(projectPath, "documentation/_site/index.html") + indexFilePath <- fs::path(projectPath, "documentation/hub/_site/index.html") check <- fs::file_exists(indexFilePath) if (check ) { @@ -142,12 +162,25 @@ previewStudyHub <- function(projectPath = here::here()) { #' Function to build study hub #' @param projectPath path to ohdsi study +#' @param logoPath a path to a logo png to use in the quarto website, defaults to +#' ohdsi logo from Ulysses inst. +#' @param footer add a footer to the study Hub +#' @param backgroundColor change background color, defaults to OHDSI blue #336B91 #' @return builds a _site folder in documenation that holds the html website #' @export -buildStudyHub <- function(projectPath = here::here()) { +buildStudyHub <- function(projectPath = here::here(), + logoPath = NULL, + footer = NULL, + backgroundColor = "#336B91" #OHDSI Blue + ) { # Step 1: Make yml - makeWebsiteYaml(projectPath = projectPath) + makeWebsiteYaml( + footer = footer, + logoPath = logoPath, + backgroundColor = backgroundColor, + projectPath = projectPath + ) # step 2: check standard files for website missingDocs <- missingStandardDocs(projectPath = projectPath) @@ -162,7 +195,7 @@ buildStudyHub <- function(projectPath = here::here()) { makeNewsQuarto(projectPath = projectPath) # make doc path - docsPath <- fs::path(projectPath, "documentation") + docsPath <- fs::path(projectPath, "documentation/hub") # step 6: build study hub cli::cat_bullet("Build Study Hub", bullet = "tick", bullet_col = "green") @@ -175,3 +208,22 @@ buildStudyHub <- function(projectPath = here::here()) { invisible(docsPath) } + +#' Function to import a folder of images for a study hub +#' @param imageFolder the file path for an image folder +#' @param projectPath path to ohdsi study +#' @return invisible return of the image file folder +#' @export +importImages <- function(imageFolder, projectPath = here::here()) { + + newImageFolder <- fs::path(projectPath, "documentation/hub/images") %>% + fs::dir_create() + + + imageFiles <- fs::dir_copy( + path = imageFolder, + new_path = newImageFolder + ) + + invisible(imageFiles) +} diff --git a/README.md b/README.md index 3ce23be..ae16fa2 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,7 @@ Requires R (version 4.1 or higher) install.packages("remotes") remotes::install_github("ohdsi/Ulysses") ``` - +3. Install [quarto](https://quarto.org/docs/get-started/index.html) # User Documentation @@ -36,7 +36,6 @@ Documentation can be found on the [package website](https://ohdsi.github.io/Ulys PDF versions of the documentation are available: - Vignette: [Ulysses Intro](https://raw.githubusercontent.com/OHDSI/Ulysses/main/extras/pdf_vignette/start_study.pdf) -- Vignette: [Ulysses Directory](https://raw.githubusercontent.com/OHDSI/Ulysses/main/extras/pdf_vignette/ulysses_directory.pdf) - [Package manual](https://raw.githubusercontent.com/OHDSI/Ulysses/main/extras/Ulysses.pdf) # Support diff --git a/docs/404.html b/docs/404.html index 82c535a..b3f206d 100644 --- a/docs/404.html +++ b/docs/404.html @@ -39,7 +39,7 @@ Ulysses - 0.0.2 + 0.0.4 @@ -58,9 +58,6 @@
  • Creating a study using Ulysses
    • -
  • - Introduction to Ulysses Directory -
  • diff --git a/docs/LICENSE.html b/docs/LICENSE.html index 1cfce0d..a801a13 100644 --- a/docs/LICENSE.html +++ b/docs/LICENSE.html @@ -17,7 +17,7 @@ Ulysses - 0.0.2 + 0.0.4 @@ -34,9 +34,6 @@
  • Changelog @@ -120,19 +117,19 @@

    9. Accepting Warranty o

    APPENDIX: How to apply the Apache License to your work

    To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets [] replaced with your own identifying information. (Don’t include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same “printed page” as the copyright notice for easier identification within third-party archives.

    -
    Copyright [yyyy] [name of copyright owner]
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-  http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
    +
    Copyright [yyyy] [name of copyright owner]
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
    diff --git a/docs/articles/images/ulysses_directory.png b/docs/articles/images/ulysses_directory.png index 1ae4655..61a69c5 100644 Binary files a/docs/articles/images/ulysses_directory.png and b/docs/articles/images/ulysses_directory.png differ diff --git a/docs/articles/images/ulysses_meta.png b/docs/articles/images/ulysses_meta.png new file mode 100644 index 0000000..5de8d36 Binary files /dev/null and b/docs/articles/images/ulysses_meta.png differ diff --git a/docs/articles/images/ulysses_study_hub.png b/docs/articles/images/ulysses_study_hub.png new file mode 100644 index 0000000..65e07fa Binary files /dev/null and b/docs/articles/images/ulysses_study_hub.png differ diff --git a/docs/articles/index.html b/docs/articles/index.html index 6534453..0bbdc06 100644 --- a/docs/articles/index.html +++ b/docs/articles/index.html @@ -17,7 +17,7 @@ Ulysses - 0.0.2 + 0.0.4 @@ -34,9 +34,6 @@

  • Changelog @@ -62,8 +59,6 @@

    All vignettes

    Creating a study using Ulysses
    -
    Introduction to Ulysses Directory
    -
    diff --git a/docs/articles/start_study.html b/docs/articles/start_study.html index 4569294..47c8b3d 100644 --- a/docs/articles/start_study.html +++ b/docs/articles/start_study.html @@ -40,7 +40,7 @@ Ulysses - 0.0.2 + 0.0.4 @@ -59,9 +59,6 @@
  • Creating a study using Ulysses
    • -
  • - Introduction to Ulysses Directory -
  • @@ -146,68 +143,278 @@

    Initializing an OHDSI study in R 
    -Ulysses::newOhdsiStudy(
+newOhdsiStudy(
   path = here::here("my_ohdsi_study"),
-  author = "Ulysses S. Grant",
-  type = "Characterization",
-  directory = "[my_directory]",
-  open = TRUE
+  studyInfo = setStudyInfo(id = basename(here::here("my_ohdsi_study")),
+                           title = "My OHDSI Study"),
+  authors = setStudyAuthors(
+    developer = "John Smith",
+    developerEmail = "john.smith@ohdsi.org"
+  ),
+  about = setStudyDescription(
+    desc = "This is an OHDSI study for characterizing a population. This is an example.",
+    ta = "Cardiovascular",
+    dataSources = list("Synthea", "Synpuf")
+  ),
+  tags = setStudyTags("OHDSI", "OMOP")
 )

    This function will print some information to your console about start-up tasks and open an R project in a new session, for details on Rstudio projects see link.

    -

    In the new R session, we are directed to a clean R studio session. In -the files pane you will see a directory structure as depicted in the -image below. For more details about the directory structure refer to the -Introduction to Ulysses Directory vignette in this package. -Congratulations! You have started an OHDSI study!

    -
    -

    Ulysses Style OHDSI Study Directory

    -
    +

    The additional inputs of the newOhdsiStudy function +build meta data for the study repository that will be stored in a +_study.yml file. This meta data serves two purposes: 1) +provides human-readable information about the study and 2) serves as a +source of information to populate fields for templated files generated +using Ulysses. For example, if we were to generate a +README file using Ulysses it would be built +using this meta information.

    -

    Adding Repository Documentation +

    Ulysses Directory structure

    -
    -

    The README file -

    -

    With your new OHDSI study created, you need to begin adding -documentation for the repository. The first file we usually create is -the repository README. For those unfamiliar with code development, the -README file is a standard file used to introduce a describe the the -project. Think of the README as your cover page. It is the first file -users see when they navigate to the github page. All OHDSI projects -require a README file, thus Ulysses provides a function -(makeReadMe) that initializes it.

    -
    -Ulysses::makeReadMe()
    -

    The readme file is initailized using information found in the -_study.yml file. A typical OHDSI study readme has a section -of meta information as seen below:

    +

    In a new R session, users will notice a pre-populated directory +structure in their project folder. This directory structure contains +specific folders and files that are important for a study to be +self-contained within the new R project.

    +
    +Ulysses Directory Structure
    Ulysses Directory Structure
    +
    +

    Ulysses builds the following folders:

    +
    +

    +analysis +

    +

    The analysis folder contains files that correspond to study analysis. +There are three main folders created.

    • -Study Lead: Ulysses S. Grant
      • +src - contains the underlying functions that execute +the analysis. These files can be R scripts, sql files or python scripts, +for example. With Ulysses, users can generate templated +internal R files using the command makeInternals.
    • -Analytics Use Case: Characterization
      • +tasks - hold the executing scripts that generate the +results of the study. With Ulysses, we think of studies as +a series of tasks implemented in a specific order, like a pipeline. The +tasks folder organizes these individual tasks. With +Ulysses, users can generate templated internal R files +using the command makeAnalysisScript.
    • -Study Start Date: 04-27-1822
      • -
    • -Study End Date: 07-23-1885
      • +migrations - contain post-processing scripts to move +and prepare data from a series of results to a format that is +“presentation ready”. When conducting studies in OMOP, it is common to +run the same analysis on different databases. Migration scripts help +bind the results of all databases run in the study and format tables to +present in a quarto report or shiny app. With Ulysses, +users can generate templated internal R files using the command +makeMigrationScript. +
    +
    +
    +

    +cohorts +

    +

    The cohorts folder is meant to organize files that are used to +generate cohort definitions in the database. In an OHDSI study, cohort +definitions are specified in a json file format following +the specifications of circe-be. We +suggest placing cohorts used in the analysis in the cohort folder in +order for the study to be self-contained, meaning it does not rely on +ATLAS to execute. However, we highly recommend that +users maintain the organization of their cohorts in ATLAS as a source of +truth for both cohort definition and generation. The sql +folder is created to store sql files used to build cohort definitions. +This is a good location for cohort definitions that do not follow the +circe-be structure.

    +

    Keeping track of cohorts can be a bit tricky. Ulysses +provides a helper function to track json files in the cohorts folder +called cohortManifest. This function will list the name of +the json file and its corresponding id. By default, the cohort Id +assigned to the cohort json is in alphabetical order starting with 1. +Ulysses also creates a file called the +CohortDetails.qmd which prints the human-readable rendering +of the json expression using CirceR. +These functions are still in development as of +v0.0.4.

    +
    +
    +

    +documentation +

    +

    Study repositories should not only contain code, they should also +contain documentation about the design of the study and how to run the +study. Study repo’s should be self-contained, meaning we can go to one +location to get all code and human-readable documentation about the +study. Ulysses builds this into its repository structure +with a hub folder and a misc folder. The +hub folder contains files that are specific to the study +hub, an html website that provides all information about the study. The +misc folder is a place-holder to store word documents, +excel files, slide decks or other important documentation needed for the +study.

    +
    +
    Study Hub +
    +

    The study hub is a website that a user can generate through +Ulysses that provides information about the design of a +study and its results. The study hub is generated using +quarto. The study hub can be generated using the function +buildStudyHub. The study hub relies on the generation and +maintenance of 4 files: README.md, NEWS.md, AnalysisPlan.qmd and +ResultsReport.qmd.

    +
    +Ulysses Study Hub
    Ulysses Study Hub
    +
    +
    +
    +
    Suggested Files +
    +

    Ulysses has functions to initialize some suggested files +for a study:

    +
    • -Study Tags: None
      • +AnalysisPlan.qmd: the statistical analysis plan for the +study, which specifies the study design and analytical methods. This +file can be templated in Ulysses using the command +makeAnalysisPlan.
    • -Protocol: Unavailable
      • +ResultsReport.qmd: the report summarizing results from +the study following its execution. This file can be templated in +Ulysses using the command +makeResultsReport.
    • -Publications: Unavailable
      • +ContributionGuidelines.qmd: if the study is a network +studies, maintainers should provide resources on how others can +contribute to the study. Topics ranges from how to file issues, how to +send results to the study host, and how to collaborate in a positive +environment. This file can be templated in Ulysses using +the command makeContributionGuidelines.
    • -Results Explorer: Unavailable
      • +HowToRun.qmd: a document that explains how to execute +the study code to study nodes or interested parties. Should describe +technical requirements needed prior to running the study, local setup, +and execution. This file can be templated in Ulysses using +the command makeHowToRun.
    -

    Following the Meta section, the user will need to provide a -description of the study and information on the databases used in the -study. Finally, the README provides links to important study information -including the protocol, how to run and contributions files. Users can -add as much as they please to the README file, Ulysses -offers suggested guidance for starting it.

    +
    +
    +
    +

    +exec +

    +

    The exec folder is a location to store output files that +result from the study execution. This includes results and logs from the +study run and a folder to store post-processed data called +export. The exec folder is always ignored in +git.

    +
    +
    +

    +extras +

    +

    Sometimes studies have files that don’t have a natural location from +those specified above. The extras folder is a location to +store any additional files needed to run or support the execution of the +study. This is also a good location to store internal setup scripts, but +remember to ignore them in git.

    +
    +
    +
    +

    Additional Repository Files +

    +

    In addition to the pre-generated folders in the new study repository, +Ulysses also helps generate additional files that should be +in the repository. Some of these key files are described below.

    +
    +

    +_study.yml +

    +

    A file unique to directories initialized using Ulysses +is a metadata file called _study.yml. Using the inputs +specified in the newOhdsiStudy function, a metadata file is +populated. As mentioned this file store information about the study +directory and also uses it as inputs to templated files generated in +Ulysses. It is important to maintain this file during the +development of a study, whether that is to update default fields in the +yaml file or add information. Below is a snapshot of a +_study.yml file with the essential metadata fields.

    +
    +Ulysses MetaData
    Ulysses MetaData
    +
    +
    +
    Fields +
    +

    Below we describe the key fields in this file.

    +
      +
    • id: an identifier for the study which is the same as the directory +name. Use either a study id or acronym
      • +
    • title: a full title for the study, more thorough than the id. If no +title is provided, the input defaults to the id.
      • +
    • type: a keyword describing the type of study being conducted. Could +be a Characterization, Population-Level +Estimation, Patient-Level Prediction, or +Database Assessment, for example.
      • +
    • version: a value that represents the version of the study. Suggest +using semantic versioning logic.
      • +
    • authors: stores the name and email of the developer (person +in-charge of code development) and the lead (person in-charge of the +study). You may add other authors who are designated as +members +
      • +
    • timeline: a list of information relating to the development timeline +of the study. This includes the study start and end dates. The study +status is also listed here, where acceptable values are +Started, In-Progress, +Stopped and Completed.
      • +
    • about: a short description about the study, the therapeutic area it +covers and data sources used.
      • +
    • links: a listing of hyperlinks to guide people to key documentation +such as the analysis plan, report, dashboard and other resources.
      • +
    • tags: a list of keyword identifiers for the project
      • +
    +
    +
    +
    Maintenance +
    +

    Ulysses provides functions to maintain the +_study.yml file.

    + +
    +
    +
    +

    +README.md +

    +

    For those unfamiliar with code development, the +README file is a standard file used to introduce the +contents of a repository, like a cover-page. It is the first file users +see when they navigate to the repository page in your repository hosting +service (i.e. BitBucket or Github). Therefore a strong README file is +essential for a study. Ulysses provides the function +makeReadMe() which initializes the README using inputs from +the metadata stored in the _study.yml.

    Another feature offered by Ulysses is support for svg badges. These simple badges appear at the top of the README and provide useful information about the study. Badges seen in OHDSI studies include @@ -215,9 +422,10 @@

    The README file -

    The NEWS file -

    +
    +

    +NEWS.md +

    Another common file in software repositories is the NEWS file. The purpose of the NEWS file is to track changes to the software over time. Of course, version control software such as github keeps a record of the @@ -227,19 +435,18 @@

    The NEWS file
    -Ulysses::makeNews()

    +makeNews().

    -
    -
    -

    Handling database credentials -

    +
    +

    +config.yml +

    An important aspect of running an OHDSI study is handling credentials to connect to the Database Management System (DBMS) that hosts the OMOP data. Security of these credentials is very important. -Ulysses offers support on handling these credentials. -Credentials needed to run a study are as follows:

    +Ulysses offers support on handling these credentials +through the config.yml file. Credentials needed to run a +study are as follows:

    • dbms: the name of the dbms used to host the OMOP @@ -300,8 +507,8 @@

      Handling database credentials
      -Ulysses::makeConfig(block = "example", database = "synpuf_110k")

    +
    +Ulysses::makeConfig(block = "example", database = "synpuf_110k")

    When a user creates a new config.yml file it is added to .gitignore to ensure it is not committed to a github repository. The config file shows each credential connected to the block @@ -329,98 +536,9 @@

    Handling database credentials
    makeKeyringSetup(configBlock = "example", database = "synpuf_110k")

    -
    -

    Adding R scripts -

    -

    One way we can add analytical scripts to Ulysses is by -using the line below

    -
    -Ulysses::makeAnalysisScript(scriptName = "buildCohorts")
    -

    This function will create a new R script written to the folder -analysis/studyTasks. The R script will have a prefix of a -number indicating the order in which the script should be executed. The -first script for example will follow the syntax -01_. Ulysses will automatically -open this file to begin editing.

    -

    Each analytical task is formatted with the following sections:

    -
      -
    1. File Info -> includes information about the file
      2. -
    2. Dependencies -> a list of libraries, options and source files -required to run script
      3. -
    3. Connection -> set up connection to dbms
      4. -
    4. Variables -> set variables (parameters) needed for the -script
      5. -
    5. Script -> the script to run
      6. -
    6. Session Info -> a summary of the session info and clean up
      7. -
    -

    To complement the analysis scripts, we can also create internal -files. These are R files that contain functions or other code that needs -to be sourced in the analysis. These files are saved in the -analysis/private folder. Making an internal function can be -done by the following:

    -
    -Ulysses::makeInternals(internalsName = "buildCohorts")
    -

    The R package Strategus -helps execute OHDSI analytics. Analytical modules are executed via -Strategus. This paradigm to OHDSI studies can also be -handled by Ulysses. More support for using -Strategus with Ulysses will be explored in -future releases.

    -
    -
    -

    Adding Documenation -

    -

    An important part of a study repository is communicating its contents -to study nodes. A study node in a network study must understand the -scientific components of the study, how to run the study locally and how -to contribute towards the study. Ulysses provides functions -to help develop documentation to communicate the study to participants -in the OHDSI network.

    -
    -

    Analysis Specification -

    -

    A study requires a protocol or a study analysis plan (SAP), -specifying the scientific components of the study. These documents -specify the study design, definition of the target, exposure and outcome -cohorts and how the data analysis is conducted. This documentation is -important because it provides guidance and rationale for the study. Many -study nodes also require submission of documentation to an institutional -review board to justify execution of the study. Ulysses -provides templates for an OHDSI protocol, PASS protocols and a suggested -format for a SAP. Below are examples of building these templates:

    -
    -Ulysses::makeOhdsiProtocol()
-Ulysses::makePassProtocol()
-Ulysses::makeStudySAP()
    -
    -
    -

    How to Run -

    -

    Next, a repository needs to communicate how to run the study. This -document informs study nodes on technical requirements needed to run the -study, provides instructions on installations, and the process of -running the study. OHDSI studies are designed in several different ways, -so it is important that the developer explains how this study should be -run. Below is an example of how to create the howToRun.md -file:

    -
    -Ulysses::makeHowToRun(org = "Ohdsi", repo = "my_ohdsi_study")
    -
    -
    -

    Contributing -

    -

    Finally, the repository needs to communicate how study nodes can -contribute to the study. This include information on posting results, -asking for help and code of conduct. Contribution guidelines are -standard documentation of software and would be helpful additions to -OHDSI studies. To create a template contribution guideline follow the -example below:

    - -
    diff --git a/docs/authors.html b/docs/authors.html index b8a4924..3321b9c 100644 --- a/docs/authors.html +++ b/docs/authors.html @@ -17,7 +17,7 @@ Ulysses - 0.0.2 + 0.0.4 @@ -34,9 +34,6 @@

  • Changelog @@ -71,15 +68,15 @@

    Citation

    -

    Lavallee M (2023). +

    Lavallee M (2024). Ulysses: Automate OHDSI Study Setup. -R package version 0.0.2. +R package version 0.0.4. 

    @Manual{,
   title = {Ulysses: Automate OHDSI Study Setup},
   author = {Martin Lavallee},
-  year = {2023},
-  note = {R package version 0.0.2},
+  year = {2024},
+  note = {R package version 0.0.4},
 }
    diff --git a/docs/index.html b/docs/index.html index 2123b1f..7c90b42 100644 --- a/docs/index.html +++ b/docs/index.html @@ -41,7 +41,7 @@ Ulysses - 0.0.2 + 0.0.4 @@ -60,9 +60,6 @@
  • Creating a study using Ulysses
    • -
  • - Introduction to Ulysses Directory -
  • @@ -114,6 +111,10 @@

    Installation
     install.packages("remotes")
 remotes::install_github("ohdsi/Ulysses")
    +
      +
    1. Install quarto +
      2. +

    User Documentation @@ -123,8 +124,6 @@

    User DocumentationUlysses Intro

    • -
  • Vignette: Ulysses Directory -
  • Package manual
    • diff --git a/docs/news/index.html b/docs/news/index.html index 5b2cd1c..a1bfcc3 100644 --- a/docs/news/index.html +++ b/docs/news/index.html @@ -17,7 +17,7 @@ Ulysses - 0.0.2 + 0.0.4 @@ -34,9 +34,6 @@
  • Changelog @@ -57,6 +54,30 @@

    Changelog

    +
    +

    Ulysses 0.0.4

    +
    • Finalize Directory
      • +
    • Finalize meta fields for _study.yml
      • +
    • Reconfigure newOhdsiStudy() with better meta inputs
      • +
    • Add functions to interface with _study.yml
      • +
    • Reroute makeFiles to directory and meta fields
      • +
    • Add makeMigrationsScript() template
      • +
    • Update study hub website format
      • +
    • Update vignette
      • +
    +
    +

    Ulysses 0.0.3

    +
    • add study hub builder
      • +
    • convert all documents to qmd
      • +
    • add functions to define study settings prior to build
      • +
    • add cohort functions +
      • +cohortManifest lists cohorts used in study
        • +
      • +makeCohortDetails renders human-readable file to convey cohort definitions
        • +
      • add versioning to cohort definitions
        • +
      • +

    Ulysses 0.0.2

    • Add keyring functions and update SetupKeyring.R template
      • diff --git a/docs/pkgdown.yml b/docs/pkgdown.yml index 326e9df..e852c25 100644 --- a/docs/pkgdown.yml +++ b/docs/pkgdown.yml @@ -1,8 +1,7 @@ -pandoc: 2.19.2 +pandoc: 3.1.1 pkgdown: 2.0.7 pkgdown_sha: ~ articles: start_study: start_study.html - ulysses_directory: ulysses_directory.html -last_built: 2023-07-05T19:27Z +last_built: 2024-01-28T20:09Z diff --git a/docs/reference/Ulysses-package.html b/docs/reference/Ulysses-package.html index 620ac7a..0849465 100644 --- a/docs/reference/Ulysses-package.html +++ b/docs/reference/Ulysses-package.html @@ -18,7 +18,7 @@ Ulysses - 0.0.2 + 0.0.4
    @@ -35,9 +35,6 @@
  • Changelog diff --git a/docs/reference/addConfig.html b/docs/reference/addConfig.html index 73cc013..dda3eb7 100644 --- a/docs/reference/addConfig.html +++ b/docs/reference/addConfig.html @@ -17,7 +17,7 @@ Ulysses - 0.0.2 + 0.0.4 @@ -34,9 +34,6 @@
  • Changelog diff --git a/docs/reference/addDataSources.html b/docs/reference/addDataSources.html new file mode 100644 index 0000000..fcee1b5 --- /dev/null +++ b/docs/reference/addDataSources.html @@ -0,0 +1,106 @@ + +Function to add study data sources — addDataSources • Ulysses + + +
    +
    + + + +
    +
    +
    +

    Function to add study data sources

    + + +
    + +
    +

    Function to add study data sources

    +
    + +
    + 
    addDataSources(..., projectPath = here::here())
    +
    + +
    +

    Arguments

    +
    ...
    +

    a list of data sources to add

    + + +
    projectPath
    +

    the path to the project

    + +
    +
    +

    Value

    + + +

    invisible studyYml, prints specifying what changes happened

    +
    + +
    + +
    + + +
    +

    Developed by Martin Lavallee.

    +
    + +
    +

    Site built with pkgdown 2.0.7.

    +
    + +
    + + + + + + + + diff --git a/docs/reference/addLinks.html b/docs/reference/addLinks.html new file mode 100644 index 0000000..dd4077d --- /dev/null +++ b/docs/reference/addLinks.html @@ -0,0 +1,106 @@ + +Function to add study links — addLinks • Ulysses + + +
    +
    + + + +
    +
    +
    +

    Function to add study links

    + + +
    + +
    +

    Function to add study links

    +
    + +
    + 
    addLinks(..., projectPath = here::here())
    +
    + +
    +

    Arguments

    +
    ...
    +

    a list of links to add

    + + +
    projectPath
    +

    the path to the project

    + +
    +
    +

    Value

    + + +

    invisible studyYml, prints specifying what changes happened

    +
    + +
    + +
    + + +
    +

    Developed by Martin Lavallee.

    +
    + +
    +

    Site built with pkgdown 2.0.7.

    +
    + +
    + + + + + + + + diff --git a/docs/reference/addStudyMember.html b/docs/reference/addStudyMember.html new file mode 100644 index 0000000..ae853d4 --- /dev/null +++ b/docs/reference/addStudyMember.html @@ -0,0 +1,110 @@ + +Function to add a study member — addStudyMember • Ulysses + + +
    +
    + + + +
    +
    +
    +

    Function to add a study member

    + + +
    + +
    +

    Function to add a study member

    +
    + +
    + 
    addStudyMember(name, email = NULL, projectPath = here::here())
    +
    + +
    +

    Arguments

    +
    name
    +

    the name of the study member

    + + +
    email
    +

    the study member's email

    + + +
    projectPath
    +

    the path to the project

    + +
    +
    +

    Value

    + + +

    invisible studyYml, prints specifying what changes happened

    +
    + +
    + +
    + + +
    +

    Developed by Martin Lavallee.

    +
    + +
    +

    Site built with pkgdown 2.0.7.

    +
    + +
    + + + + + + + + diff --git a/docs/reference/addTags.html b/docs/reference/addTags.html new file mode 100644 index 0000000..e38f61b --- /dev/null +++ b/docs/reference/addTags.html @@ -0,0 +1,106 @@ + +Function to add study tags — addTags • Ulysses + + +
    +
    + + + +
    +
    +
    +

    Function to add study tags

    + + +
    + +
    +

    Function to add study tags

    +
    + +
    + 
    addTags(..., projectPath = here::here())
    +
    + +
    +

    Arguments

    +
    ...
    +

    a list of study tags to add

    + + +
    projectPath
    +

    the path to the project

    + +
    +
    +

    Value

    + + +

    invisible studyYml, prints specifying what changes happened

    +
    + +
    + +
    + + +
    +

    Developed by Martin Lavallee.

    +
    + +
    +

    Site built with pkgdown 2.0.7.

    +
    + +
    + + + + + + + + diff --git a/docs/reference/buildStudyHub.html b/docs/reference/buildStudyHub.html new file mode 100644 index 0000000..e6f224d --- /dev/null +++ b/docs/reference/buildStudyHub.html @@ -0,0 +1,120 @@ + +Function to build study hub — buildStudyHub • Ulysses + + +
    +
    + + + +
    +
    +
    +

    Function to build study hub

    + + +
    + +
    +

    Function to build study hub

    +
    + +
    + 
    buildStudyHub(
+  projectPath = here::here(),
+  logoPath = NULL,
+  footer = NULL,
+  backgroundColor = "#336B91"
+)
    +
    + +
    +

    Arguments

    +
    projectPath
    +

    path to ohdsi study

    + + +
    logoPath
    +

    a path to a logo png to use in the quarto website, defaults to +ohdsi logo from Ulysses inst.

    + + +
    footer
    +

    add a footer to the study Hub

    + + +
    backgroundColor
    +

    change background color, defaults to OHDSI blue #336B91

    + +
    +
    +

    Value

    + + +

    builds a _site folder in documenation that holds the html website

    +
    + +
    + +
    + + +
    +

    Developed by Martin Lavallee.

    +
    + +
    +

    Site built with pkgdown 2.0.7.

    +
    + +
    + + + + + + + + diff --git a/docs/reference/checkConfig.html b/docs/reference/checkConfig.html index e724556..cf26607 100644 --- a/docs/reference/checkConfig.html +++ b/docs/reference/checkConfig.html @@ -17,7 +17,7 @@ Ulysses - 0.0.2 + 0.0.4 @@ -34,9 +34,6 @@
  • Changelog diff --git a/docs/reference/checkDatabaseCredential.html b/docs/reference/checkDatabaseCredential.html index f02c34a..efd2340 100644 --- a/docs/reference/checkDatabaseCredential.html +++ b/docs/reference/checkDatabaseCredential.html @@ -17,7 +17,7 @@ Ulysses - 0.0.2 + 0.0.4 @@ -34,9 +34,6 @@
  • Changelog diff --git a/docs/reference/cohortManifest.html b/docs/reference/cohortManifest.html new file mode 100644 index 0000000..30cae44 --- /dev/null +++ b/docs/reference/cohortManifest.html @@ -0,0 +1,102 @@ + +Function that lists all cohort definitions loaded into the study — cohortManifest • Ulysses + + +
    +
    + + + +
    +
    +
    +

    Function that lists all cohort definitions loaded into the study

    + + +
    + +
    +

    Function that lists all cohort definitions loaded into the study

    +
    + +
    + 
    cohortManifest(projectPath = here::here())
    +
    + +
    +

    Arguments

    +
    projectPath
    +

    the path to the project

    + +
    +
    +

    Value

    + + +

    tibble of the cohorts in the project

    +
    + +
    + +
    + + +
    +

    Developed by Martin Lavallee.

    +
    + +
    +

    Site built with pkgdown 2.0.7.

    +
    + +
    + + + + + + + + diff --git a/docs/reference/defaultCredentials.html b/docs/reference/defaultCredentials.html index 29b1885..1b8c9de 100644 --- a/docs/reference/defaultCredentials.html +++ b/docs/reference/defaultCredentials.html @@ -18,7 +18,7 @@ Ulysses - 0.0.2 + 0.0.4 @@ -35,9 +35,6 @@
  • Changelog diff --git a/docs/reference/importCredentialsToConfig.html b/docs/reference/importCredentialsToConfig.html new file mode 100644 index 0000000..81525c5 --- /dev/null +++ b/docs/reference/importCredentialsToConfig.html @@ -0,0 +1,104 @@ + +Function to import credentials in stored csv to study config.yml — importCredentialsToConfig • Ulysses + + +
    +
    + + + +
    +
    +
    +

    Function to import credentials in stored csv to study config.yml

    + + +
    + +
    +

    Function to import credentials in stored csv to study config.yml

    +
    + +
    + 
    importCredentialsToConfig(credFile, projectPath = here::here(), open = TRUE)
    +
    + +
    +

    Arguments

    +
    credFile
    +

    a credential.csv file stored in a secure location

    + + +
    projectPath
    +

    the path to the project

    + + +
    open
    +

    toggle on whether the file should be opened

    + +
    + +
    + +
    + + +
    +

    Developed by Martin Lavallee.

    +
    + +
    +

    Site built with pkgdown 2.0.7.

    +
    + +
    + + + + + + + + diff --git a/docs/reference/importImages.html b/docs/reference/importImages.html new file mode 100644 index 0000000..d4a1b8a --- /dev/null +++ b/docs/reference/importImages.html @@ -0,0 +1,106 @@ + +Function to import a folder of images for a study hub — importImages • Ulysses + + +
    +
    + + + +
    +
    +
    +

    Function to import a folder of images for a study hub

    + + +
    + +
    +

    Function to import a folder of images for a study hub

    +
    + +
    + 
    importImages(imageFolder, projectPath = here::here())
    +
    + +
    +

    Arguments

    +
    imageFolder
    +

    the file path for an image folder

    + + +
    projectPath
    +

    path to ohdsi study

    + +
    +
    +

    Value

    + + +

    invisible return of the image file folder

    +
    + +
    + +
    + + +
    +

    Developed by Martin Lavallee.

    +
    + +
    +

    Site built with pkgdown 2.0.7.

    +
    + +
    + + + + + + + + diff --git a/docs/reference/index.html b/docs/reference/index.html index e6261f6..e155f81 100644 --- a/docs/reference/index.html +++ b/docs/reference/index.html @@ -17,7 +17,7 @@ Ulysses - 0.0.2 + 0.0.4 @@ -34,9 +34,6 @@
  • Changelog @@ -61,17 +58,29 @@

    All functions

    -

    addCohortFolder()

    - -

    Function to create a cohort folder in input/cohortsToCreate

    -

    addConfig()

    Add a line to the config file

    -

    addScratchFolder()

    +

    addDataSources()

    + +

    Function to add study data sources

    + +

    addLinks()

    + +

    Function to add study links

    + +

    addStudyMember()

    + +

    Function to add a study member

    + +

    addTags()

    -

    Function to create a scratch folder

    +

    Function to add study tags

    + +

    buildStudyHub()

    + +

    Function to build study hub

    checkConfig()

    @@ -80,14 +89,34 @@

    All functions checkDatabaseCredential()

    Function to check the database credential

    + +

    cohortManifest()

    + +

    Function that lists all cohort definitions loaded into the study

    defaultCredentials()

    Function to list default credentials

    + +

    importCredentialsToConfig()

    + +

    Function to import credentials in stored csv to study config.yml

    + +

    importImages()

    + +

    Function to import a folder of images for a study hub

    + +

    initConfig()

    + +

    Function to create a config.yml file

    isOhdsiStudy()

    -

    Function to check if the directory is a picard project

    +

    Function to check if the directory is an ohdsi project

    + +

    makeAnalysisPlan()

    + +

    Function to create a SAP

    makeAnalysisScript()

    @@ -99,23 +128,15 @@

    All functions

    makeCohortDetails()

    -

    Function to create a cohort details file

    - -

    makeConfig()

    - -

    Function to create a config.yml file

    +

    Function to create the cohort details for the study

    makeContributionGuidelines()

    R Markdown file to make the contribution guidelines

    - -

    makeExample()

    - -

    Function to create an example OHDSI script

    makeHowToRun()

    -

    Function to create a Synopsis file

    +

    Function to create a HowToRun file

    makeInternals()

    @@ -125,21 +146,13 @@

    All functions

    Function to create a config.yml file

    -

    makeMeetingMinutes()

    +

    makeMigrationScript()

    -

    Function to create a meeting minutes file

    +

    Function to create a migration script

    makeNews()

    Function to create a NEWS file

    - -

    makeOhdsiProtocol()

    - -

    R Markdown file to make the ohdsi protocol

    - -

    makePassProtocol()

    - -

    R Markdown file to make the pass protocol

    makeReadMe()

    @@ -148,26 +161,30 @@

    All functions makeResultsReport()

    Quarto file to make a results report

    - -

    makeStudySAP()

    - -

    Function to create a SAP

    makeWebApiScript()

    Function to create a pipeline task as an R file

    + +

    moduleTable()

    + +

    Function to retrieve table of modules

    newOhdsiStudy()

    Function that initializes a new ohdsi study project environment

    + +

    previewStudyHub()

    + +

    Function to preview study hub

    publishStudyToRepository()

    Publish Study to Repo

    -

    requestStudyRepository()

    +

    retrieveStudySettings()

    -

    Email asking to initialize an ohdsi-studies repo

    +

    Function to convert yml into a specified list format

    setCredential()

    @@ -176,10 +193,70 @@

    All functions setMultipleCredentials()

    Function to set multi credentials

    + +

    setStudyAuthors()

    + +

    Function to set study authors

    + +

    setStudyDescription()

    + +

    Function to set study description

    + +

    setStudyInfo()

    + +

    Function to set study info

    setStudyKeyring()

    Function to set study keyring

    + +

    setStudyLinks()

    + +

    Function to set study links

    + +

    setStudyTags()

    + +

    Function to set study tags

    + +

    setStudyTimeline()

    + +

    Function to set study timeline

    + +

    updateDeveloperInfo()

    + +

    Function to update developer Infor

    + +

    updateLeadInfo()

    + +

    Function to update lead Infor

    + +

    updateStudyDescription()

    + +

    Function to update study description

    + +

    updateStudyEndDate()

    + +

    Function to update study end date

    + +

    updateStudyStatus()

    + +

    Function to update study status

    + +

    updateStudyTitle()

    + +

    Function to update study title

    + +

    updateStudyVersion()

    + +

    Function to update study version

    + +

    updateTherapeuticArea()

    + +

    Function to update study therapeutic area

    + +

    zipResults()

    + +

    Funciton to compress results into a zip file

    @@ -34,9 +34,6 @@

  • Changelog @@ -53,13 +50,13 @@
    -

    Function to check if the directory is a picard project

    +

    Function to check if the directory is an ohdsi project

    -

    Function to check if the directory is a picard project

    +

    Function to check if the directory is an ohdsi project

    diff --git a/docs/reference/makeAnalysisPlan.html b/docs/reference/makeAnalysisPlan.html new file mode 100644 index 0000000..c55bd70 --- /dev/null +++ b/docs/reference/makeAnalysisPlan.html @@ -0,0 +1,100 @@ + +Function to create a SAP — makeAnalysisPlan • Ulysses + + +
    +
    + + + +
    +
    +
    +

    Function to create a SAP

    + + +
    + +
    +

    Function to create a SAP

    +
    + +
    + 
    makeAnalysisPlan(projectPath = here::here(), open = TRUE)
    +
    + +
    +

    Arguments

    +
    projectPath
    +

    the path to the project

    + + +
    open
    +

    toggle on whether the file should be opened

    + +
    + +
    + +
    + + +
    +

    Developed by Martin Lavallee.

    +
    + +
    +

    Site built with pkgdown 2.0.7.

    +
    + +
    + + + + + + + + diff --git a/docs/reference/makeAnalysisScript.html b/docs/reference/makeAnalysisScript.html index e06c24e..995a82a 100644 --- a/docs/reference/makeAnalysisScript.html +++ b/docs/reference/makeAnalysisScript.html @@ -17,7 +17,7 @@ Ulysses - 0.0.2 + 0.0.4
    @@ -34,9 +34,6 @@
  • Changelog @@ -66,6 +63,7 @@

    Function to create a pipeline task as a Rmd file

    makeAnalysisScript(
   scriptName,
   configBlock = NULL,
+  date = lubridate::today(),
   projectPath = here::here(),
   open = TRUE
 )
    @@ -81,6 +79,10 @@

    Arguments

    the name of the config block to use for the script

    +
    date
    +

    the date the script was built, default to today's date

    + +
    projectPath

    the path to the project

    diff --git a/docs/reference/makeCaprScript.html b/docs/reference/makeCaprScript.html index 98080b9..0d68b8e 100644 --- a/docs/reference/makeCaprScript.html +++ b/docs/reference/makeCaprScript.html @@ -17,7 +17,7 @@ Ulysses - 0.0.2 + 0.0.4 @@ -34,9 +34,6 @@
  • Changelog @@ -66,6 +63,7 @@

    Function to create a pipeline task as an R file

    makeCaprScript(
   scriptName,
   configBlock = NULL,
+  date = lubridate::today(),
   projectPath = here::here(),
   open = TRUE
 )
    @@ -81,6 +79,10 @@

    Arguments

    the name of the config block to use for the script

    +
    date
    +

    the date the script was built, default to today's date

    + +
    projectPath

    the path to the project

    diff --git a/docs/reference/makeCohortDetails.html b/docs/reference/makeCohortDetails.html index cb37756..0f761e4 100644 --- a/docs/reference/makeCohortDetails.html +++ b/docs/reference/makeCohortDetails.html @@ -1,5 +1,7 @@ -Function to create a cohort details file — makeCohortDetails • UlyssesFunction to create the cohort details for the study — makeCohortDetails • Ulysses @@ -17,7 +19,7 @@ Ulysses - 0.0.2 + 0.0.4 @@ -34,9 +36,6 @@
  • Changelog @@ -53,13 +52,15 @@
    -

    Function to create a cohort details file

    +

    Function to create the cohort details for the study

    -

    Function to create a cohort details file

    +

    The cohort details file is a document that provides a human-readable version +of the circe cohort definitions used in the study. This function targets +the cohortsToCreate folder and makes a quarto of the cohort details.

    @@ -76,6 +77,12 @@

    Arguments

    toggle on whether the file should be opened

    +
    +

    Value

    + + +

    writes a CohortDetails.qmd file to the documentation folder

    +
    @@ -34,9 +34,6 @@
  • Changelog diff --git a/docs/reference/makeHowToRun.html b/docs/reference/makeHowToRun.html index d9465d6..c0a4387 100644 --- a/docs/reference/makeHowToRun.html +++ b/docs/reference/makeHowToRun.html @@ -1,5 +1,5 @@ -Function to create a Synopsis file — makeHowToRun • UlyssesFunction to create a HowToRun file — makeHowToRun • Ulysses @@ -17,7 +17,7 @@ Ulysses - 0.0.2 + 0.0.4 @@ -34,9 +34,6 @@
  • Changelog @@ -53,31 +50,22 @@
    -

    Function to create a Synopsis file

    +

    Function to create a HowToRun file

    -

    Function to create a Synopsis file

    +

    Function to create a HowToRun file

    - 
    makeHowToRun(org = NULL, repo = NULL, projectPath = here::here(), open = TRUE)
    + 
    makeHowToRun(projectPath = here::here(), open = TRUE)

    Arguments

    -
    org
    -

    the name of the organization hosting the repo, for example 'ohdsi-studies'. -If null defaults to a dummy text

    - - -
    repo
    -

    the name of the study repository on github, defaults to the study title

    - - -
    projectPath
    +
    projectPath

    the path to the project

    diff --git a/docs/reference/makeInternals.html b/docs/reference/makeInternals.html index 3ae12d6..b042609 100644 --- a/docs/reference/makeInternals.html +++ b/docs/reference/makeInternals.html @@ -17,7 +17,7 @@ Ulysses - 0.0.2 + 0.0.4
    @@ -34,9 +34,6 @@
  • Changelog @@ -63,7 +60,12 @@

    Function to create a pipeline task as an R file

    - 
    makeInternals(internalsName, projectPath = here::here(), open = TRUE)
    + 
    makeInternals(
+  internalsName,
+  date = lubridate::today(),
+  projectPath = here::here(),
+  open = TRUE
+)
    @@ -72,6 +74,10 @@

    Arguments

    The name of the internals file that is being created

    +
    date
    +

    the date the script was built, default to today's date

    + +
    projectPath

    the path to the project

    diff --git a/docs/reference/makeKeyringSetup.html b/docs/reference/makeKeyringSetup.html index 2a023eb..8b86099 100644 --- a/docs/reference/makeKeyringSetup.html +++ b/docs/reference/makeKeyringSetup.html @@ -17,7 +17,7 @@ Ulysses - 0.0.2 + 0.0.4
    @@ -34,9 +34,6 @@
  • Changelog diff --git a/docs/reference/makeMigrationScript.html b/docs/reference/makeMigrationScript.html new file mode 100644 index 0000000..678dcc6 --- /dev/null +++ b/docs/reference/makeMigrationScript.html @@ -0,0 +1,113 @@ + +Function to create a migration script — makeMigrationScript • Ulysses + + +
    +
    + + + +
    +
    +
    +

    Function to create a migration script

    + + +
    + +
    +

    Function to create a migration script

    +
    + +
    + 
    makeMigrationScript(
+  scriptName,
+  date = lubridate::today(),
+  projectPath = here::here(),
+  open = TRUE
+)
    +
    + +
    +

    Arguments

    +
    scriptName
    +

    The name of the analysis script

    + + +
    date
    +

    the date the script was built, default to today's date

    + + +
    projectPath
    +

    the path to the project

    + + +
    open
    +

    toggle on whether the file should be opened

    + +
    + +
    + +
    + + +
    +

    Developed by Martin Lavallee.

    +
    + +
    +

    Site built with pkgdown 2.0.7.

    +
    + +
    + + + + + + + + diff --git a/docs/reference/makeNews.html b/docs/reference/makeNews.html index 6f30a9f..116c827 100644 --- a/docs/reference/makeNews.html +++ b/docs/reference/makeNews.html @@ -17,7 +17,7 @@ Ulysses - 0.0.2 + 0.0.4 @@ -34,9 +34,6 @@
  • Changelog diff --git a/docs/reference/makeReadMe.html b/docs/reference/makeReadMe.html index 675c10c..76dc4cb 100644 --- a/docs/reference/makeReadMe.html +++ b/docs/reference/makeReadMe.html @@ -17,7 +17,7 @@ Ulysses - 0.0.2 + 0.0.4 @@ -34,9 +34,6 @@
  • Changelog diff --git a/docs/reference/makeResultsReport.html b/docs/reference/makeResultsReport.html index b08f4c8..755be76 100644 --- a/docs/reference/makeResultsReport.html +++ b/docs/reference/makeResultsReport.html @@ -17,7 +17,7 @@ Ulysses - 0.0.2 + 0.0.4 @@ -34,9 +34,6 @@
  • Changelog diff --git a/docs/reference/makeWebApiScript.html b/docs/reference/makeWebApiScript.html index 24cb8c1..424b6a0 100644 --- a/docs/reference/makeWebApiScript.html +++ b/docs/reference/makeWebApiScript.html @@ -17,7 +17,7 @@ Ulysses - 0.0.2 + 0.0.4 @@ -34,9 +34,6 @@
  • Changelog diff --git a/docs/reference/moduleTable.html b/docs/reference/moduleTable.html new file mode 100644 index 0000000..c28a293 --- /dev/null +++ b/docs/reference/moduleTable.html @@ -0,0 +1,96 @@ + +Function to retrieve table of modules — moduleTable • Ulysses + + +
    +
    + + + +
    +
    +
    +

    Function to retrieve table of modules

    + + +
    + +
    +

    Function to retrieve table of modules

    +
    + +
    + 
    moduleTable(projectPath = here::here())
    +
    + +
    +

    Arguments

    +
    projectPath
    +

    the path to the project

    + +
    + +
    + +
    + + +
    +

    Developed by Martin Lavallee.

    +
    + +
    +

    Site built with pkgdown 2.0.7.

    +
    + +
    + + + + + + + + diff --git a/docs/reference/newOhdsiStudy.html b/docs/reference/newOhdsiStudy.html index cb22142..b706802 100644 --- a/docs/reference/newOhdsiStudy.html +++ b/docs/reference/newOhdsiStudy.html @@ -17,7 +17,7 @@ Ulysses - 0.0.2 + 0.0.4 @@ -34,9 +34,6 @@
  • Changelog @@ -66,8 +63,12 @@

    Function that initializes a new ohdsi study project environment

    newOhdsiStudy(
   path,
   projectName = basename(path),
-  author,
-  type,
+  studyInfo = setStudyInfo(id = basename(path)),
+  authors = setStudyAuthors(),
+  timeline = setStudyTimeline(),
+  about = setStudyDescription(),
+  links = setStudyLinks(),
+  tags = setStudyTags(),
   verbose = TRUE,
   openProject = TRUE
 )
    @@ -83,12 +84,34 @@

    Arguments

    the name of the project

    -
    author
    -

    the name of the study lead

    +
    studyInfo
    +

    a list object identifying the title, type and study version, +defaults to setStudyInfo, see documentation

    + + +
    authors
    +

    a list object identifying the lead and developer authors names and emails, +defaults to setStudyAuthors, see documentation.

    + + +
    timeline
    +

    a list object identifying the study status, start and end date, +defaults to setStudyTimeline, see documentation

    + + +
    about
    +

    a list object identifying the study description, therapeutic area and databases, +defaults to setStudyDescription, see documentation

    + + +
    links
    +

    a list object identifying the linked resources of the study, +defaults to setStudyLinks, see documentation

    -
    type
    -

    the type of study either Characterization, PLP or PLE

    +
    tags
    +

    a list object identifying tags to the study, +defauls to setStudyTags, see documentation

    verbose
    diff --git a/docs/reference/pipe.html b/docs/reference/pipe.html index b108ea0..9190073 100644 --- a/docs/reference/pipe.html +++ b/docs/reference/pipe.html @@ -17,7 +17,7 @@ Ulysses - 0.0.2 + 0.0.4 @@ -34,9 +34,6 @@
  • Changelog diff --git a/docs/reference/previewStudyHub.html b/docs/reference/previewStudyHub.html new file mode 100644 index 0000000..697a608 --- /dev/null +++ b/docs/reference/previewStudyHub.html @@ -0,0 +1,102 @@ + +Function to preview study hub — previewStudyHub • Ulysses + + +
    +
    + + + +
    +
    +
    +

    Function to preview study hub

    + + +
    + +
    +

    Function to preview study hub

    +
    + +
    + 
    previewStudyHub(projectPath = here::here())
    +
    + +
    +

    Arguments

    +
    projectPath
    +

    path to ohdsi study

    + +
    +
    +

    Value

    + + +

    previews study hub in browser

    +
    + +
    + +
    + + +
    +

    Developed by Martin Lavallee.

    +
    + +
    +

    Site built with pkgdown 2.0.7.

    +
    + +
    + + + + + + + + diff --git a/docs/reference/publishStudyToRepository.html b/docs/reference/publishStudyToRepository.html index 524af6a..07dd22d 100644 --- a/docs/reference/publishStudyToRepository.html +++ b/docs/reference/publishStudyToRepository.html @@ -17,7 +17,7 @@ Ulysses - 0.0.2 + 0.0.4 @@ -34,9 +34,6 @@
  • Changelog diff --git a/docs/reference/retrieveStudySettings.html b/docs/reference/retrieveStudySettings.html new file mode 100644 index 0000000..1f05abc --- /dev/null +++ b/docs/reference/retrieveStudySettings.html @@ -0,0 +1,102 @@ + +Function to convert yml into a specified list format — retrieveStudySettings • Ulysses + + +
    +
    + + + +
    +
    +
    +

    Function to convert yml into a specified list format

    + + +
    + +
    +

    Function to convert yml into a specified list format

    +
    + +
    + 
    retrieveStudySettings(projectPath)
    +
    + +
    +

    Arguments

    +
    projectPath
    +

    the path to the project

    + +
    +
    +

    Value

    + + +

    the study yml as an R object (list)

    +
    + +
    + +
    + + +
    +

    Developed by Martin Lavallee.

    +
    + +
    +

    Site built with pkgdown 2.0.7.

    +
    + +
    + + + + + + + + diff --git a/docs/reference/setCredential.html b/docs/reference/setCredential.html index e279502..9f362e7 100644 --- a/docs/reference/setCredential.html +++ b/docs/reference/setCredential.html @@ -17,7 +17,7 @@ Ulysses - 0.0.2 + 0.0.4 @@ -34,9 +34,6 @@
  • Changelog diff --git a/docs/reference/setMultipleCredentials.html b/docs/reference/setMultipleCredentials.html index 4abc58e..54a9762 100644 --- a/docs/reference/setMultipleCredentials.html +++ b/docs/reference/setMultipleCredentials.html @@ -17,7 +17,7 @@ Ulysses - 0.0.2 + 0.0.4 @@ -34,9 +34,6 @@
  • Changelog diff --git a/docs/reference/setStudyAuthors.html b/docs/reference/setStudyAuthors.html new file mode 100644 index 0000000..6a915e8 --- /dev/null +++ b/docs/reference/setStudyAuthors.html @@ -0,0 +1,119 @@ + +Function to set study authors — setStudyAuthors • Ulysses + + +
    +
    + + + +
    +
    +
    +

    Function to set study authors

    + + +
    + +
    +

    Function to set study authors

    +
    + +
    + 
    setStudyAuthors(
+  developer = Sys.getenv("USERNAME"),
+  developerEmail = glue::glue("{developer}@ohdsi.org"),
+  lead = "Ulysses",
+  leadEmail = "Ulysses@ohdsi.org"
+)
    +
    + +
    +

    Arguments

    +
    developer
    +

    specify the study developer, default to system variable

    + + +
    developerEmail
    +

    the email of the developer

    + + +
    lead
    +

    specify the lead of the study

    + + +
    leadEmail
    +

    specify the lead of the study email

    + +
    +
    +

    Value

    + + +

    a list containing study authors

    +
    + +
    + +
    + + +
    +

    Developed by Martin Lavallee.

    +
    + +
    +

    Site built with pkgdown 2.0.7.

    +
    + +
    + + + + + + + + diff --git a/docs/reference/setStudyDescription.html b/docs/reference/setStudyDescription.html new file mode 100644 index 0000000..9aa54e3 --- /dev/null +++ b/docs/reference/setStudyDescription.html @@ -0,0 +1,114 @@ + +Function to set study description — setStudyDescription • Ulysses + + +
    +
    + + + +
    +
    +
    +

    Function to set study description

    + + +
    + +
    +

    Function to set study description

    +
    + +
    + 
    setStudyDescription(
+  desc = "Provide a 1 to 2 sentence description of your study. Be concise.",
+  ta = "Specify the therapeutic area of the study",
+  dataSources = list("Truven MarketScan", "Optum Market Clarity")
+)
    +
    + +
    +

    Arguments

    +
    desc
    +

    a brief description of the study

    + + +
    ta
    +

    a character string of the therapeutic area

    + + +
    dataSources
    +

    a list of data sources

    + +
    +
    +

    Value

    + + +

    a list containing study description info

    +
    + +
    + +
    + + +
    +

    Developed by Martin Lavallee.

    +
    + +
    +

    Site built with pkgdown 2.0.7.

    +
    + +
    + + + + + + + + diff --git a/docs/reference/setStudyInfo.html b/docs/reference/setStudyInfo.html new file mode 100644 index 0000000..1cef441 --- /dev/null +++ b/docs/reference/setStudyInfo.html @@ -0,0 +1,119 @@ + +Function to set study info — setStudyInfo • Ulysses + + +
    +
    + + + +
    +
    +
    +

    Function to set study info

    + + +
    + +
    +

    Function to set study info

    +
    + +
    + 
    setStudyInfo(
+  id,
+  title = id,
+  type = c("Characterization"),
+  version = "0.0.0.999"
+)
    +
    + +
    +

    Arguments

    +
    id
    +

    specify the study id

    + + +
    title
    +

    specify the study title

    + + +
    type
    +

    specify the type of study

    + + +
    version
    +

    specify the study version

    + +
    +
    +

    Value

    + + +

    a list containing study info

    +
    + +
    + +
    + + +
    +

    Developed by Martin Lavallee.

    +
    + +
    +

    Site built with pkgdown 2.0.7.

    +
    + +
    + + + + + + + + diff --git a/docs/reference/setStudyKeyring.html b/docs/reference/setStudyKeyring.html index 209d654..14f826d 100644 --- a/docs/reference/setStudyKeyring.html +++ b/docs/reference/setStudyKeyring.html @@ -17,7 +17,7 @@ Ulysses - 0.0.2 + 0.0.4 @@ -34,9 +34,6 @@
  • Changelog diff --git a/docs/reference/setStudyLinks.html b/docs/reference/setStudyLinks.html new file mode 100644 index 0000000..65aa5a2 --- /dev/null +++ b/docs/reference/setStudyLinks.html @@ -0,0 +1,102 @@ + +Function to set study links — setStudyLinks • Ulysses + + +
    +
    + + + +
    +
    +
    +

    Function to set study links

    + + +
    + +
    +

    Function to set study links

    +
    + +
    + 
    setStudyLinks(...)
    +
    + +
    +

    Arguments

    +
    ...
    +

    a series of resource links for the study

    + +
    +
    +

    Value

    + + +

    a list containing links to resources

    +
    + +
    + +
    + + +
    +

    Developed by Martin Lavallee.

    +
    + +
    +

    Site built with pkgdown 2.0.7.

    +
    + +
    + + + + + + + + diff --git a/docs/reference/setStudyTags.html b/docs/reference/setStudyTags.html new file mode 100644 index 0000000..a6e9519 --- /dev/null +++ b/docs/reference/setStudyTags.html @@ -0,0 +1,102 @@ + +Function to set study tags — setStudyTags • Ulysses + + +
    +
    + + + +
    +
    +
    +

    Function to set study tags

    + + +
    + +
    +

    Function to set study tags

    +
    + +
    + 
    setStudyTags(...)
    +
    + +
    +

    Arguments

    +
    ...
    +

    a series of tags for the study

    + +
    +
    +

    Value

    + + +

    a list containing study tags

    +
    + +
    + +
    + + +
    +

    Developed by Martin Lavallee.

    +
    + +
    +

    Site built with pkgdown 2.0.7.

    +
    + +
    + + + + + + + + diff --git a/docs/reference/setStudyTimeline.html b/docs/reference/setStudyTimeline.html new file mode 100644 index 0000000..4314e38 --- /dev/null +++ b/docs/reference/setStudyTimeline.html @@ -0,0 +1,114 @@ + +Function to set study timeline — setStudyTimeline • Ulysses + + +
    +
    + + + +
    +
    +
    +

    Function to set study timeline

    + + +
    + +
    +

    Function to set study timeline

    +
    + +
    + 
    setStudyTimeline(
+  status = "Started",
+  startDate = as.character(lubridate::today()),
+  endDate = as.character(lubridate::today() + (365 * 2))
+)
    +
    + +
    +

    Arguments

    +
    status
    +

    the study status, default is started

    + + +
    startDate
    +

    the start of the study, defaults to todays date

    + + +
    endDate
    +

    the date specifying the end (or expected end) of the study

    + +
    +
    +

    Value

    + + +

    a list containing study timeline

    +
    + +
    + +
    + + +
    +

    Developed by Martin Lavallee.

    +
    + +
    +

    Site built with pkgdown 2.0.7.

    +
    + +
    + + + + + + + + diff --git a/docs/reference/updateDeveloperInfo.html b/docs/reference/updateDeveloperInfo.html new file mode 100644 index 0000000..15150f5 --- /dev/null +++ b/docs/reference/updateDeveloperInfo.html @@ -0,0 +1,106 @@ + +Function to update developer Infor — updateDeveloperInfo • Ulysses + + +
    +
    + + + +
    +
    +
    +

    Function to update developer Infor

    + + +
    + +
    +

    Function to update developer Infor

    +
    + +
    + 
    updateDeveloperInfo(newName, newEmail, projectPath = here::here())
    +
    + +
    +

    Arguments

    +
    newName
    +

    change the developer name

    + + +
    newEmail
    +

    change the developer email

    + +
    +
    +

    Value

    + + +

    invisible studyYml, prints specifying what changes happened

    +
    + +
    + +
    + + +
    +

    Developed by Martin Lavallee.

    +
    + +
    +

    Site built with pkgdown 2.0.7.

    +
    + +
    + + + + + + + + diff --git a/docs/reference/updateLeadInfo.html b/docs/reference/updateLeadInfo.html new file mode 100644 index 0000000..79b0921 --- /dev/null +++ b/docs/reference/updateLeadInfo.html @@ -0,0 +1,106 @@ + +Function to update lead Infor — updateLeadInfo • Ulysses + + +
    +
    + + + +
    +
    +
    +

    Function to update lead Infor

    + + +
    + +
    +

    Function to update lead Infor

    +
    + +
    + 
    updateLeadInfo(newName, newEmail, projectPath = here::here())
    +
    + +
    +

    Arguments

    +
    newName
    +

    change the lead name

    + + +
    newEmail
    +

    change the lead email

    + +
    +
    +

    Value

    + + +

    invisible studyYml, prints specifying what changes happened

    +
    + +
    + +
    + + +
    +

    Developed by Martin Lavallee.

    +
    + +
    +

    Site built with pkgdown 2.0.7.

    +
    + +
    + + + + + + + + diff --git a/docs/reference/updateStudyDescription.html b/docs/reference/updateStudyDescription.html new file mode 100644 index 0000000..0fda041 --- /dev/null +++ b/docs/reference/updateStudyDescription.html @@ -0,0 +1,106 @@ + +Function to update study description — updateStudyDescription • Ulysses + + +
    +
    + + + +
    +
    +
    +

    Function to update study description

    + + +
    + +
    +

    Function to update study description

    +
    + +
    + 
    updateStudyDescription(newStudyDescription, projectPath = here::here())
    +
    + +
    +

    Arguments

    +
    projectPath
    +

    the path to the project

    + + +
    newStudyVersion
    +

    the new study description

    + +
    +
    +

    Value

    + + +

    invisible studyYml, prints specifying what changes happened

    +
    + +
    + +
    + + +
    +

    Developed by Martin Lavallee.

    +
    + +
    +

    Site built with pkgdown 2.0.7.

    +
    + +
    + + + + + + + + diff --git a/docs/reference/updateStudyEndDate.html b/docs/reference/updateStudyEndDate.html new file mode 100644 index 0000000..5e44065 --- /dev/null +++ b/docs/reference/updateStudyEndDate.html @@ -0,0 +1,106 @@ + +Function to update study end date — updateStudyEndDate • Ulysses + + +
    +
    + + + +
    +
    +
    +

    Function to update study end date

    + + +
    + +
    +

    Function to update study end date

    +
    + +
    + 
    updateStudyEndDate(newEndDate, projectPath = here::here())
    +
    + +
    +

    Arguments

    +
    newEndDate
    +

    the new end date of the study, suggest format YYYY-MM-DD

    + + +
    projectPath
    +

    the path to the project

    + +
    +
    +

    Value

    + + +

    invisible studyYml, prints specifying what changes happened

    +
    + +
    + +
    + + +
    +

    Developed by Martin Lavallee.

    +
    + +
    +

    Site built with pkgdown 2.0.7.

    +
    + +
    + + + + + + + + diff --git a/docs/reference/updateStudyStatus.html b/docs/reference/updateStudyStatus.html new file mode 100644 index 0000000..30b8e9c --- /dev/null +++ b/docs/reference/updateStudyStatus.html @@ -0,0 +1,109 @@ + +Function to update study status — updateStudyStatus • Ulysses + + +
    +
    + + + +
    +
    +
    +

    Function to update study status

    + + +
    + +
    +

    Function to update study status

    +
    + +
    + 
    updateStudyStatus(
+  newStudyStatus = c("Started", "In-Progress", "Stopped", "Completed"),
+  projectPath = here::here()
+)
    +
    + +
    +

    Arguments

    +
    newStudyStatus
    +

    the new status of the study, accepts Started, In-Progress, Stopped, Completed

    + + +
    projectPath
    +

    the path to the project

    + +
    +
    +

    Value

    + + +

    invisible studyYml, prints specifying what changes happened

    +
    + +
    + +
    + + +
    +

    Developed by Martin Lavallee.

    +
    + +
    +

    Site built with pkgdown 2.0.7.

    +
    + +
    + + + + + + + + diff --git a/docs/reference/updateStudyTitle.html b/docs/reference/updateStudyTitle.html new file mode 100644 index 0000000..a5cfdfc --- /dev/null +++ b/docs/reference/updateStudyTitle.html @@ -0,0 +1,106 @@ + +Function to update study title — updateStudyTitle • Ulysses + + +
    +
    + + + +
    +
    +
    +

    Function to update study title

    + + +
    + +
    +

    Function to update study title

    +
    + +
    + 
    updateStudyTitle(newStudyTitle, projectPath = here::here())
    +
    + +
    +

    Arguments

    +
    newStudyTitle
    +

    the new study title

    + + +
    projectPath
    +

    the path to the project

    + +
    +
    +

    Value

    + + +

    invisible studyYml, prints specifying what changes happened

    +
    + +
    + +
    + + +
    +

    Developed by Martin Lavallee.

    +
    + +
    +

    Site built with pkgdown 2.0.7.

    +
    + +
    + + + + + + + + diff --git a/docs/reference/updateStudyVersion.html b/docs/reference/updateStudyVersion.html new file mode 100644 index 0000000..9f86b36 --- /dev/null +++ b/docs/reference/updateStudyVersion.html @@ -0,0 +1,106 @@ + +Function to update study version — updateStudyVersion • Ulysses + + +
    +
    + + + +
    +
    +
    +

    Function to update study version

    + + +
    + +
    +

    Function to update study version

    +
    + +
    + 
    updateStudyVersion(newStudyVersion, projectPath = here::here())
    +
    + +
    +

    Arguments

    +
    newStudyVersion
    +

    the new study version

    + + +
    projectPath
    +

    the path to the project

    + +
    +
    +

    Value

    + + +

    invisible studyYml, prints specifying what changes happened

    +
    + +
    + +
    + + +
    +

    Developed by Martin Lavallee.

    +
    + +
    +

    Site built with pkgdown 2.0.7.

    +
    + +
    + + + + + + + + diff --git a/docs/reference/updateTherapeuticArea.html b/docs/reference/updateTherapeuticArea.html new file mode 100644 index 0000000..c8b0adc --- /dev/null +++ b/docs/reference/updateTherapeuticArea.html @@ -0,0 +1,106 @@ + +Function to update study therapeutic area — updateTherapeuticArea • Ulysses + + +
    +
    + + + +
    +
    +
    +

    Function to update study therapeutic area

    + + +
    + +
    +

    Function to update study therapeutic area

    +
    + +
    + 
    updateTherapeuticArea(newTA, projectPath = here::here())
    +
    + +
    +

    Arguments

    +
    newTA
    +

    the new study therapeutic area

    + + +
    projectPath
    +

    the path to the project

    + +
    +
    +

    Value

    + + +

    invisible studyYml, prints specifying what changes happened

    +
    + +
    + +
    + + +
    +

    Developed by Martin Lavallee.

    +
    + +
    +

    Site built with pkgdown 2.0.7.

    +
    + +
    + + + + + + + + diff --git a/docs/reference/zipResults.html b/docs/reference/zipResults.html new file mode 100644 index 0000000..faad19a --- /dev/null +++ b/docs/reference/zipResults.html @@ -0,0 +1,100 @@ + +Funciton to compress results into a zip file — zipResults • Ulysses + + +
    +
    + + + +
    +
    +
    +

    Funciton to compress results into a zip file

    + + +
    + +
    +

    Funciton to compress results into a zip file

    +
    + +
    + 
    zipResults(databaseName, projectPath = here::here())
    +
    + +
    +

    Arguments

    +
    databaseName
    +

    the name of the database folder to compress

    + + +
    projectPath
    +

    the path to the project

    + +
    + +
    + +
    + + +
    +

    Developed by Martin Lavallee.

    +
    + +
    +

    Site built with pkgdown 2.0.7.

    +
    + +
    + + + + + + + + diff --git a/docs/sitemap.xml b/docs/sitemap.xml index 08620be..77d9a83 100644 --- a/docs/sitemap.xml +++ b/docs/sitemap.xml @@ -30,24 +30,54 @@ /reference/addConfig.html + + /reference/addDataSources.html + + + /reference/addLinks.html + /reference/addScratchFolder.html + + /reference/addStudyMember.html + + + /reference/addTags.html + + + /reference/buildStudyHub.html + /reference/checkConfig.html /reference/checkDatabaseCredential.html + + /reference/cohortManifest.html + /reference/defaultCredentials.html + + /reference/importCredentialsToConfig.html + + + /reference/importImages.html + /reference/index.html + + /reference/initConfig.html + /reference/isOhdsiStudy.html + + /reference/makeAnalysisPlan.html + /reference/makeAnalysisScript.html @@ -78,6 +108,9 @@ /reference/makeMeetingMinutes.html + + /reference/makeMigrationScript.html + /reference/makeNews.html @@ -99,12 +132,18 @@ /reference/makeWebApiScript.html + + /reference/moduleTable.html + /reference/newOhdsiStudy.html /reference/pipe.html + + /reference/previewStudyHub.html + /reference/publishStudyToRepository.html @@ -117,16 +156,64 @@ /reference/requestStudyRepository.html + + /reference/retrieveStudySettings.html + /reference/setCredential.html /reference/setMultipleCredentials.html + + /reference/setStudyAuthors.html + + + /reference/setStudyDescription.html + + + /reference/setStudyInfo.html + /reference/setStudyKeyring.html + + /reference/setStudyLinks.html + + + /reference/setStudyTags.html + + + /reference/setStudyTimeline.html + /reference/Ulysses-package.html + + /reference/updateDeveloperInfo.html + + + /reference/updateLeadInfo.html + + + /reference/updateStudyDescription.html + + + /reference/updateStudyEndDate.html + + + /reference/updateStudyStatus.html + + + /reference/updateStudyTitle.html + + + /reference/updateStudyVersion.html + + + /reference/updateTherapeuticArea.html + + + /reference/zipResults.html + diff --git a/extras/PackageMaintenance.R b/extras/PackageMaintenance.R index 3792ab8..00447a4 100644 --- a/extras/PackageMaintenance.R +++ b/extras/PackageMaintenance.R @@ -1,6 +1,6 @@ # @file PackageMaintenance # -# Copyright 2023 Observational Health Data Sciences and Informatics +# Copyright 2024 Observational Health Data Sciences and Informatics # # This file is part of Capr # @@ -43,13 +43,6 @@ rmarkdown::render("vignettes/start_study.Rmd", unlink("extras/pdf_vignette/start_study.tex") -### start study -rmarkdown::render("vignettes/ulysses_directory.Rmd", - output_file = "../extras/pdf_vignette/ulysses_directory.pdf", - - rmarkdown::pdf_document(latex_engine = "pdflatex", toc = TRUE, number_sections = TRUE)) -unlink("extras/pdf_vignette/ulysses_directory.tex") - # 4) build site ------------------------ pkgdown::build_site() OhdsiRTools::fixHadesLogo() diff --git a/extras/Ulysses.pdf b/extras/Ulysses.pdf index 9d3c1b1..f411dd6 100644 Binary files a/extras/Ulysses.pdf and b/extras/Ulysses.pdf differ diff --git a/extras/pdf_vignette/start_study.pdf b/extras/pdf_vignette/start_study.pdf index 109e5c0..53473a3 100644 Binary files a/extras/pdf_vignette/start_study.pdf and b/extras/pdf_vignette/start_study.pdf differ diff --git a/inst/images/ohdsi_logo.png b/inst/images/ohdsi_logo.png new file mode 100644 index 0000000..345571e Binary files /dev/null and b/inst/images/ohdsi_logo.png differ diff --git a/inst/templates/AnalysisPlan.qmd b/inst/templates/AnalysisPlan.qmd index a4fbc7e..47cbf93 100644 --- a/inst/templates/AnalysisPlan.qmd +++ b/inst/templates/AnalysisPlan.qmd @@ -1,5 +1,7 @@ --- -title: {{{ Study }}} Analysis Plan +title: Analysis Plan +subtitle: {{{ Title }}} +author: {{ Developer }} number-sections: true --- @@ -50,20 +52,6 @@ knitr::opts_chunk$set(echo = FALSE) -```{r} -#| label: tbl-data_sources -#| echo: false -#| tbl-cap: Data Sources used in study - -dataSources <- tibble::tribble( - ~Name, ~Country, ~Type, ~Size, ~Availability, ~Description, - "Synpuf", "US", "claims", "110K", "2008-2010", "Synthetic data source based on US Medicare data" -) - -flextable::flextable(dataSources) - -``` - # Analysis Plan diff --git a/inst/templates/AnalysisScript.R b/inst/templates/AnalysisScript.R index 0bee77d..c5a5a62 100644 --- a/inst/templates/AnalysisScript.R +++ b/inst/templates/AnalysisScript.R @@ -2,7 +2,7 @@ # A. File Info ----------------------- -# Study: {{{ Study }}} +# Study: {{{ Title }}} # Author: {{{ Author }}} # Date: {{{ Date }}} # Description: The purpose of this script is to..... diff --git a/inst/templates/Capr.R b/inst/templates/Capr.R index 193841f..a439be3 100644 --- a/inst/templates/Capr.R +++ b/inst/templates/Capr.R @@ -2,7 +2,7 @@ # A. File Info ----------------------- -# Study: {{{ Study }}} +# Study: {{{ Title }}} # Author: {{{ Author }}} # Date: {{{ Date }}} # Description: The purpose of this Capr script is to develop xxx cohorts.... diff --git a/inst/templates/ContributionGuidelines.qmd b/inst/templates/ContributionGuidelines.qmd index 5724f95..948421a 100644 --- a/inst/templates/ContributionGuidelines.qmd +++ b/inst/templates/ContributionGuidelines.qmd @@ -3,7 +3,7 @@ title: "Contribution Guidelines" number-sections: true --- -Welcome to the {{{ Study }}}! Thank you for your interest in participating in this network study. Please read the contribution guidelines carefully to understand how to participate in this study. +Welcome to the {{{ Title }}}! Thank you for your interest in participating in this network study. Please read the contribution guidelines carefully to understand how to participate in this study. # Code of Conduct @@ -26,7 +26,7 @@ Please contract the study coordinator to express your interest in participating ## Issues -The {{{ Study }}} study uses github to version control the study code required to run the analysis. As a github repository, we use [issues](https://docs.github.com/en/issues/tracking-your-work-with-issues/about-issues) to track bugs and answer questions about the study code. Debugging issues collaboratively ensures that all study nodes are informed on code issues and have the most up-to-date code required to successfully run the study. An issue at your site is likely a similar problem for someone else. +The {{{ Title }}} study uses github to version control the study code required to run the analysis. As a github repository, we use [issues](https://docs.github.com/en/issues/tracking-your-work-with-issues/about-issues) to track bugs and answer questions about the study code. Debugging issues collaboratively ensures that all study nodes are informed on code issues and have the most up-to-date code required to successfully run the study. An issue at your site is likely a similar problem for someone else. Creating an issue can be done through the github repository. Via web UI, navigate to the tab labelled **Issues** and select the green button **New Issue**. This will create a post powered by Markdown which you will be able to describe the **Issue** in the repository. For more efficient communication, @mention collaborators to guide the conversation in their direction. diff --git a/inst/templates/HowToRun.qmd b/inst/templates/HowToRun.qmd index 94e61aa..cf82a3f 100644 --- a/inst/templates/HowToRun.qmd +++ b/inst/templates/HowToRun.qmd @@ -1,8 +1,40 @@ --- -title: How-to-Run {{{ Study }}} +title: How-to-Run {{{ Title }}} +author: {{ Developer }} number-sections: true --- +# Technical Specifications and pre-requisites + +In order to execute the {{{ Title }}} study please ensure the following technical requirements have been installed or are satisfied. + +## HADES Setup + +To run this study you must setup the [HADES environment](https://ohdsi.github.io/Hades/rSetup.html). + +- Install [R](https://cloud.r-project.org/) (version 4.1 or greater) +- Install [R Studio](https://posit.co/download/rstudio-desktop/) +- On Windows: Install [RTools](https://cran.r-project.org/bin/windows/Rtools/) +- Install [Java](https://www.java.com/en/) + + +## Supported Databases + +You also require your site data to be mapped to the [OMOP CDM](https://ohdsi.github.io/CommonDataModel/) and administered on one of the following supported database platforms: + +- Microsoft SQL Server +- PostgreSQL +- Google BigQuery +- Amazon RedShift +- Snowflake + +## OMOP CDM Data Quality + +Prior to running this analysis, the data standardized to the OMOP CDM must undergo a level of quality control to ensure the data is ready for use in a network study. The OHDSI community provides two tools for running data quality checks: + +- [ACHILLES](https://github.com/OHDSI/Achilles) +- [DataQualityDashboard](https://github.com/OHDSI/DataQualityDashboard) + # Download and Install diff --git a/inst/templates/Internals.R b/inst/templates/Internals.R index ca405e5..52ac2f5 100644 --- a/inst/templates/Internals.R +++ b/inst/templates/Internals.R @@ -2,7 +2,6 @@ # A. Meta Info ----------------------- -# Study: {{{ Study }}} # Author: {{{ Author }}} # Date: {{{ Date }}} # Description: The purpose of the {{{ FileName }}}.R script is to..... diff --git a/inst/templates/MigrationScript.R b/inst/templates/MigrationScript.R new file mode 100644 index 0000000..afab5e5 --- /dev/null +++ b/inst/templates/MigrationScript.R @@ -0,0 +1,33 @@ +# {{{ FileName }}}.R + +# A. Meta Info ----------------------- + +# Study: {{{ Title }}} +# Author: {{{ Author }}} +# Date: {{{ Date }}} +# Description: The purpose of this script is to migrate data from..... + + +# B. Dependencies ------------------------ + + +library(tidyverse) #import tidyverse + +resultsPath <- here::here("exec/results") +exportPath <- here::here("exec/export") + +# C. Script ----------------------- + + +## 1. Import Raw ------------------ + +dat <- fs::path(studyPath, ".csv") %>% + readr::read_csv(show_col_types = FALSE) + +## 2. Format -------------------- + +## Input formatting pipeline ------------------- + +## 3. Save as Export -------------- + +readr::write_csv(modifiedData, file = fs::path(exportPath, ".csv")) diff --git a/inst/templates/NEWS.md b/inst/templates/NEWS.md index 2bfb42a..36c6aec 100644 --- a/inst/templates/NEWS.md +++ b/inst/templates/NEWS.md @@ -1,4 +1,4 @@ -# {{{ Project }}} v0.0.1 +# {{{ ID }}} {{{ Version }}} -* Initialize OHDSI study -* Add `NEWS.md` to track changes to OHDSI study +* Initialize study using `Ulysses` +* Add `NEWS.md` to track changes of study diff --git a/inst/templates/README.md b/inst/templates/README.md index 354ffb3..ce7a8e2 100644 --- a/inst/templates/README.md +++ b/inst/templates/README.md @@ -1,4 +1,4 @@ -# {{{ Project }}} +# {{{ Title }}} @@ -6,31 +6,35 @@ +## Study Information -## Description +- **Study Id**: {{{ ID }}} +- **Study Type**: {{{ Type }}} +- **Study Start Date**: {{{ Start }}} +- **Expected Study End Date**: {{{ End }}} +- **Study Lead**: {{{ Lead }}} +- **Study Developer**: {{{ Developer }}} +- **Tags**: {{{ Tags }}} -Welcome to the {{{ Project }}} study! {{{ Project }}} is a {{{ StudyType }}} study. +## Study Description - +{{{ Description }}} +- **Therapeutic Area**: {{{ TA }}} +- **Data Sources**: {{{ DS }}} -## Study Information +## Resources -- **Study Type**: {{{ Study Type }}} -- **Contact Name**: {{{ Contact }}} -- **Contact Email **: {{{ ContactEmail }}} + + +- **Study Concept**: TBD +- **Analysis Plan**: TBD +- **Report**: TBD +- **Dashboard**: TBD + + -## CDM Information -- **CDM Version**: {{{ CdmVersion }}} -- **Vocabulary Version**: {{{ VocabVersion }}} -- **Vocabulary Release**: {{{ VocabRelease}}} -## Resources -- **Forum Post**: {{{ ForumPost }}} -- **Study Hub**: {{{ Hub }}} -- **Protocol**: {{{ Protocol }}} -- **Report**: {{{ Report }}} -- **Results Dashboard**: {{{ Dashboard }}} diff --git a/inst/templates/ResultsReport.qmd b/inst/templates/ResultsReport.qmd index 530dea7..9fa1c08 100644 --- a/inst/templates/ResultsReport.qmd +++ b/inst/templates/ResultsReport.qmd @@ -1,5 +1,7 @@ --- -title: {{{ Study }}} Results Report +title: Results Report +subtitle: {{{ Title }}} +author: {{ Developer }} number-sections: true --- diff --git a/inst/templates/TechSpecs.qmd b/inst/templates/TechSpecs.qmd index ad88671..d07306f 100644 --- a/inst/templates/TechSpecs.qmd +++ b/inst/templates/TechSpecs.qmd @@ -1,9 +1,9 @@ --- -title: Technical Specifications for {{{ Study }}} +title: Technical Specifications for {{{ Title }}} number-sections: true --- -In order to execute the {{{ Study }}} study please ensure the following technical requirements have been installed or are satisfied. +In order to execute the {{{ Title }}} study please ensure the following technical requirements have been installed or are satisfied. # HADES Setup diff --git a/inst/templates/config.yml b/inst/templates/config.yml deleted file mode 100644 index 15d4fc4..0000000 --- a/inst/templates/config.yml +++ /dev/null @@ -1,18 +0,0 @@ -# Config File for {{{ Project }}} - -default: - projectName: {{{ Project }}} - -# Config block for {{{ Block }}} - -{{{ Block }}}: - databaseName: {{{ Database }}} - cohortTable: {{{ Cohort }}} - dbms: !expr keyring::key_get('{{{ Block }}}_dbms', keyring = '{{{ Project }}}') - user: !expr keyring::key_get('{{{ Block }}}_user', keyring = '{{{ Project }}}') - password: !expr keyring::key_get('{{{ Block }}}_password', keyring = '{{{ Project }}}') - connectionString: !expr keyring::key_get('{{{ Block }}}_connectionString', keyring = '{{{ Project }}}') - cdmDatabaseSchema: !expr keyring::key_get('{{{ Block }}}_cdmDatabaseSchema', keyring = '{{{ Project }}}') - vocabDatabaseSchema: !expr keyring::key_get('{{{ Block }}}_vocabDatabaseSchema', keyring = '{{{ Project }}}') - workDatabaseSchema: !expr keyring::key_get('{{{ Block }}}_workDatabaseSchema', keyring = '{{{ Project }}}') - diff --git a/inst/templates/config_keyring.yml b/inst/templates/config_keyring.yml new file mode 100644 index 0000000..00b1090 --- /dev/null +++ b/inst/templates/config_keyring.yml @@ -0,0 +1,21 @@ +# Config File for {{ Title }} + +default: + projectName: {{ ID }} + +{{#data}} + +# Config block for {{ Block }} + +{{ Block }}: + databaseName: {{{ Database }}} + cohortTable: {{{ Cohort }}} + dbms: !expr keyring::key_get('{{ Block }}_dbms', keyring = '{{ ID }}') + user: !expr keyring::key_get('{{ Block }}_user', keyring = '{{ ID }}') + password: !expr keyring::key_get('{{ Block }}_password', keyring = '{{ ID }}') + connectionString: !expr keyring::key_get('{{ Block }}_connectionString', keyring = '{{ ID }}') + cdmDatabaseSchema: !expr keyring::key_get('{{ Block }}_cdmDatabaseSchema', keyring = '{{ ID }}') + vocabDatabaseSchema: !expr keyring::key_get('{{ Block }}_vocabDatabaseSchema', keyring = '{{ ID }}') + workDatabaseSchema: !expr keyring::key_get('{{ Block }}_workDatabaseSchema', keyring = '{{ ID }}') + +{{/data}} diff --git a/inst/templates/config_raw.yml b/inst/templates/config_raw.yml new file mode 100644 index 0000000..15fa365 --- /dev/null +++ b/inst/templates/config_raw.yml @@ -0,0 +1,20 @@ +# Config File for {{{ Title }}} + +default: + projectName: {{{ ID }}} + + +# Config block for {{ Block }} + +{{ Block }}: + databaseName: {{ Database }} + cohortTable: {{ Cohort }} + dbms: '{{ Block }}_dbms' + user: '{{ Block }}_user' + password: '{{ Block }}_password' + connectionString: '{{ Block }}_connectionString' + cdmDatabaseSchema: '{{ Block }}_cdmDatabaseSchema' + vocabDatabaseSchema: '{{ Block }}_vocabDatabaseSchema' + workDatabaseSchema: '{{ Block }}_workDatabaseSchema' + tempEmulationSchema: NULL + diff --git a/inst/templates/quartoWebsite.yml b/inst/templates/quartoWebsite.yml index 826b73b..998ba34 100644 --- a/inst/templates/quartoWebsite.yml +++ b/inst/templates/quartoWebsite.yml @@ -2,31 +2,27 @@ project: type: website website: - title: {{{ Study }}} + title: '{{{ Title }}}' navbar: - background: primary + background: '{{{ Color }}}' + logo: 'images/{{{ Logo }}}' left: - href: index.qmd text: Home + - text: Analysis Plan + href: AnalysisPlan.qmd + - text: Results Report + href: ResultsReport.qmd - href: news.qmd text: Changelog - - text: "Study Resources" - menu: - - text: Analysis Plan - href: AnalysisPlan.qmd - - text: Results Report - href: ResultsReport.qmd - - text: Technical Specifications - href: TechSpecs.qmd - - text: How-To-Run - href: HowToRun.qmd - - text: Contibution Guidelines - href: ContributionGuidelines.qmd + page-footer: '{{{ Footer }}}' format: html: theme: cosmo toc: true + fig-cap-location: "top" + tbl-cap-location: "top" diff --git a/man/addDataSources.Rd b/man/addDataSources.Rd new file mode 100644 index 0000000..fe3c35b --- /dev/null +++ b/man/addDataSources.Rd @@ -0,0 +1,19 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/studySettings.R +\name{addDataSources} +\alias{addDataSources} +\title{Function to add study data sources} +\usage{ +addDataSources(..., projectPath = here::here()) +} +\arguments{ +\item{...}{a list of data sources to add} + +\item{projectPath}{the path to the project} +} +\value{ +invisible studyYml, prints specifying what changes happened +} +\description{ +Function to add study data sources +} diff --git a/man/addLinks.Rd b/man/addLinks.Rd new file mode 100644 index 0000000..cc93427 --- /dev/null +++ b/man/addLinks.Rd @@ -0,0 +1,19 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/studySettings.R +\name{addLinks} +\alias{addLinks} +\title{Function to add study links} +\usage{ +addLinks(..., projectPath = here::here()) +} +\arguments{ +\item{...}{a list of links to add} + +\item{projectPath}{the path to the project} +} +\value{ +invisible studyYml, prints specifying what changes happened +} +\description{ +Function to add study links +} diff --git a/man/addStudyMember.Rd b/man/addStudyMember.Rd new file mode 100644 index 0000000..025f6b7 --- /dev/null +++ b/man/addStudyMember.Rd @@ -0,0 +1,21 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/studySettings.R +\name{addStudyMember} +\alias{addStudyMember} +\title{Function to add a study member} +\usage{ +addStudyMember(name, email = NULL, projectPath = here::here()) +} +\arguments{ +\item{name}{the name of the study member} + +\item{email}{the study member's email} + +\item{projectPath}{the path to the project} +} +\value{ +invisible studyYml, prints specifying what changes happened +} +\description{ +Function to add a study member +} diff --git a/man/addTags.Rd b/man/addTags.Rd new file mode 100644 index 0000000..411ec04 --- /dev/null +++ b/man/addTags.Rd @@ -0,0 +1,19 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/studySettings.R +\name{addTags} +\alias{addTags} +\title{Function to add study tags} +\usage{ +addTags(..., projectPath = here::here()) +} +\arguments{ +\item{...}{a list of study tags to add} + +\item{projectPath}{the path to the project} +} +\value{ +invisible studyYml, prints specifying what changes happened +} +\description{ +Function to add study tags +} diff --git a/man/buildStudyHub.Rd b/man/buildStudyHub.Rd index 0b001ad..d66823f 100644 --- a/man/buildStudyHub.Rd +++ b/man/buildStudyHub.Rd @@ -4,10 +4,22 @@ \alias{buildStudyHub} \title{Function to build study hub} \usage{ -buildStudyHub(projectPath = here::here()) +buildStudyHub( + projectPath = here::here(), + logoPath = NULL, + footer = NULL, + backgroundColor = "#336B91" +) } \arguments{ \item{projectPath}{path to ohdsi study} + +\item{logoPath}{a path to a logo png to use in the quarto website, defaults to +ohdsi logo from Ulysses inst.} + +\item{footer}{add a footer to the study Hub} + +\item{backgroundColor}{change background color, defaults to OHDSI blue #336B91} } \value{ builds a _site folder in documenation that holds the html website diff --git a/man/importCredentialsToConfig.Rd b/man/importCredentialsToConfig.Rd new file mode 100644 index 0000000..3d0f5d1 --- /dev/null +++ b/man/importCredentialsToConfig.Rd @@ -0,0 +1,18 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/config.R +\name{importCredentialsToConfig} +\alias{importCredentialsToConfig} +\title{Function to import credentials in stored csv to study config.yml} +\usage{ +importCredentialsToConfig(credFile, projectPath = here::here(), open = TRUE) +} +\arguments{ +\item{credFile}{a credential.csv file stored in a secure location} + +\item{projectPath}{the path to the project} + +\item{open}{toggle on whether the file should be opened} +} +\description{ +Function to import credentials in stored csv to study config.yml +} diff --git a/man/importImages.Rd b/man/importImages.Rd new file mode 100644 index 0000000..3e34497 --- /dev/null +++ b/man/importImages.Rd @@ -0,0 +1,19 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/website.R +\name{importImages} +\alias{importImages} +\title{Function to import a folder of images for a study hub} +\usage{ +importImages(imageFolder, projectPath = here::here()) +} +\arguments{ +\item{imageFolder}{the file path for an image folder} + +\item{projectPath}{path to ohdsi study} +} +\value{ +invisible return of the image file folder +} +\description{ +Function to import a folder of images for a study hub +} diff --git a/man/initConfig.Rd b/man/initConfig.Rd new file mode 100644 index 0000000..f7b63e6 --- /dev/null +++ b/man/initConfig.Rd @@ -0,0 +1,28 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/config.R +\name{initConfig} +\alias{initConfig} +\title{Function to create a config.yml file} +\usage{ +initConfig( + block = "BlockName", + database = "DatabaseName", + withKeyring = FALSE, + projectPath = here::here(), + open = TRUE +) +} +\arguments{ +\item{block}{the name of the config block, defaults to BlockName} + +\item{database}{the name of the database for the block, default to DatabaseName} + +\item{withKeyring}{should the config file use keyring, default FALSE} + +\item{projectPath}{the path to the project} + +\item{open}{toggle on whether the file should be opened} +} +\description{ +Function to create a config.yml file +} diff --git a/man/makeAnalysisScript.Rd b/man/makeAnalysisScript.Rd index 67363ba..24cbed2 100644 --- a/man/makeAnalysisScript.Rd +++ b/man/makeAnalysisScript.Rd @@ -7,7 +7,6 @@ makeAnalysisScript( scriptName, configBlock = NULL, - author = NULL, date = lubridate::today(), projectPath = here::here(), open = TRUE @@ -18,6 +17,8 @@ makeAnalysisScript( \item{configBlock}{the name of the config block to use for the script} +\item{date}{the date the script was built, default to today's date} + \item{projectPath}{the path to the project} \item{open}{toggle on whether the file should be opened} diff --git a/man/makeCaprScript.Rd b/man/makeCaprScript.Rd index 66fa19a..2535bc9 100644 --- a/man/makeCaprScript.Rd +++ b/man/makeCaprScript.Rd @@ -7,7 +7,6 @@ makeCaprScript( scriptName, configBlock = NULL, - author = NULL, date = lubridate::today(), projectPath = here::here(), open = TRUE @@ -18,6 +17,8 @@ makeCaprScript( \item{configBlock}{the name of the config block to use for the script} +\item{date}{the date the script was built, default to today's date} + \item{projectPath}{the path to the project} \item{open}{toggle on whether the file should be opened} diff --git a/man/makeConfig.Rd b/man/makeConfig.Rd deleted file mode 100644 index e631bf8..0000000 --- a/man/makeConfig.Rd +++ /dev/null @@ -1,20 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/makeFiles.R -\name{makeConfig} -\alias{makeConfig} -\title{Function to create a config.yml file} -\usage{ -makeConfig(block, database = block, projectPath = here::here(), open = TRUE) -} -\arguments{ -\item{block}{the name of the config block} - -\item{database}{the name of the database for the block, default to block name} - -\item{projectPath}{the path to the project} - -\item{open}{toggle on whether the file should be opened} -} -\description{ -Function to create a config.yml file -} diff --git a/man/makeInternals.Rd b/man/makeInternals.Rd index 6d171d8..eea343a 100644 --- a/man/makeInternals.Rd +++ b/man/makeInternals.Rd @@ -6,20 +6,17 @@ \usage{ makeInternals( internalsName, - projectPath = here::here(), - author = NULL, date = lubridate::today(), + projectPath = here::here(), open = TRUE ) } \arguments{ \item{internalsName}{The name of the internals file that is being created} -\item{projectPath}{the path to the project} +\item{date}{the date the script was built, default to today's date} -\item{author}{the author of the R file, defaults to first author in _study.yml} - -\item{date}{the date the file was initialized, defaults to today} +\item{projectPath}{the path to the project} \item{open}{toggle on whether the file should be opened} } diff --git a/man/makeMeetingMinutes.Rd b/man/makeMeetingMinutes.Rd deleted file mode 100644 index 1a6521b..0000000 --- a/man/makeMeetingMinutes.Rd +++ /dev/null @@ -1,16 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/makeFiles.R -\name{makeMeetingMinutes} -\alias{makeMeetingMinutes} -\title{Function to create a meeting minutes file} -\usage{ -makeMeetingMinutes(projectPath = here::here(), open = TRUE) -} -\arguments{ -\item{projectPath}{the path to the project} - -\item{open}{toggle on whether the file should be opened} -} -\description{ -Function to create a meeting minutes file -} diff --git a/man/makeMigrationScript.Rd b/man/makeMigrationScript.Rd new file mode 100644 index 0000000..070b980 --- /dev/null +++ b/man/makeMigrationScript.Rd @@ -0,0 +1,25 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/makeFiles.R +\name{makeMigrationScript} +\alias{makeMigrationScript} +\title{Function to create a migration script} +\usage{ +makeMigrationScript( + scriptName, + date = lubridate::today(), + projectPath = here::here(), + open = TRUE +) +} +\arguments{ +\item{scriptName}{The name of the analysis script} + +\item{date}{the date the script was built, default to today's date} + +\item{projectPath}{the path to the project} + +\item{open}{toggle on whether the file should be opened} +} +\description{ +Function to create a migration script +} diff --git a/man/makeOhdsiProtocol.Rd b/man/makeOhdsiProtocol.Rd deleted file mode 100644 index 51e538e..0000000 --- a/man/makeOhdsiProtocol.Rd +++ /dev/null @@ -1,16 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/makeFiles.R -\name{makeOhdsiProtocol} -\alias{makeOhdsiProtocol} -\title{R Markdown file to make the ohdsi protocol} -\usage{ -makeOhdsiProtocol(projectPath = here::here(), open = TRUE) -} -\arguments{ -\item{projectPath}{the path to the project} - -\item{open}{toggle on whether the file should be opened} -} -\description{ -R Markdown file to make the ohdsi protocol -} diff --git a/man/makeStudySettings.Rd b/man/makeStudySettings.Rd deleted file mode 100644 index 2f71c94..0000000 --- a/man/makeStudySettings.Rd +++ /dev/null @@ -1,38 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/studySettings.R -\name{makeStudySettings} -\alias{makeStudySettings} -\title{Function to initialize study settings} -\usage{ -makeStudySettings( - title, - authors = defaultAuthors(), - milestones = defaultMilestones(), - cdm = defaultCdmDetails(), - strategus = getLatestModules(), - desc = defaultDesc(), - contact = defaultContact(), - links = defaultLinks() -) -} -\arguments{ -\item{title}{the title of the study} - -\item{authors}{the author list for the study} - -\item{milestones}{list of milestone information including study status and timeframe for study} - -\item{cdm}{list of info about the cdm} - -\item{desc}{a list of attributes describing the study including the study type and tages} - -\item{contact}{a list of contact information for study} - -\item{links}{a list of links to files used in study} -} -\value{ -a list containing study settings -} -\description{ -Function to initialize study settings -} diff --git a/man/makeTechSpecs.Rd b/man/makeTechSpecs.Rd deleted file mode 100644 index 0e115bb..0000000 --- a/man/makeTechSpecs.Rd +++ /dev/null @@ -1,16 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/makeFiles.R -\name{makeTechSpecs} -\alias{makeTechSpecs} -\title{Function to create a HowToRun file} -\usage{ -makeTechSpecs(projectPath = here::here(), open = TRUE) -} -\arguments{ -\item{projectPath}{the path to the project} - -\item{open}{toggle on whether the file should be opened} -} -\description{ -Function to create a HowToRun file -} diff --git a/man/newOhdsiStudy.Rd b/man/newOhdsiStudy.Rd index 52c9b72..745e0ca 100644 --- a/man/newOhdsiStudy.Rd +++ b/man/newOhdsiStudy.Rd @@ -7,7 +7,12 @@ newOhdsiStudy( path, projectName = basename(path), - studySettings = makeStudySettings(title = basename(path)), + studyInfo = setStudyInfo(id = basename(path)), + authors = setStudyAuthors(), + timeline = setStudyTimeline(), + about = setStudyDescription(), + links = setStudyLinks(), + tags = setStudyTags(), verbose = TRUE, openProject = TRUE ) @@ -17,7 +22,23 @@ newOhdsiStudy( \item{projectName}{the name of the project} -\item{studySettings}{a list of study settings} +\item{studyInfo}{a list object identifying the title, type and study version, +defaults to \code{setStudyInfo}, see documentation} + +\item{authors}{a list object identifying the lead and developer authors names and emails, +defaults to \code{setStudyAuthors}, see documentation.} + +\item{timeline}{a list object identifying the study status, start and end date, +defaults to \code{setStudyTimeline}, see documentation} + +\item{about}{a list object identifying the study description, therapeutic area and databases, +defaults to \code{setStudyDescription}, see documentation} + +\item{links}{a list object identifying the linked resources of the study, +defaults to \code{setStudyLinks}, see documentation} + +\item{tags}{a list object identifying tags to the study, +defauls to \code{setStudyTags}, see documentation} \item{verbose}{whether the function should provide steps, default TRUE} diff --git a/man/requestStudyRepository.Rd b/man/requestStudyRepository.Rd deleted file mode 100644 index 3bbda0f..0000000 --- a/man/requestStudyRepository.Rd +++ /dev/null @@ -1,39 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/makeFiles.R -\name{requestStudyRepository} -\alias{requestStudyRepository} -\title{Email asking to initialize an ohdsi-studies repo} -\usage{ -requestStudyRepository( - senderName, - senderEmail, - githubUserName = NULL, - recipientName = NULL, - recipientEmail = NULL, - projectPath = here::here(), - open = TRUE -) -} -\arguments{ -\item{senderName}{your name as the person sending the email} - -\item{senderEmail}{your email address} - -\item{githubUserName}{your github username.} - -\item{recipientName}{the recipients name, defaults to Admin} - -\item{recipientEmail}{the recipients email, defaults to a dummy email} - -\item{projectPath}{the path to the Ulysses project} - -\item{open}{toggle on whether the file should be opened} -} -\description{ -Email asking to initialize an ohdsi-studies repo -} -\details{ -This function works best if you have properly setup a Github PAT. To configure the PAT -follow the \href{https://gh.r-lib.org/articles/managing-personal-access-tokens.html}{instructions} -from the gh package. -} diff --git a/man/retrieveStudySettings.Rd b/man/retrieveStudySettings.Rd new file mode 100644 index 0000000..e206ec2 --- /dev/null +++ b/man/retrieveStudySettings.Rd @@ -0,0 +1,17 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/studySettings.R +\name{retrieveStudySettings} +\alias{retrieveStudySettings} +\title{Function to convert yml into a specified list format} +\usage{ +retrieveStudySettings(projectPath) +} +\arguments{ +\item{projectPath}{the path to the project} +} +\value{ +the study yml as an R object (list) +} +\description{ +Function to convert yml into a specified list format +} diff --git a/man/setStudyAuthors.Rd b/man/setStudyAuthors.Rd new file mode 100644 index 0000000..10daf00 --- /dev/null +++ b/man/setStudyAuthors.Rd @@ -0,0 +1,28 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/studySettings.R +\name{setStudyAuthors} +\alias{setStudyAuthors} +\title{Function to set study authors} +\usage{ +setStudyAuthors( + developer = Sys.getenv("USERNAME"), + developerEmail = glue::glue("{developer}@ohdsi.org"), + lead = "Ulysses", + leadEmail = "Ulysses@ohdsi.org" +) +} +\arguments{ +\item{developer}{specify the study developer, default to system variable} + +\item{developerEmail}{the email of the developer} + +\item{lead}{specify the lead of the study} + +\item{leadEmail}{specify the lead of the study email} +} +\value{ +a list containing study authors +} +\description{ +Function to set study authors +} diff --git a/man/setStudyDescription.Rd b/man/setStudyDescription.Rd new file mode 100644 index 0000000..74c1cde --- /dev/null +++ b/man/setStudyDescription.Rd @@ -0,0 +1,25 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/studySettings.R +\name{setStudyDescription} +\alias{setStudyDescription} +\title{Function to set study description} +\usage{ +setStudyDescription( + desc = "Provide a 1 to 2 sentence description of your study. Be concise.", + ta = "Specify the therapeutic area of the study", + dataSources = list("Truven MarketScan", "Optum Market Clarity") +) +} +\arguments{ +\item{desc}{a brief description of the study} + +\item{ta}{a character string of the therapeutic area} + +\item{dataSources}{a list of data sources} +} +\value{ +a list containing study description info +} +\description{ +Function to set study description +} diff --git a/man/setStudyInfo.Rd b/man/setStudyInfo.Rd new file mode 100644 index 0000000..f3b7b5c --- /dev/null +++ b/man/setStudyInfo.Rd @@ -0,0 +1,28 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/studySettings.R +\name{setStudyInfo} +\alias{setStudyInfo} +\title{Function to set study info} +\usage{ +setStudyInfo( + id, + title = id, + type = c("Characterization"), + version = "0.0.0.999" +) +} +\arguments{ +\item{id}{specify the study id} + +\item{title}{specify the study title} + +\item{type}{specify the type of study} + +\item{version}{specify the study version} +} +\value{ +a list containing study info +} +\description{ +Function to set study info +} diff --git a/man/setStudyLinks.Rd b/man/setStudyLinks.Rd new file mode 100644 index 0000000..e13588a --- /dev/null +++ b/man/setStudyLinks.Rd @@ -0,0 +1,17 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/studySettings.R +\name{setStudyLinks} +\alias{setStudyLinks} +\title{Function to set study links} +\usage{ +setStudyLinks(...) +} +\arguments{ +\item{...}{a series of resource links for the study} +} +\value{ +a list containing links to resources +} +\description{ +Function to set study links +} diff --git a/man/setStudyTags.Rd b/man/setStudyTags.Rd new file mode 100644 index 0000000..9b78bc7 --- /dev/null +++ b/man/setStudyTags.Rd @@ -0,0 +1,17 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/studySettings.R +\name{setStudyTags} +\alias{setStudyTags} +\title{Function to set study tags} +\usage{ +setStudyTags(...) +} +\arguments{ +\item{...}{a series of tags for the study} +} +\value{ +a list containing study tags +} +\description{ +Function to set study tags +} diff --git a/man/setStudyTimeline.Rd b/man/setStudyTimeline.Rd new file mode 100644 index 0000000..db715be --- /dev/null +++ b/man/setStudyTimeline.Rd @@ -0,0 +1,25 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/studySettings.R +\name{setStudyTimeline} +\alias{setStudyTimeline} +\title{Function to set study timeline} +\usage{ +setStudyTimeline( + status = "Started", + startDate = as.character(lubridate::today()), + endDate = as.character(lubridate::today() + (365 * 2)) +) +} +\arguments{ +\item{status}{the study status, default is started} + +\item{startDate}{the start of the study, defaults to todays date} + +\item{endDate}{the date specifying the end (or expected end) of the study} +} +\value{ +a list containing study timeline +} +\description{ +Function to set study timeline +} diff --git a/man/updateDeveloperInfo.Rd b/man/updateDeveloperInfo.Rd new file mode 100644 index 0000000..fb7c71a --- /dev/null +++ b/man/updateDeveloperInfo.Rd @@ -0,0 +1,19 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/studySettings.R +\name{updateDeveloperInfo} +\alias{updateDeveloperInfo} +\title{Function to update developer Infor} +\usage{ +updateDeveloperInfo(newName, newEmail, projectPath = here::here()) +} +\arguments{ +\item{newName}{change the developer name} + +\item{newEmail}{change the developer email} +} +\value{ +invisible studyYml, prints specifying what changes happened +} +\description{ +Function to update developer Infor +} diff --git a/man/updateLeadInfo.Rd b/man/updateLeadInfo.Rd new file mode 100644 index 0000000..b8170d6 --- /dev/null +++ b/man/updateLeadInfo.Rd @@ -0,0 +1,19 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/studySettings.R +\name{updateLeadInfo} +\alias{updateLeadInfo} +\title{Function to update lead Infor} +\usage{ +updateLeadInfo(newName, newEmail, projectPath = here::here()) +} +\arguments{ +\item{newName}{change the lead name} + +\item{newEmail}{change the lead email} +} +\value{ +invisible studyYml, prints specifying what changes happened +} +\description{ +Function to update lead Infor +} diff --git a/man/updateStudyDescription.Rd b/man/updateStudyDescription.Rd new file mode 100644 index 0000000..da6a3ec --- /dev/null +++ b/man/updateStudyDescription.Rd @@ -0,0 +1,19 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/studySettings.R +\name{updateStudyDescription} +\alias{updateStudyDescription} +\title{Function to update study description} +\usage{ +updateStudyDescription(newStudyDescription, projectPath = here::here()) +} +\arguments{ +\item{projectPath}{the path to the project} + +\item{newStudyVersion}{the new study description} +} +\value{ +invisible studyYml, prints specifying what changes happened +} +\description{ +Function to update study description +} diff --git a/man/updateStudyEndDate.Rd b/man/updateStudyEndDate.Rd new file mode 100644 index 0000000..07b9890 --- /dev/null +++ b/man/updateStudyEndDate.Rd @@ -0,0 +1,19 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/studySettings.R +\name{updateStudyEndDate} +\alias{updateStudyEndDate} +\title{Function to update study end date} +\usage{ +updateStudyEndDate(newEndDate, projectPath = here::here()) +} +\arguments{ +\item{newEndDate}{the new end date of the study, suggest format YYYY-MM-DD} + +\item{projectPath}{the path to the project} +} +\value{ +invisible studyYml, prints specifying what changes happened +} +\description{ +Function to update study end date +} diff --git a/man/updateStudyStatus.Rd b/man/updateStudyStatus.Rd new file mode 100644 index 0000000..3ae3b97 --- /dev/null +++ b/man/updateStudyStatus.Rd @@ -0,0 +1,22 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/studySettings.R +\name{updateStudyStatus} +\alias{updateStudyStatus} +\title{Function to update study status} +\usage{ +updateStudyStatus( + newStudyStatus = c("Started", "In-Progress", "Stopped", "Completed"), + projectPath = here::here() +) +} +\arguments{ +\item{newStudyStatus}{the new status of the study, accepts Started, In-Progress, Stopped, Completed} + +\item{projectPath}{the path to the project} +} +\value{ +invisible studyYml, prints specifying what changes happened +} +\description{ +Function to update study status +} diff --git a/man/updateStudyTitle.Rd b/man/updateStudyTitle.Rd new file mode 100644 index 0000000..e4105d9 --- /dev/null +++ b/man/updateStudyTitle.Rd @@ -0,0 +1,19 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/studySettings.R +\name{updateStudyTitle} +\alias{updateStudyTitle} +\title{Function to update study title} +\usage{ +updateStudyTitle(newStudyTitle, projectPath = here::here()) +} +\arguments{ +\item{newStudyTitle}{the new study title} + +\item{projectPath}{the path to the project} +} +\value{ +invisible studyYml, prints specifying what changes happened +} +\description{ +Function to update study title +} diff --git a/man/updateStudyVersion.Rd b/man/updateStudyVersion.Rd new file mode 100644 index 0000000..a674fb9 --- /dev/null +++ b/man/updateStudyVersion.Rd @@ -0,0 +1,19 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/studySettings.R +\name{updateStudyVersion} +\alias{updateStudyVersion} +\title{Function to update study version} +\usage{ +updateStudyVersion(newStudyVersion, projectPath = here::here()) +} +\arguments{ +\item{newStudyVersion}{the new study version} + +\item{projectPath}{the path to the project} +} +\value{ +invisible studyYml, prints specifying what changes happened +} +\description{ +Function to update study version +} diff --git a/man/updateTherapeuticArea.Rd b/man/updateTherapeuticArea.Rd new file mode 100644 index 0000000..385c647 --- /dev/null +++ b/man/updateTherapeuticArea.Rd @@ -0,0 +1,19 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/studySettings.R +\name{updateTherapeuticArea} +\alias{updateTherapeuticArea} +\title{Function to update study therapeutic area} +\usage{ +updateTherapeuticArea(newTA, projectPath = here::here()) +} +\arguments{ +\item{newTA}{the new study therapeutic area} + +\item{projectPath}{the path to the project} +} +\value{ +invisible studyYml, prints specifying what changes happened +} +\description{ +Function to update study therapeutic area +} diff --git a/vignettes/images/ulysses_directory.png b/vignettes/images/ulysses_directory.png index 1ae4655..61a69c5 100644 Binary files a/vignettes/images/ulysses_directory.png and b/vignettes/images/ulysses_directory.png differ diff --git a/vignettes/images/ulysses_meta.png b/vignettes/images/ulysses_meta.png new file mode 100644 index 0000000..5de8d36 Binary files /dev/null and b/vignettes/images/ulysses_meta.png differ diff --git a/vignettes/images/ulysses_study_hub.png b/vignettes/images/ulysses_study_hub.png new file mode 100644 index 0000000..65e07fa Binary files /dev/null and b/vignettes/images/ulysses_study_hub.png differ diff --git a/vignettes/start_study.Rmd b/vignettes/start_study.Rmd index d192dbd..402e8c1 100644 --- a/vignettes/start_study.Rmd +++ b/vignettes/start_study.Rmd @@ -37,57 +37,138 @@ In this vignette we walk-through how to build an OHDSI study using the `Ulysses` Once you have downloaded the `Ulysses` package, you can begin creating an OHDSI study. To do this, you can run code as shown in the block below: ```{r initStudy, echo=TRUE, eval=FALSE} -Ulysses::newOhdsiStudy( +newOhdsiStudy( path = here::here("my_ohdsi_study"), - author = "Ulysses S. Grant", - type = "Characterization", - directory = "[my_directory]", - open = TRUE + studyInfo = setStudyInfo(id = basename(here::here("my_ohdsi_study")), + title = "My OHDSI Study"), + authors = setStudyAuthors( + developer = "John Smith", + developerEmail = "john.smith@ohdsi.org" + ), + about = setStudyDescription( + desc = "This is an OHDSI study for characterizing a population. This is an example.", + ta = "Cardiovascular", + dataSources = list("Synthea", "Synpuf") + ), + tags = setStudyTags("OHDSI", "OMOP") ) ``` This function will print some information to your console about start-up tasks and open an R project in a new session, for details on Rstudio projects see [link](https://r-pkgs.org/workflow101.html#sec-workflow101-rstudio-projects). -In the new R session, we are directed to a clean R studio session. In the files pane you will see a directory structure as depicted in the image below. For more details about the directory structure refer to the *Introduction to Ulysses Directory* vignette in this package. Congratulations! You have started an OHDSI study! +The additional inputs of the `newOhdsiStudy` function build meta data for the study repository that will be stored in a `_study.yml` file. This meta data serves two purposes: 1) provides human-readable information about the study and 2) serves as a source of information to populate fields for templated files generated using `Ulysses`. For example, if we were to generate a `README` file using `Ulysses` it would be built using this meta information. -![Ulysses Style OHDSI Study Directory](images/ulysses_directory.png) +# Ulysses Directory structure -# Adding Repository Documentation +In a new R session, users will notice a pre-populated directory structure in their project folder. This directory structure contains specific folders and files that are important for a study to be self-contained within the new R project. -## The *README* file +![Ulysses Directory Structure](images/ulysses_directory.png) -With your new OHDSI study created, you need to begin adding documentation for the repository. The first file we usually create is the repository README. For those unfamiliar with code development, the README file is a standard file used to introduce a describe the the project. Think of the README as your cover page. It is the first file users see when they navigate to the github page. All OHDSI projects require a README file, thus `Ulysses` provides a function (`makeReadMe`) that initializes it. -```{r readMeStart, echo=TRUE, eval=FALSE} -Ulysses::makeReadMe() -``` +`Ulysses` builds the following folders: + +### `analysis` + +The analysis folder contains files that correspond to study analysis. There are three main folders created. + +* `src` - contains the underlying functions that execute the analysis. These files can be R scripts, sql files or python scripts, for example. With `Ulysses`, users can generate templated internal R files using the command `makeInternals`. +* `tasks` - hold the executing scripts that generate the results of the study. With `Ulysses`, we think of studies as a series of tasks implemented in a specific order, like a pipeline. The `tasks` folder organizes these individual tasks. With `Ulysses`, users can generate templated internal R files using the command `makeAnalysisScript`. +* `migrations` - contain post-processing scripts to move and prepare data from a series of results to a format that is "presentation ready". When conducting studies in OMOP, it is common to run the same analysis on different databases. Migration scripts help bind the results of all databases run in the study and format tables to present in a quarto report or shiny app. With `Ulysses`, users can generate templated internal R files using the command `makeMigrationScript`. + + +### `cohorts` + +The cohorts folder is meant to organize files that are used to generate cohort definitions in the database. In an OHDSI study, cohort definitions are specified in a `json` file format following the specifications of [`circe-be`](https://github.com/OHDSI/circe-be). We suggest placing cohorts used in the analysis in the cohort folder in order for the study to be self-contained, meaning it does not rely on ATLAS to execute. However, we **highly** recommend that users maintain the organization of their cohorts in ATLAS as a source of truth for both cohort definition and generation. The `sql` folder is created to store sql files used to build cohort definitions. This is a good location for cohort definitions that do not follow the `circe-be` structure. + +Keeping track of cohorts can be a bit tricky. `Ulysses` provides a helper function to track json files in the cohorts folder called `cohortManifest`. This function will list the name of the json file and its corresponding id. By default, the cohort Id assigned to the cohort json is in alphabetical order starting with 1. `Ulysses` also creates a file called the `CohortDetails.qmd` which prints the human-readable rendering of the json expression using [`CirceR`](https://github.com/OHDSI/CirceR). **These functions are still in development as of v0.0.4**. + +### `documentation` + +Study repositories should not only contain code, they should also contain documentation about the design of the study and how to run the study. Study repo's should be self-contained, meaning we can go to one location to get all code and human-readable documentation about the study. `Ulysses` builds this into its repository structure with a `hub` folder and a `misc` folder. The `hub` folder contains files that are specific to the study hub, an html website that provides all information about the study. The `misc` folder is a place-holder to store word documents, excel files, slide decks or other important documentation needed for the study. + +#### Study Hub + +The study hub is a website that a user can generate through `Ulysses` that provides information about the design of a study and its results. The study hub is generated using `quarto`. The study hub can be generated using the function `buildStudyHub`. The study hub relies on the generation and maintenance of 4 files: README.md, NEWS.md, AnalysisPlan.qmd and ResultsReport.qmd. + +![Ulysses Study Hub](images/ulysses_study_hub.png) + +#### Suggested Files + +`Ulysses` has functions to initialize some suggested files for a study: + +* `AnalysisPlan.qmd`: the statistical analysis plan for the study, which specifies the study design and analytical methods. This file can be templated in `Ulysses` using the command `makeAnalysisPlan`. +* `ResultsReport.qmd`: the report summarizing results from the study following its execution. This file can be templated in `Ulysses` using the command `makeResultsReport`. +* `ContributionGuidelines.qmd`: if the study is a network studies, maintainers should provide resources on how others can contribute to the study. Topics ranges from how to file issues, how to send results to the study host, and how to collaborate in a positive environment. This file can be templated in `Ulysses` using the command `makeContributionGuidelines`. +* `HowToRun.qmd`: a document that explains how to execute the study code to study nodes or interested parties. Should describe technical requirements needed prior to running the study, local setup, and execution. This file can be templated in `Ulysses` using the command `makeHowToRun`. + + +## `exec` + +The `exec` folder is a location to store output files that result from the study execution. This includes results and logs from the study run and a folder to store post-processed data called `export`. The `exec` folder is always ignored in git. + +## `extras` + +Sometimes studies have files that don't have a natural location from those specified above. The `extras` folder is a location to store any additional files needed to run or support the execution of the study. This is also a good location to store internal setup scripts, but remember to ignore them in git. + +# Additional Repository Files + +In addition to the pre-generated folders in the new study repository, `Ulysses` also helps generate additional files that should be in the repository. Some of these key files are described below. + +### `_study.yml` + +A file unique to directories initialized using `Ulysses` is a metadata file called `_study.yml`. Using the inputs specified in the `newOhdsiStudy` function, a metadata file is populated. As mentioned this file store information about the study directory and also uses it as inputs to templated files generated in `Ulysses`. It is important to maintain this file during the development of a study, whether that is to update default fields in the yaml file or add information. Below is a snapshot of a `_study.yml` file with the essential metadata fields. + +![Ulysses MetaData](images/ulysses_meta.png) + +#### Fields + +Below we describe the key fields in this file. + +* id: an identifier for the study which is the same as the directory name. Use either a study id or acronym +* title: a full title for the study, more thorough than the id. If no title is provided, the input defaults to the id. +* type: a keyword describing the type of study being conducted. Could be a **Characterization**, **Population-Level Estimation**, **Patient-Level Prediction**, or **Database Assessment**, for example. +* version: a value that represents the version of the study. Suggest using semantic versioning logic. +* authors: stores the name and email of the developer (person in-charge of code development) and the lead (person in-charge of the study). You may add other authors who are designated as *members* +* timeline: a list of information relating to the development timeline of the study. This includes the study start and end dates. The study status is also listed here, where acceptable values are **Started**, **In-Progress**, **Stopped** and **Completed**. +* about: a short description about the study, the therapeutic area it covers and data sources used. +* links: a listing of hyperlinks to guide people to key documentation such as the analysis plan, report, dashboard and other resources. +* tags: a list of keyword identifiers for the project + +#### Maintenance -The readme file is initailized using information found in the `_study.yml` file. A typical OHDSI study readme has a section of meta information as seen below: +`Ulysses` provides functions to maintain the `_study.yml` file. -- **Study Lead**: Ulysses S. Grant -- **Analytics Use Case**: Characterization -- **Study Start Date**: 04-27-1822 -- **Study End Date**: 07-23-1885 -- **Study Tags**: None -- **Protocol**: Unavailable -- **Publications**: Unavailable -- **Results Explorer**: Unavailable +* Add Fields + - `addStudyMember()` + - `addTags()` + - `addDataSources()` + - `addLinks()` + +* Update Fields + - `updateStudyEndDate()` + - `updateSutdyStatus()` + - `updateStudyTitle()` + - `updatStudyVersion()` + - `updateStudyDescription()` + - `updateTherapeuticArea()` + - `updateDeveloperInfo()` + - `updateLeadInfo()` + +### `README.md` + +For those unfamiliar with code development, the **README** file is a standard file used to introduce the contents of a repository, like a cover-page. It is the first file users see when they navigate to the repository page in your repository hosting service (i.e. BitBucket or Github). Therefore a strong README file is essential for a study. `Ulysses` provides the function `makeReadMe()` which initializes the README using inputs from the metadata stored in the `_study.yml`. -Following the Meta section, the user will need to provide a description of the study and information on the databases used in the study. Finally, the README provides links to important study information including the protocol, how to run and contributions files. Users can add as much as they please to the README file, `Ulysses` offers suggested guidance for starting it. Another feature offered by `Ulysses` is support for svg badges. These simple badges appear at the top of the README and provide useful information about the study. Badges seen in OHDSI studies include a study status badge and badges versioning the CDM and OMOP vocabulary. `Ulysses` will provide more support and documentation for badges in the future. -## The *NEWS* file +### `NEWS.md` -Another common file in software repositories is the NEWS file. The purpose of the NEWS file is to track changes to the software over time. Of course, version control software such as github keeps a record of the iterations of the study as it is developed, however it is helpful to have a "plain english" file that explains what has happened as the study has developed over time. NEWS files are often maintained via a [semantic versioning](https://semver.org/) system. OHDSI studies are not entirely software, however it is important to maintain order over the development of the technical pieces of the study. `Ulysses` offers a simple function that initiates this file, `makeNews`. +Another common file in software repositories is the NEWS file. The purpose of the NEWS file is to track changes to the software over time. Of course, version control software such as github keeps a record of the iterations of the study as it is developed, however it is helpful to have a "plain english" file that explains what has happened as the study has developed over time. NEWS files are often maintained via a [semantic versioning](https://semver.org/) system. OHDSI studies are not entirely software, however it is important to maintain order over the development of the technical pieces of the study. `Ulysses` offers a simple function that initiates this file, `makeNews()`. -```{r newsStart, echo=TRUE, eval=FALSE} -Ulysses::makeNews() -``` -# Handling database credentials +### `config.yml` -An important aspect of running an OHDSI study is handling credentials to connect to the Database Management System (DBMS) that hosts the OMOP data. Security of these credentials is very important. `Ulysses` offers support on handling these credentials. Credentials needed to run a study are as follows: +An important aspect of running an OHDSI study is handling credentials to connect to the Database Management System (DBMS) that hosts the OMOP data. Security of these credentials is very important. `Ulysses` offers support on handling these credentials through the `config.yml` file. Credentials needed to run a study are as follows: - **dbms**: the name of the dbms used to host the OMOP data - **user**: your user name needed to access the data in the dbms @@ -133,60 +214,3 @@ If we wanted to add another credential in this block we can add new line beneath Ulysses::makeKeyringSetup(configBlock = "example", database = "synpuf_110k") ``` -# Adding R scripts - -One way we can add analytical scripts to `Ulysses` is by using the line below - -```{r analysisScript, echo=TRUE, eval=FALSE} -Ulysses::makeAnalysisScript(scriptName = "buildCohorts") -``` - -This function will create a new R script written to the folder `analysis/studyTasks`. The R script will have a prefix of a number indicating the order in which the script should be executed. The first script for example will follow the syntax **01_**. `Ulysses` will automatically open this file to begin editing. - -Each analytical task is formatted with the following sections: - -A) File Info -> includes information about the file -B) Dependencies -> a list of libraries, options and source files required to run script -C) Connection -> set up connection to dbms -D) Variables -> set variables (parameters) needed for the script -E) Script -> the script to run -F) Session Info -> a summary of the session info and clean up - -To complement the analysis scripts, we can also create internal files. These are R files that contain functions or other code that needs to be sourced in the analysis. These files are saved in the `analysis/private` folder. Making an internal function can be done by the following: - -```{r internalScript, echo=TRUE, eval=FALSE} -Ulysses::makeInternals(internalsName = "buildCohorts") -``` - -The R package [`Strategus`](https://github.com/OHDSI/Strategus) helps execute OHDSI analytics. Analytical modules are executed via `Strategus`. This paradigm to OHDSI studies can also be handled by `Ulysses`. More support for using `Strategus` with `Ulysses` will be explored in future releases. - -# Adding Documenation - -An important part of a study repository is communicating its contents to study nodes. A study node in a network study must understand the scientific components of the study, how to run the study locally and how to contribute towards the study. `Ulysses` provides functions to help develop documentation to communicate the study to participants in the OHDSI network. - -## Analysis Specification - -A study requires a protocol or a study analysis plan (SAP), specifying the scientific components of the study. These documents specify the study design, definition of the target, exposure and outcome cohorts and how the data analysis is conducted. This documentation is important because it provides guidance and rationale for the study. Many study nodes also require submission of documentation to an institutional review board to justify execution of the study. `Ulysses` provides templates for an OHDSI protocol, PASS protocols and a suggested format for a SAP. Below are examples of building these templates: - -```{r doc1, echo=TRUE, eval=FALSE} -Ulysses::makeOhdsiProtocol() -Ulysses::makePassProtocol() -Ulysses::makeStudySAP() -``` - -## How to Run - -Next, a repository needs to communicate how to run the study. This document informs study nodes on technical requirements needed to run the study, provides instructions on installations, and the process of running the study. OHDSI studies are designed in several different ways, so it is important that the developer explains how this study should be run. Below is an example of how to create the `howToRun.md` file: - -```{r doc2, echo=TRUE, eval=FALSE} -Ulysses::makeHowToRun(org = "Ohdsi", repo = "my_ohdsi_study") -``` - - -## Contributing - -Finally, the repository needs to communicate how study nodes can contribute to the study. This include information on posting results, asking for help and code of conduct. Contribution guidelines are standard documentation of software and would be helpful additions to OHDSI studies. To create a template contribution guideline follow the example below: - -```{r doc3, echo=TRUE, eval=FALSE} -Ulysses::makeContributionGuidelines() -``` diff --git a/vignettes/ulysses_directory.Rmd b/vignettes/ulysses_directory.Rmd deleted file mode 100644 index c473f5d..0000000 --- a/vignettes/ulysses_directory.Rmd +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: "Introduction to Ulysses Directory" -output: rmarkdown::html_vignette -vignette: > - %\VignetteIndexEntry{Introduction to Ulysses Directory} - %\VignetteEngine{knitr::rmarkdown} - %\VignetteEncoding{UTF-8} ---- - -```{r, include = FALSE} -knitr::opts_chunk$set( - collapse = TRUE, - comment = "", - message = FALSE, - echo = FALSE -) -``` - -```{r setup} -library(Ulysses) -``` - - -# Introduction - -Running an OHDSI study is exciting effort that can lead to meaningful new evidence on clinical questions across a network of study participants who have data mapped to the OMOP CDM. However, there are a lot of tasks to keep track to make an OHDSI study successful. We introduce the `Ulysses` R package, as a tool to assist in the development and organization of an OHDSI study. The idea of the `Ulysses` package is inspired by the [`usethis` package](https://usethis.r-lib.org/) that is used to assist in the development workflow of novel R packages and projects alike. Similar to the development of an R package, there are several steps and pieces of documentation needed in an OHDSI study to effectively run the study across the OHDSI network. By providing functions that automate tasks and provide consistent structure to OHDSI studies, `Ulysses` attempts to help users develop and communicate new OHDSI studies. - -# Directory Structure - -The first step towards assisting OHDSI studies is to introduce a consistent directory structure that contains also necessary components towards executing a study and is easy to follow. Below is a proposed directory structure, offered by the `Ulysses` package for OHDSI studies. - -![Ulysses Style OHDSI Study Directory](images/ulysses_directory.png) - - -### Analysis Folder - -The analysis folder contains files that are required for running an OHDSI study. There are three sub-folders: *private*, *settings* and *studyTasks*. The *studyTasks* folder contains files needed to run the OHDSI study. These could be several files in a pipeline (i.e. `01_buildCohorts.R`, `02_buildStrata.R`, `03_baselineCharacteristics.R`) or a single strategus json file that contains details of the modules to run. Next, the *settings* folder contains any files that provide details of the analysis settings. For example, this folder could contain scripts that specify the settings of an incidence analysis to run in the study. Likewise, this folder could contain the `createStrategusAnalysisSpecification.R` which creates the strategus json to run the analysis. Finally, the *private* folder contains any internal files needed to run the analysis. For example this could include internal functions to run a study script. The `Ulysses` package offers functions to help develop components of the analysis such as: - -- `makeAnalysisScript`: initializes an organized .R file, pre-rendered with details about the analysis. -- `makeInternals`: creates a .R file used for developing internal functions. - -### Cohorts to Create Folder - -OHDSI studies revolve around generated cohort definitions used to enumerate persons with a particular clinical occurrence (i.e. persons prescribed ACE Inhibitors for first time). Keeping track of these cohort definitions, is very important for a successful OHDSI study. Clinical phenotypes often change during the development of studies, so it is very important to keep the latest cohort definition json files organized. The *cohortsToCreate* folder stores all the json files of cohort definitions used in the study. They are organized in numbered folders that are listed at the developers description. By default, `Ulysses` creates a starting `01_target` folder to store the target cohort definitions of the study. `Ulysses` offers functions that support the organization of this folder, such as: - -- `makeCohortFolder`: initializes a new folder to store cohort definitions, i.e. a new folder for comparator cohorts -- `makeCohortDetails`: a markdown file that provides "plain english" descriptions of the cohort definitions and tracks updates. - -### Documentation Folder - -An OHDSI study consists of lots of documentation that effectively communicate what the study is, how to run it and how to participate. There are three key files stored in this folder: - -- **Study Protocol**: the protocol offers guidance on the scientific methods used to conduct the study and justification for why scientific decisions were made. `Ulysses` auto-generates a skeleton file via `makeOhdisProtocol` or `makePassProtocol`. -- **How To Run**: a file is needed that provides all technical specifications and instructions needed to run the study at a site. This file provides information on how to download the OHDSI study, prepare the environment for running the study, executing the study and how to dissiminate the results to the study host. `Ulysses` auto-generates a skeleton file via `makeHowToRun` -- **Contribution Guidelines**: a file is required to communicate how others can contribute to the study. Contributions can range from simply running the study to providing significant development. OHDSI studies require transparency to nodes on what are the rules and expectations for meaningful contribution to the study. `Ulysses` auto-generates a skeleton file via `makeContribution` - -There exist scenarios when a full-fledged protocol is not required for a study. While a study protocol is not required by the institution running the study, it is still good practice to provide guidance on the scientific decision making for the study. `Ulysses` offers a skeleton file called the *Study SAP*, implemented via `makeStudySAP`, that gives structure to the methods and rationale for the study while not being as formal as a study protocol. - -The documentation folder may also contain other files that are essential for communicating important aspects of the study. - -### Results Folder - -When an OHDSI study is executed, we require a location to store the results in an organized fashion. These results can be easily zipped and sent to the study host. `Ulysses` initializes a *results* folder that can be used as a target for the output. The results folder is automatically added to the `.gitignore` so that results are not accidentally committed to github repository of the OHDSI study. We intend to add functions to compliment the results folder in the future. - -### Logs Folder - -Running an OHDSI study is like executing a pipeline of tasks. It is vital that we know what is going on in the pipeline, whether an error has occurred or when an execution has taken place. Loggers are an important part of a pipeline and likewise an OHDSI study. `Ulysses` offers a folder to save logs in a single location. The log folder is is automatically added to the `.gitignore` so that results are not accidentally committed to github repository of the OHDSI study. - -### Extras Folder - -OHDSI studies sometimes contain files that are important to a study but do not have a natural save location; the extras folder hosts these files. A prime use for the extras folder is for scripts or files that are ancillary to the main study. For example scripts such as `KeyringSetup.R` are helpful for running the study but not core to the study itself. `Ulysses` offers functions that support the extras folder. - -### \_study.yml - -The final file initiated by `Ulysses` is the `_study.yml` file. This is a meta file that provides an overview of the study. It contains information about who is the study lead, the date the study started and the full name of the study. We plan to expand upon this meta file as we feel quality meta data for a study is useful for 1) automating start-up tasks and 2) providing records to users. - - - -