--- title: "Introduction to the rqualify Package" description: > Introduction to the rqualify Package. output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{Introduction to the rqualify Package} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- # R Installation IQ/OQ This vignette is an overview of the `R-validation.Rmd` file, showing what code is executed when the file is rendered. This overview is for informational purposes and documents the internal structure of the `R-validation.Rmd` file. If any of the code blocks are updated, this is not considered a breaking change as the document will still render properly. The LaTeX and Quarto templates both call shared package functions to execute tests and classify their results. Please see for the full documentation. Here is a minimal usage example: ```{r, eval = FALSE} library(rqualify) # Render the R-validation report, must have TinyTeX and Pandoc installed, # otherwise set setup_tinytex and setup_pandoc to TRUE. rqualify(path_save = tempdir(), setup_tinytex = FALSE, setup_pandoc = FALSE) ``` ## R-validation.Rmd Contents Below includes example output of installation facts, installation qualification, and operational qualification. The installation facts and qualification results are generated at the time of the package build or site build, while the operational qualification results were generated on a Windows machine with R version 4.5.1. Here, the code blocks are shown for informational purposes, the actual PDF report does not include the code blocks, only the results of each executed code block. ```{r codeexec, echo=FALSE, message=FALSE} code_exec <- rqualify:::validation_output # Define tempdir() dir_temp <- file.path(tempdir(), "IQ-OQ-TestOutput") dir.create(dir_temp, showWarnings = FALSE) dir_temp <- normalizePath(dir_temp, winslash="/") ``` ### Installation Qualification First, some R installation facts are gathered and stored in variables. These variables are then used to populate the title page of the report with details about the R installation being qualified. ```{r titlepage, message=FALSE} # Get R installation facts RVersionInfo <- R.Version() Version <- RVersionInfo$version.string Arch <- gsub("_", " ", RVersionInfo$arch) Platform <- gsub("_", " ", RVersionInfo$platform) ``` ~~~~~~~ R Version: `r Version` Architecture: `r Arch` Platform: `r Platform` ~~~~~~~ --- The following is the output of `R.home()`, showing where R was installed on this computer: ```{r rhome} r_home <- paste0(R.home(), sep="\n") ``` ~~~~~~~ ```{r echo=FALSE, results="asis"} cat(paste0(r_home, collapse = "\n")) ``` ~~~~~~~ --- The following is the output of a fresh R subprocess, including its explicit completion result. A successful exit and completion result are both required to pass Installation Qualification: ```{r rbanner} iq_run <- rqualify:::run_validation_suite("iq", dir_temp) results0 <- paste(iq_run$output, collapse = "\n") ``` ~~~~~~~ ```{r echo=FALSE, results="asis"} cat(results0) ``` ~~~~~~~ --- The following is the output of `Sys.info()`, defining some details about the current system upon which R is running and user information: ```{r rsysinfo} # Run Sys.info() at the command line results_sysinfo <- code_exec(code_block = "Sys.info()", file_prefix = "sysinfo", folder_output = dir_temp) # Clean-up the results (remove the unnecessary preamble and arrow) results_sysinfo_clean <- results_sysinfo[-(1:(which(results_sysinfo == "> Sys.info()")))] if(any(results_sysinfo_clean == "> ")){ results_sysinfo_clean <- results_sysinfo_clean[-which(results_sysinfo_clean == "> ")] } ``` ~~~~~~~ ```{r echo=FALSE, results="asis"} cat(paste0(results_sysinfo_clean, collapse = "\n")) ``` ~~~~~~~ --- The following is the output of `.Platform`, defining some details of the platform upon which R was built (compiled): ```{r rplatform} # Run .Platform at the command line results_platform <- code_exec(code_block = ".Platform", file_prefix = "platform", folder_output = dir_temp) # Clean-up the results (remove the unnecessary preamble) results_platform_clean <- results_platform[-(1:(which(results_platform == "> .Platform")))] if(any(results_platform_clean == "> ")){ results_platform_clean <- results_platform_clean[-which(results_platform_clean == "> ")] } ``` ~~~~~~~ ```{r echo=FALSE, results="asis"} cat(paste0(results_platform_clean, collapse = "\n")) ``` ~~~~~~~ --- The following is the output of `R.version`, defining detailed information on the currently running version of R: ```{r rversion} # Run R.version at the command line results_rversion <- code_exec(code_block = "R.version", file_prefix = "rversion", folder_output = dir_temp) # Clean-up the results (remove the unnecessary preamble) results_rversion_clean <- results_rversion[-(1:(which(results_rversion == "> R.version")))] if(any(results_rversion_clean == "> ")){ results_rversion_clean <- results_rversion_clean[-which(results_rversion_clean == "> ")] } ``` ~~~~~~~ ```{r echo=FALSE, results="asis"} cat(paste0(results_rversion_clean, collapse = "\n")) ``` ~~~~~~~ --- The following is the output of `.Machine`, defining the numerical characteristics of the computer upon which R is running: ```{r rmachine} # Run .Machine at the command line results_machine <- code_exec(code_block = ".Machine", file_prefix = "machine", folder_output = dir_temp) # Clean-up the results (remove the unnecessary preamble) results_machine_clean <- results_machine[-(1:(which(results_machine == "> .Machine")))] if(any(results_machine_clean == "> ")){ results_machine_clean <- results_machine_clean[-which(results_machine_clean == "> ")] } ``` ~~~~~~~ ```{r echo=FALSE, results="asis"} cat(paste0(results_machine_clean, collapse = "\n")) ``` ~~~~~~~ --- The following is the output of `sessionInfo()`, defining current R version, locale information and attached packages: ```{r rsession} # Run sessionInfo() at the command line results_sessioninfo <- code_exec(code_block = "sessionInfo()", file_prefix = "sessioninfo", folder_output = dir_temp) # Clean-up the results (remove the unnecessary preamble) results_sessioninfo_clean <- results_sessioninfo[-(1:(which(results_sessioninfo == "> sessionInfo()")))] if(any(results_sessioninfo_clean == "> ")){ results_sessioninfo_clean <- results_sessioninfo_clean[-which(results_sessioninfo_clean == "> ")] } ``` ~~~~~~~ ```{r echo=FALSE, results="asis"} cat(paste0(results_sessioninfo_clean, collapse = "\n")) ``` ~~~~~~~ --- The following is the output of `.libPaths()`, the current package library location; may be more than one folder: ```{r lib_path} results_libpath <- code_exec(code_block = ".libPaths()", file_prefix = "libpaths", folder_output = dir_temp) # Clean-up the results (remove the unnecessary preamble) results_libpath_clean <- results_libpath[-(1:(which(results_libpath == "> .libPaths()")))] if(any(results_libpath_clean == "> ")){ results_libpath_clean <- results_libpath_clean[-which(results_libpath_clean == "> ")] } ``` ~~~~~~~ ```{r echo=FALSE, results="asis"} cat(paste0(results_libpath_clean, collapse = "\n")) ``` ~~~~~~~ --- The following is the output of `rmarkdown::pandoc_version()` listing the version of Pandoc used to render the report (note, if Pandoc is not installed, the output will indicate that Pandoc is not available): ```{r pandoc_ver} if(pandoc::pandoc_available()){ results_pandoc_ver <- code_exec(code_block = "rmarkdown::pandoc_version()", file_prefix = "pandoc_ver", folder_output = dir_temp) # Clean-up the results (remove the unnecessary preamble) results_pandoc_ver_clean <- results_pandoc_ver[-(1:(which(results_pandoc_ver == "> rmarkdown::pandoc_version()")))] if(any(results_pandoc_ver_clean == "> ")){ results_pandoc_ver_clean <- results_pandoc_ver_clean[-which(results_pandoc_ver_clean == "> ")] } } else{ results_pandoc_ver_clean <- "Pandoc not available" } ``` ~~~~~~~ ```{r echo=FALSE, results="asis"} cat(paste0(results_pandoc_ver_clean, collapse = "\n")) ``` ~~~~~~~ --- The following is the output of `tinytex::tlmgr_version()` listing the version and installation path of TinyTex used to render the report to pdf (note, if TinyTeX is not installed, the output will indicate that TinyTeX is not available): ```{r tinytex_ver} if(tinytex::is_tinytex()){ results_tinytex_ver <- code_exec(code_block = "tinytex::tlmgr_version()", file_prefix = "tinytex_ver", folder_output = dir_temp) # Clean-up the results (remove the unnecessary preamble) results_tinytex_ver_clean <- results_tinytex_ver[-(1:(which(results_tinytex_ver == "> tinytex::tlmgr_version()")))] if(any(results_tinytex_ver_clean == "> ")){ results_tinytex_ver_clean <- results_tinytex_ver_clean[-which(results_tinytex_ver_clean == "> ")] } } else{ results_tinytex_ver_clean <- "TinyTeX not available" } ``` ~~~~~~~ ```{r echo=FALSE, results="asis"} cat(paste0(results_tinytex_ver_clean, collapse = "\n")) ``` ~~~~~~~ --- ### Operational Qualification #### R Core Operational Qualification - System Tests (OQ) The following is the output of `testInstalledBasic(scope = "basic")`, which runs the installed basic system tests; development and internet scopes are not run: ```{r oq1, eval=FALSE} results1 <- rqualify:::run_validation_suite("basic", "IQ-OQ-TestOutput") ``` ~~~~~~~ ```{r oq1read, echo=FALSE, results="asis"} cat(paste0(readLines(system.file("qualify_r/example_success/CMDFile1Out.txt", package="rqualify")), collapse = "\n")) ``` ~~~~~~~ The final line of the above output displays the status of running the above tests. `PASS` indicates a successful running of the tests, a `FAIL` would indicate that an error was detected during the running of the tests. There may be some tests where the result of performing a `diff` on two files that were being compared demonstrate a content difference that may or may not be relevant and may be dependent upon locale settings. Any such differences displayed in the above output should be reviewed in detail to determine their relevance to the Operational Qualification of this R installation. --- #### R Base Package Operational Qualification - Package Examples (OQ) The following is the output of `testInstalledPackages(outDir = "IQ-OQ-TestOutput", scope = "base", types = "examples", errorsAreFatal = FALSE)`, which runs a series of operational tests of the R Base package code examples: ```{r oq2, eval=FALSE} results2 <- rqualify:::run_validation_suite("base_examples", "IQ-OQ-TestOutput") ``` ~~~~~~~ ```{r oq2read, echo=FALSE, results="asis"} cat(paste0(readLines(system.file("qualify_r/example_success/CMDFile2Out.txt", package="rqualify")), collapse = "\n")) ``` ~~~~~~~ The final line of the above output displays the status of running the above tests. `PASS` indicates a successful running of the tests, a `FAIL` would indicate that an error was detected during the running of the tests. There may be some tests where the result of performing a `diff` on two files that were being compared demonstrate a content difference that may or may not be relevant and may be dependent upon locale settings. Any such differences displayed in the above output should be reviewed in detail to determine their relevance to the Operational Qualification of this R installation. --- #### R Base Package Operational Qualification - Package Vignettes (OQ) The following is the output of `testInstalledPackages(outDir = "IQ-OQ-TestOutput", scope = "base", types = "vignettes", errorsAreFatal = FALSE)`, which runs a series of operational tests of the R Base package vignette code examples: ```{r oq3, eval=FALSE} results3 <- rqualify:::run_validation_suite("base_vignettes", "IQ-OQ-TestOutput") ``` ~~~~~~~ ```{r oq3read, echo=FALSE, results="asis"} cat(paste0(readLines(system.file("qualify_r/example_success/CMDFile3Out.txt", package="rqualify")), collapse = "\n")) ``` ~~~~~~~ The final line of the above output displays the status of running the above tests. `PASS` indicates a successful running of the tests, a `FAIL` would indicate that an error was detected during the running of the tests. There may be some tests where the result of performing a `diff` on two files that were being compared demonstrate a content difference that may or may not be relevant and may be dependent upon locale settings. Any such differences displayed in the above output should be reviewed in detail to determine their relevance to the Operational Qualification of this R installation. --- #### R Recommended Package Operational Qualification - Package Examples (OQ) The following is the output of `testInstalledPackages(outDir = "IQ-OQ-TestOutput", scope = "recommended", types = "examples", errorsAreFatal = FALSE)`, which runs a series of operational tests of the R Recommended package code examples: ```{r oq4, eval=FALSE} results4 <- rqualify:::run_validation_suite("recommended_examples", "IQ-OQ-TestOutput") ``` ~~~~~~~ ```{r oq4read, echo=FALSE, results="asis"} cat(paste0(readLines(system.file("qualify_r/example_success/CMDFile4Out.txt", package="rqualify")), collapse = "\n")) ``` ~~~~~~~ The final line of the above output displays the status of running the above tests. `PASS` indicates a successful running of the tests, a `FAIL` would indicate that an error was detected during the running of the tests. There may be some tests where the result of performing a `diff` on two files that were being compared demonstrate a content difference that may or may not be relevant and may be dependent upon locale settings. Any such differences displayed in the above output should be reviewed in detail to determine their relevance to the Operational Qualification of this R installation. --- #### R Recommended Package Operational Qualification - Package Vignettes (OQ) The following is the output of `testInstalledPackages(outDir = "IQ-OQ-TestOutput", scope = "recommended", types = "vignettes", errorsAreFatal = FALSE)`, which runs a series of operational tests of the R Recommended package vignette code examples: ```{r oq5, eval=FALSE} results5 <- rqualify:::run_validation_suite("recommended_vignettes", "IQ-OQ-TestOutput") ``` ~~~~~~~ ```{r oq5read, echo=FALSE, results="asis"} cat(paste0(readLines(system.file("qualify_r/example_success/CMDFile5Out.txt", package="rqualify")), collapse = "\n")) ``` ~~~~~~~ The final line of the above output displays the status of running the above tests. `PASS` indicates a successful running of the tests, a `FAIL` would indicate that an error was detected during the running of the tests. There may be some tests where the result of performing a `diff` on two files that were being compared demonstrate a content difference that may or may not be relevant and may be dependent upon locale settings. Any such differences displayed in the above output should be reviewed in detail to determine their relevance to the Operational Qualification of this R installation. --- #### R Base Package Operational Qualification - Package Tests (OQ) The following is the output of `testInstalledPackages(outDir = "IQ-OQ-TestOutput", scope = "base", types = "tests", errorsAreFatal = FALSE)`, which runs a series of operational tests of the R Base package code tests: ```{r oq6, eval=FALSE} results6 <- rqualify:::run_validation_suite("base_tests", "IQ-OQ-TestOutput") ``` ~~~~~~~ ```{r oq6read, echo=FALSE, results="asis"} cat(paste0(readLines(system.file("qualify_r/example_success/CMDFile6Out.txt", package="rqualify")), collapse = "\n")) ``` ~~~~~~~ The final line of the above output displays the status of running the above tests. `PASS` indicates a successful running of the tests, a `FAIL` would indicate that an error was detected during the running of the tests. There may be some tests where the result of performing a `diff` on two files that were being compared demonstrate a content difference that may or may not be relevant and may be dependent upon locale settings. Any such differences displayed in the above output should be reviewed in detail to determine their relevance to the Operational Qualification of this R installation. --- #### R Recommended Package Operational Qualification - Package Tests (OQ) The following is the output of `testInstalledPackages(outDir = "IQ-OQ-TestOutput", scope = "recommended", types = "tests", errorsAreFatal = FALSE)`, which runs a series of operational tests of the R Recommended package code tests: ```{r oq7, eval=FALSE} results7 <- rqualify:::run_validation_suite("recommended_tests", "IQ-OQ-TestOutput") ``` ~~~~~~~ ```{r oq7read, echo=FALSE, results="asis"} cat(paste0(readLines(system.file("qualify_r/example_success/CMDFile7Out.txt", package="rqualify")), collapse = "\n")) ``` ~~~~~~~ The final line of the above output displays the status of running the above tests. `PASS` indicates a successful running of the tests, a `FAIL` would indicate that an error was detected during the running of the tests. There may be some tests where the result of performing a `diff` on two files that were being compared demonstrate a content difference that may or may not be relevant and may be dependent upon locale settings. Any such differences displayed in the above output should be reviewed in detail to determine their relevance to the Operational Qualification of this R installation. ### Summary of Findings The final page of the report will include a table with the summary of findings from the above tests, including the overall status of the Installation Qualification and Operational Qualification of this R installation. A PASS requires a successful subprocess exit and an explicit completion result. The summary must contain all eight expected suites and valid statuses; missing or malformed evidence cannot establish a successful qualification. Please see for the full documentation and an example of a successful report. ```{r codecleanup, echo=FALSE, message=FALSE} unlink(dir_temp) ```