latex: Print Dataset to LaTeX Table

In qrat/plaint: Plain Table Markup Language

Description

Prints a dataset into a user-designed LaTeX table based on a simple markup language for tables: PlainT.

Usage

latex(data, file = "table.tex", design = "design.txt", options = NULL,
  ...)

## S3 method for class 'form'
latex(data, file = "table.tex", design = "design.txt",
  options = NULL)

## S3 method for class 'data.frame'
latex(data, file = "table.tex", design = "design.txt",
  options = NULL, ...)

## S3 method for class 'matrix'
latex(data, file = "table.tex", design = "design.txt",
  options = NULL, ...)

## S3 method for class 'table'
latex(data, file = "table.tex", design = "design.txt",
  options = NULL, ...)

Arguments

data	The object to be printed. Will coerce data via form into a "formed" frame. Supports arbitrary formats such as data.frame, matrix or table.
file	The character file path to print the latex table to. Default: table.tex.
design	The path to the PlainT table design. By default, the name is set to 'design.txt'. If the design file does not exist, a basic default design for data will be created automatically and saved to design. The design rules as outlined in the Details section apply. See the vignette for examples of the intuitive WYSIWYM PlainT markup language in practice. Caution: If you use tabs for formatting, they will be replaced by three spaces. Better use spaces directly.
options	A list with options <name> = <value> may be specified here. These options will overwrite all options which might be written in the head of the design file (see Details). By default, a wrapper document document.tex is created. It embeds file within a table environment with all necessary packages. This is considered very useful for an easy migration of the table into other documents as well as for quick testing purposes. See Details for a list with all options and their default values.
...	All additional arguments are passed to form. Notice that form can only be applied to unformed datasets.

Details

The function creates a state of the art user-designed LaTeX table from data based on the What You See Is What You Mean (WYSIWYM) Plain Table Markup Language (PlainT) which is highly flexible and accessible. PlainT was suggested by this package's author to allow for easy creation, manipulation and re-use of table designs for dynamically generated contents. Review the vignettesa and the example section for feature rich example designs.

PlainT syntax and usage:

A PlainT design file is a plain text file allowing you to visually design your table with characters by means of a preferred simple text editor of your choice.

The table design is divided into the head consisting of column "titles" and the body with column "elements" which are placeholders for the dynamically inserted column contents from an arbitrary dataset. The column design is defined by the relative positions of the head titles which can be written in multiple rows. Head and body may contain an arbitrary number of horizontal and vertical spaces and ruler as outlined below.

Spaces are set to separate columns. Use three spaces to separate two columns by an empty column. You can create groups and subgroups by an arbitrary depth. Multiple empty columns are also supported. Tabs are converted to three spaces but better use spaces only in order to still see an unique PlainT design in different text editor. Empty lines or space lines are directly adopted.

Ruler just containing "-" (thin line) or "=" (thick line) are regarded as horizontal separators. A standard table contains three of them: top (thick, above the head), mid (thin, betweem head and body) and bottom (thick, below the body). Vertical lines are created by means of the character "|". Horizontal and vertical lines can be connected by "+".

All titles and elements as mentioned above can be written and aligned as outlined:

1. ":<text>:" aligns the title or column to center, ":<text>" aligns to the left and "<text>:" aligns to the right.

2. ":.<text>.:" is only available for body elements and aligns each column value at the decimal sign (a dot).

3. Above, <text> is an arbtrary LaTeX body text. Use $ to even print math formulas in your titles. Caution: If <text> contains spaces, you must surround it by quotes, i. e. "<text>".

Currently, the body must contain one row with "@" signs referring data columns from the dataset to be inserted. A data column will be inserted in the column of the next title above "@" or a preceding ":" that covers its position. If you write "@<nr>" and "<nr>" refers to a valid column index in data then that column is inserted at this position. Also, if you write "@<name>" and "<name>" refers to a valid column name in data then that column taken. If no index or name reference is provided, the columns will be filled in as they appear in data without the subset of those which are referenced directly. Additionally, you can

1. combine multiple data columns in one table column,

2. the mentioned alignment rules apply, and

3. you can surround each value per column by static text, for instance: :.@mean(@sd).:.

Subsets are arbitrary text lines beginning or ending with "::". They are employed to write subtitles and divide the body in several parts.

Options can be written directly in the design file. They are set line by line on top of design by means of the syntax "#+<name> = <value>". All available options with their default values:

• centering = TRUE

• document = document.tex

• landscape = FALSE

• rownames = TRUE

• size = normalsize

• tabularx = FALSE

Caution: The function argument options overwrites the design file specified options.

Description is to be coming soon.

The package and this function will be improved by missing functionality on a regular basis. The author is eager to receive your suggestions in order to improve the dynamics and power of PlainT and latex. Please write to Fabian Raters ([e-mail]).

Value

The function returns TRUE if no error occurred.

See Also

For forming a dataset, see form.

Examples

## basic example
latex(mtcars)


## table example
latex(table(state.division, state.region), design = "table.txt")


## advanced example in combination with form
mtcarsf <- form(data = mtcars,
                format = "%i",
                formatcolumns = list("%5.1f" = "disp",
                                     "%3i" = "hp",
                                     "%4.1f" = "qsec",
                                     "%4.2f" = c("drat", "wt")),
                marker = list(min = c("mpg", "cyl", "disp", "hp", "drat", "wt", "qsec"),
                              max = c("mpg", "cyl", "disp", "hp", "drat", "wt", "qsec"),
                              "v==1" = "am",
                              "sqrt(v)==2" = c("cyl", "gear", "carb")),
                symbols = list("** v" = "max.all",
                               ".. v" = "min.all",
                               "* v" = "max.german",
                               ". v" = "min.german",
                               "\\textbf{v}" = "=="),
                groups = list(german = c("Merc", "Porsche")))

# translate the formed frame into a LaTeX table
latex(mtcarsf, design = "mtcars.txt")

# use the generated template "mtcars.txt" to design the LaTeX table and
# re-run the last command
latex(mtcarsf, design = "mtcars.txt")

# Three different example plaint designs are already included in this package
# for learning purposes. You are free to view, copy or edit them with your
# prefered text editor. You find their paths within this package by means
# of system.file().

# design 1
latex(mtcarsf,
      file = "mt_table1.tex",
      design = system.file("extdata", "mt_design1.txt", package = "plaint"),
      options = list(document = "document1.tex"))

# design 2
latex(mtcarsf,
      file = "mt_table2.tex",
      design = system.file("extdata", "mt_design2.txt", package = "plaint"))

# design 3
latex(mtcarsf,
      file = "mt_table3.tex",
      design = system.file("extdata", "mt_design3.txt", package = "plaint"))

qrat/plaint documentation built on May 26, 2019, 12:34 p.m.