Installing Cairo for R on Ubuntu 17.04

The Cairo library is a great 2D graphics library supporting multiple output devices. I usually use it to save plots in R.

Getting Cairo work in Ubuntu environment is pretty easy, although there is a problem which shows up pretty regularly: some dependencies are not set up properly in the Cairo DEB package.

In order to get Cairo work in R, one has to install the libcairo package first:

$ apt-get install libcairo2-dev

After that, trying to install the Cairo R package:

$ R

R version 3.3.2 (2016-10-31) -- "Sincere Pumpkin Patch"
Copyright (C) 2016 The R Foundation for Statistical Computing
Platform: x86_64-pc-linux-gnu (64-bit)

R is free software and comes with ABSOLUTELY NO WARRANTY.
You are welcome to redistribute it under certain conditions.
Type 'license()' or 'licence()' for distribution details.

Natural language support but running in an English locale

R is a collaborative project with many contributors.
Type 'contributors()' for more information and
'citation()' on how to cite R or R packages in publications.

Type 'demo()' for some demos, 'help()' for on-line help, or
'help.start()' for an HTML browser interface to help.
Type 'q()' to quit R.

> install.packages('Cairo')

leads to a compilation error:

gcc -std=gnu99 -I/usr/share/R/include -DNDEBUG -I/usr/include/cairo -I/usr/include/glib-2.0 -I/usr/lib/x86_64-linux-gnu/glib-2.0/include -I/usr/include/pixman-1 -I/usr/include/freetype2 -I/usr/include/libpng16  -I. -Ii
nclude    -g -O2 -fdebug-prefix-map=/build/r-base-6WVosl/r-base-3.3.2=. -fstack-protector-strong -Wformat -Werror=format-security -Wdate-time -D_FORTIFY_SOURCE=2 -g -fpic  -g -O2 -fdebug-prefix-map=/build/r-base-6WVosl
/r-base-3.3.2=. -fstack-protector-strong -Wformat -Werror=format-security -Wdate-time -D_FORTIFY_SOURCE=2 -g  -c xlib-backend.c -o xlib-backend.o
xlib-backend.c:34:74: fatal error: X11/Intrinsic.h: No such file or directory
#include <X11/Intrinsic.h>      /*->    Xlib.h  Xutil.h Xresource.h .. */
^
compilation terminated.
/usr/lib/R/etc/Makeconf:132: recipe for target 'xlib-backend.o' failed
make: *** [xlib-backend.o] Error 1
ERROR: compilation failed for package ‘Cairo’
* removing ‘/home/gykovacs/R/x86_64-pc-linux-gnu-library/3.3/Cairo’

The downloaded source packages are in
‘/tmp/RtmpZt8OjJ/downloaded_packages’
Warning message:
In install.packages("Cairo") :
installation of package ‘Cairo’ had non-zero exit status

In order to get rid of this error, you have to install a couple of additional Ubuntu packages:

  • libgtk2.0-dev – GTK is a popular graphical toolkit
  • xvfb – provides an X server that can run on machines with no display hardware and no physical input devices.
  • xauth – a small utility to read and manipulate Xauthority files, which are used by servers and clients alike to control authentication and access to X sessions
  • xfonts-base – provides a standard set of low-resolution bitmapped fonts. In most cases it is desirable to have the X font server (xfs) and/or an X server installed to make the fonts available to X clients.
  • libxt-dev – provides the X Toolkit Intrinsics (development headers), an abstract widget library upon which other toolkits are based.

by firing

$ apt-get install libgtk2.0-dev xvfb xauth xfonts-base libxt-dev

After that, the installation of the R Cairo package should work:

$ R

R version 3.3.2 (2016-10-31) -- "Sincere Pumpkin Patch"
Copyright (C) 2016 The R Foundation for Statistical Computing
Platform: x86_64-pc-linux-gnu (64-bit)

R is free software and comes with ABSOLUTELY NO WARRANTY.
You are welcome to redistribute it under certain conditions.
Type 'license()' or 'licence()' for distribution details.

Natural language support but running in an English locale

R is a collaborative project with many contributors.
Type 'contributors()' for more information and
'citation()' on how to cite R or R packages in publications.

Type 'demo()' for some demos, 'help()' for on-line help, or
'help.start()' for an HTML browser interface to help.
Type 'q()' to quit R.

> install.packages('Cairo')
Installing package into ‘/home/gykovacs/R/x86_64-pc-linux-gnu-library/3.3’
(as ‘lib’ is unspecified)
--- Please select a CRAN mirror for use in this session ---
trying URL 'https://cran.wu.ac.at/src/contrib/Cairo_1.5-9.tar.gz'
Content type 'application/x-gzip' length 86982 bytes (84 KB)
==================================================
downloaded 84 KB

* installing *source* package ‘Cairo’ ...
** package ‘Cairo’ successfully unpacked and MD5 sums checked
checking for gcc... gcc -std=gnu99
checking whether the C compiler works... yes
checking for C compiler default output file name... a.out
checking for suffix of executables...
checking whether we are cross compiling... no
checking for suffix of object files... o
checking whether we are using the GNU C compiler... yes
checking whether gcc -std=gnu99 accepts -g... yes
checking for gcc -std=gnu99 option to accept ISO C89... none needed
checking how to run the C preprocessor... gcc -std=gnu99 -E
checking for grep that handles long lines and -e... /bin/grep
checking for egrep... /bin/grep -E
checking for ANSI C header files... yes
checking for sys/wait.h that is POSIX.1 compatible... yes
checking for sys/types.h... yes
checking for sys/stat.h... yes
checking for stdlib.h... yes
checking for string.h... yes
checking for memory.h... yes
checking for strings.h... yes
checking for inttypes.h... yes
checking for stdint.h... yes
checking for unistd.h... yes
checking for string.h... (cached) yes
checking sys/time.h usability... yes
checking sys/time.h presence... yes
checking for sys/time.h... yes
checking for unistd.h... (cached) yes
checking for an ANSI C-conforming const... yes
checking for pkg-config... /usr/bin/pkg-config
checking whether pkg-config knows about cairo... yes
checking for configurable backends... cairo cairo-ft cairo-pdf cairo-png cairo-ps cairo-xlib cairo-xlib-xrender
configure: CAIRO_CFLAGS=-I/usr/include/cairo -I/usr/include/glib-2.0 -I/usr/lib/x86_64-linux-gnu/glib-2.0/include -I/usr/include/pixman-1 -I/usr/include/freetype2 -I/usr/include/libpng16
checking if R was compiled with the RConn patch... no
checking cairo.h usability... yes
checking cairo.h presence... yes
checking for cairo.h... yes
checking for PNG support in Cairo... yes
checking for ATS font support in Cairo... no
configure: CAIRO_LIBS=-lfreetype -lz -lpng16 -lz -lcairo -lXext -lXrender -lX11
checking for library containing deflate... none required
checking whether Cairo programs can be compiled... yes
checking whether cairo_image_surface_get_format is declared... no
checking for FreeType support in cairo... yes
checking whether FreeType needs additional flags... no
checking wheter libjpeg works... yes
checking wheter libtiff works... yes
configure: creating ./config.status
config.status: creating src/Makevars
config.status: creating src/cconfig.h
** libs
gcc -std=gnu99 -I/usr/share/R/include -DNDEBUG -I/usr/include/cairo -I/usr/include/glib-2.0 -I/usr/lib/x86_64-linux-gnu/glib-2.0/include -I/usr/include/pixman-1 -I/usr/include/freetype2 -I/usr/include/libpng16  -I. -Ii
nclude    -g -O2 -fdebug-prefix-map=/build/r-base-6WVosl/r-base-3.3.2=. -fstack-protector-strong -Wformat -Werror=format-security -Wdate-time -D_FORTIFY_SOURCE=2 -g -fpic  -g -O2 -fdebug-prefix-map=/build/r-base-6WVosl
/r-base-3.3.2=. -fstack-protector-strong -Wformat -Werror=format-security -Wdate-time -D_FORTIFY_SOURCE=2 -g  -c cairobem.c -o cairobem.o
gcc -std=gnu99 -I/usr/share/R/include -DNDEBUG -I/usr/include/cairo -I/usr/include/glib-2.0 -I/usr/lib/x86_64-linux-gnu/glib-2.0/include -I/usr/include/pixman-1 -I/usr/include/freetype2 -I/usr/include/libpng16  -I. -Ii
nclude    -g -O2 -fdebug-prefix-map=/build/r-base-6WVosl/r-base-3.3.2=. -fstack-protector-strong -Wformat -Werror=format-security -Wdate-time -D_FORTIFY_SOURCE=2 -g -fpic  -g -O2 -fdebug-prefix-map=/build/r-base-6WVosl
/r-base-3.3.2=. -fstack-protector-strong -Wformat -Werror=format-security -Wdate-time -D_FORTIFY_SOURCE=2 -g  -c cairogd.c -o cairogd.o
gcc -std=gnu99 -I/usr/share/R/include -DNDEBUG -I/usr/include/cairo -I/usr/include/glib-2.0 -I/usr/lib/x86_64-linux-gnu/glib-2.0/include -I/usr/include/pixman-1 -I/usr/include/freetype2 -I/usr/include/libpng16  -I. -Ii
nclude    -g -O2 -fdebug-prefix-map=/build/r-base-6WVosl/r-base-3.3.2=. -fstack-protector-strong -Wformat -Werror=format-security -Wdate-time -D_FORTIFY_SOURCE=2 -g -fpic  -g -O2 -fdebug-prefix-map=/build/r-base-6WVosl
/r-base-3.3.2=. -fstack-protector-strong -Wformat -Werror=format-security -Wdate-time -D_FORTIFY_SOURCE=2 -g  -c cairotalk.c -o cairotalk.o
gcc -std=gnu99 -I/usr/share/R/include -DNDEBUG -I/usr/include/cairo -I/usr/include/glib-2.0 -I/usr/lib/x86_64-linux-gnu/glib-2.0/include -I/usr/include/pixman-1 -I/usr/include/freetype2 -I/usr/include/libpng16  -I. -Ii
nclude    -g -O2 -fdebug-prefix-map=/build/r-base-6WVosl/r-base-3.3.2=. -fstack-protector-strong -Wformat -Werror=format-security -Wdate-time -D_FORTIFY_SOURCE=2 -g -fpic  -g -O2 -fdebug-prefix-map=/build/r-base-6WVosl
/r-base-3.3.2=. -fstack-protector-strong -Wformat -Werror=format-security -Wdate-time -D_FORTIFY_SOURCE=2 -g  -c img-backend.c -o img-backend.o
gcc -std=gnu99 -I/usr/share/R/include -DNDEBUG -I/usr/include/cairo -I/usr/include/glib-2.0 -I/usr/lib/x86_64-linux-gnu/glib-2.0/include -I/usr/include/pixman-1 -I/usr/include/freetype2 -I/usr/include/libpng16  -I. -Ii
nclude    -g -O2 -fdebug-prefix-map=/build/r-base-6WVosl/r-base-3.3.2=. -fstack-protector-strong -Wformat -Werror=format-security -Wdate-time -D_FORTIFY_SOURCE=2 -g -fpic  -g -O2 -fdebug-prefix-map=/build/r-base-6WVosl
/r-base-3.3.2=. -fstack-protector-strong -Wformat -Werror=format-security -Wdate-time -D_FORTIFY_SOURCE=2 -g  -c img-jpeg.c -o img-jpeg.o
gcc -std=gnu99 -I/usr/share/R/include -DNDEBUG -I/usr/include/cairo -I/usr/include/glib-2.0 -I/usr/lib/x86_64-linux-gnu/glib-2.0/include -I/usr/include/pixman-1 -I/usr/include/freetype2 -I/usr/include/libpng16  -I. -Ii
nclude    -g -O2 -fdebug-prefix-map=/build/r-base-6WVosl/r-base-3.3.2=. -fstack-protector-strong -Wformat -Werror=format-security -Wdate-time -D_FORTIFY_SOURCE=2 -g -fpic  -g -O2 -fdebug-prefix-map=/build/r-base-6WVosl
/r-base-3.3.2=. -fstack-protector-strong -Wformat -Werror=format-security -Wdate-time -D_FORTIFY_SOURCE=2 -g  -c img-tiff.c -o img-tiff.o
gcc -std=gnu99 -I/usr/share/R/include -DNDEBUG -I/usr/include/cairo -I/usr/include/glib-2.0 -I/usr/lib/x86_64-linux-gnu/glib-2.0/include -I/usr/include/pixman-1 -I/usr/include/freetype2 -I/usr/include/libpng16  -I. -Ii
nclude    -g -O2 -fdebug-prefix-map=/build/r-base-6WVosl/r-base-3.3.2=. -fstack-protector-strong -Wformat -Werror=format-security -Wdate-time -D_FORTIFY_SOURCE=2 -g -fpic  -g -O2 -fdebug-prefix-map=/build/r-base-6WVosl
/r-base-3.3.2=. -fstack-protector-strong -Wformat -Werror=format-security -Wdate-time -D_FORTIFY_SOURCE=2 -g  -c pdf-backend.c -o pdf-backend.o
gcc -std=gnu99 -I/usr/share/R/include -DNDEBUG -I/usr/include/cairo -I/usr/include/glib-2.0 -I/usr/lib/x86_64-linux-gnu/glib-2.0/include -I/usr/include/pixman-1 -I/usr/include/freetype2 -I/usr/include/libpng16  -I. -Ii
nclude    -g -O2 -fdebug-prefix-map=/build/r-base-6WVosl/r-base-3.3.2=. -fstack-protector-strong -Wformat -Werror=format-security -Wdate-time -D_FORTIFY_SOURCE=2 -g -fpic  -g -O2 -fdebug-prefix-map=/build/r-base-6WVosl
/r-base-3.3.2=. -fstack-protector-strong -Wformat -Werror=format-security -Wdate-time -D_FORTIFY_SOURCE=2 -g  -c ps-backend.c -o ps-backend.o
gcc -std=gnu99 -I/usr/share/R/include -DNDEBUG -I/usr/include/cairo -I/usr/include/glib-2.0 -I/usr/lib/x86_64-linux-gnu/glib-2.0/include -I/usr/include/pixman-1 -I/usr/include/freetype2 -I/usr/include/libpng16  -I. -Ii
nclude    -g -O2 -fdebug-prefix-map=/build/r-base-6WVosl/r-base-3.3.2=. -fstack-protector-strong -Wformat -Werror=format-security -Wdate-time -D_FORTIFY_SOURCE=2 -g -fpic  -g -O2 -fdebug-prefix-map=/build/r-base-6WVosl
/r-base-3.3.2=. -fstack-protector-strong -Wformat -Werror=format-security -Wdate-time -D_FORTIFY_SOURCE=2 -g  -c svg-backend.c -o svg-backend.o
gcc -std=gnu99 -I/usr/share/R/include -DNDEBUG -I/usr/include/cairo -I/usr/include/glib-2.0 -I/usr/lib/x86_64-linux-gnu/glib-2.0/include -I/usr/include/pixman-1 -I/usr/include/freetype2 -I/usr/include/libpng16  -I. -Ii
nclude    -g -O2 -fdebug-prefix-map=/build/r-base-6WVosl/r-base-3.3.2=. -fstack-protector-strong -Wformat -Werror=format-security -Wdate-time -D_FORTIFY_SOURCE=2 -g -fpic  -g -O2 -fdebug-prefix-map=/build/r-base-6WVosl
/r-base-3.3.2=. -fstack-protector-strong -Wformat -Werror=format-security -Wdate-time -D_FORTIFY_SOURCE=2 -g  -c w32-backend.c -o w32-backend.o
gcc -std=gnu99 -I/usr/share/R/include -DNDEBUG -I/usr/include/cairo -I/usr/include/glib-2.0 -I/usr/lib/x86_64-linux-gnu/glib-2.0/include -I/usr/include/pixman-1 -I/usr/include/freetype2 -I/usr/include/libpng16  -I. -Ii
nclude    -g -O2 -fdebug-prefix-map=/build/r-base-6WVosl/r-base-3.3.2=. -fstack-protector-strong -Wformat -Werror=format-security -Wdate-time -D_FORTIFY_SOURCE=2 -g -fpic  -g -O2 -fdebug-prefix-map=/build/r-base-6WVosl
/r-base-3.3.2=. -fstack-protector-strong -Wformat -Werror=format-security -Wdate-time -D_FORTIFY_SOURCE=2 -g  -c xlib-backend.c -o xlib-backend.o
gcc -std=gnu99 -shared -L/usr/lib/R/lib -Wl,-Bsymbolic-functions -Wl,-z,relro -o Cairo.so cairobem.o cairogd.o cairotalk.o img-backend.o img-jpeg.o img-tiff.o pdf-backend.o ps-backend.o svg-backend.o w32-backend.o xlib
-backend.o -lfreetype -lz -lpng16 -lz -lcairo -lXext -lXrender -lX11 -ljpeg -ltiff -L/usr/lib/R/lib -lR
installing to /home/gykovacs/R/x86_64-pc-linux-gnu-library/3.3/Cairo/libs
** R
** preparing package for lazy loading
** help
*** installing help indices
** building package indices
** testing if installed package can be loaded
* DONE (Cairo)

The downloaded source packages are in
‘/tmp/RtmpMkK8NN/downloaded_packages’

Having a successfully installed Cairo library, one can

  • import it into an R session or in a script by 
    library('Cairo')
  • open a plotting device, like PS: 
    cairo_ps(filename='dummy.ps", width=4, height=8)
  • create a plot object, for example using ggplot2: 
    p <- ggplot(data, aes(x=x, y=y))
  • print the plot on the device: 
    print(p)
  • and finally, close the device: 
    def.off()

To read more on Cairo devices, check out the official documentation: https://cran.r-project.org/web/packages/Cairo/Cairo.pdf.

Building a simple and flexible academic-like website in 6 easy steps

Introduction

A couple of days ago I have realized that my presence on the Internet is very limited. In order to improve my visibility, I decided to build a website where my CV, list of publications and some code for download are available. As an enthusiast of open source and scripting, I was sure that I won’t use the browser-based website builders, like wix.com. Instead, I try to discover the world of open source static generators, which seem to be the handiest for me.

The result can be visited at gykovacs.github.io. In the rest of this post, I describe how to create, customize and deploy a similar website in 6 simple steps.

Choosing the right technology

I found a wide variety of static generators that can be used for building simple but fancy websites by scripting. One can find a great comparison of available technologies here: link.

The features I was looking for:

  • fancy themes – What I really want is a clean but good looking, eye-candy website;
  • publications – one of the main purpose of creating the website is to make my work available on the Internet. Consequently, I want a simple way to generate and update the list of publications, preferably based on my already existing BibTex file;
  • free – I want the technology and the hosting be totally free.

After doing a deep dive into the world of technologies, I decided to try hugo.io, because I really liked the academic theme (https://github.com/gcushen/hugo-academic/), it seemed to be quite popular, simple and available for Windows and Linux, as well. However, it turned out soon that there are no built-in features neither plugins enabling the handling of publications.

Finally, I decided to turn to Jekyll, because the plugin called jekyll-scholar provides a genuine way to handle publications.

Step 1: Install Jekyll

Installing Jekyll is pretty simple in Linux environments as it is part of the repositories of popular distributions. For example, in Ubuntu and its variants:

$ [sudo] apt-get install jekyll

Step 2: Download the dummy code of a likable theme

As Jekyll is pretty popular, there are many websites collecting fancy themes for it, check out them and choose the most likable one:

My personal taste was totally satisfied by the pretty simple Hyde theme, which can be downloaded or cloned from https://github.com/poole/hyde. Create a folder to store your website related stuff and clone the Hyde repository into it. For example

$ mkdir webpage
$ cd webpage
$ git clone https://github.com/poole/hyde.git
$ cd hyde

You can test if it works on your local machine by issuing

$ jekyll serve

in the directory and checking the website served at port 4000 of your localhost by typing http://127.0.0.1:4000// into the browser.

At this point, you have a fancy Jekyll theme working.

Step 3: Customize the content of the pages

The most important file in the downloaded code is _config.yml, this is where the main configurational properties of the page are stored. In the case of the Hyde theme, I kept the default settings for the technical attributes and changed the descriptors title, tagline, description, url, author, and repo. My _config.yml looks like:

# Dependencies
markdown: redcarpet
highlighter: pygments

# Permalinks
permalink: pretty
relative_permalinks: false

# Setup
title: 'Gyorgy Kovacs'
tagline: 'Gyorgy Kovacs'
description: 'PhD in Informatics'
url: https://gykovacs.github.io
baseurl: /

author:
    name: 'Gyorgy Kovacs'
    url: https://gykovacs.github.io

paginate: 5

# Custom vars
version: 2.1.0

github:
repo: https://github.com/gykovacs

Maybe some of the fields like description do not have the right content, but on the sidebar of the theme, the right thing got to the right position.

Customize the website according to your personal taste. Feel free to open the existing pages and rewrite/customize their content. You can add any further page in the root of the directory with the extensions .html or .md and the page will be automatedly included in the menu of the sidebar. Both the .html and .md files can contain HTML or Markdown language code. The latter one gives a really easy way to develop the content. The only thing you should be careful that all .md Markdown pages should begin by specifying the layout and the title of the page, like

---
layout: page
title: Professional experience
---

A side remark on blogging

One of the main features of Jekyll is blogging. You can write posts in Markdown, copy them into the right folder and the blog post appears. What is more fascinating is that GitHub supports Jekyll, so, you can host your website in a GitHub repository and all you have to do to write a blog post is to update your repository, GitHub executes Jekyll and the post appears. On the contrary of these fancy features, for some reasons I decided to move my blogging activity to one of the web-based services:

  • On the one hand, Jekyll is not available for Windows (yes, I use Windows sometimes). This is the less important issue, as you have git on Windows/Linux/Mac, so you can still update your repository in the same way from any environments.
  • The other, more important point is that GitHub does not support the use of Jekyll plugins like jekyll-scholar, thus generating the website on GitHub would divest from the most important feature: the automated generation and updating of the publication list. You can still generate your website locally and host only the generated pages on GitHub, however, as I mentioned earlier, it wouldn’t work on Windows.

Taking into account all of these, I decided to do the blogging on WordPress.com, and link that blog to the one automatically generated by Jekyll. In order to achieve this, I had to change the sidebar.html file in the _includes directory:

<div class="sidebar">
<div class="container sidebar-sticky">
<div class="sidebar-about">
<h1>{{ site.title }}</h1>
{{ site.description }}</div>
<nav class="sidebar-nav">
			{% comment %}
				The code below dynamically generates a sidebar nav of pages with `layout: page` in the front-matter. See readme for usage.
			{% endcomment %}{% assign pages_list = site.pages %}
			{% for node in pages_list %}
				{% if node.title != null %}
					{% if node.layout == "page" %}
						<a class="sidebar-nav-item{% if page.url == node.url %} active{% endif %}" href="{{ node.url }}">{{ node.title }}</a>
					{% endif %}
				{% endif %}
			{% endfor %}
			<a class="sidebar-nav-item" href="https://drive.google.com/open?id=0B3E8L0dtBKcsWUNXalNQYTJuc3c">Download detailed CV in PDF</a>
			<a class="sidebar-nav-item" href="gykovacsblog.wordpress.com">Blog</a>
			<span class="sidebar-nav-item">Jekyll Hyde, Currently v{{ site.version }}</span>
</nav>

© {{ site.time | date: '%Y' }}. All rights reserved.</div>
</div>

Step 4: Generating a fancy publication list

In order to get a fancy publication list from your BibTex file, you need to get jekyll-scholar, so go to https://github.com/inukshuk/jekyll-scholar and clone it using git, or alternatively download it as a package. Before cloning the repository, don’t forget to change your working directory to from hyde to its parent we called webpage. Then call

$ git clone https://github.com/inukshuk/jekyll-scholar.git

Navigate into the cloned directory and fire:

$ cd jekyll-scholar
$ [sudo] gem install jekyll-scholar

First I got some build errors as I didn’t have the ruby sources installed on my Ubuntu, this can be resolved by

$ [sudo] apt-get install ruby-dev

Go back to the directory of the dummy website (in our case hyde), and create a new directory called _plugins. In order to get jekyll-scholar work, create a file in the _plugins directory called ext.rb with the following content.

$ mkdir _plugins
$ echo "require 'jekyll/scholar'" >> _plugins/ext.rb

You also need to update the _config.yml file to set some basic properties of jekyll-scholar. I have added the following lines

scholar:
    style: apa
    bibliography: refs.bib
    replace_strings: true
    query: "@*"

which reads as:

  • the style of publications is “apa”, which is one of the most basic styles available in BibTex,
  • the bibliography is available in a file called refs.bib,
  • queries can be made by the special character sequence “@*”.

Create another directory called _bibliography and copy your .bib BibTex file there. My BibTex entries have some custom fields and look like:

@article{j006,
    author="Gy. Kov\'acs and A. Hajdu",
    title="A Self-Calibrating Approach for the Segmentation of Retinal Vessels by Template Matching and Contour Reconstruction",
    journal="Medical Image Analysis",
    volume="29(4)",
    pages="24--46",
    year="2016",
    note="(IF=4.565)",
    doi={10.1016/j.media.2015.12.003},
    group="journal",
    preprint = {https://drive.google.com/open?id=0B3E8L0dtBKcsUUtSRWloVFpCRlE},
    link = {http://www.medicalimageanalysisjournal.com/article/S1361-8415(15)00184-X/fulltext?cc=y=},
    code = {http://gykovacs.github.io}
}

The custom fields are

  • group, which makes the querying of publications easier,
  • preprint, which is a link to the preprint version of the document at my Google Drive,
  • link, containing a link to the publisher’s website and
  • code, containing a link to corresponding codes on the web.

Finally, create a new Markdown file in the root of your website, called publications.md with a content like

---
layout: page
title: List of publications
---

## Journal Papers

{% bibliography --query @*[group=journal] %}

The page will automatically be included in the menu of the website on the name “List of publications” and will contain all the entries having group = "journal" in the BibTex file. Use simply

{% bibliography %}

to print the entire bibliography. Now, building the page or simply calling

$ jekyll serve

in the root of the website will add a new page called “List of publications” to the sidebar with the references generated from the .bib BibTex file.

Step 5: Customize the bibliography

A simple list of publications is cool. However, I have found some really fancy solutions using Jekyll and jekyll-scholar, and I tried to create my own variant of that. My customization was highly influenced by the great works of:

In order to customize the look of the bibliography, you need to create a template file which describes how to visualize the entries of your publication list. To be exact, the file describes what to visualize after the line is rendered according to the BibTex style specified in the _config.yml (in our case “apa”). Let us call this template file bibtemplate.html and create it in the _layouts directory of your website’s root. In my case the content of the file is:

---
---
<div class="text-justify">{{reference}}</div>
<button class="button0"  onclick="toggleBibtex{{entry.key}}()">Bibtex</button>

{% if entry.doi %}
	<a href="{{ entry.doi | prepend: 'http://doi.org/' }}"><input class="button1" type="button" value="doi" /></a>
{% endif %}

{% if entry.preprint %}
	<a href="{{ entry.preprint }}"><input class="button2" type="button" value="preprint" /></a>
{% endif %}

{% if entry.link %}
	<a href="{{ entry.link }}"><input class="button4" type="button" value="link" /></a>
{% endif %}

{% if entry.code %}
	<a href="{{ entry.code }}"><input class="button3" type="button" value="code" /></a>
{% endif %}
<div id="a{{entry.key}}" style="display: none;">
<pre>{{entry.bibtex}}</pre>
</div>
<script>
function toggleBibtex{{entry.key}}(parameter) {
    var x= document.getElementById('a{{entry.key}}');
    if (x.style.display === 'none') {
        x.style.display = 'block';
    } else {
        x.style.display = 'none';
    }
}
</script>

This can be interpreted as follows:

  • I have implemented a hidable paragraph for the entire BibTex entry, as it is pretty useful to have these entries available if someone wants to cite your work properly. The hidden paragraph is implemented in the second div environment of the code, the id of the div comes from the key of the BibTex entry to make it referrable and the content of the div is the BibTex entry itself as a preformatted text. By default the div is hidden by setting the style attribute "display:none". The JavaScript code in the script environment is a function which changes the hidden status of the entry to visible. The name of the function contains the key of the BibTex entry to make it well-defined. The first visible object after the rendered BibTex entry will be a CSS button created in the button environment, stilized by the class button0 and the onclick-handler function is added, as well.
  • The rest of the file contains the code of the other objects, which is pretty similar: if any of the preprint, doi, link or code custom fields of the BibTex entry is populated, the corresponding link is rendered.

In order to make this template work, two more things are left to do. On the one hand, one has to specify in the _config.yml file that a bibliography_template has been implemented. This can be done by adding a further line with the name of the file:

scholar:
    style: apa
    bibliography: refs.bib
    bibliography_template: bibtemplate
    replace_strings: true
    query: "@*"

The last thing to do is to specify the look of the objects we defined in the file bibtemplate.html by adding the proper CSS entries to one of the .css files in the public/css directory. I have added entries to syntax.css like

.button0 {
    background-color: #4CAF50;
    border: none;
    color: white;
    padding: 4px 8px;
    text-align: center;
    text-decoration: none;
    display: inline-block;
    font-size: 10px;
    font-weight: bold;
    margin: 2px 1px;
    cursor: pointer;
    border-radius: 5px;
}

for the button0, button1, button2, button3 and button4 styles, differing in the background-color attribute only. Once you are ready with all of these, you can check your fancy publication list by issuing

$ jekyll serve

in the root of your website source and checking the result in your browser.

One more thing to customize is the structure of the entries in the list of publications. Initially, we used the “apa” style (specified in the _config.yml file), which refers to the style of the journal of the American Psychological Association. This is a widely used style, however, one may want to customize it to some extent. For example, this style does not add the content of the note field of bibentries to the list of publications.

Generally, one has two options: on the one hand, one can discover the hundreds of styles available at http://editor.citationstyles.org/about/. Download the .csl definition of the style, copy it into, say, the _layout directory and modify the _config.yml file by changing the string “apa” to the name of the file downloaded. The other option is to create your own style, or modify one of the existing files according to your taste. The citation styles page has a very handy editor to modify existing or create new citation styles.

Step 6: Deploy the website on GitHub

Jekyll generates the real website into the directory _site. You can copy the contents of this directory to any webhosting service and your website becomes visible. I decided to use GitHub to host my website. However, as mentioned before, the jekyll-scholar plugin does not work on GitHub, so you can’t simply upload the entire code and wait for GitHub to build your page, because it won’t work. The only workaround is to deploy the generated website to GitHub. First, create a directory with the username of your GitHub account and the .github.io postfix:

$ mkdir username.github.io

Navigate to the directory and initialize a new git repository by

$ cd username.github.io
$ git init

Now move the contents of the generated _site Jekyll directory to this new git repository:

$ cp -R ../hyde/_site/* .

Then, add everything to the repository, commit and push the files to your GitHub repository:

$ git add --all
$ git commit -m "First version"
$ git push

If everything worked fine, your website will be available on the URL http://username.github.io in a couple of minutes.

+1: Setting up Google Analytics

Google Analytics is a great tool to track the popularity of your website. In order to set up Google Analytics working, one has to register an account and register the URL of your website. Then, Google Analytics provides a JavaScript snippet (in red frame) that has to be embedded into all your websites properly. This snippet contains your unique tracking code.

analytics

In order to add this code snippet to all your pages, create a new file called analytics.html in your _layouts directory, and put the script into it. Then, add the following lines just before the closing body tag of your default.html file in the _layouts directory:

{% if jekyll.environment == 'production' %}
{% include analytics.html %}
{% endif %}

These lines ensure that the analytics code will be included only in production environment. If you use GitHub to generate your website, it will set the JEKYLL_ENV environment variable properly and the analytics code will be embedded. If you copy only the generated website to GitHub, make sure that you run the jekyll build or jekyll serve commands with the JEKYLL_ENV set to production. For example:

$ JEKYLL_ENV=production jekyll build

You can check the embedding by loading your website and inspecting the source code in a browser. It should contain the analytics script right before the closing body tag. If the script is present in the source of the website, you can start monitoring the user activity by looking at the wide variety of statistics available at Google Analytics.

Summary

If you have any remarks regarding the previous tutorial, just leave a comment or contact me at gyuriofkovacs@gmail.com.

The source code of my entire website is available for download at https://github.com/gykovacs/gykovacs.website

Why?

The reason why I start this blog is that I always run into technical issues in my daily work using Ubuntu, Latex, Python, etc. and I decided to document the results in a way which may be useful for mankind, at least very very slightly.