Some introductory notes and videos on loon

Getting ready

The workshop will be conducted via an online livestream and involves you carrying out interactive analyses on your machine. This means there are requirements on your end for the workshop to be successful.

Don’t worry, these are not onerous and you probably have (nearly?) everything you need already.

Nevertheless, it would be a good idea to set your environment up a few days before the workshop.

Software

All of these can be downloaded and used for free.

Video conferencing

The workshop workshop will be carried out using Cisco’s Webex real time video conferencing

Analysis software

The workshop wil involve hands on analysis by you on your machine. You will need to have the following installed.

  1. A recent release of R (at least R 3.5.0 but NOT 4.0.1 for 64 bit Windows)

  2. A relatively recent release of RStudio, Note that this must be the desktop version, not the server version (which your company might force you to use, which will not work with loon).

  3. The loon package (at least 1.3.0, though 1.2.3 will do for much of the workshop).

  4. Some other R packages used in loon examples and demos

Installation instructions follow below.

Hardware

  • loon assumes that your mouse/trackpad has two buttons and the ability to scroll
  • for data visualization in general, but especially for an online streaming workshop like this, you should have at least two screens, the bigger the better:
    • one screen for the presentation,
    • a second where you can carry out your own analyses.

Register

If you have not yet done so, please register for the workshop here.

R

For this workshop, your R release must be at least version 3.5 (but NOT 4.0.1 for Windows at least).

Check your release

R.version.string
## [1] "R version 4.0.0 (2020-04-24)"

If the version number is greater than 3.5.0 (and is not 4.0.1) you should be good. If not, skip to install a new R release

Unless your R was a custom install, the R release will have come with the package tcltk installed as part of the base R.
Just to make sure you can check whether this is the case attaching the tcltk library:

library(tcltk)

If this works and your R version is greater than 3.5.0 then you are in business. If it failed to find the tcltk package, then you should install a new R release as described in the next subsection.

Install a new R release if necessary

If you already have a version of R installed, you may want to take note of which packages your version contains so that you can re-install them in the new version. R will install only with a base suite of packages each time you re-install it.

To get the latest R go to https://cran.r-project.org and select the appropriate download for your machine. Note that tcltk needs to be part of the installation.

  • Macs: this happens automatically with the basic system;
  • Windows: this also happens automatically with the basic system.
    Note however that the instructions there mention that
    • “Support Files for Package tcltk” needs to be selected from the installer.
    • NOTE do NOT install R release 4.0.1 if you are running a 64 bit Windows machine. Coincidently, this release came out the day of the workshop (June 6, 2020) but introduced a major BUG in R so that it will not run tcltk … and hence loon!!!
  • Linux: you should be able to figure this out :-)
    • You should also install the libtk-img debian package (e.g. with sudo apt-get install libtk-img) in order to get a wide variety of export formats with the l_export function. (Tested at least on Ubuntu.)

Once the new release of R has been installed, you may want to re-install those R packages that you would like. For example, you will want to have the devtools package installed:

install.packages("devtools")

RStudio

While other GUIs exist for R, we will be using RStudio. It provides one of the most complete integrated development environments (IDEs) presently available for R.

Note: you must be using the RStudio desktop version; not the RStudio server.

The RStudio desktop IDE can be downloaded from https://rstudio.com/products/rstudio/download/ and updated without disruption to the underlying R.

The loon software we use can also be used simply with R from the command line and X windows, though we will use RStudio.

loon

Some of the data we will be using in the workshop will be come from the loon.data package which can be installed from CRAN:

install.packages("loon.data")

Similarly, loon itself can be installed from CRAN:

install.packages("loon")

This must be at least loon version 1.3.0:

packageVersion("loon")

For this workshop, it is probably best to use this version from CRAN. However, in the future, you might want to experiment with the pre-release development version from github. For this you will need to have installed the devtools package beforehand.

devtools::install_github("great-northern-diver/loon", subdir = "R")

The source for loon and related packages can be explored at the github site great-northern-diver: https://github.com/great-northern-diver/loon.

If you were given warning that packages were missing before you could load loon.

check

Once loon is installed, you can check it out in R

library(loon)
p <- with(iris, 
          l_plot(x = Sepal.Length, y = Sepal.Width, color = Species))

If this creates a scatterplot and an inspector window, then loon was correctly installed.

mouse interaction

The direct manipulation interface of loon assumes a two-button mouse with a scroll-wheel. Before the workshop, make sure that you set up your laptop’s mouse or trackpad so that you have a primary and secondary mouse click and scrolling enabled (as in a document).

learn more l_web()

In addition to the help pages in R, the function l_web() will pop up a website which can be explored in more detail.
This will lead to the site

https://great-northern-diver.github.io/loon/

where you will find the entire reference manual, articles/vignettes on how to use loon, and the videos mentioned at the top of this document.

Other packages

The following CRAN packages will be used in the workshop

install.packages(c("MASS", "gridExtra", 
                   "maps", "sp", "rworldmap",   
                   "ggplot2", "dplyr", "magrittr", "tidyr" # Or all of "tidyverse"
                   )
                 )

Optional packages used in loon examples and demos

Note that these packages are not needed to install loon, nor are they required for the workshop. They are just nice to have to run all the examples and demos that loon provides.

After you have successfully installed loon you might want to try some of the demos that loon provides. These can be found by executing

demo(package = "loon")
# for example, the interactive graphics equivalent of 'Hello world'
demo(l_power)

You may find for some demos, the packages described here need to be installed for the demo to work.

Not all packages are installed in the same way, so we consider them in three groups.

CRAN packages

These packages from CRAN should install without any issues:

install.packages(c("RColorBrewer", "scales", "dimRed", "vegan"))

There is, for example, a somewhat esoteric demo that uses the rgl package to show how some loon tools might interact with other graphics packages. This is not likely to be of wide interest. Nevertheless, feel free to install it (it is fun in and of itself).

install.packages("rgl")

Bioconductor

Other packages are not on CRAN but on Bioconductor. That means we need a means to install them.

To install packages from bioconductor:

if (!requireNamespace("BiocManager", quietly = TRUE)) install.packages("BiocManager")
BiocManager::install(version = "3.11")

Now you can install specific R packages from bioconductor:

BiocManager::install(c("graph", "RDRToolbox", "Rgraphviz"))

For example, packages from CRAN like PairViz might depend on bioconductor packages. Once the bioconductor package have been installed, then the CRAN package which depends on them can be installed.

install.packages(c("PairViz"))

A final package which is presently essential to some of the most interesting loon high-dimensional data analysis tools is the CRAN scagnostics package. Unfortunately, it depends on the CRAN rjava package which in turn requires java to be installed on your machine and properly linked in R. This is only for one part of the workshop as an example; it is not necessary to use loon.
However, it is a very cool use of loon and worth getting installed.

loon.ggplot

If time permits, we will also be using the loon.ggplot package. This provides functionality (largely through a single function loon.ggplot()) that allows ggplot2 plots to be transformed into interactive loon plots and vive versa.

At the time of this writing (2020-06-09), the package is not yet on CRAN and so will need to be installed from github as follows

devtools::install_github("great-northern-diver/loon.ggplot")

Finally

Please revisit this site on the day before the workshop in case there are updates to this information. Such updates may need to be made to your machine to ensure a successful workshop session.

Good luck and have fun!