# textab

## 0. Installation

To install the package from CRAN:

    install.packages("textab")

To install the package from Github:

    devtools::install_github("setzler/textab")

To use the package after it is installed:

    library(textab)

## 1. Character rows

Basic character row:

    vec = c("hello", "world")
    TexRow(vec)
    #> % created using textab on Tue Apr 25 07:41:52 2023
    #> \begin{tabular}{rr}
    #> hello & world \\
    #> \end{tabular}

Character row with LaTeX formatting:

    vec = c('Hello','\\textbf{World}','$\\alpha$','$\\frac{1}{2}$')
    TexRow(vec)
    #> % created using textab on Tue Apr 25 07:41:52 2023
    #> \begin{tabular}{rrrr}
    #> Hello & \textbf{World} & $\alpha$ & $\frac{1}{2}$ \\
    #> \end{tabular}

Note: Double backslashes are required for LaTeX commands.

## 2. Numeric rows

Basic numeric row:

    vec <- c(1.0, 1.01, 1.001)
    TexRow(vec)
    #> % created using textab on Tue Apr 25 07:41:52 2023
    #> \begin{tabular}{rrr}
    #> 1.000 & 1.010 & 1.001 \\
    #> \end{tabular}

Numeric row rounded to the second decimal place:

    vec <- c(1.0, 1.01, 1.001)
    TexRow(vec, dec = 2)
    #> % created using textab on Tue Apr 25 07:41:52 2023
    #> \begin{tabular}{rrr}
    #> 1.00 & 1.01 & 1.00 \\
    #> \end{tabular}

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 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:

    vec = c(5.081, 2.345, 6.789)
    TexRow(vec, dec = 1, surround = "{\\color{red} %s}")
    #> % created using textab on Tue Apr 25 07:41:52 2023
    #> \begin{tabular}{rrr}
    #> {\color{red} 5.1} & {\color{red} 2.3} & {\color{red} 6.8} \\
    #> \end{tabular}

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:

    vec = c("hello", "world")
    TexRow(vec, dec = 1, surround = c("{\\color{blue} %s}", "$\\frac{\\text{%s}}{2}$"))
    #> % created using textab on Tue Apr 25 07:41:52 2023
    #> \begin{tabular}{rr}
    #> {\color{blue} hello} & $\frac{\text{world}}{2}$ \\
    #> \end{tabular}

## 4. Multicolumn Rows

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

    vec = c("hello", "world")
    TexRow(vec, cspan = c(1,2))
    #> % created using textab on Tue Apr 25 07:41:52 2023
    #> \begin{tabular}{rr}
    #> hello & \multicolumn{2}{c}{world} \\
    #> \end{tabular}

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

    vec = c("hello", "world")
    TexRow(vec, cspan = c(1,2), position = "l")
    #> % created using textab on Tue Apr 25 07:41:52 2023
    #> \begin{tabular}{rr}
    #> hello & \multicolumn{2}{l}{world} \\
    #> \end{tabular}

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

    vec = c("hello", "world")
    TexRow(vec, cspan = c(2,3), position = c("l","r"))
    #> % created using textab on Tue Apr 25 07:41:52 2023
    #> \begin{tabular}{rr}
    #> \multicolumn{2}{l}{hello} & \multicolumn{3}{r}{world} \\
    #> \end{tabular}

## 5. Combine Rows

#### Combine Rows Side-by-side

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

    first_block = TexRow(c("hello", "world"))
    second_block = TexRow(c("$\\alpha$","$\\frac{1}{2}$"))
    combined_row = first_block / second_block
    combined_row
    #> % created using textab on Tue Apr 25 07:41:52 2023
    #> \begin{tabular}{rrrr}
    #> hello & world & $\alpha$ & $\frac{1}{2}$ \\
    #> \end{tabular}

#### Stack Rows Vertically

The plus sign `+` stacks rows vertically:

    first_block = TexRow(c("hello", "world"))
    second_block = TexRow(c("$\\alpha$","$\\frac{1}{2}$"))
    combined_row = first_block + second_block
    combined_row
    #> % created using textab on Tue Apr 25 07:41:52 2023
    #> \begin{tabular}{rr}
    #> hello & world \\
    #> $\alpha$ & $\frac{1}{2}$ \\
    #> \end{tabular}

#### Order of Operations: Horizontal Comes First

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

    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
    #> % created using textab on Tue Apr 25 07:41:52 2023
    #> \begin{tabular}{rr}
    #> hello & world \\
    #> $\alpha$ & $\frac{1}{2}$ \\
    #> \end{tabular}

## 6. Vertical Space between Rows

To add 3pt of space between two rows:

    TexRow(c("hello", "world"), space=3) +
      TexRow(c('$\\alpha$','$\\frac{1}{2}$'))
    #> % created using textab on Tue Apr 25 07:41:52 2023
    #> \begin{tabular}{rr}
    #> hello & world \\[3pt]
    #> $\alpha$ & $\frac{1}{2}$ \\
    #> \end{tabular}

## 7. Midrule and Partial Midrules

Add a full midrule between two rows:

    TexRow(c("hello", "world"), cspan=c(1,2)) +
      TexMidrule() +
      TexRow(c('$\\alpha$','$\\frac{1}{2}$','$\\sqrt{\\frac{2}{3}}$'))
    #> % created using textab on Tue Apr 25 07:41:52 2023
    #> \begin{tabular}{rrr}
    #> hello & \multicolumn{2}{c}{world} \\
    #> \midrule
    #> $\alpha$ & $\frac{1}{2}$ & $\sqrt{\frac{2}{3}}$ \\
    #> \end{tabular}

Add two partial midrules:

    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}}$'))
    #> % created using textab on Tue Apr 25 07:41:52 2023
    #> \begin{tabular}{rrr}
    #> hello & \multicolumn{2}{c}{world} \\
    #>  \cmidrule(lr){1-1} \cmidrule(lr){2-3}
    #> $\alpha$ & $\frac{1}{2}$ & $\sqrt{\frac{2}{3}}$ \\
    #> \end{tabular}

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

Let us work with the following table:

    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:

    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:

    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:

    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.