In dmontaner/TiddlyWikiR: Create dynamic reports using a TiddlyWiki template.

Getting started with TiddlyWikiR

David Montaner

26-10-2013

---

TiddlyWikiR is an R package for writing dynamic reports using TiddlyWiki as a template.

The library implements S4 classes to organize and handle statistical results within R, and functions to insert those results into the wiki file.

In this document you can find a brief introduction to the package.

About TiddlyWiki

TiddlyWiki is a single page wiki application. It is built in a unique HTML file which includes CSS and JavaScript besides the document content. As any other wiki system, users may add, modify, or delete content using a web browser. Being a wiki, it has the advantage over plain HTML pages of the simplified markup language and the easiness of edition. But unlike most other wiki applications, TiddlyWiki does not need any installation; it does not even need being hosted in a web server. The single file that constitutes the application is downloaded and kept locally while the edition is ongoing. It can be used as a local document or it may be finally uploaded to a server and made accessible via Internet as any other HTML file.

TiddlyWiki content organization relies on chunks of information called tiddlers. Tiddlers can be set to be displayed in the document when it is first opened, or they can be accessed through the appropriated links when necessary. This feature makes TiddlyWiki optimal for writing small statistical reports: the most relevant information in the document can be display linearly by default while complementary information as for instance the explanation of the statistical glossary can be kept in the background and accessed just when the reader needs it.

Being a single file, a TiddlyWiki document can be straightforward used as a template for such statistical reports. First the wiki system will allow for the quick edition of the text and for the specification of the document lay out. Then, as TiddlyWiki is ultimately a text file, automatic routines implemented in TiddlyWikiR may insert additional information into the report as for instance tables of descriptive statistics, results form hypothesis testing, or links to plots that will be displayed within the document.

TiddlyWiki is published under an open source license which makes it very suitable to the R users community.

Visit http://tiddlywiki.com for more in formation about TiddlyWiki.

TiddlyWikiR usage

First of all load the library:

library (package = "TiddlyWikiR")

TiddlyWikiR is intended for automatically inserting R results into a TiddlyWiki template. Thus, first of all you will need to get a TiddlyWiki file where the results of our R session will be inserted. Generally you will download an empty TiddlyWiki file form the TiddlyWiki web page, but, for a quick start, you can use the example wiki file distributed within TiddlyWikiR.

The following code will copy the template to your working directory:

newEmptyWiki ("myTemplate.html")
dir ()

The local file myTemplate.html has been crated. You can view this html file in your browser and use the TiddlyWiki editor to write into it. (An external copy of the file may be found here).

The TiddlySaver.jar file is needed by some browsers to be able to save changes in the wiki. See the TiddlyWiki web page for details.

From this point the idea is to work at the same time with two files: - the wiki template file where you will write your report: introduction, methods, conclusions ... - an R script that will help you inserting your statistical results into the wiki file creating the final document.

TiddlyWikiR will let you insert data into the wiki in two ways: - replacing tags within already existing tiddlers. - creating new tiddlers.

Replace a tag within an existing tiddler

If you open the template file myTemplate.html you will see that it has been edited using a web browser.

A section called "Tag example" has been created. Some text has been written and two tags are left to be replaced by TiddlyWikiR in the tiddler GettingStarted.

We may for instance replace the first tag by an image and the second by a number, but any other elements would be allowed: tables, hyper links, text ...

Let's first create the image to be displayed:

dir.create ("files")

png ("files/myplot.png")
plot (1:10)
dev.off ()

and now let's create the TiddlyWikiR object holding the information about how the image should be displayed in the report:

myImage <- twImage (imgf = "files/myplot.png", label = "drag the image with your mouse", ref = "LinkToTiddler", width = "10%+")

Finally we replace the tag for the image and the tag for the number:

tagList <- list ('@@my_tag_for_plot@@' = myImage, '@@my_tag_for_number@@' = 1000000)
writeTags (tagList, infile = "myTemplate.html", outfile = "myReport_1.html")

You can see the result of the insertion in the newly locally created file myReport_1.html (or a copy of it in this external link).

Insert a new tiddler

In this section we will show how new tiddlers can be introduced in the wiki by TiddlyWikiR. We also exemplify the different elements TiddlyWikiR is able to format:

• images
• hyperlinks to internal or external content
• lists
• tables
• tiddlers
• text lines
• R objects display

As an example we may create a hyper link to a tiddler called TiddlerName:

myLink <- twLink ("follow the link to a tiddler", ref = "TiddlerName")

We can also create a list:

myList <- twList (elements = c("line 1", "line 2", "line 3","line 4"), 
                  level = c(1,1,2,2), 
                  type = c("o", "o", "u", "u")) 

that will be inserted in the wiki file as:

cat (wikify (myList), sep = "\n")

We create data set:

myData <- as.data.frame (matrix (rnorm (12), ncol = 4))
rownames (myData) <- c("one", "two", "three")
myData 

and convert it into a table to be included in the report:

myTable <- twTable (dat = myData, sortable = TRUE)

we include internal and external links in the third column of the table:

ref (myTable)[,"V3"] <- c("tiddlerOne", "tiddlerTwo", "http://tiddlywiki.com/")

and color the cells in the second column:

color (myTable)[,"V2"] <- c("red", "blue", "green")

We also store some standard R object from an statistical analysis:

x <- 1:100
y <- rnorm (100)
my.stats <- summary (glm (y ~ x))

And finally we create a text vector containing some wiki syntax:

myVector <- c("This may be some ''bold text''",
              "!This may be a heading")

Now we are ready to insert all those objects into a tiddler of our TiddlyWiki report.

We first gather all of them into a tiddler object entitled "MyNewTiddler":

myTiddler <- newTiddler (title = "MyNewTiddler", content = list (myVector, myLink, myList, myTable, my.stats))

And finally we insert the tiddler into the wiki file:

writeTiddlers (tid = myTiddler, infile = "myReport_1.html", outfile = "myReport_2.html")

Observe that with the above command we created a third file called myReport_2.html. We did so for clarifying the TiddlyWikiR process but generally one will overwrite the first report file doing:

writeTiddlers (tid = myTiddler, file = "myReport_1.html")

Notice that in such way we would overwrite the first created report, but not the wiki template myTemplate.html which we are editing in our browser and that is not intended to be modified by TiddlyWikiR.

Finally we may replace our last tag (now overwriting the file):

writeTags (list ('@@currently does not exist@@' = "has been created"), file = "myReport_2.html")

Thus, the final report is ready to go in the local file myReport_2.html (use this link to find an external copy of the file).

Session Info

sessionInfo ()

More about TiddlyWikiR

Some more documentation about TiddlyWikiR may be found at:

• https://github.com/dmontaner/TiddlyWikiR
• http://www.dmontaner.com/

---

Last revision: 30-12-2013 | Compiled: r format (Sys.time(), "%d-%m-%Y")

dmontaner/TiddlyWikiR documentation built on May 15, 2019, 9:35 a.m.