Repository: FredHutch/VISCtemplates
Pull request #233: Create README files at assay folder level, and clean up inst/ folder
Author: login: kelliemac
Created: 2024-09-04T23:04:46Z | Merged: 2025-03-24T21:56:24Z

## Description

Instead of creating a README file for each PT report at the time of knitting to visc_pdf_document or visc_word_document, the README file will now be at the assay level and created at the first time that use_visc_report() is called within an assay folder.

## Related Issues

Related to https://github.com/FredHutch/VISCtemplates/issues/92

## Checklist

- [ ] This PR includes unit tests
- [ ] This PR establishes a new function or updates parameters in an existing function
  - [ ]  The roxygen skeleton for this function has been updated using `devtools::document`
- [x] I have updated NEWS.md to describe the proposed changes



Diff:
diff --git a/NEWS.md b/NEWS.md
index 53e093b1..8549c1ce 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -14,6 +14,9 @@ Other improvements
 * Add auxiliary files to template .gitignore (.aux, .toc, .lof, .lot, .out, cache files, and .smbdelete files) (#230)
 * Update names in template acknowledgements section (#234)
 * Gitignore html files in data-raw via use_visc_gitignore() (#254)
+* Structured README.md files are now created at the assay folder level at the time of calling use_visc_report(),
+and minimally structured README.md files are created at the report folder level at the same time (#233)
+* Reorganized inst/ folder within package for clarity (#233)
 * Add explicit reference to the version of the data package being installed, and note about changing if needed (#257)
 * Update installation of system dependencies and R packages on CI runners (#261, #265)
 
diff --git a/R/use_visc_report.R b/R/use_visc_report.R
index 34897742..c5153f62 100644
--- a/R/use_visc_report.R
+++ b/R/use_visc_report.R
@@ -89,7 +89,7 @@ use_project_objectives <- function(study_name) {
 
 use_group_colors <- function(study_name) {
   usethis::use_template(
-    template = "group_colors.R",
+    template = "visc-project-group-colors.R",
     save_as = "R/group_colors.R",
     data = list(study_name = study_name),
     package = "VISCtemplates"
@@ -98,7 +98,7 @@ use_group_colors <- function(study_name) {
 
 use_study_schema <- function(study_name) {
   usethis::use_template(
-    template = "study_schema.R",
+    template = "visc-project-study-schema.R",
     save_as = "R/study_schema.R",
     data = list(study_name = study_name),
     package = "VISCtemplates"
@@ -107,7 +107,7 @@ use_study_schema <- function(study_name) {
 
 use_bib <- function(study_name) {
   usethis::use_template(
-    template = "bibliography.bib",
+    template = "visc-project-bibliography.bib",
     save_as = "docs/bibliography.bib",
     data = list(study_name = study_name),
     package = "VISCtemplates"
@@ -134,12 +134,16 @@ use_bib <- function(study_name) {
 #'   report_type = "bama"
 #'   )
 #' }
-use_visc_report <- function(report_name = "PTreport",
+use_visc_report <- function(report_name = "VDCnnn_assay_PTreport",
                             path = ".",
                             report_type = c("empty", "generic", "bama", "nab", "adcc"),
                             interactive = TRUE) {
 
-  stopifnot(report_type %in% c("empty", "generic", "bama", "nab", "adcc"))
+  report_type <- match.arg(report_type)
+
+  if (dirname(report_name) != ".") {
+    stop("report_name cannot include a subdirectory. you can instead specify a subdirectory using the path argument of use_visc_report().")
+  }
 
   # suppress usethis output when non-interactive
   old_usethis_quiet <- getOption('usethis.quiet')
@@ -147,28 +151,75 @@ use_visc_report <- function(report_name = "PTreport",
   options(usethis.quiet = !interactive)
 
   if (report_type != 'empty') challenge_visc_report(report_name, interactive)
-  if (!dir.exists(path)) dir.create(path, recursive = TRUE)
-  use_template <- paste0(
+
+  # create assay level folder (specified in path) and readme, if don't yet exist
+  if (!dir.exists(path)) {
+    dir.create(path, recursive = TRUE)
+
+    usethis::use_template(
+      template = "README_assay_folder.md",
+      data = list(study_name = get_study_name(report_name), assay_name = get_assay_name(report_name)),
+      save_as = file.path(path, "README.md"),
+      package = "VISCtemplates"
+    )
+  }
+
+  # create report folder and main Rmd document
+  visc_report_type <- paste0(
     'visc', '_', if (report_type == 'empty') 'empty' else 'report'
   )
   rmarkdown::draft(
     file = file.path(path, report_name),
-    template = use_template,
-    package = "VISCtemplates",
+    template = system.file("templates", visc_report_type, package = "VISCtemplates"),
     edit = FALSE
   )
+
   usethis::ui_done(
-    glue::glue("Creating {{report_type}} VISC report at '{{file.path(path, report_name)}}'")
+    glue::glue("Created {{report_type}} VISC report at '{{file.path(path, report_name)}}'")
   )
-  if (report_type != 'empty') {
+
+  # create readme for report folder
+  usethis::use_template(
+    template = "README_report_folder.md",
+    data = list(),
+    save_as = file.path(path, report_name, "README.md"),
+    package = "VISCtemplates"
+  )
+
+  # add draft methods
+  if (report_type != 'empty'){
     use_visc_methods(path = file.path(path, report_name), assay = report_type,
                      interactive = interactive)
   }
 
+}
 
+# function to infer study name from report name
+get_study_name <- function(report_name) {
+  underscore_positions <- gregexpr('\\_', report_name)[[1]]
+  n_underscores <- length(underscore_positions[underscore_positions != -1])
+  if (n_underscores >= 2) {
+    study_name <- strsplit(report_name, '_')[[1]][1]
+  } else {
+    study_name <- "Study"
+  }
+  return(study_name)
+}
+
+# function to infer assay name from report name
+get_assay_name <- function(report_name) {
+  underscore_positions <- gregexpr('\\_', report_name)[[1]]
+  n_underscores <- length(underscore_positions[underscore_positions != -1])
+  if (n_underscores >= 2) {
+    assay_name <- strsplit(report_name, '_')[[1]][2]
+  } else {
+    assay_name <- "Assay"
+  }
+  return(assay_name)
 }
 
 challenge_visc_report <- function(report_name, interactive = TRUE) {
+
   if (!interactive) return(invisible(NULL))
 
   continue <- usethis::ui_yeah("
diff --git a/R/visc_output_document.R b/R/visc_output_document.R
index b8eb06d2..5755a490 100644
--- a/R/visc_output_document.R
+++ b/R/visc_output_document.R
@@ -15,11 +15,12 @@
 visc_pdf_document <- function(latex_engine = "pdflatex",
                               keep_tex = TRUE,
                               ...) {
-  template <- find_resource("visc_report", "template.tex")
 
-  logo_path_scharp <- find_resource("visc_report", "SCHARP_logo.png")
-  logo_path_fh <- find_resource("visc_report", "FredHutch_logo.png")
-  logo_path_visc <- find_resource("visc_report", "VISC_logo.jpg")
+  template <- system.file("templates", "report_latex_template.tex", package = "VISCtemplates")
+
+  logo_path_scharp <- find_logo("SCHARP_logo.png")
+  logo_path_fh <- find_logo("FredHutch_logo.png")
+  logo_path_visc <- find_logo("VISC_logo.jpg")
 
   # If no project-level bib file creating report specific bib
   if (!file.exists(
@@ -31,10 +32,6 @@ visc_pdf_document <- function(latex_engine = "pdflatex",
               overwrite = FALSE)
   }
 
-  file.copy(from = find_resource("visc_report", "README_PT_Report.md"),
-            to = "README.md",
-            overwrite = FALSE)
-
   # switch for a breaking change in pandoc template, see notes in template.tex
   use_old_csl_refs <- tolower(rmarkdown::pandoc_version() < '3.1.7')
 
@@ -73,7 +70,7 @@ visc_word_document <- function(toc = TRUE,
                                keep_md = TRUE,
                                ...) {
 
-  word_style_path <- find_resource("visc_report", "word-styles-reference.docx")
+  word_style_path <- system.file("templates", "report_word_template.docx", package = "VISCtemplates")
 
   # If no project-level bib file creating report specific bib
   if (!file.exists(
@@ -85,10 +82,6 @@ visc_word_document <- function(toc = TRUE,
               overwrite = FALSE)
   }
 
-  file.copy(from = find_resource("visc_report", "README_PT_Report.md"),
-            to = "README.md",
-            overwrite = FALSE)
-
   bookdown::word_document2(
     toc = toc,
     fig_caption = fig_caption,
@@ -98,12 +91,14 @@ visc_word_document <- function(toc = TRUE,
     ...)
 }
 
-find_resource <- function(template, file = 'template.tex', package = "VISCtemplates") {
+
+find_logo <- function(filename) {
   res <- system.file(
-    "rmarkdown", "templates", template, "resources", file, package = package
+    "logos", filename, package = "VISCtemplates"
   )
   if (res == "") stop(
-    "Couldn't find template file ", template, "/resources/", file, call. = FALSE
+    "Couldn't find logo file ", filename, call. = FALSE
   )
   res
 }
+
diff --git a/README.md b/README.md
index 9664956d..df0e8af1 100644
--- a/README.md
+++ b/README.md
@@ -9,13 +9,14 @@ coverage](https://codecov.io/gh/FredHutch/VISCtemplates/graph/badge.svg)](https:
 
 # VISCtemplates
 
-The goal of VISCtemplates is to:
+The goal of the VISCtemplates package is to:
 
-- automate project setup
-- provide a common, easy-to-understand directory structure across
-  analyses
+- automate VISC project setup
+- provide a common, easy-to-understand directory structure across VISC analyses
 - provide consistency across VISC reports
 
+Most of the actual template files (including rmarkdown, latex, and docx files) are located in the `inst/templates/` folder, while convenience functions in R (building on the style and functionality of the [usethis](https://github.com/r-lib/usethis) package) for setting up VISC projects and reports can be found in the `R` folder.
+
 ## Installation
 
 The package is available on the Fred Hutch organization GitHub page.
diff --git a/inst/rmarkdown/templates/visc_report/resources/FredHutch_logo.png b/inst/logos/FredHutch_logo.png
similarity index 100%
rename from inst/rmarkdown/templates/visc_report/resources/FredHutch_logo.png
rename to inst/logos/FredHutch_logo.png
diff --git a/inst/rmarkdown/templates/visc_report/resources/SCHARP_logo.png b/inst/logos/SCHARP_logo.png
similarity index 100%
rename from inst/rmarkdown/templates/visc_report/resources/SCHARP_logo.png
rename to inst/logos/SCHARP_logo.png
diff --git a/inst/rmarkdown/templates/visc_report/resources/VISC_logo.jpg b/inst/logos/VISC_logo.jpg
similarity index 100%
rename from inst/rmarkdown/templates/visc_report/resources/VISC_logo.jpg
rename to inst/logos/VISC_logo.jpg
diff --git a/inst/rmarkdown/templates/visc_report/resources/README_PT_Report.md b/inst/rmarkdown/templates/visc_report/resources/README_PT_Report.md
deleted file mode 100644
index 6007b374..00000000
--- a/inst/rmarkdown/templates/visc_report/resources/README_PT_Report.md
+++ /dev/null
@@ -1,20 +0,0 @@
-## Report history
-
-<!-- Use a permanent link (with git hash) to link to any data specs and 
-     to the version of the report sent to the VDC. 
-     
-<!-- To find the appropriate commit hash and report link: 
-       - Navigate to the file on GitHub
-       - Click the history button
-       - Click the commit corresponding to the distributed report
-       - Find the report among the edits and click "View"
-       - The hash is url: https://github.com/fredhutch/.../blob/hash/... -->
-
-| **Version** | **Date sent to VDC**| **Unblinded** | **Data Spec.**| **Commit link** |
-|------------------|-----------------|------------------|-----------------|------------------|-----------------|
-|1.0 | [Date] | [Yes/No] |[Data Spec.](permanent link) | [hash](https://github.com/fredhutch/...) |
-
-
-## Analysis notes
-
-<!-- If there is something worth noting about the methods or report versions, briefly describe that here. -->
diff --git a/inst/templates/README_assay_folder.md b/inst/templates/README_assay_folder.md
new file mode 100644
index 00000000..a798a098
--- /dev/null
+++ b/inst/templates/README_assay_folder.md
@@ -0,0 +1,35 @@
+## Overview of {{ study_name}} {{ assay_name }} Reports
+
+<!-- Use a permanent link (with git tag or hash) to link to any data specs and 
+     to the version of the report sent to the VDC. -->
+
+<!-- Consider using a tag instead of just the hash to make it easier to compare report versions.
+     Tags are also more meaningful and human-readable. -->
+     
+<!-- To find the appropriate commit hash and report link: 
+       - Navigate to the file on GitHub
+       - Click the history button
+       - Click the commit corresponding to the distributed report
+       - Find the report among the edits and click "View"
+       - The hash is url: https://github.com/fredhutch/.../blob/hash/... -->
+
+| **Report Version** | **Date Sent to VDC**| **Unblinded** | **Data Spec. and Link**| **Commit Tag/Hash and Link** |
+|-------------|---------------------|---------------|---------------|-----------------|
+| **Report Version** | **Date sent to VDC** | **Unblinded** |  **Report Commit Tag/Hash and Link**    | **Pdata location** | **Pdata Commit**| 
+|-----------|----------------------|-------------------|-------------|-------------------|---------------|
+|1.0 | [Date] | [Yes/No] | [tag/hash](https://github.com/fredhutch/...) | [location]  |  [hash]  | 
+
+For additional data, supplement table (long-format by report version if multiple data)
+
+| *Report Version* | *Data description* | *Data location* | *Data date*| 
+|-----------|----------------------|-------------------|------------------|
+|  1.0| [description]| [path]|  [Date]|   
+|  1.0| [description]| [path]|  [Date]|   
+
+
+
+## Analysis Notes
+
+If there is anything worth noting about the report versions or methods, briefly describe that here.
+
+More detailed descriptions specific to an individual report version can go in the README file within that report's folder.
diff --git a/inst/templates/README_report_folder.md b/inst/templates/README_report_folder.md
new file mode 100644
index 00000000..5a0ba559
--- /dev/null
+++ b/inst/templates/README_report_folder.md
@@ -0,0 +1,3 @@
+## Notes on [Insert PT Report Title]
+
+Include any notes here that would be helpful for a new person (or possibly yourself a year or two from now) trying to understand this PT report context or contents, folder structure, or the underlying code.
diff --git a/inst/rmarkdown/templates/visc_report/resources/template.tex b/inst/templates/report_latex_template.tex
similarity index 100%
rename from inst/rmarkdown/templates/visc_report/resources/template.tex
rename to inst/templates/report_latex_template.tex
diff --git a/inst/rmarkdown/templates/visc_report/resources/word-styles-reference.docx b/inst/templates/report_word_template.docx
similarity index 100%
rename from inst/rmarkdown/templates/visc_report/resources/word-styles-reference.docx
rename to inst/templates/report_word_template.docx
diff --git a/inst/rstudio/templates/project/VISCtemplates.dcf b/inst/templates/rstudio-project/VISCtemplates.dcf
similarity index 100%
rename from inst/rstudio/templates/project/VISCtemplates.dcf
rename to inst/templates/rstudio-project/VISCtemplates.dcf
diff --git a/inst/templates/bibliography.bib b/inst/templates/visc-project-bibliography.bib
similarity index 100%
rename from inst/templates/bibliography.bib
rename to inst/templates/visc-project-bibliography.bib
diff --git a/inst/templates/group_colors.R b/inst/templates/visc-project-group-colors.R
similarity index 100%
rename from inst/templates/group_colors.R
rename to inst/templates/visc-project-group-colors.R
diff --git a/inst/templates/study_schema.R b/inst/templates/visc-project-study-schema.R
similarity index 100%
rename from inst/templates/study_schema.R
rename to inst/templates/visc-project-study-schema.R
diff --git a/inst/rmarkdown/templates/visc_empty/skeleton/skeleton.Rmd b/inst/templates/visc_empty/skeleton/skeleton.Rmd
similarity index 100%
rename from inst/rmarkdown/templates/visc_empty/skeleton/skeleton.Rmd
rename to inst/templates/visc_empty/skeleton/skeleton.Rmd
diff --git a/inst/rmarkdown/templates/visc_empty/template.yaml b/inst/templates/visc_empty/template.yaml
similarity index 100%
rename from inst/rmarkdown/templates/visc_empty/template.yaml
rename to inst/templates/visc_empty/template.yaml
diff --git a/inst/rmarkdown/templates/visc_report/skeleton/skeleton.Rmd b/inst/templates/visc_report/skeleton/skeleton.Rmd
similarity index 100%
rename from inst/rmarkdown/templates/visc_report/skeleton/skeleton.Rmd
rename to inst/templates/visc_report/skeleton/skeleton.Rmd
diff --git a/inst/rmarkdown/templates/visc_report/template.yaml b/inst/templates/visc_report/template.yaml
similarity index 100%
rename from inst/rmarkdown/templates/visc_report/template.yaml
rename to inst/templates/visc_report/template.yaml
diff --git a/man/use_visc_report.Rd b/man/use_visc_report.Rd
index 086cd8fd..1df64d33 100644
--- a/man/use_visc_report.Rd
+++ b/man/use_visc_report.Rd
@@ -5,7 +5,7 @@
 \title{Use a VISC Report Template}
 \usage{
 use_visc_report(
-  report_name = "PTreport",
+  report_name = "VDCnnn_assay_PTreport",
   path = ".",
   report_type = c("empty", "generic", "bama", "nab", "adcc"),
   interactive = TRUE
diff --git a/tests/testthat/test-use_visc_report.R b/tests/testthat/test-use_visc_report.R
index 5316610a..8283512f 100644
--- a/tests/testthat/test-use_visc_report.R
+++ b/tests/testthat/test-use_visc_report.R
@@ -1,18 +1,66 @@
-test_that("use_visc_report() creates missing subdirectory", {
+test_that("use_visc_report() creates main report .Rmd file and assay and report level README files, even if specified path does not already exist", {
   temp_dir <- withr::local_tempdir()
   create_visc_project(temp_dir, interactive = FALSE)
   local({
     withr::local_dir(temp_dir)
     report_name <- "Caskey820_BAMA_PT_Report"
+    report_type <- "bama"
     path <- "BAMA"
     expect_no_warning(
       use_visc_report(
-        report_name, path = path, report_type = "bama", interactive = FALSE
+        report_name, path = path, report_type = report_type, interactive = FALSE
       )
     )
     expect_true(
       file.exists(file.path(path, report_name, paste0(report_name, ".Rmd")))
     )
+    expect_true(
+      # report level readme file exists
+      file.exists(file.path(path, report_name, "README.md"))
+    )
+    expect_true(
+      # assay level readme file exists
+      file.exists(file.path(path, "README.md"))
+    )
+  })
+})
+
+test_that("use_visc_report() creates main report .Rmd file and assay and report level README files, even if report_type not specified and report_name doesn't use correct formatting", {
+  temp_dir <- withr::local_tempdir()
+  create_visc_project(temp_dir, interactive = FALSE)
+  local({
+    withr::local_dir(temp_dir)
+    report_name <- "NonstandardReportName"
+    expect_no_warning(
+      use_visc_report(
+        report_name, interactive = FALSE
+      )
+    )
+    expect_true(
+      file.exists(file.path(report_name, paste0(report_name, ".Rmd")))
+    )
+    expect_true(
+      # report level readme file exists
+      file.exists(file.path(report_name, "README.md"))
+    )
+    expect_true(
+      # assay level readme file exists
+      file.exists(file.path("README.md"))
+    )
+  })
+})
+
+test_that("use_visc_report() throws error if subdirectory included in report_name argument", {
+  temp_dir <- withr::local_tempdir()
+  create_visc_project(temp_dir, interactive = FALSE)
+  local({
+    withr::local_dir(temp_dir)
+    report_name <- "BAMA/Caskey820_BAMA_PT_Report"
+    expect_error(
+      use_visc_report(
+        report_name, report_type = "bama", interactive = FALSE
+      )
+    )
   })
 })
 


Reviews:
user: login: slager
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-02-04T18:58:16Z
user: login: slager
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-02-04T19:07:25Z
user: login: kelliemac
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-04T18:09:01Z
user: login: kelliemac
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-04T18:09:30Z
user: login: kelliemac
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-04T18:10:32Z
user: login: asatofh
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-17T18:19:44Z
user: login: kelliemac
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-22T00:08:41Z
user: login: kelliemac
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-22T00:55:57Z
user: login: mayerbry
state: APPROVED
author_association: CONTRIBUTOR
submitted_at: 2025-03-24T18:00:22Z
user: login: slager
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-24T21:16:03Z
user: login: slager
body: Approving with the comment about the `<-` operator, and just noting that Codecov annotates about 3 places in `R/` where there are new untested code branches.  Up to you @kelliemac if you think it's worth making unit tests for those.
state: APPROVED
author_association: CONTRIBUTOR
submitted_at: 2025-03-24T21:22:10Z

Review comments:
diff_hunk: @@ -147,20 +147,44 @@ use_visc_report <- function(report_name = "PTreport",
   options(usethis.quiet = !interactive)
 
   if (report_type != 'empty') challenge_visc_report(report_name, interactive)
-  if (!dir.exists(path)) dir.create(path, recursive = TRUE)
-  use_template <- paste0(
+
+  # create assay level folder (specified in path) and readme, if don't yet exist
+  if (!dir.exists(path)) {
+    dir.create(path, recursive = TRUE)
+    study_name <- strsplit(report_name, '_')[[1]][1]
path: R/use_visc_report.R
user: login: slager
body: These two lines assume pretty rigid expectations for how `report_name` is structured.  Do more thorough checks on report_name earlier that include informative error messages?
created_at: 2025-02-04T18:58:16Z
author_association: CONTRIBUTOR
diff_hunk: @@ -98,12 +91,14 @@ visc_word_document <- function(toc = TRUE,
     ...)
 }
 
-find_resource <- function(template, file = 'template.tex', package = "VISCtemplates") {
+
+find_logo <- function(filename) {
path: R/visc_output_document.R
user: login: slager
body: This internal helper function could maybe be deleted, and just replaced by system.file() / file.path() calls nearer to where it is used?
created_at: 2025-02-04T19:07:25Z
author_association: CONTRIBUTOR
diff_hunk: @@ -147,20 +147,44 @@ use_visc_report <- function(report_name = "PTreport",
   options(usethis.quiet = !interactive)
 
   if (report_type != 'empty') challenge_visc_report(report_name, interactive)
-  if (!dir.exists(path)) dir.create(path, recursive = TRUE)
-  use_template <- paste0(
+
+  # create assay level folder (specified in path) and readme, if don't yet exist
+  if (!dir.exists(path)) {
+    dir.create(path, recursive = TRUE)
+    study_name <- strsplit(report_name, '_')[[1]][1]
path: R/use_visc_report.R
user: login: kelliemac
body: I think that this shows up elsewhere in the code? Need to check
created_at: 2025-03-04T18:09:01Z
author_association: CONTRIBUTOR
diff_hunk: @@ -147,20 +147,44 @@ use_visc_report <- function(report_name = "PTreport",
   options(usethis.quiet = !interactive)
 
   if (report_type != 'empty') challenge_visc_report(report_name, interactive)
-  if (!dir.exists(path)) dir.create(path, recursive = TRUE)
-  use_template <- paste0(
+
+  # create assay level folder (specified in path) and readme, if don't yet exist
+  if (!dir.exists(path)) {
+    dir.create(path, recursive = TRUE)
+    study_name <- strsplit(report_name, '_')[[1]][1]
path: R/use_visc_report.R
user: login: kelliemac
body: Consider writing a helper function `get_study_name()` instead
created_at: 2025-03-04T18:09:30Z
author_association: CONTRIBUTOR
diff_hunk: @@ -98,12 +91,14 @@ visc_word_document <- function(toc = TRUE,
     ...)
 }
 
-find_resource <- function(template, file = 'template.tex', package = "VISCtemplates") {
+
+find_logo <- function(filename) {
path: R/visc_output_document.R
user: login: kelliemac
body: Note to self: check if shows up anywhere else? 
created_at: 2025-03-04T18:10:32Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,25 @@
+## Overview of {{ study_name}} {{ assay_name }} Reports
+
+<!-- Use a permanent link (with git tag or hash) to link to any data specs and 
+     to the version of the report sent to the VDC. -->
+
+<!-- Consider using a tag instead of just the hash to make it easier to compare report versions.
+     Tags are also more meaningful and human-readable. -->
+     
+<!-- To find the appropriate commit hash and report link: 
+       - Navigate to the file on GitHub
+       - Click the history button
+       - Click the commit corresponding to the distributed report
+       - Find the report among the edits and click "View"
+       - The hash is url: https://github.com/fredhutch/.../blob/hash/... -->
+
+| **Report Version** | **Date Sent to VDC**| **Unblinded** | **Data Spec. and Link**| **Commit Tag/Hash and Link** |
+|-------------|---------------------|---------------|---------------|-----------------|
+|1.0 | [Date] | [Yes/No] |[Data Spec.](permanent link) | [tag/hash](https://github.com/fredhutch/...) |
path: inst/templates/README_assay_folder.md
user: login: asatofh
body: ```suggestion
| **Report Version** | **Date sent to VDC** | **Unblinded** |  **Report Commit Tag/Hash and Link**    | **Pdata location** | **Pdata Commit**| 
|-----------|----------------------|-------------------|-------------|-------------------|---------------|
|1.0 | [Date] | [Yes/No] | [tag/hash](https://github.com/fredhutch/...) | [location]  |  [hash]  | 

For additional data, supplement table (long-format by report version if multiple data)

| *Report Version* | *Data description* | *Data location* | *Data date*| 
|-----------|----------------------|-------------------|------------------|
|  1.0| [description]| [path]|  [Date]|   
|  1.0| [description]| [path]|  [Date]|   

```
Suggested based on git issue: https://github.com/FredHutch/VISCtemplates/issues/260
created_at: 2025-03-17T18:19:43Z
author_association: CONTRIBUTOR
diff_hunk: @@ -98,12 +91,14 @@ visc_word_document <- function(toc = TRUE,
     ...)
 }
 
-find_resource <- function(template, file = 'template.tex', package = "VISCtemplates") {
+
+find_logo <- function(filename) {
path: R/visc_output_document.R
user: login: kelliemac
body: I am going to leave this for now. I think the main use is that it will provide a more descriptive error message if any issues with the logo files appear during CI in the future. We can consider changing this later, though.
created_at: 2025-03-22T00:08:41Z
author_association: CONTRIBUTOR
diff_hunk: @@ -147,20 +147,44 @@ use_visc_report <- function(report_name = "PTreport",
   options(usethis.quiet = !interactive)
 
   if (report_type != 'empty') challenge_visc_report(report_name, interactive)
-  if (!dir.exists(path)) dir.create(path, recursive = TRUE)
-  use_template <- paste0(
+
+  # create assay level folder (specified in path) and readme, if don't yet exist
+  if (!dir.exists(path)) {
+    dir.create(path, recursive = TRUE)
+    study_name <- strsplit(report_name, '_')[[1]][1]
path: R/use_visc_report.R
user: login: kelliemac
body: added error handling in case this doesn't work nicely
created_at: 2025-03-22T00:55:57Z
author_association: CONTRIBUTOR
diff_hunk: @@ -1,18 +1,66 @@
-test_that("use_visc_report() creates missing subdirectory", {
+test_that("use_visc_report() creates main report .Rmd file and assay and report level README files, even if specified path does not already exist", {
   temp_dir <- withr::local_tempdir()
   create_visc_project(temp_dir, interactive = FALSE)
   local({
     withr::local_dir(temp_dir)
     report_name <- "Caskey820_BAMA_PT_Report"
+    report_type = "bama"
path: tests/testthat/test-use_visc_report.R
user: login: slager
body: Suggest using standard `<-` assignment operator
created_at: 2025-03-24T21:16:03Z
author_association: CONTRIBUTOR

PR comments:
user: login: kelliemac
created_at: 2024-09-05T19:03:38Z
body: @mayerbry to review this PR! Alicia gave verbal approval at our meeting today.
author_association: CONTRIBUTOR
user: login: kelliemac
created_at: 2025-01-07T18:24:21Z
body: Per group discussion on 1/7, ok to move templated README to assay level, and also create a blank README file for each report.
author_association: CONTRIBUTOR
user: login: codecov[bot]
created_at: 2025-01-11T01:21:22Z
body: ## [Codecov](https://app.codecov.io/gh/FredHutch/VISCtemplates/pull/233?dropdown=coverage&src=pr&el=h1&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=FredHutch) Report
Attention: Patch coverage is `93.02326%` with `3 lines` in your changes missing coverage. Please review.
> Project coverage is 82.24%. Comparing base [(`082a90d`)](https://app.codecov.io/gh/FredHutch/VISCtemplates/commit/082a90d9ec646f005f84c32ae230ebe7cf8a2837?dropdown=coverage&el=desc&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=FredHutch) to head [(`eece718`)](https://app.codecov.io/gh/FredHutch/VISCtemplates/commit/eece7185d4346d76d0237b324d187e4398d106c0?dropdown=coverage&el=desc&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=FredHutch).

| [Files with missing lines](https://app.codecov.io/gh/FredHutch/VISCtemplates/pull/233?dropdown=coverage&src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=FredHutch) | Patch % | Lines |
|---|---|---|
| [R/use\_visc\_report.R](https://app.codecov.io/gh/FredHutch/VISCtemplates/pull/233?src=pr&el=tree&filepath=R%2Fuse_visc_report.R&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=FredHutch#diff-Ui91c2VfdmlzY19yZXBvcnQuUg==) | 94.44% | [2 Missing :warning: ](https://app.codecov.io/gh/FredHutch/VISCtemplates/pull/233?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=FredHutch) |
| [R/visc\_output\_document.R](https://app.codecov.io/gh/FredHutch/VISCtemplates/pull/233?src=pr&el=tree&filepath=R%2Fvisc_output_document.R&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=FredHutch#diff-Ui92aXNjX291dHB1dF9kb2N1bWVudC5S) | 85.71% | [1 Missing :warning: ](https://app.codecov.io/gh/FredHutch/VISCtemplates/pull/233?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=FredHutch) |

<details><summary>Additional details and impacted files</summary>


```diff
@@             Coverage Diff             @@
##           develop     #233      +/-   ##
===========================================
+ Coverage    81.79%   82.24%   +0.44%     
===========================================
  Files            8        8              
  Lines          346      366      +20     
===========================================
+ Hits           283      301      +18     
- Misses          63       65       +2     
```

</details>

[:umbrella: View full report in Codecov by Sentry](https://app.codecov.io/gh/FredHutch/VISCtemplates/pull/233?dropdown=coverage&src=pr&el=continue&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=FredHutch).   
:loudspeaker: Have feedback on the report? [Share it here](https://about.codecov.io/codecov-pr-comment-feedback/?utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=FredHutch).

<details><summary> :rocket: New features to boost your workflow: </summary>

- :snowflake: [Test Analytics](https://docs.codecov.com/docs/test-analytics): Detect flaky tests, report on failures, and find test suite problems.
</details>
author_association: NONE
user: login: kelliemac
created_at: 2025-01-11T01:26:42Z
body: since I moved around some of the relevant files, I will go ahead and address https://github.com/FredHutch/VISCtemplates/issues/241 now too
author_association: CONTRIBUTOR
user: login: kelliemac
created_at: 2025-01-11T01:27:14Z
body: I also added a note about using git tags instead of hashes, in line with https://github.com/FredHutch/VISCtemplates/issues/238
author_association: CONTRIBUTOR
user: login: kelliemac
created_at: 2025-01-11T01:45:46Z
body: @mayerbry and @slager can you please review this PR when you have a chance? I increased the scope a little bit because I got frustrated with the organization of files in the `inst` folder while I was updating the README creation steps. so I renamed a bunch of files (all within `inst`) but didn't actually change their contents for the most part. we had discussed in the past that it was sometimes difficult to find the right files to edit in this package, so I'm hoping the new organization helps with that.

please focus on the following in your review:

- [ ] are the new file names and organization of the `inst` folder more intuitive than before? are these changes + the additional text in the package README sufficient to address https://github.com/FredHutch/VISCtemplates/issues/241?
- [ ] are the updated README formats of `inst/templates/README_assay_folder.md` and `inst/templates/README_report_folder.md` acceptable?
- [ ] do you have any concerns about the code changes in `use_visc_report.R` and `visc_output_document.R`?

thank you!!!
author_association: CONTRIBUTOR
user: login: slager
created_at: 2025-02-04T18:52:45Z
body: Unit tests for new README creation behaving as expected at project and report level could go near here:

https://github.com/FredHutch/VISCtemplates/blob/bcc9a0f78847f159e6b6328eabc1428509edc229/tests/testthat/test-use_visc_report.R#L13

And this test_that title could be changed to something more general about project/report structure:

https://github.com/FredHutch/VISCtemplates/blob/bcc9a0f78847f159e6b6328eabc1428509edc229/tests/testthat/test-use_visc_report.R#L1
author_association: CONTRIBUTOR
user: login: mayerbry
created_at: 2025-03-17T19:07:09Z
body: It wasn't immediately clear to me that the `path` argument needs to be specified to generate the subdirectory README

For example, I originally tested
```
VISCtemplates::use_visc_report(report_name = "BAMA/testReport",  report_type = "generic")
# gets error
dir.create("BAMA") # or uses point and click
VISCtemplates::use_visc_report(report_name = "BAMA/testReport",  report_type = "generic")
# this runs but without the folder-level readme
```
Once the sub-directory is created, the README won't be generated even with path specified for a future report.

Confirm this does work as expected with syntax:
```
VISCtemplates::use_visc_report(report_name = "testReport",  path = "BAMA", report_type = "generic")
```

Suggestion:
remove `path` argument from this function and have it dynamically created within `use_visc_report` as follows
```
path <- dirname(report_name)
```
I don't think any other code would need to be modified actually

author_association: CONTRIBUTOR
user: login: kelliemac
created_at: 2025-03-22T00:01:42Z
body: > It wasn't immediately clear to me that the `path` argument needs to be specified to generate the subdirectory README
> 
> For example, I originally tested
> 
> ```
> VISCtemplates::use_visc_report(report_name = "BAMA/testReport",  report_type = "generic")
> # gets error
> dir.create("BAMA") # or uses point and click
> VISCtemplates::use_visc_report(report_name = "BAMA/testReport",  report_type = "generic")
> # this runs but without the folder-level readme
> ```
> 
> Once the sub-directory is created, the README won't be generated even with path specified for a future report.
> 
> Confirm this does work as expected with syntax:
> 
> ```
> VISCtemplates::use_visc_report(report_name = "testReport",  path = "BAMA", report_type = "generic")
> ```
> 
> Suggestion: remove `path` argument from this function and have it dynamically created within `use_visc_report` as follows
> 
> ```
> path <- dirname(report_name)
> ```
> 
> I don't think any other code would need to be modified actually

I am hesitant to remove the "path" argument because people may already be using it (this argument predates my time at VISC) and I don't want to interrupt anyone's workflow.

However, I can add improve automatic handling for the case you're describing, Bryan.


author_association: CONTRIBUTOR
user: login: kelliemac
created_at: 2025-03-22T00:54:17Z
body: @mayerbry I updated the code to throw an explicit error if the subdirectory is included in the report_name argument to use_visc_report(). I hope this resolves your concern. I think this keeps the spirit of use_visc_report() as originally intended, while making it clear to the user how to adjust.
author_association: CONTRIBUTOR
user: login: kelliemac
created_at: 2025-03-22T00:54:58Z
body: @slager I added some unit tests and addressed your other comments, lmk if adequate
author_association: CONTRIBUTOR
user: login: kelliemac
created_at: 2025-03-22T00:55:16Z
body: @asatofh I accepted your suggestions - thank you!
author_association: CONTRIBUTOR
user: login: kelliemac
created_at: 2025-03-22T01:52:40Z
body: @slager any insights as to why the ubuntu-latest (4.0.4) check is failing? do you think this is actually because of my code changes, or due to some other mysterious reason?
author_association: CONTRIBUTOR