R/create_protocol.R
create_protocol.RdThis 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.
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
)Either sfp (standard field protocol), spp (
standard project protocol), sap (standard analytical protocol), sip (
standard instrument protocol), sop (standard operating protocol)
A character string giving the main title of the protocol
A character string of less than 20 characters to use in folder and file names
A character vector for authors of the form
c("lastname1, firstname1", "lastname2, firstname2")
A character vector of orcid IDs, equal in length to authors.
If one of the authors does not have an orcid ID, use NA to indicate this
in the corresponding position of the character vector (or get an orcid ID).
A character string of the date in ISO 8601 format (YYYY-MM-DD)
A character vector for reviewers of the form First name Last name
A character string for the name of the document maintainer of the form First name Last name
A version number of the form YYYY.##.
The default is a function which will determine this number automatically.
It should normally not be changed.
A character string equal to one of "generic" (default),
"water", "air", "soil", "vegetation" or "species". It is used as
the folder location (source/sfp/theme) where standard field protocols
that belong to the same theme will be stored.
Ignored if protocol_type is other than "sfp".
A character string that is used as the folder location
(source/spp/project_name) where project-specific protocols that belong to
the same project will be stored. Preferably a short name or acronym. If the
folder does not exist, it will be created.
Ignored if protocol_type is other than "spp".
Language of the protocol, either "nl" (Dutch),
the default, or "en" (English).
A character string for an optional subtitle
A character string with the path (absolute or relative) to
a .docx file containing a pre-existing protocol.
Please make sure to copy-paste all relevant meta-data from the .docx file
to the corresponding parameters of this function.
If nothing is provided (i.e. default = NULL), an empty template will be used.
A character string giving the protocol number.
This parameter should normally not be specified (i.e. NULL), unless
from_docx is specified.
A protocol number is a three digit string where the first digit corresponds
with a theme and the last two digits identify a protocol within a theme for
standard field protocols. A protocol number for other protocol types
is just a three digit string.
If NULL (the default), a protocol number will be determined automatically
based on pre-existing protocol numbers.
Note that for backwards compatibility with protocol numbers that were already
in use at INBO, we made a list of reserved numbers.
These reserved numbers will not be used when protocol_number is NULL.
The only time you will need to explicitly pass a protocol number to the
protocol_number argument is when you want to migrate a pre-existing INBO
protocol to protocolsource and hence use one of the reserved numbers.
Protocol numbers that are already in use in protocolsource can be retrieved
with get_protocolnumbers().
Which template to use?
Default is set equal to protocol_type.
However, you can also set this to "generic" in which case a simplified
template will be used that can be used as an alternative to the default
templates.
Whether or not to render the protocol to html. Defaults to FALSE.
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.
Other creation:
add_dependencies(),
add_one_subprotocol(),
add_subprotocols(),
insert_protocolsection(),
update_protocol(),
update_version_number()
if (FALSE) { # \dontrun{
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")
} # }