rlist v0.4.6.1

0

Monthly downloads

0th

Percentile

A Toolbox for Non-Tabular Data Manipulation

Provides a set of functions for data manipulation with list objects, including mapping, filtering, grouping, sorting, updating, searching, and other useful functions. Most functions are designed to be pipeline friendly so that data processing with lists can be chained.

Readme

rlist

Linux Build Status Windows Build status codecov.io CRAN Version

rlist is a set of tools for working with list objects. Its goal is to make it easier to work with lists by providing a wide range of functions that operate on non-tabular data stored in them.

This package supports list mapping, filtering, grouping, sorting, updating, searching, file input/output, and many other functions. Most functions in the package are designed to be pipeline friendly so that data processing with lists can be chained.

rlist Tutorial is a highly recommended complete guide to rlist.

This document is also translated into 日本語 (by @teramonagi).

Installation

Install the latest version from GitHub:

devtools::install_github("renkun-ken/rlist")

Install from CRAN:

install.packages("rlist")

Motivation

In R, there are numerous powerful tools to deal with structured data stored in tabular form such as data frame. However, a variety of data is non-tabular: different records may have different fields; for each field they may have different number of values.

It is hard or no longer straightforward to store such data in data frame, but the list object in R is flexible enough to represent such records of diversity. rlist is a toolbox to deal with non-structured data stored in list objects, providing a collection of high-level functions which are pipeline friendly.

Getting started

Suppose we have a list of developers, each of whom has a name, age, a few interests, a list of programming languages they use and the number of years they have been using them.

library(rlist)
devs <- 
  list(
    p1=list(name="Ken",age=24,
      interest=c("reading","music","movies"),
      lang=list(r=2,csharp=4)),
    p2=list(name="James",age=25,
      interest=c("sports","music"),
      lang=list(r=3,java=2,cpp=5)),
    p3=list(name="Penny",age=24,
      interest=c("movies","reading"),
      lang=list(r=1,cpp=4,python=2)))

This type of data is non-relational since it does not well fit the shape of a data frame, yet it can be easily stored in JSON or YAML format. In R, list objects are flexible enough to represent a wide range of non-relational datasets like this. This package provides a wide range of functions to query and manipulate this type of data.

The following examples use str() to show the structure of the output.

Filtering

Filter those who like music and has been using R for more than 3 years.

str( list.filter(devs, "music" %in% interest & lang$r >= 3) )
List of 1
 $ p2:List of 4
  ..$ name    : chr "James"
  ..$ age     : num 25
  ..$ interest: chr [1:2] "sports" "music"
  ..$ lang    :List of 3
  .. ..$ r   : num 3
  .. ..$ java: num 2
  .. ..$ cpp : num 5

Selecting

Select their names and ages.

str( list.select(devs, name, age) )
List of 3
 $ p1:List of 2
  ..$ name: chr "Ken"
  ..$ age : num 24
 $ p2:List of 2
  ..$ name: chr "James"
  ..$ age : num 25
 $ p3:List of 2
  ..$ name: chr "Penny"
  ..$ age : num 24

Mapping

Map each of them to the number of interests.

str( list.map(devs, length(interest)) )
List of 3
 $ p1: int 3
 $ p2: int 2
 $ p3: int 2

More functions

In addition to these basic functions, rlist also supports various types of grouping, joining, searching, sorting, updating, etc. For the introduction to more functionality, please go through the rlist Tutorial.

Lambda expression

In this package, almost all functions that work with expressions accept the following forms of lambda expressions:

  • Implicit lambda expression: expression
  • Univariate lambda expressions:
    • x ~ expression
    • f(x) ~ expression
  • Multivariate lambda expressions:
    • f(x,i) ~ expression
    • f(x,i,name) ~ expression

where x refers to the list member itself, i denotes the index, name denotes the name. If the symbols are not explicitly declared, ., .i and .name will by default be used to represent them, respectively.

nums <- list(a=c(1,2,3),b=c(2,3,4),c=c(3,4,5))
list.map(nums, c(min=min(.),max=max(.)))
list.filter(nums, x ~ mean(x)>=3)
list.map(nums, f(x,i) ~ sum(x,i))

Using pipeline

Working with pipeR

Query the name of each developer who likes music and uses R, and put the results in a data frame.

library(pipeR)
devs %>>% 
  list.filter("music" %in% interest & "r" %in% names(lang)) %>>%
  list.select(name,age) %>>%
  list.stack
   name age
1   Ken  24
2 James  25

The example above uses pipeR(http://renkun.me/pipeR/) package for pipeline operator %>>% that chains commands in a fluent style.

List environment

List() function wraps a list within an environment where almost all list functions are defined. Here is the List-environment version of the previous example.

ldevs <- List(devs)
ldevs$filter("music" %in% interest & "r" %in% names(lang))$
  select(name,age)$
  stack()$
  data
   name age
1   Ken  24
2 James  25

Help overview

help(package = rlist)

or view the documentation on CRAN

License

This package is under MIT License.

Functions in rlist

Name Description
list.findi Find the indices of a number of elements in a list or vector satisfying a given condition
list.clean Clean a list by a function
subset.list Subset a list by a logical condition
nyweather New York hourly weather data
list.skip Skip a number of elements
list.class Classify list elments into unique but non-exclusive cases
list.load Load a list from file
list.all Examine if a condition is true for all elements of a list
list.rbind Bind all list elements by row
list.extract Extract an element from a list or vector
list.skipWhile Keep skipping elements while a condition holds
list.any Examine if a condition is true for at least one list element
list.ungroup Ungroup a list by taking out second-level elements
list.iter Iterate a list by evaluating an expression on each list element
rlist-package The rlist package
list.reverse Reverse a list
list.parse Convert an object to list with identical structure
list.cbind Bind all list elements by column
List Create a List environment that wraps given data and most list functions are defined for chainable operations.
list.exclude Exclude members of a list that meet given condition.
list.prepend Prepend elements to a list
list.first Find the first element that meets a condition
list.merge Merge a number of named lists in sequential order
list.flatten Flatten a nested list to a one-level list
list.map Map each element in a list or vector by an expression.
list.subset Subset a list
list.insert Insert a series of lists at the given index
list.serialize Serialize a list
list.take Take a number of elements
list.takeWhile Keep taking elements while a condition holds
list.stack Stack all list elements to tabular data
list.find Find a specific number of elements in a list or vector satisfying a given condition
list.count Count the number of elements that satisfy given condition
list.expand Create a list from all combinations of factors
list.mapv Map each member of a list by an expression to a vector.
list.table Generate a table for a list by expression
list.search Search a list recusively by an expression
list.is Return a logical vector that indicates if each member of a list satisfies a given condition
list.join Join two lists by single or multiple keys
list.last Find the last element that meets a condition
tryGet Try to get the value of a symbol if exists or return a default value
list.update Update a list by appending or modifying its elements.
list.sample Sample a list or vector
list.filter Filter a list or vector by a series of conditions
list.names Get or set the names of a list by expression
list.unserialize Unserialize a file
list.apply Apply a function to each list element (lapply)
list.cases Get all unique cases of a list field by expression
list.do Call a function with a list of arguments
list.order Give the order of each list element by expression
tryEval Try to evaluate an expression and return a default value if an error occurs or otherwise return its value.
list.sort Sort a list by given expressions
list.unzip Transform a list of elements with similar structure into a list of decoupled fields
list.common Get all common cases by expression for a list
list.which Give the indices of list elements satisfying a given condition
list.save Save a list to a file
list.select Select by name or expression for each member of a list
list.match Select members of a list that match given regex pattern
list.append Append elements to a list
list.zip Combine multiple lists element-wisely.
list.group Divide list/vector elements into exclusive groups
list.remove Remove members from a list by index or name
list.maps Map multiple lists with an expression
No Results!

Last month downloads

Details

Type Package
Date 2016-04-04
License MIT + file LICENSE
URL https://renkun.me/rlist, https://github.com/renkun-ken/rlist, https://renkun.me/rlist-tutorial
BugReports https://github.com/renkun-ken/rlist/issues
ByteCompile TRUE
LazyData true
RoxygenNote 5.0.1
NeedsCompilation no
Packaged 2016-04-04 08:55:10 UTC; Kun
Repository CRAN
Date/Publication 2016-04-04 11:49:36

Include our badge in your README

[![Rdoc](http://www.rdocumentation.org/badges/version/rlist)](http://www.rdocumentation.org/packages/rlist)