Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/coachshea/knitlatex

An R package to provide longtable and supertabular support to knitr-latex (.Rnw) files
https://github.com/coachshea/knitlatex

knitr latex r

Last synced: about 16 hours ago
JSON representation

An R package to provide longtable and supertabular support to knitr-latex (.Rnw) files

Host: GitHub
URL: https://github.com/coachshea/knitlatex
Owner: coachshea
Created: 2015-05-20T18:48:35.000Z (over 9 years ago)
Default Branch: master
Last Pushed: 2020-04-28T16:43:22.000Z (over 4 years ago)
Last Synced: 2023-08-17T09:42:14.007Z (over 1 year ago)
Topics: knitr, latex, r
Language: TeX
Homepage: https://coachshea.github.io/knitLatex/
Size: 1.18 MB
Stars: 1
Watchers: 2
Forks: 1
Open Issues: 0
Metadata Files:
- Readme: README.Rmd

Awesome Lists containing this project

README

---
output:
md_document:
variant: markdown_github
---

```{r, include = FALSE}
devtools::load_all('./')
knitr_sethooks()
knitr::opts_chunk$set(
collapse = TRUE,
fig.path = "README-"
)
cars <- mtcars[1:10,1:5]
```

# Introduction

This package provides several helper functions for working with knitr and LaTeX.
It includes xTab for creating traditional LaTeX tables, lTab for generating
longtable environments, and sTab for generating a supertabular environment.
Additionally, this package contains a knitr_sethooks function. knitr_sethooks
serves two purposes. First, it fixes a well-known bug in knitr, which distorts
the "results='asis'" command when used in conjunction with user-defined
commands. Second, it provides a com command (\<\\>=) which renders
the output from knitr as a LaTeX command.

In the examples below, the code is shown as it would be provided in a knitr
chunk, with the resultant LaTeX depcited below. If this was an actual LaTeX
file, setting results = 'asis' would eliminate the comment markings (which is
generally what you would want). Additionally, the examples below show only the
basic usages of each function. For a more detailed examination, you should view
the vigenttes or the help documentation. To see a complete working example, see
the documentation provided inst/example (if you are viewing on github).

**Important Notes**

* When passing LaTeX commands to an xTab argument, backslashes must be escaped.
For example, you need to pass '\\\\hline' to produce '\\hline' in the LaTeX
document. Similarly you must pass'\\\\\\\\' to produce '\\\\'.
* For all of the examples that follow, we will be using the first ten rows and
five columns of the mtcars data.frame, which we have saved in the variable
'cars'.
* The following examples write the LaTeX tables to stdout for demonstration
purposes. To see an actual .Rnw file, and the resultant pdf file select the
links below. The pdf file is written to be a knitLatex tutorial in and of
itself. However, reading the .Rnw file can provide further insight into the
uses of this package.
+ [example.Rnw](./inst/examples/example.Rnw)
+ [example.pdf](./inst/examples/example.pdf)

# xTab

xTab is a function that produces a standard LaTeX table/tabular environment

## Basics

### Standard xTab table

To produce a LaTeX table, simply pass a matrix or a data.frame to the xTab
function.

```{r}
xTab(cars)
```

### Labels

Pass a string into the 'label' option. When not set, defaults to NULL.

```{r}
xTab(cars, label = 'tab:mytable')
```

### Captions

Place a caption at the top of the table.

```{r}
xTab(cars, caption.top = 'my table')
```

Place a caption at the bottom of the table

```{r}
xTab(cars, caption.bottom = 'my table')
```

### Booktabs

Setting booktabs = TRUE sets the defaults of the toprule, midrule, and
bottomrule arguments to \\toprule, \\midrule, and \\bottomrule respectively.
When using booktabs rules, regardless of whether you set booktabs = TRUE or set
them individually, make sure to include \\usepackage{booktabs} in your LaTeX
document. When booktabs is not set, xTab looks for the value of
kLat.xTab.booktabs, then kLat.booktabs, then defaults to FALSE.

```{r}
xTab(cars, booktabs = TRUE)
```

If any of those options are explicitly set, the booktabs value has no effect.

```{r}
xTab(cars, booktabs = TRUE, midrule = '\\hline')
```

### Table Position

If not set, xTAb will look for the value of kLat.xTab.position. If not set,
defaults to 'ht'

```{r}
xTab(cars, position = '!htbp')
```

## Headers

By default, xTab will use the column names for the head of the table(as
demonstrated in the above examples). To customize the table head simply pass in
the appropriate LaTeX to the 'head' argument. The values of toprule and midrule
are still used and should not be set in the head argument. If you do not want
them included in your custom header, set either or both to NULL

```{r}
xTab(cars,
head = 'col1 & col 2 & col3 & \\eta & col5 \\\\')
```

Pass in NULL to avoid a table head. In the case of a NULL head, toprule and
midrule will not be used.

```{r}
xTab(cars, head = NULL)
```

To preserve the top and midrules, pass an empty string to head. Often, people
want a toprule with no head or midrule. In that case, pass an empty string into
the head argument and NULL into midule. You can then use the default toprule
value (as depicted below), explicitly set toprule, or set booktabs = TRUE to set
the toprule and bottomrule simultaneously.

```{r}
lTab(cars, head = '', midrule = NULL)
```

## Rows

### Rownames

When including row names in a table, by default xTab will use an empty column
name for the 'rownames' column. When rows is not set, xTab looks for the value
of kLat.xTab.rows, then klat.rows, then defaults to false.

```{r}
xTab(cars, rows = TRUE)
```

### Rownames with custom header

When providing a custom head with rows set to TRUE, remember to account for the
extra column produced by the row names

```{r}
xTab(cars,
rows = TRUE,
head = 'rows & col1 & col2 & col3 & \\eta & col5 \\\\')
```

### Row separator

Any arbitrary LaTeX command can be inserted between each row, but the most
common are \\hline and \\midrule. To use \\midrule, \\usepackage{booktabs} must
be declared in the preamble of the LaTeX document, but booktabs = TRUE **does
not** need to be set on the table. When rowsep is not set, xTab looks for the
value of kLat.xTab.rowsep, then kLat.rowsep, then defaults to an empty string.

```{r}
xTab(cars, rowsep = '\\hline')
```

```{r}
xTab(cars, rowsep = '\\midrule')
```

## Columns

### Column alginment

Explicilty set the column definitions. If this is set, colsep will have no effect
and you must handle column separation within this declaration. Defaults to 'r' for
numeric vector columns and 'l' for character vector columns.

```{r}
xTab(cars, coldef ='rlc|l|p{5cm}')
```

### Column separator

Place any arbitrary LaTeX between each column. Will have no effect if coldef is
set.

```{r}
xTab(cars, colsep = '|')
```

# sTab

sTab is a function that produces a supertabular environment

## Basics

### Standard sTab table

To produce a LaTeX table, simply pass a matrix or a data.frame to the sTab
function.

```{r}
sTab(cars)
```

### Labels

Pass a string into the 'label' option. When not set, defaults to NULL.

```{r}
sTab(cars, label = 'tab:mytable')
```

### Captions

Place a caption at the top of the table.

```{r}
sTab(cars, caption.top = 'my table')
```

Place a caption at the bottom of the table

```{r}
sTab(cars, caption.bottom = 'my table')
```

### Booktabs

Setting booktabs = TRUE sets the defaults of the toprule, midrule, and
bottomrule arguments to \\toprule, \\midrule, and \\bottomrule respectively.
When using booktabs rules, regardless of whether you set booktabs = TRUE or set
them individually, make sure to include \\usepackage{booktabs} in your LaTeX
document. When booktabs is not set, sTab looks for the value of
kLat.sTab.booktabs, then kLat.booktabs, then defaults to FALSE.

```{r}
sTab(cars, booktabs = TRUE)
```

If any of those options are explicitly set, the booktabs value has no effect.

```{r}
sTab(cars, booktabs = TRUE, midrule = '\\hline')
```

## Headers

### Head

By default, sTab will use the column names for the head of the table(as
demonstrated in the above examples). The head argument is diplayed at the top of
the table on each page that the table spans. To customize the table head simply
pass in the appropriate LaTeX to the 'head' argument. The values of toprule and
midrule are still used and should not be set in the head argument. If you do not
want them included in your custom header, set either or both to NULL

```{r}
sTab(cars,
head = 'col1 & col 2 & col3 & \\eta & col5 \\\\')
```

Pass in NULL to avoid a table head. In the case of a NULL head, toprule and
midrule will not be used.

```{r}
sTab(cars, head = NULL)
```

```{r}
sTab(cars, head = '', midrule = NULL)
```

### FirstHead

In a supertabular environment, it is possible to present a different first head
(i.e. header on first page of table only).

```{r}
sTab(cars,
firsthead = 'f1 & f2 & f3 & f4 & f5 \\\\')
```

**Important Note**

As demonstrated in the above example, both head and firsthead use the toprule
and midrule commands by default. If you desire to use different commands for the
head and firsthead (or if you want one, but not both to use a top and
midrule), you must set both toprule and midrule to NULL and manually insert the
commands into head and firsthead as shown below examples.

```{r}
sTab(cars, toprule = NULL, midrule = NULL,
firsthead = '\\toprule\nf1 & f2 & f3 & f4 & f5 \\\\\nmidrule',
head = '\\hline\n col1 & col2 & col3 & cll4 & col5 \\\\\n\\hline')
```

```{r}
sTab(cars, toprule = NULL, midrule = NULL,
firsthead = '\\toprule\nf1 & f2 & f3 & f4 & f5 \\\\\nmidrule',
head = '\\toprule')
```

## Rows

### Rownames

When including row names in a table, by default sTab will use an empty column
name for the 'rownames' column. When rows is not set, sTab looks for the value
of kLat.sTab.rows, then klat.rows, then defaults to false.

```{r}
sTab(cars, rows = TRUE)
```

### Rownames with custom header

When providing a custom head with rows set to TRUE, remember to account for the
extra column produced by the row names

```{r}
sTab(cars,
rows = TRUE,
head = 'rows & col1 & col2 & col3 & \\eta & col5 \\\\')
```

### Row separator

Any arbitrary LaTeX command can be inserted between each row, but the most
common are \\hline and \\midrule. To use \\midrule, \\usepackage{booktabs} must
be declared in the preamble of the LaTeX document, but booktabs = TRUE **does
not** need to be set on the table. When rowsep is not set, sTab looks for the
value of kLat.sTab.rowsep, then kLat.rowsep, then defaults to an empty string.

```{r}
sTab(cars, rowsep = '\\hline')
```

```{r}
sTab(cars, rowsep = '\\midrule')
```

## Columns

### Column alginment

```{r}
sTab(cars, coldef ='rlc|l|p{5cm}')
```

### Column separator

Place any arbitrary LaTeX between each column. Will have no effect if coldef is
set.

```{r}
sTab(cars, colsep = '|')
```

# lTab

lTab is a function for creating a longtable environment

## Basics

### Standard lTab table

To produce a LaTeX table, simply pass a matrix or a data.frame to the lTab
function.

```{r}
lTab(cars)
```

### Labels

Pass a string into the 'label' option. When not set, defaults to NULL.

```{r}
lTab(cars, label = 'tab:mytable')
```

### Captions

The lTab environment can place a caption in the head, firsthead, foot, or last
foot. When placing captions in the firsthad or lastfoot, it is important to set
these options (even if they are empty strings) or strange bugs can occur.

```{r}
lTab(cars, caption.head = 'my caption in head')
```

```{r}
lTab(cars,
firsthead = 'f1 & f2 & f3 & f4 & f5 \\\\',
caption.firsthead = 'my caption in firsthead')
```

```{r}
lTab(cars, caption.foot = 'my caption in foot')
```

```{r}
lTab(cars,
lastfoot = '\\hline',
caption.lastfoot = 'my caption in last foot')
```

### Booktabs

Setting booktabs = TRUE sets the defaults of the toprule, midrule, and
bottomrule arguments to \\toprule, \\midrule, and \\bottomrule respectively.
When using booktabs rules, regardless of whether you set booktabs = TRUE or set
them individually, make sure to include \\usepackage{booktabs} in your LaTeX
document. When booktabs is not set, lTab looks for the value of
kLat.lTab.booktabs, then kLat.booktabs, then defaults to FALSE.

```{r}
lTab(cars, booktabs = TRUE)
```

If any of those options are explicitly set, the booktabs value has no effect.

```{r}
lTab(cars, booktabs = TRUE, midrule = '\\hline')
```

## Headers

### Head

By default, lTab will use the column names for the head of the table(as
demonstrated in the above examples). The head argument is displayed at the top of
the table on each page that the table spans. To customize the table head simply
pass in the appropriate LaTeX to the 'head' argument. The values of toprule and
midrule are still used and should not be set in the head argument. If you do not
want them included in your custom header, set either or both to NULL

```{r}
lTab(cars,
head = 'col1 & col 2 & col3 & \\eta & col5 \\\\')
```

Pass in NULL to avoid a table head. In the case of a NULL head, toprule and
midrule will not be used.

```{r}
lTab(cars, head = NULL)
```

```{r}
lTab(cars, head = '', midrule = NULL)
```

### FirstHead

In a supertabular environment, it is possible to present a different first head
(i.e. header on first page of table only).

```{r}
lTab(cars,
firsthead = 'f1 & f2 & f3 & f4 & f5 \\\\')
```

**Important Note**

```{r}
lTab(cars, toprule = NULL, midrule = NULL,
firsthead = '\\toprule\nf1 & f2 & f3 & f4 & f5 \\\\\nmidrule',
head = '\\hline\n col1 & col2 & col3 & cll4 & col5 \\\\\n\\hline')
```

```{r}
lTab(cars, toprule = NULL, midrule = NULL,
firsthead = '\\toprule\nf1 & f2 & f3 & f4 & f5 \\\\\nmidrule',
head = '\\toprule')
```

## Rows

### Rownames

When including row names in a table, by default lTab will use an empty column
name for the 'rownames' column. When rows is not set, lTab looks for the value
of kLat.lTab.rows, then klat.rows, then defaults to false.

```{r}
lTab(cars, rows = TRUE)
```

### Rownames with custom header

When providing a custom head with rows set to TRUE, remember to account for the
extra column produced by the row names

```{r}
lTab(cars,
rows = TRUE,
head = 'rows & col1 & col2 & col3 & \\eta & col5 \\\\')
```

### Row separator

Any arbitrary LaTeX command can be inserted between each row, but the most
common are \\hline and \\midrule. To use \\midrule, \\usepackage{booktabs} must
be declared in the preamble of the LaTeX document, but booktabs = TRUE **does
not** need to be set on the table. When rowsep is not set, lTab looks for the
value of kLat.lTab.rowsep, then kLat.rowsep, then defaults to an empty string.

```{r}
lTab(cars, rowsep = '\\hline')
```

```{r}
lTab(cars, rowsep = '\\midrule')
```

## Columns

### Column alginment

```{r}
lTab(cars, coldef ='rlc|l|p{5cm}')
```

### Column separator

Place any arbitrary LaTeX between each column. Will have no effect if coldef is
set.

```{r}
lTab(cars, colsep = '|')
```