Add vignette on generating lockfile from log

[parmsam-pfizer]

Thank you for your Pull Request!

We have developed a Pull Request template to aid you and our reviewers. Completing the below tasks helps to ensure our reviewers can maximize their time on your code as well as making sure the logrx codebase remains robust and consistent.

The spirit of logrx

While many packages to facilitate the logging of code already exist in the R ecosystem, it is hard to find a solution that works well for clinical programming applications. Many logging implementations are more implicit and rely on user input to create the log for the execution of a script. While this is useful for logging specific events of an application, in clinical programming a log has a set purpose.

logrx is built around the concept of creating a log for the execution of an R script that provides an overview of what happened as well as the environment that it happened in. We set out to create a flexible logging utility that could provide the necessary information to anyone reviewing the code execution so they can recreate the execution environment and run the code for themselves. Please make sure your Pull Request meets this spirit of logrx.

Please check off each taskbox as an acknowledgment that you completed the task. This checklist is part of the Github Action workflows and the Pull Request will not be merged into the dev branch until you have checked off each task.

• [x] The spirit of logrx is met in your Pull Request
• [x] Code is formatted according to the tidyverse style guide
• [x] Updated relevant unit tests or have written new unit tests. Remember to remove any configured log objects at the end of every test using log_remove().
• [x] Creation/updates to relevant roxygen headers and examples.
• [ ] Run devtools::document() so all .Rd files in the man folder and the NAMESPACE file in the project root are updated appropriately
• [ ] Run pkgdown::build_site() and check that all affected examples are displayed correctly and that all new functions occur on the "Reference" page.
• [ ] Update NEWS.md if the changes pertain to a user-facing function (i.e. it has an @export tag) or documentation aimed at users (rather than developers)
• [x] Address any updates needed for vignettes and/or templates
• [x] Run R CMD check locally and address all errors and warnings - devtools::check()
• [x] Link the issue so that it closes after successful merging. - fixes #161
• [x] Address all merge conflicts and resolve appropriately
• [x] Pat yourself on the back for a job well done! Much love to your accomplishment!

[parmsam-pfizer]

Not sure if I need to add renv into the suggests section of the DESCRIPTION file. It's used in the vignette. Any thoughts @bms63 @nicholas-masel @thomasp-b @kodesiba?

Run options(crayon.enabled = TRUE)
── R CMD build ─────────────────────────────────────────────────────────────────
pdflatex not found! Not building PDF manual.
* checking for file ‘.../DESCRIPTION’ ... OK
* preparing ‘logrx’:
* checking DESCRIPTION meta-information ... OK
* installing the package to build vignettes
* creating vignettes ... ERROR
Error: --- re-building ‘approved.Rmd’ using rmarkdown
--- finished re-building ‘approved.Rmd’
--- re-building ‘execution.Rmd’ using rmarkdown
--- finished re-building ‘execution.Rmd’
--- re-building ‘generate-lockfile.Rmd’ using rmarkdown
Quitting from lines [20](https://github.com/pharmaverse/logrx/actions/runs/13313538018/job/37181842469?pr=233#step:9:21)-24 [setup] (generate-lockfile.Rmd)
Error: Error: processing vignette 'generate-lockfile.Rmd' failed with diagnostics:
there is no package called 'renv'
--- failed re-building ‘generate-lockfile.Rmd’
--- re-building ‘logrx.Rmd’ using rmarkdown
--- finished re-building ‘logrx.Rmd’
--- re-building ‘options.Rmd’ using rmarkdown
--- finished re-building ‘options.Rmd’
SUMMARY: processing the following file failed:
  ‘generate-lockfile.Rmd’
Error: Error: Vignette re-building failed.
Execution halted
Error: Error in proc$get_built_file() : Build process failed
Calls: <Anonymous> ... build_package -> with_envvar -> force -> <Anonymous>
Execution halted
Error: Process completed with exit code 1.

[parmsam-pfizer]

Resolved based on short discussion on this in today's meeting.

[parmsam-pfizer]

Spell check failing due to "renv" and "lockfile" words which are used properly. That check for this PR can be ignored or maybe we can add those terms into the whitelist.

Run insightsengineering/r-spellcheck-action@v3
Run options(repos = c(CRAN = "https://cloud.r-project.org/"))
Loading required package: spelling
Run cd .
DESCRIPTION does not contain 'Language' field. Defaulting to 'en-US'.
  WORD       FOUND IN
lockfile   generate-lockfile.Rmd:2,52
renv       generate-lockfile.Rmd:2,52

Number of misspelled words: 2
You may correct the spellings of the words above or add them to the "inst/WORDLIST" file by running spelling::update_wordlist()
Error: Process completed with exit code 2.

[bms63]

So interesting these are passing now @kodesiba

[parmsam-pfizer]

Made a bunch of fixes last night, @bms63.

[parmsam-pfizer]

Sorry for the delay. Updated the vignette so that the lockfile is updated according to the used package versions using renv::record(), as we discussed. @kodesiba, do you think I should also update lockfile to match up with all of the packages/package versions listed in the session info section of the log? It seems that a lot of them are package dependencies of dplyr in the example.

I would just need to not filter the used package dataframe, as I do here:

pkgs <- parsedFile$`Used Package and Functions` %>%
  transmute(package_name = str_extract(library, "(?<=package\\:).+"))

used_pkgs <- parsedFile$`Session Information`$Packages %>%
  filter(package %in% pkgs$package_name)

[parmsam-pfizer]

Oh, I also need to test out the lockfile again to ensure that it works as intended. Could use help with that to confirm.

[kodesiba]

@parmsam-pfizer I think this looks right, I'll need to check it out for myself to check things are working. We can chat in check-in today to make sure we're on the same page and then I should have time this evening to check the lockfile and everything to make sure it's working as intended.

[kodesiba]

@parmsam-pfizer this works as I would expect I believe, tested it out this morning and it's looking right. @nicholas-masel can you test this out as well, I know you said you wanted to use this workflow

[nicholas-masel]

@parmsam-pfizer this works as I would expect I believe, tested it out this morning and it's looking right. @nicholas-masel can you test this out as well, I know you said you wanted to use this workflow

Yep, I'll try it out now. I don't think we would use this since we have lock files already stored for the interactive execution environment. I'm mostly interested if it would create the same lock file I already have.

[bms63]

is rstudioapi needed? I removed it in the DESCRIPTION in my shiny PR but saw it being used here

[parmsam-pfizer]

Good point. I guess I could print the file contents in R console instead. That or maybe I could just put it in a conditional block that is FALSE by default like

if (FALSE) {
...
}

That might remove the need to put it in SUGGESTS.

[bms63]

If it is part of SUGGEST, then maybe not a big deal. I just removed it from IMPORTS in my PR and thought it was need going to be needed.

[kodesiba]

My vote is to have it in suggests, definitely something we shouldn't nee in imports but we do need vignettes to be able to be built without it so an if block might work

[parmsam-pfizer]

It should be fine as a SUGGESTS according to the r-pkgs book: https://r-pkgs.org/vignettes.html#sec-vignettes-eval-option

"Any package used in a vignette must be a formal dependency, i.e. it must be listed in Imports or Suggests in DESCRIPTION. Similar to our stance in tests (Section 11.5.2), our policy is to write vignettes under the assumption that suggested packages will be installed in any context where the vignette is being built (Section 11.5.3). We generally use suggested packages unconditionally in vignettes. But, as with tests, if a package is particularly hard to install, we might make an exception and take extra measures to guard its use."

Just made the change in the branch.

[parmsam-pfizer]

Seems like the R CMD check needs it in imports. I'm just going to comment those line out and make a note to uncomment those lines to open it in RStudio. Update: It's related to logrxAddin.R which is still in this branch. It uses two rstudioapi functions. I think the checks should pass after PR #252 gets merged.

[parmsam-pfizer]

Checks passing now, @kodesiba.

[kodesiba]

@nicholas-masel did you have a chance to check this out?