---
title: "textab"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{textab}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```


## 0. Installation

To install the package from CRAN:

```{r echo=TRUE, eval=FALSE, message=FALSE}
install.packages("textab")
```

To install the package from Github:

```{r echo=TRUE, eval=FALSE, message=FALSE}
devtools::install_github("setzler/textab")
```

To use the package after it is installed:

```{r echo=TRUE, eval=TRUE, message=FALSE}
library(textab)
```




## 1. Character rows
 
Basic character row:

```{r echo=TRUE, eval=TRUE, message=FALSE}
vec = c("hello", "world")
TexRow(vec)
```


Character row with LaTeX formatting:

```{r echo=TRUE, eval=TRUE, message=FALSE}
vec = c('Hello','\\textbf{World}','$\\alpha$','$\\frac{1}{2}$')
TexRow(vec)
```

Note: Double backslashes are required for LaTeX commands.




## 2. Numeric rows


Basic numeric row:

```{r echo=TRUE, eval=TRUE, message=FALSE}
vec <- c(1.0, 1.01, 1.001)
TexRow(vec)
```


Numeric row rounded to the second decimal place:

```{r echo=TRUE, eval=TRUE, message=FALSE}
vec <- c(1.0, 1.01, 1.001)
TexRow(vec, dec = 2)
```

There are four other arguments specific to numeric rows:

- `percentage`: if TRUE, add a "%" sign after each number.
- `dollar`: if TRUE, add a "$" sign before each number.
- `se`: if TRUE, surround each number with parentheses.
- `pvalues`: if provided, these numbers are used to add stars "*" after the numbers.

See [this article](https://setzler.github.io/textab/articles/Numerics.html) about formatting numbers. 


## 3. Custom Formatting using Surround

While many common formatting options are explicitly provided in `TexRow`, we also include the `surround` argument so that the user can specify custom formatting.

The surround argument allows you to provide raw LaTeX code. Place the `%s` symbol wherever your number or character should be placed.

Suppose you wish to make each number red. In LaTeX, you can make a number red using the code `{\color{red} %s}`, where `%s` indicates where the number should go. In order to make each number red, we would specify the following:

```{r echo=TRUE, eval=TRUE, message=FALSE}
vec = c(5.081, 2.345, 6.789)
TexRow(vec, dec = 1, surround = "{\\color{red} %s}")
```

Note: Double backslashes are required for LaTeX commands.

The `surround` argument works for character vectors as well, and we can apply different formatting to each value:

```{r echo=TRUE, eval=TRUE, message=FALSE}
vec = c("hello", "world")
TexRow(vec, dec = 1, surround = c("{\\color{blue} %s}", "$\\frac{\\text{%s}}{2}$"))
```





## 4. Multicolumn Rows

Merge and center the second and third rows using the `cspan` argument:

```{r echo=TRUE, eval=TRUE, message=FALSE}
vec = c("hello", "world")
TexRow(vec, cspan = c(1,2))
```

Merge and left-align the second and third rows using the `position` argument:

```{r echo=TRUE, eval=TRUE, message=FALSE}
vec = c("hello", "world")
TexRow(vec, cspan = c(1,2), position = "l")
```

Two multi-column rows, where the first is two-column left-aligned and the second is three-column right-aligned:

```{r echo=TRUE, eval=TRUE, message=FALSE}
vec = c("hello", "world")
TexRow(vec, cspan = c(2,3), position = c("l","r"))
```




## 5. Combine Rows

#### Combine Rows Side-by-side

The slash sign `/` combines rows side-by-side:

```{r echo=TRUE, eval=TRUE, message=FALSE} 
first_block = TexRow(c("hello", "world"))
second_block = TexRow(c("$\\alpha$","$\\frac{1}{2}$"))
combined_row = first_block / second_block
combined_row
```

#### Stack Rows Vertically

The plus sign `+` stacks rows vertically:

```{r echo=TRUE, eval=TRUE, message=FALSE} 
first_block = TexRow(c("hello", "world"))
second_block = TexRow(c("$\\alpha$","$\\frac{1}{2}$"))
combined_row = first_block + second_block
combined_row
```

#### Order of Operations: Horizontal Comes First

When using both horizontal and vertical concatenation in the same line, horizontal concatenation will be performed first:

```{r echo=TRUE, eval=TRUE, message=FALSE} 
first_block = TexRow(c("hello", "world"))
second_block = TexRow(c("$\\alpha$"))
third_block = TexRow(c("$\\frac{1}{2}$"))
combined_row = first_block + second_block / third_block
combined_row
```



## 6. Vertical Space between Rows

To add 3pt of space between two rows:

```{r echo=TRUE, eval=TRUE, message=FALSE}
TexRow(c("hello", "world"), space=3) +
  TexRow(c('$\\alpha$','$\\frac{1}{2}$'))
```



## 7. Midrule and Partial Midrules

Add a full midrule between two rows:

```{r echo=TRUE, eval=TRUE, message=FALSE}
TexRow(c("hello", "world"), cspan=c(1,2)) + 
  TexMidrule() +
  TexRow(c('$\\alpha$','$\\frac{1}{2}$','$\\sqrt{\\frac{2}{3}}$'))
```

Add two partial midrules:

```{r echo=TRUE, eval=TRUE, message=FALSE}
TexRow(c("hello", "world"), cspan=c(1,2)) + 
  TexMidrule(list(c(1,1), c(2,3))) +
  TexRow(c('$\\alpha$','$\\frac{1}{2}$','$\\sqrt{\\frac{2}{3}}$'))
```



## 8. Save a LaTeX table in .tex format

Let us work with the following table:

```{r echo=TRUE, eval=TRUE, message=FALSE}
tt = TexRow(c("hello", "world"), cspan=c(1,2), surround = c("{\\color{red} %s}", "{\\color{blue} %s}")) + 
  TexMidrule(list(c(1,1), c(2,3))) +
  TexRow(c('$\\alpha$','$\\frac{1}{2}$','$\\sqrt{\\frac{2}{3}}$'))
```


Save a simple .tex document containing this table:

```{r echo=TRUE, eval=FALSE, message=FALSE}
TexSave(tab = tt, positions = c("l","c","c"), 
        filename = "example1", output_path = tempdir())
```

Save a stand-alone .tex document that could be compiled, as it has begin-document and end-document statements as well as import statements for common LaTeX packages:

```{r echo=TRUE, eval=FALSE, message=FALSE}
TexSave(tab = tt, positions = c("l","c","c"), 
        filename = "example2", output_path = tempdir(), 
        stand_alone = TRUE)
```

Note: these examples saved the table to a temporary directory, `tempdir()`. In practice, you will likely want to save the table to a permanent directory. If you do not provide an `output_path`, the table will be saved to your current working directory, `getwd()`.

## 9. Save LaTeX Table and Compile to PDF

Produce and compile the stand-alone .tex document to .pdf:

```{r echo=TRUE, eval=FALSE, message=FALSE}
TexSave(tab = tt, positions = c("l","c","c"), 
        filename = "example3", output_path = tempdir(), 
        stand_alone = TRUE, compile_tex = TRUE)
```

The final command will produce a PDF similar to [this](https://github.com/setzler/textab/blob/main/inst/example3.pdf).