An Introduction to listr
In listr: Tools for Lists

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

library(listr)

The idea behind the listr package is to make working with lists with in R a bit more convenient. There is nothing wrong with lists in R per se, but sometimes the tools around lists and the syntax can be a bit confusing and complicated. With the tools provided by listr common tasks with lists and especially lists containing data frames can hopefully be simplified by providing a consistent and easy to read syntax that is also suited for use with pipes.

For our examples below, assume we split the mtcars data by the cyl variable.

by_cyl <- split(mtcars, mtcars$cyl)

Basic operations

by_cyl <- by_cyl |>
  list_rename("cyl4" = `4`, "cyl6" = `6`, "cyl8" = `8`)

by_cyl |> list_select(cyl6)

There is both list_extract and list_select that can appear a bit similar in some cases. However, there are some important distinctions between both:

list_select allows you to select several items from a list.
list_select always returns a list.

In contrast

list_extract only allows you to select a single item.
list_extract unlists the selected item.

Thus, list_select is equivalent to selecting from a list with a single square bracket, while list_extract is equivalent to using double square brackets.

by_cyl |> list_select(1, 2)

cyl4 <- by_cyl |> list_extract(cyl4)
cyl4

The list_remove function is straightforward.

by_cyl <- by_cyl |> list_remove(cyl4)
by_cyl

The opposite can be achieved with list_insert and its more specialised versions list_append and list_prepend.

by_cyl <- by_cyl |> list_prepend(cyl4, name = "cyl4")
by_cyl

Operations with data frames

There is a certain focus on operations with data frames in this package.

The function list_name_to_df adds a column to each data frame in the list containing the name of the list item. This is particularly useful if you have a list where each item is data from an experimental group or something similar.

by_cyl |>
  list_name_to_df() |>
  list_select(1)

Using list_bind you can bind together data frame elements of a list. This is roughly similar to calling do.call(rbind, list) or the same with cbind, but there is a bit more flexibility.

by_cyl |>
  list_bind(cyl4, cyl6, what = "rows", name = "cyl4_and_6")

As the list_bind function wraps calls to rbind and cbind it will have the same effect on names as calling those two functions directly.

Finally, there is also list_join_df allowing to form a single element out of many by joining data on an index.

Flattening

Finally, there is list_flatten which takes in a list with nested list and flattens it. The depth of the flattening process can be specified, by default all items are moved to one level.

foo <- list(
  1,
  list(1, 2, 3,
       list(4, 5, 6),
       list(7, 8, 9,
            list(10, 11,
                 list(12))),
       13, 14),
  15
)

foo |> list_flatten()