Package 'protocolhelper'

Description

After using convert_docx_to_rmd(), figure and table captions are part of the main text and cross references to them are just text and numbers, making it difficult to integrate these .Rmd files in reports: they are not automatically renumbered, these captions cannot be listed,... This function replaces the figure and table descriptions with true captions, and cross references to these figures and tables with dynamic references (that refer to the figure or table label).

Usage

add_captions(
  from,
  to,
  name_figure_from = "Figuur",
  name_table_from = "Tabel",
  name_figure_to = "Figuur",
  name_table_to = "Tabel"
)

Arguments

Details

This function expects an input that is generated by convert_docx_to_rmd(), with

• figure captions below the figure and starting with Figuur (or other name to be defined in variable name_figure), then a unique number and finally the description in one paragraph

• table captions above the table and starting with Tabel (or other name to be defined in variable name_table), then a unique number and finally the description in one paragraph

• figures consisting of one image, not 2 figures near each other

• cross references having the same label as the figure or table they refer to, default Figuur or Tabel followed by the unique number written in exactly the same way

Please check carefully for mistakes after using this function

See Also

Other convert: convert_docx_to_rmd()

Description

Adds dependencies to the YAML of an index.Rmd file

Usage

add_dependencies(
  code_mainprotocol,
  protocol_code,
  version_number,
  params,
  appendix = !is.na(params)
)

Arguments

See Also

Other creation: add_one_subprotocol(), add_subprotocols(), create_protocol(), insert_protocolsection(), update_protocol(), update_version_number()

Examples

## Not run: 
protocolhelper::add_dependencies(
  code_mainprotocol = "spp-999-en",
  protocol_code = c("sfp-123-en", "spp-124-en"),
  version_number = c("2020.01", "2020.02"),
  params = list(NA, list(width = 8, height = 8))
  )

## End(Not run)

Description

The function adds a reference label to the caption so that pander tables can be cross-referenced in bookdown using the ⁠\@ref(tab:label)⁠ syntax. The function should only be used in pander(x, caption = add_label()).

Usage

add_label(caption = "", tag = "tab")

Arguments

Value

The caption text prefixed with a reference label.

See Also

Other utility: get_path_to_protocol(), get_protocol_type(), get_protocolnumbers(), get_short_titles(), get_version_number(), increment_version_number()

Examples

add_label("caption text")

Description

The function renders the sub-protocol to bookdown::markdown_document2() and saves the resulting md file (and any associated media and data files) in a subfolder of the directory of the project-specific protocol. This function should normally not be called directly. Use add_subprotocols() instead.

Usage

add_one_subprotocol(
  code_subprotocol,
  version_number,
  params2 = NULL,
  code_mainprotocol,
  fetch_remote = TRUE
)

Arguments

See Also

Other creation: add_dependencies(), add_subprotocols(), create_protocol(), insert_protocolsection(), update_protocol(), update_version_number()

Examples

## Not run: 
  add_subprotocols(code_mainprotocol = 'spp-999-en')

## End(Not run)

Description

The function should be called interactively (in the console) after the dependencies section in the YAML header of the index.Rmd file of the main protocol has been filled in with the aid of the protocolhelper::add_dependencies() function. For reproducibility, it is good practice to save the call in a separate R script. For each sub-protocol a single markdown file and associated media and data files will be written. Each sub-protocol will be written to a subfolder of the main protocol. The subfolder name is the same as the version number of the sub-protocol.

Usage

add_subprotocols(code_mainprotocol, fetch_remote = TRUE)

Arguments

See Also

Other creation: add_dependencies(), add_one_subprotocol(), create_protocol(), insert_protocolsection(), update_protocol(), update_version_number()

Description

Combines check_frontmatter() and check_structure() in one function.

Usage

check_all(protocol_code, fail = !interactive())

Arguments

Value

A report of all failed checks.

See Also

Other check: check_all_author_info(), check_frontmatter(), check_structure(), protocolcheck, validate_orcid()

Description

Checks the format of author names and orcid ids.

Usage

check_all_author_info(author_list, problems_vect)

Arguments

Value

a character vector of previously encountered problems and problems identified for author names and orcid ids.

See Also

Other check: check_all(), check_frontmatter(), check_structure(), protocolcheck, validate_orcid()

Description

This function reads metadata from the yaml front matter stored in the index.Rmd file of a protocol and checks if the metadata format is correct. This function is intended for checking if a protocol is ready to be rendered and published (for instance, it will fail if version number is YYYY.NN.dev).

Usage

check_frontmatter(protocol_code, fail = !interactive())

Arguments

Value

A report of all failed checks.

See Also

Other check: check_all(), check_all_author_info(), check_structure(), protocolcheck, validate_orcid()

Description

This function reads the protocol and checks if the document structure is correct: chunks have head and tail, required headings are present and in the right order,... This function is intended for checking if a protocol is ready to be rendered and published.

Usage

check_structure(protocol_code, fail = !interactive())

Arguments

Value

A report of all failed checks.

See Also

Other check: check_all(), check_all_author_info(), check_frontmatter(), protocolcheck, validate_orcid()

Description

This function is derived from the redoc::dedoc() function and uses pandoc to convert between docx and markdown. Several options are preset to end-up with a markdown document that is in syntax as close as possible to Rmarkdown files in RStudio. During conversion, graphics (e.g. png, jpg) will be extracted from the docx archive and placed in a folder ./media and named image1, image2, etcetera. Additionally, .emf files will be converted to .png.

Usage

convert_docx_to_rmd(
  from,
  to = sub("docx$", "Rmd", from),
  dir_media = ".",
  wrap = NA,
  overwrite = FALSE,
  verbose = FALSE,
  wd = getwd()
)

Arguments

Details

Metadata in the page headers and footers of the docx are ignored and will thus be lost during conversion. In case the header or footer did contain important metadata, it will need to be recovered manually. Usually header information will go inside a yaml section of an Rmarkdown.

See Also

Other convert: add_captions()

Description

This function will create a new folder based on values that are passed on via the parameters and creates a R-markdown (bookdown) skeleton based on a template file to start working on a new protocol. Optionally, the rmarkdown chapters are rendered to an html file which will be saved in a matching subfolder of the docs folder.

Usage

create_protocol(
  protocol_type = c("sfp", "spp", "sap", "sop", "sip"),
  title,
  short_title,
  authors,
  orcids,
  date = Sys.Date(),
  reviewers,
  file_manager,
  version_number = get_version_number(),
  theme = NULL,
  project_name = NULL,
  language = c("nl", "en"),
  subtitle = NULL,
  from_docx = NULL,
  protocol_number = NULL,
  template = protocol_type,
  render = FALSE
)

create_sfp(
  title,
  subtitle = NULL,
  short_title,
  authors,
  orcids,
  date = Sys.Date(),
  reviewers,
  file_manager,
  version_number = get_version_number(),
  theme = c("generic", "water", "air", "soil", "vegetation", "species"),
  language = c("nl", "en"),
  from_docx = NULL,
  protocol_number = NULL,
  template = c("sfp", "generic"),
  render = FALSE
)

create_spp(
  title,
  subtitle = NULL,
  short_title,
  authors,
  orcids,
  date = Sys.Date(),
  reviewers,
  file_manager,
  version_number = get_version_number(),
  project_name,
  language = c("nl", "en"),
  from_docx = NULL,
  protocol_number = NULL,
  template = c("spp"),
  render = FALSE
)

create_sap(
  title,
  subtitle = NULL,
  short_title,
  authors,
  orcids,
  date = Sys.Date(),
  reviewers,
  file_manager,
  version_number = get_version_number(),
  language = c("nl", "en"),
  from_docx = NULL,
  protocol_number = NULL,
  template = c("sap", "generic"),
  render = FALSE
)

create_sip(
  title,
  subtitle = NULL,
  short_title,
  authors,
  orcids,
  date = Sys.Date(),
  reviewers,
  file_manager,
  version_number = get_version_number(),
  language = c("nl", "en"),
  from_docx = NULL,
  protocol_number = NULL,
  template = c("sip", "generic"),
  render = FALSE
)

create_sop(
  title,
  subtitle = NULL,
  short_title,
  authors,
  orcids,
  date = Sys.Date(),
  reviewers,
  file_manager,
  version_number = get_version_number(),
  language = c("nl", "en"),
  from_docx = NULL,
  protocol_number = NULL,
  template = c("sop", "generic"),
  render = FALSE
)

Arguments

Details

It is assumed that the source folder is a subfolder of an RStudio project with git version control. A target folder to which files will be written will be created as subdirectories beneath source. The subfolder structure is of the form ⁠/sfp/<theme>/<sfp>_<protocolnumber>_<language>_<short_title>/⁠ for standard field protocols. Or ⁠/spp/<project_name>/<spp>_<protocolnumber>_<language>_<short_title>/⁠ for standard project protocols. Or ⁠/sip/<sip>_<protocolnumber>_<language>_<short_title>/⁠ for sips (and analogous for sop and sap). The folder names are determined by the corresponding arguments of the function. A matching subfolder structure will be created beneath the docs folder (and output files needed for rendering to html output will be placed in it if render = TRUE. The template Rmarkdown files and the Rmarkdown files that result from converting a docx protocol (see from_docx argument), will be written to the target folder beneath source. Template Rmarkdown files with the same name as Rmarkdown files that result from converting a docx protocol will be overwritten by the latter. Besides Rmarkdown files, this target folder will also contain files needed to render to a Bookdown gitbook such as a ⁠_bookdown.yml⁠ and ⁠_output.yml⁠. The NEWS.md file must be used to document the changes between revisions of the protocol. Furthermore, a data and a media folder will be created as subdirectories of the target folder. The media folder can be used to store image files and will contain image files extracted from the docx protocol when the from_docx argument is used. The data folder can be used to store tabular data that are needed for the protocol.

See Also

Other creation: add_dependencies(), add_one_subprotocol(), add_subprotocols(), insert_protocolsection(), update_protocol(), update_version_number()

Examples

## Not run: 
protocolhelper::create_protocol(
  protocol_type = "sfp",
  title = "Test 1", subtitle = "subtitle", short_title = "water 1",
  authors = c("Someone, Else", "Another, One"),
  orcids = c("0000-0001-2345-6789", "0000-0002-2345-6789"),
  reviewers = "me", file_manager = "who?",
  theme = "water", language = "en")

## End(Not run)

Description

A function that is used by other functions and should normally not be used directly.

For existing protocol codes, arguments theme and project_name are always ignored. The function will return the absolute path for that protocol.

For new sfp or spp protocols, also either the theme or the project_name argument and short_title are required apart from the protocol_code. The function will construct the absolute path where the source code for that new protocol will be written.

Usage

get_path_to_protocol(
  protocol_code,
  theme = NULL,
  project_name = NULL,
  short_title = NULL
)

Arguments

Value

A character vector containing the full path to the protocol.

See Also

Other utility: add_label(), get_protocol_type(), get_protocolnumbers(), get_short_titles(), get_version_number(), increment_version_number()

Examples

## Not run: 
get_path_to_protocol(protocol_code = "sfp-401-nl")

## End(Not run)

Description

The protocol type corresponds to the first 3 letters of the protocol code

Usage

get_protocol_type(protocol_code, labels = TRUE, auto_identifier = FALSE)

Arguments

Value

A factor with 5 levels corresponding to sfp, sip, sap, sop and spp. The labels depend on auto_identifier setting.

See Also

Other utility: add_label(), get_path_to_protocol(), get_protocolnumbers(), get_short_titles(), get_version_number(), increment_version_number()

Description

This function will search for protocol numbers in filenames of Rmarkdown files listed underneath the source folder. The search will be restricted to files of a given protocol type and given language.

Usage

get_protocolnumbers(
  protocol_type = c("sfp", "sip", "sap", "sop", "spp"),
  language = c("nl", "en")
)

Arguments

Value

A character vector with occupied protocol numbers for a specific protocol type

See Also

Other utility: add_label(), get_path_to_protocol(), get_protocol_type(), get_short_titles(), get_version_number(), increment_version_number()

Examples

## Not run: 
get_protocolnumbers()

## End(Not run)

Description

This function will search for short titles in filenames of Rmarkdown files listed underneath the source folder. The search will be restricted to files of a given protocol type and given language.

Usage

get_short_titles(
  protocol_type = c("sfp", "sip", "sap", "sop", "spp"),
  language = c("nl", "en")
)

Arguments

Value

A character vector with short titles that are in use for a given protocol type.

See Also

Other utility: add_label(), get_path_to_protocol(), get_protocol_type(), get_protocolnumbers(), get_version_number(), increment_version_number()

Examples

## Not run: 
get_short_titles()

## End(Not run)

Description

Looks up pre-existing version numbers of protocols in the main branch and calculates an incremented (next) version number for the currently checkout branch containing the created/in development/updated/ready to be released protocol. Your local main branch needs to up to date (aligned with remote) for this. If this is not the case, or other issues are detected regarding a non-clean local git repository - informative error messages will be given.

Usage

get_version_number(path = ".")

Arguments

Value

A string containing the next (incremented) version number

See Also

Other utility: add_label(), get_path_to_protocol(), get_protocol_type(), get_protocolnumbers(), get_short_titles(), increment_version_number()

Description

Given a set of published protocol version numbers, calculate the next version number

Usage

increment_version_number(versions)

Arguments

Value

A string containing the next (incremented) version number

See Also

Other utility: add_label(), get_path_to_protocol(), get_protocol_type(), get_protocolnumbers(), get_short_titles(), get_version_number()

Description

The idea is to execute this function in an R chunk with knitr option results="asis".

Usage

insert_protocolsection(
  code_subprotocol,
  version_number,
  file_name,
  section = NULL,
  demote_header = c(0, 1, 2, -1),
  fetch_remote = TRUE
)

Arguments

Value

The function will return Rmarkdown

See Also

Other creation: add_dependencies(), add_one_subprotocol(), add_subprotocols(), create_protocol(), update_protocol(), update_version_number()

Examples

## Not run: 
insert_protocolsection(
  code_subprotocol = "sfp-401-nl",
  version_number = "2021.01",
  file_name = "07_stappenplan.Rmd"
)

## End(Not run)

Description

A class that collects and shows all check results.

Public fields

Methods

Public methods

• protocolcheck$new()

• protocolcheck$add_error()

• protocolcheck$check()

• protocolcheck$clone()

Method new()

Create a new Protocolcheck object.

Usage

protocolcheck$new(protocol_code)

Arguments

Returns

A new Protocolcheck object

Method add_error()

Add a new error to the Protocolcheck object.

Usage

protocolcheck$add_error(msg)

Arguments

Method check()

Give error report from Protocolcheck object.

Usage

protocolcheck$check(fail)

Arguments

Returns

An error report (and if desired an error is dropped).

Method clone()

The objects of this class are cloneable with this method.

Usage

protocolcheck$clone(deep = FALSE)

Arguments

See Also

Other check: check_all(), check_all_author_info(), check_frontmatter(), check_structure(), validate_orcid()

Description

This function is a simple wrapper around bookdown::render_book() and can be used to render a protocol to html and pdf in order to preview updates that have been made.

Usage

render_protocol(protocol_code = NULL, output_dir = NULL, ...)

Arguments

Details

The rendered html and pdf file and associated files needed by the html file will be put in the directory implied by the output_dir parameter.

Examples

## Not run: 
render_protocol(protocol_code = "sfp_401-nl")

## End(Not run)

Description

The function creates a branch named after the protocol_code

Usage

update_protocol(protocol_code)

Arguments

Value

NULL invisibly

See Also

Other creation: add_dependencies(), add_one_subprotocol(), add_subprotocols(), create_protocol(), insert_protocolsection(), update_version_number()

Description

Makes use of get_version_number to get a new version number and changes this accordingly in the YAML section of index.Rmd file and optionally in NEWS.md.

Usage

update_version_number(
  protocol_code,
  commit = TRUE,
  update_news = TRUE,
  path = "."
)

Arguments

Value

TRUE if version number in yaml is updated. FALSE otherwise.

See Also

Other creation: add_dependencies(), add_one_subprotocol(), add_subprotocols(), create_protocol(), insert_protocolsection(), update_protocol()

Description

Generates check digit as per ISO 7064 11,2. The last character in the ⁠ORCID ID⁠ is a checksum. In accordance with ISO/IEC 7064:2003, MOD 11-2, this checksum must be "0-9" or "X", a capital letter X which represents the value 10.

Usage

validate_orcid(orcid)

Arguments

Value

Logical. TRUE if check digit is correct.

See Also

Other check: check_all(), check_all_author_info(), check_frontmatter(), check_structure(), protocolcheck

Examples

validate_orcid("0000-0002-6378-6229")