knitr::opts_chunk$set( collapse = TRUE, comment = "#>", fig.path = "man/figures/README-", out.width = "100%" )
linelist provides a safe entry point to the Epiverse software ecosystem, adding a foundational layer through tagging, validation, and safeguarding epidemiological data, to help make data pipelines more straightforward and robust.
Our stable versions are released on CRAN, and can be installed using:
install.packages("linelist", build_vignettes = TRUE)
::: {.pkgdown-devel}
The development version of linelist can be installed from GitHub with:
if (!require(pak)) { install.packages("pak") } pak::pak("epiverse-trace/linelist")
:::
#| fig.alt: "Graphical summary of the linelist R package, with emphasis of these 4 key features: 1. Tag key epi variables, 2. Validate tagged data, 3. Safeguards vs accidental loss / alteration, 4. Robust data for stronger pipelines](man/figures/linelist_infographics.png" #| out.width: "60%" knitr::include_graphics("man/figures/linelist_infographics.png")
linelist works by tagging key epidemiological data in a data.frame
or a
tibble
to facilitate and strengthen data pipelines. The resulting object is a
linelist
object, which extends data.frame
(or tibble
) by providing three
types of features:
a tagging system to identify key data, enabling access to these data using their tags rather than actual names, which may change over time and across datasets
validation of the tagged variables (making sure they are present and of the right type/class)
safeguards against accidental losses of tagged variables in common data handling operations
The short example below illustrates these different features. See the
Documentation section for more in-depth examples and details
about linelist
objects.
# load packages and a dataset for the example # ------------------------------------------- library(linelist) library(dplyr) dataset <- outbreaks::mers_korea_2015$linelist head(dataset) # check known tagged variables # ---------------------------- tags_names() # build a linelist # ---------------- x <- dataset %>% tibble() %>% make_linelist( date_onset = "dt_onset", # date of onset date_reporting = "dt_report", # date of reporting occupation = "age" # mistake ) x tags(x) # check available tags
validate_linelist()
will error if one of your tagged column doesn't have the
correct type:
# validation of tagged variables # ------------------------------ ## (this flags a likely mistake: occupation should not be an integer) validate_linelist(x)
# change tags: fix mistakes, add new ones # --------------------------------------- x <- x %>% set_tags( occupation = NULL, # tag removal gender = "sex", # new tag outcome = "outcome" ) # safeguards against actions losing tags # -------------------------------------- ## attemping to remove geographical info but removing dates by mistake x_no_geo <- x %>% select(-(5:8))
For stronger pipelines, you can even trigger errors upon loss:
lost_tags_action("error") x_no_geo <- x %>% select(-(5:8)) x_no_geo <- x %>% select(-(5:7)) ## to revert to default behaviour (warning upon error) lost_tags_action()
Alternatively, content can be accessed by tags:
x_no_geo %>% select(has_tag(c("date_onset", "outcome"))) x_no_geo %>% tags_df()
linelist can also be connected to the incidence2 package for pipelines focused on aggregated count data:
library(incidence2) x_no_geo %>% tags_df() %>% incidence("date_onset", groups = c("gender", "outcome")) %>% plot( fill = "outcome", angle = 45, nrow = 2, border_colour = "white", legend = "bottom" )
More detailed documentation can be found at: https://epiverse-trace.github.io/linelist/
In particular:
To ask questions or give us some feedback, please use the github issues system.
Case line lists may contain personally identifiable information (PII). While linelist provides a way to store this data in R, it does not currently provide tools for data anonymization. The user is responsible for respecting individual privacy and ensuring PII is handled with the required level of confidentiality, in compliance with applicable laws and regulations for storing and sharing PII.
Note that PII is rarely needed for common analytics tasks, so that in many instances it may be advisable to remove PII from the data before sharing them with analytics teams.
This package is currently maturing, as defined by the RECON software lifecycle. This means that essential features and mechanisms are present and stable but minor breaking changes, or function renames may still occur sporadically.
Contributions are welcome via pull requests.
Please note that the linelist project is released with a Code of Conduct. By contributing to this project, you agree to abide by its terms.
This package is a reboot of the RECON package
linelist. Unlike its predecessor, the
new package focuses on the implementation of a linelist
class. The data
cleaning features of the original package will eventually be re-implemented for
linelist
objects, albeit likely in a separate package.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.