read_cells: Read Cells from file
In tidycells: Read Tabular Data from Diverse Sources and Easily Make Them Tidy

Description Usage Arguments Details Value Examples

This function is designed to read cell level information (and the finally analyze, compose and collate_columns) from many file types like xls, pdf, doc etc. This is a wrapper function to functions from multiple packages. The support for a specific file is dependent on the installed packages. To see the list of supported files and potentially required packages (if any) just run read_cells() in the console. This function supports the file format based on content and not based on just the file extension. That means if a file is saved as pdf and then the extension is removed (or extension modified to say .xlsx) then also the read_cells will detect it as pdf and read its content.

Note :

read_cells is supposed to work for any kind of data. However, if it fails in intermediate stage it will raise a warning and give results till successfully processed stage.
The heuristic-algorithm are not well-optimized (yet) so may be slow on large files.
If the target table has numerical values as data and text as their attribute (identifier of the data elements), straight forward method is sufficient in the majority of situations. Otherwise, you may need to utilize other functions.

A Word of Warning :

The functions used inside read_cells are heuristic-algorithm based. Thus, outcomes may be unexpected. It is recommend to try read_cells on the target file. If the outcome is expected., it is fine. If not try again with read_cells(file_name, at_level = "compose"). If after that also the output is not as expected then other functions are required to be used. At that time start again with read_cells(file_name, at_level = "make_cells") and proceed to further functions.

read_cells(
  x,
  at_level = c("collate", "detect_and_read", "make_cells", "va_classify", "analyze",
    "compose"),
  omit = NULL,
  simplify = TRUE,
  compose_main_cols_only = TRUE,
  from_level,
  silent = TRUE,
  ...
)

`x`	either a valid file path or a `read_cell_part`
`at_level`	till which level to process. Should be one of `detect_and_read`, `make_cells`, `va_classify`, `analyze`, `compose`, `collate`. Or simply a number (like 1 means `detect_and_read`, 5 means `compose`).
`omit`	(Optional) the file-types to omit. A character vector.
`simplify`	whether to simplify the output. (Default `TRUE`). If set to `FALSE` a `read_cell_part` will be returned.
`compose_main_cols_only`	whether to compose main columns only. (Default `TRUE`).
`from_level`	(Optional) override start level. (`read_cells` will process after `from_level`)
`silent`	if `TRUE` no message will be displayed.(Default `TRUE`)
`...`	further arguments

It performs following set of actions if called with default at_level.

detect_and_read: Detect file type based on content and attempt to read the same in a format suitable to convert as cell_df.
make_cells: Convert the file content to cell_df using as_cell_df.
va_classify: Run Value Attribute Classification using numeric_values_classifier.
analyze: Analyze the cells using analyze_cells.
compose: Compose the cell-analysis to a tidy form using compose_cells.
collate: Finally, collate columns based on content using collate_columns.

Here is the flowchart of the same:

If simplify=TRUE then different kind of object is returned in different levels (depends on at_level). If at_level="compose" then only final tibble is returned otherwise if the output is not NULL an attribute will be present named "read_cells_stage".

If simplify=FALSE then it will return a read_cell_part which you can process manually and continue again with read_cells (perhaps then from_level may be useful).

# see supported files
read_cells()

fold <- system.file("extdata", "messy", package = "tidycells", mustWork = TRUE)
# File extension is intentionally given wrong
# while filename is the actual identifier of the file type
fcsv <- list.files(fold, pattern = "^csv.", full.names = TRUE)[1]
# read the data
read_cells(fcsv)
read_cells(fcsv, simplify = FALSE)