- Installation
- Making a new PHS project
- Making a new PHS shiny app
- Adding a new PHS .gitignore
- RMarkdown Templates
Install this package by running the following code in R:
remotes::install_github("Public-Health-Scotland/phstemplates", ref = "main")
If you are working inside the PHS network then this may not work in which case follow these steps:
- Click Clone or download
- Click Download ZIP
- Save the zip file locally
- Unzip the zip file
- Replace the sections marked
<>
below (including the arrows themselves) and run the following code in R:
install.packages("<FILEPATH OF UNZIPPED FILE>/phstemplates-main", repos = NULL,
type = "source")
If you encounter any issues with the automatic installation of package dependencies using this method, you may need to install these manually prior to running the code to install phstemplates. In this case, it should tell you which packages you need. For example, if you need flextable and officer, install these first:
install.packages(c("flextable", "officer"))
A further option is to install this package using drat. The advantage of this method is that it should work from within the PHS network but the disadvantage is that it may not always be completely in sync with the latest version of the package on GitHub. Note that the first line to install the drat package is only needed if you don't already have it installed.
install.packages("drat")
drat::addRepo("alan-y")
install.packages("phstemplates")
To use this project template, install the package by following the instructions above. After doing this you will then be able to create new R projects with the recommended PHS structure within RStudio by clicking File -> New Project... -> New Directory and selecting PHS R Project Template. Name the project and select a location for the project folder. The original author can also be input - this will automatically add the name to the top section of default scripts within the project. You can then edit the files and folders as appropriate, e.g. rename the R script files or create new sub-folders. The default files and folders contained within the project are described in subsequent sections of this README.
This template aims to instill best practice within PHS and therefore git has been initialised for version control. However, if you are not using this then you can delete the .gitignore file. More information about version control.
If you are using git for version control then please be aware that the .gitignore contains the minimum recommended file types and folders to stop data being tracked and pushed to GitHub. Further guidance on using git and GitHub securely can be found here.
This template is also intended to be flexible, so you may not require every file or folder. For example, if you have written long or multiple functions then we would recommend saving these in the dedicated functions.R
file, which can then be sourced within the main script(s). Additionally, if you are using many packages then these could be saved within the packages.R
file and sourced similarly. However, decisions on whether these files are required and the exact structure of the folders and scripts should be left up to the analyst's discretion. For more guidance on structuring and writing R scripts follow the organisation's R Style Guide.
code
- R scripts required for projectcode.R
- example structure for main R script(s)functions.R
- functions sourced and used in main script(s)packages.R
- list of packages sourced and used in main script(s)
data
- data required for projectbasefiles
output
temporary
.gitignore
- tells git what files and folders not to track or upload to GitHubREADME.md
- this page.Rprofile
- R profile settingsr-project.Proj
- R project
After installation you will then be able to create new R shiny apps with PHS styling within RStudio by clicking File -> New Project... -> New Directory and selecting PHS R Shiny App. Name the app and select a location for the project folder. The original author can also be input - this will automatically add the name to the top section of default scripts within the project. You can then edit the files and folders as appropriate, e.g. rename the R script files or create new sub-folders. The default files and folders contained within the project are described in the README which is created inside the new shiny app template.
If you want to add a PHS style .gitignore
to a given directory, you can do this in R Studio by selecting Addins
on the top banner then scrolling down to the PHSTEMPLATES section and choosing Add PHS .gitignore file. This will allow you to choose the location of your new .gitignore
file. You can also do this directly from the R console using the command phstemplates::add_gitignore()
.
This package currently provides a number of RMarkdown templates including templates for PHS national statistics report and summary documents but please note that these require pandoc v2 (or RStudio v1.2 which comes with the required version of pandoc). You can check the version of pandoc that you have with rmarkdown::pandoc_version()
.
You can access these templates in RStudio by clicking File -> New File -> R Markdown -> From Template.
- Clone phstemplates and load it up in RStudio
- Create your own Git branch and switch to that branch
- In R, type
usethis::use_rmarkdown_template("my-template")
where you replacemy-template
with the name you want to give your template. This is actually just the name it gives to the folder that stores your template so the name should not have spaces but can contain dashes or underscores. The name should also not be too long as this may cause issues when building the package. This will create a basic structure for your template within the directoryinst\rmarkdown\templates\my-template
- Open up
template.yaml
in the folder just created for your template. Update the name and description as appropriate for your template. - Go to the 'skeleton' folder (
inst\rmarkdown\templates\my-template\skeleton
) and deleteskeleton.Rmd
- Copy and paste your RMarkdown template file and any associated files required for the template into the 'skeleton' folder (e.g. you may have an MS Word reference document to set up styles)
- Rename your RMarkdown template file to
skeleton.Rmd
- Run
devtools::check()
and make sure the package passes all the checks - Run
devtools::install()
, then restart RStudio and check that your templates can be loaded from the RStudio menus - Push to Github
- Create a pull request and ask for a review from an appropriate staff member so the changes can be merged
- Clone phstemplates and load it up in RStudio
- Create your own Git branch and switch to that branch
- Rename your updated template file to
skeleton.Rmd
and place it (and any associated files if they have also been updated) inside the 'skeleton' folder of your template (inst\rmarkdown\templates\your-template\skeleton
) - Run
devtools::check()
and make sure the package passes all the checks - Run
devtools::install()
, then restart RStudio and check that your templates can be loaded from the RStudio menus - Push to Github
- Create a pull request and ask for a review from an appropriate staff member so the changes can be merged