logo

DataEditR

DataEditR is a lightweight package to interactively view, enter or edit data in R. In this vignette we will explore some of the key features that are available through the data_edit() function.

Preparation

In order to get started with DataEditR, we will need to install the package from GitHub and load it into our current R session:

devtools::install_github("DillonHammill/DataEditR")
library(DataEditR)

1. Data Visualisation

Simply supply your data in the form of a matrix, data.frame or data.table to data_edit() to view it in an interactive table. For example, if we wanted to take a look at the mtcars dataset:

data_edit(mtcars)

The data editor will open in the RStudio viewer pane by default but this can be changed to a pop-up window by setting viewer = FALSE as below. Both of these options have optional support for displaying the data in a web browser as well.

data_edit(mtcars,
          viewer = FALSE)

The data editor will automatically move row names inside the table so that the row indices can be displayed on the left hand side. Once you are finished exploring the data, you can close the data editor by hitting the Save & Close button in the top left corner.

2. Data Import

data_edit() can all read in any form tabular data from file for viewing and editing. By default data_edit() will use read.csv from the utils package to read in files, but this can be changed to any reading function by supplying the name of the function to the read_fun argument. If you need to pass any additional arguments to your reading function, these can be supplied as a named list to the read_args argument. The data will be returned by data_edit() once the Save & Close button has been clicked.

mtcars <- data_edit("mtcars.csv",
                    read_fun = "read.csv",
                    read_args = list(header = TRUE))
head(mtcars)
#>                    mpg cyl disp  hp drat    wt  qsec vs am gear carb
#> Mazda RX4         21.0   6  160 110 3.90 2.620 16.46  0  1    4    4
#> Mazda RX4 Wag     21.0   6  160 110 3.90 2.875 17.02  0  1    4    4
#> Datsun 710        22.8   4  108  93 3.85 2.320 18.61  1  1    4    1
#> Hornet 4 Drive    21.4   6  258 110 3.08 3.215 19.44  1  0    3    1
#> Hornet Sportabout 18.7   8  360 175 3.15 3.440 17.02  0  0    3    2
#> Valiant           18.1   6  225 105 2.76 3.460 20.22  1  0    3    1

3. Data Manipulation

data_edit() has a variety of interactive data manipulation tools to edit your data. We will explore the use of each of these tools below:

3.1 Addition or removal of rows or columns

Rows or columns can be added to the data from within the data editor by right clicking on a cell within the table. This will display a context menu with the options to add or remove rows or columns.

data_edit(mtcars)

3.2 Rename rows or columns

data_edit() has full support for editing row and column names. Simply select the cell that you want to edit and update its value within the table. As outlined above, the row names will appear within the table so that the row indices can be displayed on the left-hand side. The row indices cannot be edited. The new row or column names must be unique!

data_edit(mtcars)

To prevent users from editing column names, set col_names = FALSE or supply the names of the columns that cannot be edited. For example, if we only wanted to prevent users from editing the name of the mpg column:

data_edit(mtcars,
          col_names = "mpg")

3.3 Resize columns

To size columns, go to the right-hand border of the cell containing the name of that column and drag the cursor to the desired width.

data_edit(mtcars)

3.4 Drag to fill

Values in cells can be dragged to other cells by selecting the filled cells and dragging the box in the lower right hand corner.

data_edit(mtcars)

3.5 Append columns or rows

data_edit() can perform rbind and cbind operations internally to append new rows or columns to the data prior to editing. The new rows or columns should be supplied as a matrix or data.frame to the row_bind or col_bind arguments. If binding both rows and columns, it is important to note that rows are bound before columns.

# New column to add
new_col <- matrix(rep(NA, nrow(mtcars)),
                  ncol = 1,
                  dimnames = list(NULL, "test"))

# Edit data with new column added
data_edit(mtcars,
          col_bind = new_col)

3.6 Read-only columns

If you would like to prevent values from being edited in certain columns, you can supply the names of the columns that cannot be edited to the col_readonly argument. Users will be able to edit values and the column name, but these will be reverted to the original values. For example, if we wanted to prevent the mpg column from being edited:

data_edit(mtcars,
          col_readonly = "mpg")

4. Data Creation

You can also use data_edit() to interactively create data.frames from scratch without any coding.

4.1 Start with empty data.frame

If no data is supplied to data_edit() an empty data.frame will be constructed with a single row and column. You can then build your data.frame from scratch by adding new rows and columns and annotating the cells.

data_edit()

4.2 Start with a template data.frame

Creating a data.frame from scratch as described above can be tedious, so instead we could start with a data.frame template that contains more rows or columns. To create a template data.frame, simply supply the required dimensions of the data.frame in the form c(nrow, ncol).

data_edit(c(3, 3))

5. Data saving

data_edit() will automatically return the edited data with appropriate column classes as an R object for use within R. Character columns are not converted to factors by default, but this can be changed by setting col_factor = TRUE.

# Add character column
mtcars_new <- cbind(rownames(mtcars), mtcars)
colnames(mtcars_new) <- "car"

# Convert characters to factors
mtcars_new <- data_edit(mtcars_new,
                        col_factor = TRUE)
str(mtcars_new)
#> 'data.frame':    32 obs. of  12 variables:
#>  $ car : Factor w/ 32 levels "AMC Javelin",..: 18 19 5 13 14 31 7 21 20 22 ...
#>  $ mpg : num  21 21 22.8 21.4 18.7 18.1 14.3 24.4 22.8 19.2 ...
#>  $ cyl : num  6 6 4 6 8 6 8 4 4 6 ...
#>  $ disp: num  160 160 108 258 360 ...
#>  $ hp  : num  110 110 93 110 175 105 245 62 95 123 ...
#>  $ drat: num  3.9 3.9 3.85 3.08 3.15 2.76 3.21 3.69 3.92 3.92 ...
#>  $ wt  : num  2.62 2.88 2.32 3.21 3.44 ...
#>  $ qsec: num  16.5 17 18.6 19.4 17 ...
#>  $ vs  : num  0 0 1 1 0 1 0 1 1 1 ...
#>  $ am  : num  1 1 1 0 0 0 0 0 0 0 ...
#>  $ gear: num  4 4 4 3 3 3 3 4 4 4 ...
#>  $ carb: num  4 4 1 1 2 1 4 2 2 4 ...

The edited data can also be written to a file of any format by specifying the name of the file to the save_as argument and specifying the name of the writing function to use through write_fun. The default is et to write.csv from the utils package. You can also pass any additional arguments to your write function in a named list to write_args.

mtcars_new <- data_edit(mtcars,
                        save_as = "mtcars.csv",
                        write_fun = "write.table",
                        write_args = list(sep = ",",
                                          row.names = TRUE))

6. Complex user inputs

data_edit() can also be used to accept complex inputs from users and these inputs can be restricted by adding columns with checkboxes or dropdown menus. To use this feature, the options for the columns must be supplied in a named list through the col_options argument. It is important to note that should you choose to use this feature, users will be unable to add or remove columns as described previously.

6.1 Checkboxes

Checkboxes can be used to obtain TRUE or FALSE value inputs from users. The resulting data will have a value of TRUE or NA based on user input.

data_edit(mtcars,
          col_bind = "fast",
          col_options = list(fast = c(TRUE,FALSE)))

7. Customisation

data_edit() has been designed to be simple, but does come with some customisation options including column stretching, addition of logos and/or titles or custom themes.

7.1 Stretch columns to fill page

If you would like to make full use of the space available to you, you can set col_stretch = TRUE to stretch the columns to fill the full width of the display.

data_edit(mtcars,
          col_stretch = TRUE)

7.2 Logo and title

data_edit() does also have support for adding a logo and/or title to the data editor. For example, if you wanted to use data_edit() within your own package you can customise it with your package logo and instructions to the user through title.

car_logo <- 'https://raw.githubusercontent.com/DillonHammill/DataEditR/master/vignettes/DataEditR/DataEditR-Car.png'
data_edit(mtcars,
          logo = car_logo,
          logo_size = 100,
          title = "mtcars")

7.3 Custom themes

data_edit() makes use of the shinythemes package to customise the appearance of the data editor. You can explore the different themes by supplying the name of a valid shinythemes theme to the theme argument.

data_edit(mtcars,
          theme = "cosmo")

Summary

DataEditR is a lightweight, powerful and intuitive package to allow interactive viewing, entry and editing of data in R. DataEditR is also appealing to developers seeking complex input from users using an interface that is robust and customisable.