README.Rmd

---
output: github_document
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# roomba <img src="img/sticker.png" alt="roomba_gif" height="150px" align="right" />

[![Travis build status](https://travis-ci.com/ropenscilabs/roomba.svg?branch=master)](https://travis-ci.com/ropenscilabs/roomba)


This is a package to transform large, multi-nested lists into a more user-friendly format (i.e. a `tibble`) in `R`. The initial focus is on making processing of return values from `jsonlite::fromJSON()` queries more seamless, but ideally this package should be useful for deeply-nested lists from an array of sources.


<!-- ![roomba_gif](https://media.giphy.com/media/mwMowfcaEcvpm/giphy.gif) -->

<p align="center">
  <img src="https://media.giphy.com/media/mP9hvHDhy4E9i/giphy.gif" alt="roomba_gif">
</p>


*Key features:*


* `roomba()` searches deeply-nested list for names specified in `cols` (a character vector) and returns a `tibble` with the associated column titles. Nothing further about nesting hierarchy or depth need be specified.

* Handles empty values gracefully by substituting `NULL` values with  `NA` or user-specified value in `default`, or truncates lists appropriately. 

* If you're only interested in sniffing out and replacing all `NULL`s, turn to the `replace_null()` function.

* Option to `keep` `any` or `all` data from the columns supplied

## Installation

You can install the development version from [GitHub](https://github.com/) with:

```{r, eval=FALSE}
# install.packages("devtools")
devtools::install_github("cstawitz/roomba")
```

## Usage

Say we have some JSON from a pesky API.

```{r example, message=FALSE}
library(roomba)

json <- '
  {
    "stuff": {
      "buried": {
        "deep": [
          {
            "location": "here",
            "name": "Laura DeCicco",
            "super_power": "fixing merge conflicts",
            "other_secret_power": []
          },
          {
            "location": "here",
            "name": "Amanda Dobbyn",
            "super_power": "flight",
            "more_nested_stuff": 4
          }
        ],
        "alsodeep": 2342423234,
        "stilldeep": {
          "even_deeper": [
            {
              "location": "not here",
              "name": "Jim Hester",
              "super_power": []
            },
            {
              "location": "here",
              "name": "Christine Stawitz",
              "super_power": "invisibility",
              "more_nested_stuff": 5
            },
            {
              "location": "here",
              "name": "Isabella Velasquez",
              "super_power": "teleportation"
            }
          ]
        }
      }
    }
  }'
```

The JSON becomes a nested R list,

```{r}
super_data <- json %>% 
  jsonlite::fromJSON(simplifyVector = FALSE) 
```

which we can pull data into the columns we want with `roomba`.

```{r}
super_data %>%
  roomba(cols = c("name", "super_power", "more_nested_stuff"), keep = any)
```


<br>

Let's try with a real-world Twitter example (see package data to use this data).


```{r}
roomba(twitter_data, c("created_at", "name"))
```

# Shiny app included!

<p align="center">
  <img src="images/shinydemo.gif" alt="roomba_gif">
</p>

Run the app like this:
```{r eval=FALSE}
shiny_roomba()

```

<br>

# What did that original data look like???

Feast your eyes on the original `super_data` list!

```{r}
super_data
```

And just the *first* element of the `twitter` dataset `r emo::ji("scream")`

```{r}
twitter_data[[1]]
```


<br>

**Happy cleaning!**

<p align="center">
  <img src="https://media.giphy.com/media/mwMowfcaEcvpm/giphy.gif" alt="roomba_gif">
</p>