fairify: an R package for creating FAIR reports
FAIR principles stands for Findability, Accessibility, Interoperability, and Reuse.
This package provide tools to help you to create HTML and PDF reports based on bookdown with data stored on the cloud.
fairify currently supports data access Owncloud/Nextcloud servers and provides templates for Inrae website and PDF reports.
Installation
# install.packages("remotes")
remotes::install_git(
"https://forgemia.inra.fr/umr-g-eau/fairify.git",
dependencies = TRUE
)Create a fairify project
create_fairify creates a R-package skeleton and open your fairify
project on Rstudio:
# Create a project in a temporary folder for the example
path <- file.path(tempdir(), "my_fairify_project")
fairify::create_fairify(path)
## ✔ Creating 'C:/Users/DDORCH~1/AppData/Local/Temp/RtmpsJQiJu/my_fairify_project/'
## ✔ Setting active project to 'C:/Users/ddorchies/AppData/Local/Temp/RtmpsJQiJu/my_fairify_project'
## ✔ Creating 'R/'
## ✔ Writing 'DESCRIPTION'
## Package: my_fairify_project
## Title: What the Package Does (One Line, Title Case)
## Version: 0.0.0.9000
## Authors@R (parsed):
## * First Last <first.last@example.com> [aut, cre] (YOUR-ORCID-ID)
## Description: What the package does (one paragraph).
## License: `use_mit_license()`, `use_gpl3_license()` or friends to pick a
## license
## Remotes:
## git::https://forgemia.inra.fr/umr-g-eau/fairify.git
## Encoding: UTF-8
## Roxygen: list(markdown = TRUE)
## RoxygenNote: 7.3.1
## ✔ Writing 'NAMESPACE'
## ✔ Setting active project to '<no active project>'
## ✔ Setting active project to 'C:/Users/ddorchies/AppData/Local/Temp/RtmpsJQiJu/my_fairify_project'
## ✔ Adding 'fairify' to Depends field in DESCRIPTION
## • Are you sure you want Depends? Imports is almost always the better choice.
## ✔ Setting active project to 'C:/Users/ddorchies/AppData/Local/Temp/RtmpsJQiJu/my_fairify_project'
## ✔ Adding '^_pkgdown\\.yml$', '^public$', '^pkgdown$' to '.Rbuildignore'
## ✔ Adding 'public' to '.gitignore'
## Fairify project created
##
## Don't forget to edit the file `inst/config.yml` for configuring the data location for your project
##
## ✔ Setting active project to 'C:/Users/ddorchies/AppData/Local/Temp/RtmpsJQiJu/my_fairify_project'
list.files(path)
## [1] "_pkgdown.yml" "DESCRIPTION" "inst" "NAMESPACE" "R"
## [6] "reports" "templates"Create reports with bookdown
By default, the fairify project contains a reports folder which will
contain bookdown reports.
Use the function fairify::add_report for creating a new report.
# Create a report
fairify::add_report("my_report", template = "umr_geau", path = path)
## [1] "C:\\Users\\DDORCH~1\\AppData\\Local\\Temp\\RtmpsJQiJu/my_fairify_project/reports/my_report"
# Add a chapter
writeLines(
c(
"# A new chapter",
"",
"With a new paragraph."
),
file.path(path, "reports/my_report/01-new_chapter.Rmd")
)Read the documentation of bookdown for more details on how to write great reports with references, figures, and formulas.
The template parameter allows to choose the LaTeX template used for
rendering the PDF report. The LaTeX template settings can be overloaded
by modifying the files “in_header.tex”, “before_body.tex”, and
“after_body.tex” located in the report folder (See bookdown
documentation for
details).
Render reports
By default, the reports are rendered in the public folder of the fairify project.
# Render the report in HTML format
fairify::render_reports(reports_dir = file.path(path, "reports"))
## folder list:
## my_report
## *******************************************************************
## ** RENDER my_report
## *******************************************************************
## output_format=bookdown::gitbook
## Rendering book in directory 'C:\Users\DDORCH~1\AppData\Local\Temp\RtmpsJQiJu/my_fairify_project/reports/my_report'
## processing file: report.Rmd
## output file: report.knit.md
## "C:/Program Files/RStudio/resources/app/bin/quarto/bin/tools/pandoc" +RTS -K512m -RTS report.knit.md --to html4 --from markdown+autolink_bare_uris+tex_math_single_backslash --output report.html --lua-filter "C:\Users\ddorchies\AppData\Local\Programs\R\R-4.3.1\library\bookdown\rmarkdown\lua\custom-environment.lua" --lua-filter "C:\Users\ddorchies\AppData\Local\Programs\R\R-4.3.1\library\rmarkdown\rmarkdown\lua\pagebreak.lua" --lua-filter "C:\Users\ddorchies\AppData\Local\Programs\R\R-4.3.1\library\rmarkdown\rmarkdown\lua\latex-div.lua" --lua-filter "C:\Users\ddorchies\AppData\Local\Programs\R\R-4.3.1\library\rmarkdown\rmarkdown\lua\anchor-sections.lua" --metadata-file "C:\Users\DDORCH~1\AppData\Local\Temp\RtmpsJQiJu\file5664ef05c75" --wrap preserve --standalone --section-divs --table-of-contents --toc-depth 3 --template "C:\Users\ddorchies\AppData\Local\Programs\R\R-4.3.1\library\bookdown\templates\gitbook.html" --highlight-style pygments --number-sections --css style.css --mathjax --include-in-header "C:\Users\DDORCH~1\AppData\Local\Temp\RtmpsJQiJu\rmarkdown-str56644c4a78c5.html" --citeproc
##
## Output created: C:/Users/DDORCH~1/AppData/Local/Temp/RtmpsJQiJu/my_fairify_project/public/reports/my_report/index.html
# Render the report in PDF format
fairify::render_reports(reports_dir = file.path(path, "reports"),
output_format = "bookdown::pdf_book")
## folder list:
## my_report
## *******************************************************************
## ** RENDER my_report
## *******************************************************************
## output_format=bookdown::pdf_book
## Rendering book in directory 'C:\Users\DDORCH~1\AppData\Local\Temp\RtmpsJQiJu/my_fairify_project/reports/my_report'
## processing file: report.Rmd
## output file: report.knit.md
## "C:/Program Files/RStudio/resources/app/bin/quarto/bin/tools/pandoc" +RTS -K512m -RTS report.knit.md --to latex --from markdown+autolink_bare_uris+tex_math_single_backslash --output report.tex --lua-filter "C:\Users\ddorchies\AppData\Local\Programs\R\R-4.3.1\library\bookdown\rmarkdown\lua\custom-environment.lua" --lua-filter "C:\Users\ddorchies\AppData\Local\Programs\R\R-4.3.1\library\rmarkdown\rmarkdown\lua\pagebreak.lua" --lua-filter "C:\Users\ddorchies\AppData\Local\Programs\R\R-4.3.1\library\rmarkdown\rmarkdown\lua\latex-div.lua" --metadata-file "C:\Users\DDORCH~1\AppData\Local\Temp\RtmpsJQiJu\file5664239a1d39" --embed-resources --standalone --table-of-contents --toc-depth 2 --number-sections --highlight-style tango --pdf-engine pdflatex --biblatex --include-in-header in_header.tex --include-before-body before_body.tex --include-after-body after_body.tex --variable graphics --wrap preserve --variable tables=yes --standalone -Mhas-frontmatter=false
##
## Output created: C:/Users/DDORCH~1/AppData/Local/Temp/RtmpsJQiJu/my_fairify_project/public/reports/my_report/report.pdfUse data located on the cloud (or not…)
How it works?
The fairify project provides a function getDataPath which helps you
to use data located on the cloud in your R scripts.
List of supported cloud servers:
To use it, you first need to define your cloud configuration in the file
inst/config.yml:
default:
data:
mode: remote
local: "path_for_data_on_your_disk"
remote: "https://public_link_on_your_cloud"
write_results: falseThe local path stands for storing your data on a local or network disk
directly readable and writable by your Operating System.
Caching results
write_results logical parameter is an helper for caching data results
of long calculations. The basic strategy is to either calculate and save
a result or read this result depending of the value of this boolean:
computeSomeThing <- function(cfg = loadConfig()) {
if (cfg$data$write_results) {
myBigResult <- 2 + 2
saveRDS(myBigResult, getDataPath("myBigResult.RDS"))
} else {
myBigResult <- readRDS(getDataPath("myBigResult.RDS"))
}
return(myBigResult)
}