Introduction to tabulizer
tabulizer provides R bindings to the Tabula java library, which can be used to computationally extract tables from PDF documents. The main function extract_tables() mimics the command-line behavior of the Tabula, by extracting all tables from a PDF file and, by default, returns those tables as a list of character matrices in R.
## [,1] [,2] [,3] [,4] [,5] [,6] [,7] [,8] [,9] [,10]
## [1,] "mpg" "cyl" "disp" "hp" "drat" "wt" "qsec" "vs" "am" "gear"
## [2,] "21.0" "6" "160.0" "110" "3.90" "2.620" "16.46" "0" "1" "4"
## [3,] "21.0" "6" "160.0" "110" "3.90" "2.875" "17.02" "0" "1" "4"
## [4,] "22.8" "4" "108.0" "93" "3.85" "2.320" "18.61" "1" "1" "4"
## [5,] "21.4" "6" "258.0" "110" "3.08" "3.215" "19.44" "1" "0" "3"
## [6,] "18.7" "8" "360.0" "175" "3.15" "3.440" "17.02" "0" "0" "3"
The pages argument allows you to select which pages to attempt to extract tables from. By default, Tabula (and thus tabulizer) checks every page for tables using a detection algorithm and returns all of them. pages can be an integer vector of any length; pages are indexed from 1.
It is possible to specify a remote file, which will be copied to R’s temporary directory before processing:
## [[1]]
## [,1] [,2] [,3] [,4] [,5]
## [1,] "Sepal.Length" "Sepal.Width" "Petal.Length" "Petal.Width" "Species"
## [2,] "5.1" "3.5" "1.4" "0.2" "setosa"
## [3,] "4.9" "3.0" "1.4" "0.2" "setosa"
## [4,] "4.7" "3.2" "1.3" "0.2" "setosa"
## [5,] "4.6" "3.1" "1.5" "0.2" "setosa"
## [6,] "5.0" "3.6" "1.4" "0.2" "setosa"
## [7,] "5.4" "3.9" "1.7" "0.4" "setosa"
##
## [[2]]
## [,1] [,2] [,3] [,4] [,5]
## [1,] "" "Sepal.Length" "Sepal.Width" "Petal.Length" "Petal.Width"
## [2,] "145" "6.7" "3.3" "5.7" "2.5"
## [3,] "146" "6.7" "3.0" "5.2" "2.3"
## [4,] "147" "6.3" "2.5" "5.0" "1.9"
## [5,] "148" "6.5" "3.0" "5.2" "2.0"
## [6,] "149" "6.2" "3.4" "5.4" "2.3"
## [7,] "150" "5.9" "3.0" "5.1" "1.8"
## [,6]
## [1,] "Species"
## [2,] "virginica"
## [3,] "virginica"
## [4,] "virginica"
## [5,] "virginica"
## [6,] "virginica"
## [7,] "virginica"
Modifying the Return Value
By default, extract_tables() returns a list of character matrices. This is because many tables might be malformed or irregular and thus not be easily coerced to an R data.frame. This can easily be changed by specifying the output argument:
## [[1]]
## Sepal.Length Sepal.Width Petal.Length Petal.Width Species
## 1 5.1 3.5 1.4 0.2 setosa
## 2 4.9 3.0 1.4 0.2 setosa
## 3 4.7 3.2 1.3 0.2 setosa
## 4 4.6 3.1 1.5 0.2 setosa
## 5 5.0 3.6 1.4 0.2 setosa
## 6 5.4 3.9 1.7 0.4 setosa
##
## [[2]]
## X Sepal.Length Sepal.Width Petal.Length Petal.Width Species
## 1 145 6.7 3.3 5.7 2.5 virginica
## 2 146 6.7 3.0 5.2 2.3 virginica
## 3 147 6.3 2.5 5.0 1.9 virginica
## 4 148 6.5 3.0 5.2 2.0 virginica
## 5 149 6.2 3.4 5.4 2.3 virginica
## 6 150 5.9 3.0 5.1 1.8 virginica
Tabula itself implements three “writer” methods that write extracted tables to disk as CSV, TSV, or JSON files. These can be specified by output = "csv", output = "tsv", and output = "json", respectively. For CSV and TSV, one file is written to disk for each table and R session’s temporary directory tempdir() is used by default (alternatively, the directory can be specified through output argument). For JSON, one file is written containing information about all tables. For these methods, extract_tables() returns a path to the directory containing the output files.
## [1] "/tmp/Rtmp176jnc"
If none of the standard methods works well, you can specify output = "asis" to return an rJava “jobjRef” object, which is a pointer to a Java ArrayList of Tabula Table objects. Working with that object might be quite awkward as it requires knowledge of Java and Tabula’s internals, but might be useful to advanced users for debugging purposes.
Miscellaneous Functionality
Tabula is built on top of the Java PDFBox library), which provides low-level functionality for working with PDFs. A few of these tools are exposed through tabulizer, as they might be useful for debugging or generally for working with PDFs. These functions include:
extract_text() converts the text of an entire file or specified pages into an R character vector.split_pdf() and merge_pdfs() split and merge PDF documents, respectively.extract_metadata() extracts PDF metadata as a list.get_n_pages() determines the number of pages in a document.get_page_dims() determines the width and height of each page in pt (the unit used by area and columns arguments).make_thumbnails() converts specified pages of a PDF file to image files.
