ascii package

Summary

ascii is an R package that provides formatted tables and lists in a number of markup formats (Asciidoc, txt2tags, reStructuredText, Org, Pandoc markdown and textile). Documents can be processed in four broad classes:

1. Using knitr or rmarkdown, with document formats including Rmd, Rasciidoc and Rrst.
2. In Org mode format using Babel for R code blocks.
3. In Sweave format for all six markup formats, with drivers that include base Sweave and caching through weaver.
4. Using R scripting to export reports to a variety of formats.

What ascii provides

ascii provides:

• A generic method: ascii(). It creates a plain text representations of many R objects.
• A function asciiCoefmat for working with coefficient matrices (similar to printCoefmat).
• Several classic Sweave drivers: RweaveAsciidoc(), RweaveT2t(), RweaveReST(), RweaveOrg(), RweavePandoc() and RweaveTextile().
• Weaver based Sweave drivers: weaverAsciidoc(), weaverT2t(), weaverReST(), weaverOrg(), weaverPandoc() and weaverTextile().
• Some simple wrappers for Sweave() named Asciidoc(), T2t(), ReST(), Org(), Pandoc() and Textile().
• A Report class for R scripting.

ascii methods

ascii provides methods for:

library(ascii)
methods(ascii)

 [1] ascii.anova*                    ascii.aov*                     
 [3] ascii.aovlist*                  ascii.cast_df*                 
 [5] ascii.character*                ascii.coxph*                   
 [7] ascii.CrossTable*               ascii.data.frame*              
 [9] ascii.default*                  ascii.density*                 
[11] ascii.describe*                 ascii.describe.single*         
[13] ascii.factor*                   ascii.freqtable*               
[15] ascii.ftable*                   ascii.glm*                     
[17] ascii.htest*                    ascii.integer*                 
[19] ascii.list*                     ascii.lm*                      
[21] ascii.matrix*                   ascii.meanscomp*               
[23] ascii.microbenchmark*           ascii.mtable*                  
[25] ascii.numeric*                  ascii.packageDescription*      
[27] ascii.prcomp*                   ascii.proc_time*               
[29] ascii.sessionInfo*              ascii.simple.list*             
[31] ascii.smooth.spline*            ascii.stat.table*              
[33] ascii.summary.aov*              ascii.summary.aovlist*         
[35] ascii.summary.formula.cross*    ascii.summary.formula.response*
[37] ascii.summary.formula.reverse*  ascii.summary.glm*             
[39] ascii.summary.lm*               ascii.summary.prcomp*          
[41] ascii.summary.survfit*          ascii.summary.table*           
[43] ascii.survdiff*                 ascii.survfit*                 
[45] ascii.table*                    ascii.ts*                      
[47] ascii.zoo*                     
see '?methods' for accessing help and source code

Examples

Pandoc markdown using R markdown

A source Rmd file is here. It can be processed to export to HTML using:

library(rmarkdown)
library(prettydoc)
rmarkdown::render(system.file("examples/test-1-Rmd.Rmd",package="ascii"), html_pretty())

Asciidoc markup using knitr

library(knitr)
options(asciiBackend="asciidoctor")
knitr::knit(system.file("examples/test-1-asciidoc.Rasciidoc",package="ascii"), "test-1-asciidoctor.txt")
system("asciidoctor test-1-asciidoctor.txt")

options(asciiBackend="asciidoc")
knitr::knit(system.file("examples/test-1-asciidoc.Rasciidoc",package="ascii"), "test-1-asciidoc.txt")
system("asciidoc test-1-asciidoc.txt")

ReStructured Text markup using knitr

library(knitr)
knitr::knit(system.file("examples/test-1-ReST.Rrst",package="ascii"), "test-1-ReST.rst")
system("rst2html test-1-ReST.rst > test-1-ReST.html")

Pandoc markdown using Noweb

A source Noweb file is here. It can be processed to export to HTML using:

Pandoc(system.file("examples/Pandoc-test-1.nw",package="ascii"))
system("pandoc Pandoc-test-1.md > Pandoc-test-1.html")

Alternatively, to allow caching using weaver, we can use:

Pandoc(system.file("examples/Pandoc-test-1.nw",package="ascii"), driver=weaverPandoc())
system("pandoc Pandoc-test-1.md > Pandoc-test-1.html")

Asciidoc markup using Noweb

A source Noweb file is here. It can be processed to export to HTML using:

options(asciiBackend="asciidoc")
Asciidoc(system.file("examples/Asciidoc-test-1.nw",package="ascii"))
system("asciidoc Asciidoc-test-1.txt")

Alternatively, to allow caching using weaver, we can use:

Asciidoc(system.file("examples/Asciidoc-test-1.nw",package="ascii"),driver=weaverAsciidoc())
system("asciidoc Asciidoc-test-1.txt")

ReStructured Text markup using Noweb

A source Noweb file is here It can be processed to export to HTML using:

ReST(system.file("examples/ReST-test-1.nw",package="ascii"))
system("rst2html ReST-test-1.rst > ReST-test-1.html")

Alternatively, to allow caching using weaver, we can use:

ReST(system.file("examples/ReST-test-1.nw",package="ascii"), driver=weaverReST())
system("rst2html ReST-test-1.rst > ReST-test-1.html")

Textile markup using Noweb

A source Noweb file is here. It can be processed to export to HTML using:

Textile(system.file("examples/Textile-test-1.nw",package="ascii"))
system("textile Textile-test-1.txt > Textile-test-1.html")

Alternatively, to allow caching using weaver, we can use:

Textile(system.file("examples/Textile-test-1.nw",package="ascii"), driver=weaverTextile())
system("textile Textile-test-1.txt > Textile-test-1.html")

Txt2tags markup using Noweb

A source Noweb file is here. It can be processed to export to HTML using:

T2t(system.file("examples/T2t-test-1.nw",package="ascii"))
system("txt2tags -t html T2t-test-1.t2t")

Alternatively, to allow caching using weaver, we can use:

T2t(system.file("examples/T2t-test-1.nw",package="ascii"), driver=weaverT2t())
system("txt2tags -t html T2t-test-1.t2t")

Org markup using Noweb

A source Noweb file is here. It can be processed to export to HTML using:

Org(system.file("examples/Org-test-1.nw",package="ascii"))

Alternatively, to allow caching using weaver, we can use:

Org(system.file("examples/Org-test-1.nw",package="ascii"), driver=weaverOrg())

Org mode using R code blocks

A common use of ascii is with Org mode using Babel and R code blocks. Initially, we set some options, including the default for asciiType.

options(asciiType = "org", width = 80)
x <- matrix(1:4, 2, 2)

Simple output

In Org Mode, we can use :results output wrap to get Org output:

ascii(x, include.rownames=TRUE, include.colnames=TRUE, header=TRUE)

This gives the following output:

	1	2
1	1.00	3.00
2	2.00	4.00

We could also use :results output raw if the output is one block (wrap is preferred over raw if there are multiple output blocks). For an example with multiple output blocks, we can use the asciiCoefmat function:

x = y = 1:100
y[1]=5
lm(y~x) |> summary() |> coef() |> asciiCoefmat()

	Estimate	Std. Error	t value	Pr(>|t|)
(Intercept)	0.1600000	0.0798017	2.005	0.04772	*
x	0.9976238	0.0013719	727.173	< 2e-16	***
Signif. codes: 0 ‘***’ 0.001 ‘**’ 0.01 ‘*’ 0.05 ‘.’ 0.1 ‘ ’ 1

Using ascii with more options:

x <- matrix(1:4, 2, 2)
ascii(x, caption = "A simple matrix", width = 50, digits = 0, align = c("c", "r"),
      style = matrix(c("d", "s", "e", "m"), 2, 2), lgroup = "group 1",
      tgroup = "group 2")

	*group 2*
**group 1**	1	3
	2	4

Note that the GitHub parser for .org files does not format this correctly.

A list example

y <- summary(with(esoph, table(alcgp, agegp)))
ascii(y, caption = "A simple list")

• Number of cases in table: 88
• Number of factors: 2
• Test for independence of all factors:
  • Chisq = 1.4189, df = 15, p-value = 1
  • Chi-squared approximation may be incorrect

Using the Report class

The code snippet below shows the use of the Report class:

options(asciiType = "asciidoc")
createreport(head(esoph))

r <- Report$new(author = "David Hajage", email = "dhajage at gmail dot com")
r$add(section("First section"))
r$addSection("First subsection", 2)
r$add(paragraph("The data set has", sexpr(nrow(esoph)), " lines. See yourself:"), esoph)
r$addSection("Second subsection: age and alc group", 2)
tab <- with(esoph, table(alcgp, agegp))
r$add(ascii(tab), ascii(summary(tab), format = "nice"))
r$create()
r$format <- "slidy"
r$create()

r$title <- "R report example"
r$author <- "David Hajage"
r$email <- "dhajage at gmail dot com"
options(asciiType = "pandoc")
r$backend <- "pandoc"
r$format <- "odt"
r$create()