linelist v1.1.0

new-release
Author

The Epiverse-TRACE development team

Published

February 28, 2024

We are very excited to announce the release of a new linelist version v1.1.0. Here is an automatically generated summary of the changes in this version.

Breaking changes

  • make_linelist() and set_tags() no longer accept a named list of characters as input. Instead, make_linelist(), set_tags() and tags_types() now use rlang’s dynamic dots, which means that you can splice list arguments. This implementation is more robust, better tested, and makes it explicit that users want to splice the list (@Bisaloo, #96).

    • Before:
    my_tags <- list(
      id = "case_ID",
      date_onset = "date_of_prodrome",
      age = "age",
      gender = "gender"
    )
    make_linelist(obj, my_tags)
    # OR
    make_linelist(
      obj,
      id = "case_ID",
      date_onset = "date_of_prodrome",
      age = "age",
      gender = "gender"
    )
    • Now:
    my_tags <- list(
      id = "case_ID",
      date_onset = "date_of_prodrome",
      age = "age",
      gender = "gender"
    )
    make_linelist(obj, !!!my_tags)
    # OR
    make_linelist(
      obj,
      id = "case_ID",
      date_onset = "date_of_prodrome",
      age = "age",
      gender = "gender"
    )

New features

  • linelist warnings and errors in the case of a tag loss now have a custom class (@Bisaloo, #109), which means it is easier to silence them specifically, or to catch them programmatically for advanced error handling. One example of a new advanced condition handling that was before not possible is:

    warning_counter <- 0
    
    withCallingHandlers({
      x <- linelist::make_linelist(cars, date_onset = "dist", age = "speed")
      x <- x[, -1]
      x <- x[, -1]
      warning("This is not a linelist warning", call. = FALSE)
    }, linelist_warning = function(w) {
      warning_counter <<- warning_counter + 1
    })
    #> Warning: The following tags have lost their variable:
    #>  age:speed
    #> Warning: The following tags have lost their variable:
    #>  date_onset:dist
    #> Warning: This is not a linelist warning
    
    warning("This pipeline generated ", warning_counter, " linelist warnings.")
    #> Warning: This pipeline generated 2 linelist warnings.
  • linelist objects now have a new custom $<-.linelist() to prevent tag loss when subsetting a linelist object (@Bisaloo, #86). This completes the functionality already provided by the [<-.linelist() and [[<-.linelist() methods.

    x$tagged_column <- NULL
    #> Warning in prune_tags(out, lost_action): The following tags have lost their variable:
    #>  tag:tagged_column
  • Validation failures in validate_types() now integrate a delayed error mechanism (@Bisaloo, #106). This ensures that the error message will return all the invalid tag types at once rather than having to go through multiple trials and runs.

    • Before: only the first invalid tag type is returned.
    # No warning about age, even though it also has an invalid type
    x <- make_linelist(cars, age = "speed", gender = "dist")
    validate_types(x, ref_types = tags_types(age = "factor"))
    #> Error in validate_types(x, ref_types = tags_types(age = "factor")) : 
    #>   Issue when checking class of tag `gender`:
    #> Must inherit from class 'character'/'factor', but has class 'numeric'
    • Now: the error message returns all the invalid tag types at once.
    x <- make_linelist(cars, age = "speed", gender = "dist")
    validate_types(x, ref_types = tags_types(age = "factor"))
    #> Some tags have the wrong class:
    #>   - gender: Must inherit from class 'character'/'factor', but has class 'numeric'
    #>   - age: Must inherit from class 'factor', but has class 'numeric'

Internal changes

  • Internal duplication in the specification of the tags supported by linelist by default has been removed. This makes it easier to add or remove tags in the future, and reduces the risk of inconsistencies between the different parts of the package (@Bisaloo, #111).
  • The internal tag_variable() function has been replace by a vectorized alternative tag_variable, thus improving performance in make_linelist() and set_tags() about twofold. The error message when tags are specified by position with a number larger than the number of columns in the dataset to tag has also been clarified (@Bisaloo, #110).

Documentation

  • linelist now provides a design vignette for future contributors or maintainers (@Bisaloo, #112).

Reuse

Citation

BibTeX citation:
@online{epiverse-trace_development_team2024,
  author = {Epiverse-TRACE development team, The},
  title = {Linelist V1.1.0},
  date = {2024-02-28},
  url = {https://epiverse-trace.github.io/posts/linelist_v1.1.0/},
  langid = {en}
}
For attribution, please cite this work as:
Epiverse-TRACE development team, The. 2024. “Linelist V1.1.0.” February 28, 2024. https://epiverse-trace.github.io/posts/linelist_v1.1.0/.