This vignette describe the worcs
package’s functionality
for automating reproducibility. The basic idea is that the entry point,
endpoint (or endpoints), and recipe by which to get to the endpoint from
the entry point are all well-defined.
In a typical worcs
project, the entry point will be a
dynamic document (e.g., manuscript.Rmd
), and the endpoint
will be the rendered manuscript (e.g., manuscript.pdf
). The
recipe by which to get from the entry point to the endpoint is a simple
call to rmarkdown::render("manuscript.Rmd")
.
By default, the entry point is documented in the .worcs
project file when the project is created.
Users can add endpoints using the function
add_endpoint("filename")
. When running this function,
filename
is added to the .worcs
project file,
and its checksum is computed so that any changes to the contents of the
file can be detected.
It is also possible to specify multiple endpoints. For example, maybe the user has finalized the analyses, and wants to track reproducibility for the analysis results - but still wants to make changes to the text of the manuscript without breaking reproducibility checks. In this case, it is useful to track files that contain analysis results instead of the rendered manuscript. Imagine these are intermediary files with analysis results:
descriptives.csv
: A file with the descriptive
statistics of study variablesmodel_fit.csv
: A table with model fit indices for
several modelsfinalmodel.RData
: An RData file with the results of the
final modelThese three files could be tracked as endpoints by calling
add_endpoint("descriptives.csv"); add_endpoint("model_fit.csv"); add_endpoint("finalmodel.RData")
.
Users can verify that the endpoint remains unchanged by calling the
function check_endpoints()
. If any endpoint has changed
relative to the version stored in the .worcs
project file,
this will result in a warning message.
To update the endpoints in the .worcs
file, call
snapshot_endpoints()
. Always call this function to log
changes to the code that should result in a different end result.
If a project is connected to a remote repository on GitHub, it is possible to use GitHub actions to automatically check a project’s reproducibility and signal the result of this reproducibility check by displaying a badge on the project’s readme page (which is the welcome page visitors of the GitHub repository first see).
To do so, follow these steps:
'manuscript/manuscript.md'
,
then you would call
add_endpoint('manuscript/manuscript.md')
github_action_check_endpoints()
readme.md
. If you do not see this message,
add the following code to your readme.md manually:
[](https://github.com/YOUR_ACCOUNT/PROJECT_REPOSITORY/actions/workflows/worcs_endpoints.yaml)
git_update()
Visit your project page on GitHub and select the Actions
tab to see that your reproducibility check is running; visit the main
project page to see the new badge in your readme.md file.