linelist-package: Base Tools for Storing and Handling Case Line Lists
In epiverse-trace/linelist: Tagging and Validating Epidemiological Data

linelist-package

R Documentation

Base Tools for Storing and Handling Case Line Lists

Description

The linelist package provides tools to help storing and handling case line list data. The linelist class adds a tagging system to classical data.frame or tibble objects which permits to identify key epidemiological data such as dates of symptom onset, epi case definition, age, gender or disease outcome. Once tagged, these variables can be seamlessly used in downstream analyses, making data pipelines more robust and reliable.

Main functions

make_linelist(): to create linelist objects from a data.frame or a tibble, with the possibility to tag key epi variables
set_tags(): to change or add tagged variables in a linelist
tags(): to get the list of tags of a linelist
tags_df(): to get a data.frame of all tagged variables
lost_tags_action(): to change the behaviour of actions where tagged variables are lost (e.g. removing columns storing tagged variables) to issue warnings, errors, or do nothing
get_lost_tags_action(): to check the current behaviour of actions where tagged variables are lost

Dedicated methods

Specific methods commonly used to handle data.frame are provided for linelist objects, typically to help flag or prevent actions which could alter or lose tagged variables (and may thus break downstream data pipelines).

⁠names() <-⁠ (and related functions, such as dplyr::rename()) will rename tags as needed
⁠x[...] <-⁠ and ⁠x[[...]] <-⁠ (see sub_linelist): will adopt the desired behaviour when tagged variables are lost
print(): prints info about the linelist in addition to the data.frame or tibble

Author(s)

Maintainer: Hugo Gruson hugo@data.org (ORCID)

Authors:

Thibaut Jombart [conceptor]

Other contributors:

Tim Taylor [contributor]
Chris Hartgerink (ORCID) [reviewer]

Examples


if (require(outbreaks)) {
  # using base R style

  ## dataset we'll create a linelist from, only using the first 50 entries
  measles_hagelloch_1861[1:50, ]

  ## create linelist
  x <- make_linelist(measles_hagelloch_1861[1:50, ],
    id = "case_ID",
    date_onset = "date_of_prodrome",
    age = "age",
    gender = "gender"
  )
  x

  ## check tagged variables
  tags(x)

  ## robust renaming
  names(x)[1] <- "identifier"
  x

  ## example of dropping tags by mistake - default: warning
  x[, 2:5]

  ## to silence warnings when taggs are dropped
  lost_tags_action("none")
  x[, 2:5]

  ## to trigger errors when taggs are dropped
  # lost_tags_action("error")
  # x[, 2:5]

  ## reset default behaviour
  lost_tags_action()


  # using tidyverse style

  ## example of creating a linelist, adding a new variable, and adding a tag
  ## for it

  if (require(dplyr) && require(magrittr)) {
    x <- measles_hagelloch_1861 %>%
      tibble() %>%
      make_linelist(
        id = "case_ID",
        date_onset = "date_of_prodrome",
        age = "age",
        gender = "gender"
      ) %>%
      mutate(result = if_else(is.na(date_of_death), "survived", "died")) %>%
      set_tags(outcome = "result") %>%
      rename(identifier = case_ID)

    head(x)

    ## extract tagged variables
    x %>%
      select(has_tag(c("gender", "age")))

    x %>%
      tags()

    x %>%
      select(starts_with("date"))
  }
}

epiverse-trace/linelist documentation built on Feb. 22, 2025, 2:47 p.m.