Skip to contents

Working with Individuals

Source: vignettes/individuals.qmd

Introduction

The citeme package provides a collection of helper functions for managing individual contributor information across your projects. These functions help you store, retrieve, and reuse information about people who contribute to your work, ensuring consistency and reducing repetitive data entry.

Why Use Individual Helper Functions?

When working on multiple projects, you often need to cite the same contributors repeatedly. The individual helper functions in citeme allow you to:

  • Build a local database of contributor information
  • Reuse stored information across projects
  • Maintain consistent contributor details
  • Convert individual information between different formats
  • Add contributors to various file types (DESCRIPTION, README, Quarto, Bookdown)

Storing Individual Information

The store_individuals() function extracts contributor information from a project and saves it to a local database for future use. This database is stored in your user data directory and persists across projects.

library(citeme)

# Store individuals from a project with a DESCRIPTION file
store_individuals("path/to/r-package")

# Store individuals from a project with citation metadata
store_individuals("path/to/project")

The function extracts information from:

  • R packages: Reads the DESCRIPTION file to get author details
  • Other projects: Reads citation metadata files

Each time you store individuals, the function tracks how often each person appears across your projects. This usage count helps prioritise frequently used contributors when selecting individuals later.

Selecting and Reusing Individuals

The select_individual() function allows you to interactively choose a contributor from your stored database or add a new one.

# Interactive selection from stored individuals
individual <- select_individual()

# Quick selection by email address
individual <- select_individual(email = "john.doe@example.com")

# Selection with specific language for affiliation
# provided the individual's email matches an organisation with multilingual
# names
individual <- select_individual(lang = "nl-BE")

The function presents stored individuals ordered by:

  1. Usage count (most frequently used first)
  2. Family name
  3. Given name
  4. ORCID identifier

When selecting interactively, you can also:

  • Add a new individual if they are not in the database
  • Update existing individual information

Converting Individual Information

To Person Objects

The individual2person() function converts individual information into R’s person object format, which is used in DESCRIPTION files and citation metadata.

# Convert with default author role
person_obj <- individual2person(individual)

# Convert with specific role
person_obj <- individual2person(individual, role = "cre")

# Convert with multiple roles
person_obj <- individual2person(individual, role = c("aut", "cre"))

# Interactive selection and conversion
person_obj <- individual2person(lang = "en-GB")

The function automatically handles:

  • Optional fields (email, ORCID, affiliation)
  • Multiple roles per person
  • Language-specific affiliations

To Badge Format

The individual2badge() function creates Markdown badges for displaying contributor information with ORCID identifiers and affiliations.

# Create a badge for an individual
badge_markdown <- individual2badge(individual)

# Result example:
# [![ORCID: 0000-0000-0000-0000](https://img.shields.io/badge/
# ORCID-0000--0000--0000--0000-brightgreen)](https://orcid.org/
# 0000-0000-0000-0000)

This is useful for README files and documentation where you want to display contributor information with clickable links.

To Data Frames

The individual2df() function converts person objects into data frames, making it easier to work with contributor information in tabular format.

# Convert a person object to a data frame
person_df <- individual2df(person_obj)

# The resulting data frame has columns:
# - given: given name
# - family: family name
# - email: email address
# - orcid: ORCID identifier
# - ror: ROR identifier for affiliation
# - affiliation: affiliation name
# - role: role(s) as comma-separated string

The function handles:

  • Single person objects
  • Lists of person objects
  • Missing fields (replaced with empty strings)
  • Multiple roles (combined into comma-separated string)

Adding Individuals to Files

The add_individual() function provides a unified interface for adding contributors to various file types in your project.

# Add an author to a DESCRIPTION file
add_individual("path/to/DESCRIPTION", role = "aut")

# Add a maintainer to an R package
add_individual("path/to/package", role = "cre")

# Add multiple roles
add_individual("path/to/package", role = c("aut", "cre"))

# Add to a Quarto document
add_individual("path/to/document.qmd", role = "aut")

# Add a reviewer to a Quarto document
add_individual("path/to/document.qmd", role = "rev")

Supported file types:

  • DESCRIPTION files: R package metadata
  • Quarto files: _quarto.yml or *.qmd documents
  • README files: README.md or README.Rmd
  • Bookdown index files: index.md or index.Rmd

The function automatically:

  1. Detects the file type
  2. Prompts for individual selection
  3. Adds the individual with the specified role(s)
  4. Updates the file in place

Role Mapping for Different File Types

For R packages (DESCRIPTION files), all standard R CMD check roles are supported:

  • "aut": Author
  • "cre": Creator/Maintainer
  • "ctb": Contributor
  • "rev": Reviewer
  • "cph": Copyright holder
  • "fnd": Funder
  • "pbl": Publisher

For Quarto and Bookdown documents, roles are mapped to YAML fields:

  • "aut" -> author field
  • "rev" -> reviewer field
  • "cph" -> rightsholder field
  • "fnd" -> funder field
  • "pbl" -> publisher field

Helper Functions for Roles

Checking Person Roles

The has_person_role() function checks whether a person object has specific roles.

# Check if person has author role
has_person_role(person_obj, role = "aut")

# Check for multiple roles
has_person_role(person_obj, role = c("aut", "cre"))

# Returns TRUE if the person has at least one of the specified roles

Selecting Roles Interactively

The select_person_role() function helps you interactively specify roles for a contributor.

# Interactive role selection
roles <- select_person_role()

# The function presents common roles and allows you to select one or more:
# - Author
# - Creator (Maintainer)
# - Contributor
# - Reviewer
# - Copyright holder
# - Funder
# - Publisher

Typical Workflow

Here is a typical workflow for managing individuals across projects:

library(citeme)

# Step 1: Store individuals from existing projects
store_individuals("projects/my-r-package")
store_individuals("projects/another-project")

# Step 2: Start a new project and add contributors
# The function will prompt you to select from stored individuals
add_individual("new-project/DESCRIPTION", role = c("aut", "cre"))

# Step 3: Add more contributors as needed
add_individual("new-project/DESCRIPTION", role = "ctb")

# Step 4: Store the new project's individuals for future use
store_individuals("new-project")

Working with Multiple Languages

The individual helper functions support multilingual affiliations through the lang parameter. This is only relevant when the individual is a member of a known organisation (see vignette("organisation")) that has names in multiple languages. When an organisation has names in multiple languages, you can specify which language to use:

# Select individual with English affiliation
individual_en <- select_individual(lang = "en-GB")

# Select individual with Dutch affiliation
individual_nl <- select_individual(lang = "nl-BE")

# The affiliation field will use the specified language when available
person_en <- individual2person(lang = "en-GB")

The language code should follow the BCP 47 standard (e.g. "en-GB", "nl-BE", "fr-FR").

Best Practices

  1. Build your database early: Run store_individuals() on your existing projects to build a comprehensive database of contributors. Please note that store_individuals() only extracts information from projects that contains metadata in the same format as the one that citeme writes.

  2. Use email for quick lookups: When you know the contributor’s email, use select_individual(email = "...") to avoid interactive selection.

  3. Keep information updated: If contributor details change (e.g. new affiliation), update them when prompted during select_individual().

  4. Store after each project: Run store_individuals() after adding contributors to a new project to keep your database current.

  5. Be consistent with roles: Use standard R CMD check roles for packages and appropriate roles for other document types.

For information about validating contributor information, see the vignette("interactive_input") vignette. For organisation-level settings, see the vignette("organisation") vignette.