new_edit_delete: Create, edit or delete projects, authors and affiliations
In projects: A Project Infrastructure for Researchers

Description Usage Arguments Details Value Examples

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.

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,
  corresp_auth = NA,
  creator = NA,
  deadline_type = NA,
  deadline = NA,
  id = NA,
  folder_name = paste0("p", stringr::str_pad(id, 4, pad = "0")),
  parent_directory = projects_folder(),
  make_directories = FALSE,
  template_folder = "default_folder"
)

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)

`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, this author's contact information will be especially included in the output of `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"`. See projects_stage-class.
`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.
`authors, affiliations`	For `new_project()`/`new_author()`, a vector of `id`s 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 and `-` to remove (see formula). Authors and affiliations 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 (via `lubridate::as_datetime()`).
`id`	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.
`folder_name`	A character string that can serve as a valid directory name. By default, it is "p" followed by the project `id` number left-filled with "0" until the number is four digits long.
`parent_directory`	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 value of `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.
`template_folder`	A character string naming a folder in the .templates folder that will be copied into the projects folder as the new project folder, renamed according to the value of the `folder_name` argument. See also Details below.
`...`	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 when `header()` is run.
`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`, `email` will be included in "Corresponding author:" section written by `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.

new_project() copies the folder in the .templates folder named by the template_name argument into the projects folder, giving it the name specified by the folder_name argument. It then creates a line in the projects() table for the newly created project, filling many of its fields with the contents of corresponding arguments of this function. See setup_projects() for more information on the .templates folder.

delete_project() deletes project folders and removes their line from the projects() table.

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.

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.

#############################################################################
# SETUP
old_home <- Sys.getenv("HOME")
old_ppath <- Sys.getenv("PROJECTS_FOLDER_PATH")
temp_dir <- tempfile("dir")
dir.create(temp_dir)
Sys.unsetenv("PROJECTS_FOLDER_PATH")
Sys.setenv(HOME = temp_dir)
setup_projects(path = temp_dir)
#############################################################################

# 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 = NA)

# 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",
  parent_directory = "famous_studied/philosophers/rocks",
  corresp_auth = "Stone",
  current_owner = "agnew",
  make_directories = 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(HOME = old_home, PROJECTS_FOLDER_PATH = old_ppath)