---
title: "An Introduction to emojifont package"
author: 
- name: Guangchuang Yu
  email: guangchuangyu@gmail.com
  affiliation: Department of Bioinformatics, School of Basic Medical Sciences, Southern Medical University
date: "`r Sys.Date()`"
output:
  prettydoc::html_pretty:
    toc: true
    theme: cayman
    highlight: github
  pdf_document:
    toc: true
vignette: >
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteIndexEntry{emojifont introduction}
  %\VignetteDepends{ggplot2}
  %\VignetteDepends{colorspace}
  %\usepackage[utf8]{inputenc}
---

```{r style, echo=FALSE, results="asis", message=FALSE}
knitr::opts_chunk$set(tidy = FALSE,
		   message = FALSE)
```


```{r echo=FALSE, results="hide", message=FALSE}
library("ggplot2")
library("emojifont")
library("colorspace")
```

# emojifont: using emoji font in `R`


The `emojifont` package is designed to bring `emoji` font to R users and is created for users that are impatient and relutant to learn.

The package is very simple, pack some emoji fonts (currently only [EmojiOne.ttf](https://github.com/eosrei/emojione-color-font)) and use [showtext](https://github.com/yixuan/showtext) to render the fonts, then we can use the font in either base plot or ggplot2.

## Installation

Get the released version from CRAN:

```r
install.packages("emojifont")
```

Or the development version from github:

```r
## install.packages("devtools")
devtools::install_github("GuangchuangYu/emojifont")
```

# Emoji characters

To use `emoji`, we need to use their corresponding unicode. Emoji unicode can be found in [http://apps.timwhitlock.info/emoji/tables/unicode](http://apps.timwhitlock.info/emoji/tables/unicode), or searched using `search_emoji` function. The `search_emoji` function will return [emoji aliases](http://www.emoji-cheat-sheet.com/) which can be converted to unicode by `emoji` function.

```{r}
library(emojifont)

search_emoji('smile')
emoji(search_emoji('smile'))
```


# Emoji in R plot

<!--

To support using emoji in R plot, we need to load `emoji` font and then use `family` parameter to specify using the font.

## load Emoji font
#```{r}
## list available emoji fonts
list.emojifonts()

## load selected emoji font
load.emojifont('EmojiOne.ttf')
#```
-->


## base plot

```{r fig.showtext=TRUE}
set.seed(123)
x <- rnorm(10)
set.seed(321)
y <- rnorm(10)
plot(x, y, cex=0)
text(x, y, labels=emoji('cow'), cex=1.5, col='steelblue', family='EmojiOne')
```


## ggplot2

```{r fig.showtext=TRUE}
d <- data.frame(x=x, y=y,
     label = sample(c(emoji('cow'), emoji('camel')), 10, replace=TRUE),
     type = sample(LETTERS[1:3], 10, replace=TRUE))

library("ggplot2")
ggplot(d, aes(x, y, color=type, label=label)) +
    geom_text(family="EmojiOne", size=6)
```

To make it easy to used with `ggplot2`, I implemented a very simple
layer, `geom_emoji`, to visualize `emoji` with `ggplot2`.

```{r fig.showtext=TRUE}
ggplot() + geom_emoji("rose", color='steelblue') + theme_void()
x = seq(0, 2*pi, length=30)
y = sin(x)
ggplot() + geom_emoji('heartbeat', x=x, y=y, size=10)
```


# Font Awesome

The `emojifont` package was initially designed for using emoji font. I found that [FontAwesome](http://fontawesome.io/cheatsheet/) is quite interesting especially in technical world.


The usage is quite similar as using emoji.

```{r fig.showtext=TRUE}
set.seed(2016-03-09)
fa <- fontawesome(c('fa-github', 'fa-weibo', 'fa-twitter', 'fa-android', 'fa-coffee'))
d <- data.frame(x=rnorm(20),
                y=rnorm(20),
     	        label=sample(fa, 20, replace=T))

ggplot(d, aes(x, y, color=label, label=label)) +
    geom_text(family='fontawesome-webfont', size=6)+
    xlab(NULL)+ylab(NULL) +
    theme(legend.text=element_text(family='fontawesome-webfont'))
```

To make it easy to used with `ggplot2`, a corresponding
`geom_fontawesome` is also provided.

```{r fig.showtext=TRUE}
ggplot() + geom_fontawesome("fa-github", color='black') + theme_void()
```


# phylomoji


Creating phylomoji is possible using `emojifont` and `ggtree`, please
refer to the [Phylomoji](https://yulab-smu.top/treedata-book/chapter8.html#phylomoji) session in the [treedata book](https://yulab-smu.top/treedata-book/).


# Limitation

`RStudio` using a different way to open graphics device and `showtext` is currently incompatible with it.

Since `emojifont` use `showtext` as backend to parse emoji font, it also incompatible with `RStudio`.

The solution is to manually open a window by calling `X11()` in Linux, `quartz()` in Mac or `windows()` in Windows, and create plots on top of that, instead of the built-in device offered by `RStudio`.


# Note

Currently, this package support Emoji Font and Font Awesome.

+ `EmojiOne.ttf` is downloaded from <https://github.com/eosrei/emojione-color-font>
+ `OpenSansEmoji.ttf` is downloaded from <https://github.com/MorbZ/OpenSansEmoji>
+ `fontawesome-webfont.ttf` is downloaded from <https://github.com/FortAwesome/Font-Awesome>.

Feel free to fork this package to add your favorite iconic fonts.

# Bugs/Feature requests

If you have any, [let me know](https://github.com/GuangchuangYu/emojifont/issues). Thx!

# Session info

Here is the output of `sessionInfo()` on the system on which this document was compiled:
```{r echo=FALSE}
sessionInfo()
```