new_edit_delete: Create, edit or delete projects, authors and affiliations

Description

These functions create, edit, or delete rows in the projects(), authors(), and affiliations() tables, which are stored in the .metadata subdirectory of the main projects folder.

Usage

new_project(title = NA, current_owner = NA, stage = c("1: design",
  "2: data collection", "3: analysis", "4: manuscript", "5: under review",
  "6: accepted", "0: idea"), status = "just created", short_title = NA,
  authors = NULL, deadline_type = NA, deadline = NA,
  path = projects_folder(), make_directories = FALSE,
  corresp_auth = NA, creator = NA, id = NA,
  protocol = c("01_protocol.Rmd", "STROBE_protocol.Rmd",
  "CONSORT_protocol.Rmd"), datawork = "02_datawork.Rmd",
  analysis = "03_analysis.Rmd", report = "04_report.Rmd",
  css = "style.css", Rproj = "pXXXX.Rproj", use_bib = FALSE,
  stitle_as_folder = FALSE)
new_idea(title, status = "just an idea", ...)
new_author(given_names = NA, last_name = NA, title = NA,
  affiliations = NULL, degree = NA, email = NA, phone = NA,
  id = NA)
new_affiliation(department_name = NA, institution_name = NA,
  address = NA, id = NA)
edit_project(project, title = NULL, short_title = NULL,
  authors = NULL, current_owner = NULL, status = NULL,
  deadline_type = NULL, deadline = NULL, stage = NULL,
  corresp_auth = NULL, creator = NULL, archived = FALSE)
edit_author(author, given_names = NULL, last_name = NULL,
  affiliations = NULL, title = NULL, degree = NULL, email = NULL,
  phone = NULL)
edit_affiliation(affiliation, department_name = NULL,
  institution_name = NULL, address = NULL)
delete_project(project, archived = FALSE)
delete_author(author)
delete_affiliation(affiliation)

Arguments

title

For new_project(), new_idea(), and edit_project(), the title of the project.

For the new_author() and edit_author(), the job title of the author.

current_owner, corresp_auth, creator

An id or unambiguous last_name/given_names of one of the authors in the authors() table, which will be coerced into a projects_author class object.

If corresp_auth is specified, all of this author's contact information will be especially included in the project's header.

If creator is left blank, the numeric portion of the resulting projects_author class object will be 0, followed by the value of Sys.info()["user"] (e.g., 0: user_j_smith).

stage

A number or string that will partially match exactly one of c("1: design", "2: data collection", "3: analysis", "4: manuscript", "5: under review", "6: accepted", "0: ideas"), communicating the stage the project is in. This will be coerced to be a character vector of class projects_stage.

For new_project(), defaults to "1: design".

If set to one of c("3: analysis", "4: manuscript", "5: under review", "6: accepted"), protocol and datawork are ignored and the 01_protocol.Rmd and 02_datawork.Rmd files will not be written.

See projects_stage.

status

A free text field, intended to communicate the most current condition the project is in.

For new_project(), default is "just created". For new_idea(), default is "just an idea".

short_title

A nickname for the project. Can be used in other projects package functions whenever needing to specify a project.

Additionally, see the parameter info for stitle_as_folder below.

authors, affiliations

For new_project()/new_author(), a vector of ids or unambiguous given_names/last_name or department_name/institution_name of authors/affiliations. Order will be preserved.

For edit_project()/edit_author(), a formula specifying authors/affiliations to add or remove from the project/author. Formulas must have no left-hand side (i.e., begin with ~) and use + to add authors and - to remove authors (see formula). Authors may be specified by id or name.

Each element must match an existing row in the authors()/affiliations() table.

deadline_type

A free text field, intended to communicate the meaning of the next field, deadline.

deadline

A POSIXct object or something coercible to one.

path

A character string that can be read as a file path. Can be either:

the absolute path of the projects folder (i.e., the value of projects_folder(), which is the default)
an absolute path pointing to a subfolder within the projects folder
a relative path (leading "." optional) that will be appended onto the end of the projects folder.

In any case, the result is that the new project folder will be a subdirectory of the main projects folder. See also setup_projects().

make_directories

Logical, indicating whether or not new_project() should create subdirectories specified in the path argument that do not already exist. Ignored if path is left as the default or if all directories in path already exist.

An integer that will become the item's permanent identification number. Must be in the range 1-9999 or left blank. If left blank, the lowest available integer in the aforementioned range will be selected.

For new_project, this number will also determine the project folder's and .Rproj file's names. See Details.

protocol, datawork, analysis, report, css, Rproj

A character string matching the name of a corresponding template file in the .templates subdirectory of the main projects folder. Default templates are placed there when setup_projects() is run, and the user can edit these if desired.

Multiple default protocol templates are available.

01_protocol.Rmd, which by default is the same as STROBE_protocol.Rmd, will be selected if protocol is unspecified. Users can edit these default templates.

If using an edited or custom template, make sure to match the case and file extension exactly.

If the stage argument is set to one of c("3: analysis", "4: manuscript", "5: under review", "6: accepted"), protocol and datawork are ignored and the 01_protocol.Rmd and 02_datawork.Rmd files will not be written.

use_bib

Logical. If TRUE, a blank .bib file will be written into the progs subdirectory of the newly created project folder. Its name will be of the form pXXXX.bib, and the YAML header of progs/01_protocol.Rmd and progs/04_report.Rmd will include the line bibliography: pXXXX.bib.

stitle_as_folder

Logical, indicating whether or not to use the short_title as the name of the new project's folder. Defaults to FALSE.

...

Additional arguments to be passed to new_project()

given_names, last_name, department_name, institution_name

Each a single character string. Can be used whenever needing to specify a specific author/affiliation.

degree

A character string (preferably an abbreviation) denoting the author's academic degree(s). Will be written next to author names in the header.

email, phone

A character string denoting the email/phone of the author. Email will be coerced to lowercase. When a project is given a corresp_auth, these items will be included in the header.

address

A character string indicating the address of the affiliation.

project, author, affiliation

The id or unambiguous name(s) of a project/author/affiliation to edit_*() or to delete_*().

archived

Logical indicating whether or not the function should consider archived projects when determining which project the user is referring to in the project argument. FALSE by default.

See the Details section of archive_project() for more information on the "archived" status of a project.

Value

new_affiliation() and edit_affiliation() simply return the new or edited row of the affiliations() tibble.

new_project(), new_author(), edit_project(), edit_author(), and the delete_*() functions invisibly return the row of the corresponding metadata tibble that was added/edited/deleted, although the contents of this row are printed as a side-effect along with the other relevant information where applicable (e.g., project authors, author affiliations, project file paths).

new_idea() returns the id, title, and status columns of the newly created row of the projects() tibble.

Details

new_project() creates a new R project folder that is automatically filled with a .Rproj file, helpful subdirectories, and .Rmd files to get your project workflow started; delete_project() deletes them. The edit_*() functions and the other new_*() and delete_*() functions only create or edit rows in the .metadata tables. new_idea() is a convenience function for quickly creating projects in the "0: idea" stage.

Unless the user sets stitle_as_folder = TRUE, the name of a newly created project folder (and the .Rproj file it contains) will be of the form "pXXXX", where "XXXX" denotes the project id number, left-filled with 0s. The folder will be an immediate subdirectory of the main projects folder (see also setup_projects()) unless the argument path specifies a deeper subdirectory. The user may enter various metadata about the project that is stored and may be called forth using the projects() function. Some of this metadata will automatically be added to the header atop the automatically created .Rmd files called progs/01_protocol.Rmd and progs/04_report.Rmd.

Examples

Run this code

# NOT RUN {
# SETUP
old_path <- Sys.getenv("PROJECTS_FOLDER_PATH")
setup_projects(path = tempdir(), .Renviron_path = fs::path_temp(".Renviron"))
############################################################################

# Creating affiliations
new_affiliation(department_name = "Math Dept.",
                institution_name = "Springfield College",
                address = "123 College St, Springfield, AB")
new_affiliation(department_name = "Art Department",
                institution_name = "Springfield College",
                address = "321 University Boulevard, Springfield, AB",
                id = 42)

# Editing an affiliation
edit_affiliation("Math Dept", department_name = "Mathematics Department")

# Creating authors
new_author(
  given_names = "Rosetta",
  last_name = "Stone",
  affiliations = c(42, "Math"),
  degree = "PhD",
  email = "slab@rock.net",
  phone = "867-555-5309",
  id = 8888
)
new_author(
  given_names = "Spiro",
  last_name = "Agnew",
  degree = "LLB",
  affiliations = "Art D", id = 13
)
new_author(last_name = "Plato", id = 303)

# Editing an author, showcasing the removal of a text element (last_name)
edit_author(author = 303, given_names = "Plato", last_name = NULL)

# Editing an author, showcasing the addition and removal of affiliations
edit_author("Spiro", affiliations = ~ -"Art D" + Math)

# Creating a project
new_project(
  title = "Understanding the Construction of the United States",
  short_title = "USA",
  authors = c(13, "Stone"),
  stage = 4,
  deadline = "2055-02-28",
  deadline_type = "submission",
  path = "famous_studied/philosophers/rocks",
  corresp_auth = "Stone",
  current_owner = "agnew",
  make_directories = TRUE,
  use_bib = TRUE,
  status = "waiting on IRB"
)

# Editing a project, showcasing the addition and removal of authors
edit_project(
  "Understanding",
  short_title = "usa1",
  authors = ~ + "303" - 13 - Stone
)

new_idea(title = "Boiling the Ocean")

# Wrapped in if (interactive()) because it requires interactive console input
# and fails automated package checking and testing.
if (interactive()) {
  delete_project("usa1")
  delete_author(303)
  delete_affiliation("Math")
}

#############################################################################
# CLEANUP
Sys.setenv(PROJECTS_FOLDER_PATH = old_path)
fs::file_delete(c(fs::path_temp("projects"), fs::path_temp(".Renviron")))
# }

Run the code above in your browser using DataLab