---
title: "RIdeogram: drawing SVG graphics to visualize and map genome-wide data in idiograms"
author: "Zhaodong Hao"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{RIdeogram Usage}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

## Introduction

RIdeogram is a R package to draw SVG (Scalable Vector Graphics) graphics to visualize and map genome-wide data in idiograms. 

## Citation

If you use this package in a published paper, please cite this paper:

Zhaodong Hao, Dekang Lv, Ying Ge, Jisen Shi, Guangchuang Yu, and Jinhui Chen (2018). RIdeogram: Drawing SVG graphics to visualize and map genome-wide data in idiograms. R package version 0.1.0.

## Usage and Examples

This is a simple package with only two functions `ideogram` and `convertSVG`.

First, you need to load the package after you installed it.

```{r}
require(RIdeogram)
```

Then, you need to load the data from the RIdeogram package.

```{r}
data(human_karyotype, package="RIdeogram")
data(gene_density, package="RIdeogram")
data(Random_RNAs_500, package="RIdeogram")
```

You can use the function "head()" to see the data format.

```{r}
head(human_karyotype)
```

Specifically, the 'karyotype' file contains the karyotype information and has five columns (or three, see below). The first column is Chromosome ID, the second and thrid columns are start and end positions of corresponding chromosomes and the fourth and fifth columns are start and end positions of corresponding centromeres.

```{r}
head(gene_density)
```

The 'mydata' file contains the heatmap information and has four columns. The first column is Chromosome ID, the second and thrid columns are start and end positions of windows in corresponding chromosomes and the fourth column is a characteristic value in corresponding windows, such as gene number.

```{r}
head(Random_RNAs_500)
```

The 'mydata_interval' file contains the label information and has six columns. The first column is the label type, the second column is the shape of label with three available options of box, triangle and circle, the third column is Chromosome ID, the fourth and fifth columns are the start and end positions of corresponding labels in the chromosomes and the sixth column is the color of the label.

Or, you can also load your own data by using the function "read.table", such as

```r
human_karyotype <- read.table("karyotype.txt", sep = "\t", header = T, stringsAsFactors = F)
gene_density <- read.table("data_1.txt", sep = "\t", header = T, stringsAsFactors = F)
Random_RNAs_500 <- read.table("data_2.txt", sep = "\t", header = T, stringsAsFactors = F)
```

The "karyotype.txt" file contains karyotype information; the "data_1.txt" file contains heatmap data; the "data_2.txt" contains track label data.

These three files are all you need, now you can visualize these information using the `ideogram` function.

Basic usage

```r
ideogram(karyotype, overlaid = NULL, label = NULL, colorset1, colorset2, width, Lx, Ly, output = "chromosome.svg")
convertSVG(svg, device, width, height, dpi)
```

Now, let's begin.

First, we draw a idiogram with no mapping data.

```r
ideogram(karyotype = human_karyotype)
convertSVG("chromosome.svg", device = "png")
```

Then, you will find a SVG file and a PNG file in your Working Directory.

<img src="figures/example1.png" width="100%" />

Next, we can map genome-wide data on the chromosome idiogram. In this case, we visulize the gene density across the human genome.

```r
ideogram(karyotype = human_karyotype, overlaid = gene_density)
convertSVG("chromosome.svg", device = "png")
```

<img src="figures/example2.png" width="100%" />

Alternatively, we can map some genome-wide data with track labels next to the chromosome idiograms.

```r
ideogram(karyotype = human_karyotype, label = Random_RNAs_500)
convertSVG("chromosome.svg", device = "png")
```

<img src="figures/example3.png" width="100%" />

We can also map the overlaid heatmap and track labels on the chromosome idiograms at the same time.

```r
ideogram(karyotype = human_karyotype, overlaid = gene_density, label = Random_RNAs_500)
convertSVG("chromosome.svg", device = "png")
```

<img src="figures/example4.png" width="100%" />

If you want to change the color of heatmap, you can modify the argument 'colorset1' (default set is colorset1 = c("#4575b4", "#ffffbf", "#d73027")). You can use either color names as listed by `colors()` or hexadecimal strings of the form "#rrggbb" or "#rrggbbaa".

```r
ideogram(karyotype = human_karyotype, overlaid = gene_density, label = Random_RNAs_500, colorset1 = c("#fc8d59", "#ffffbf", "#91bfdb"))
convertSVG("chromosome.svg", device = "png")
```

<img src="figures/example5.png" width="100%" />

If you don not know the centromere information in your species, you don not need to modify the script. In this case, the 'karyotype' file has only three columns.

To simulate this case, we deleted the last two columns of the 'human_karyotype' file.

```r
human_karyotype <- human_karyotype[,1:3]
ideogram(karyotype = human_karyotype, overlaid = gene_density, label = Random_RNAs_500)
convertSVG("chromosome.svg", device = "png")
```

<img src="figures/example6.png" width="100%" />

If there are only ten chromosomes in your species, maybe you need to motify the argument 'width' (default value is "170").

To simulate this case, we only keep the first ten columns of the 'human_karyotype' file.

Before
```r
human_karyotype <- human_karyotype[1:10,]
ideogram(karyotype = human_karyotype, overlaid = gene_density, label = Random_RNAs_500)
convertSVG("chromosome.svg", device = "png")
```

<img src="figures/example7.png" width="100%" />

After
```r
human_karyotype <- human_karyotype[1:10,]
ideogram(karyotype = human_karyotype, overlaid = gene_density, label = Random_RNAs_500, width = 100)
convertSVG("chromosome.svg", device = "png")
```

<img src="figures/example8.png" width="100%" />

If you want to move the Legend, then you need to modify the arguments 'Lx' and 'Ly'(default values are "160" and "35", separately).

'Lx' means the distance between upper-left point of the Legend and the left margin; 'Ly' means the distance between upper-left point of the Legend and the upper margin.

```r
ideogram(karyotype = human_karyotype, overlaid = gene_density, label = Random_RNAs_500, width = 100, Lx = 80, Ly = 25)
convertSVG("chromosome.svg", device = "png")
```

<img src="figures/example9.png" width="100%" />

If you have two sets of heatmap data, such as gene density and LTR density, you can use the following scripts to map and visualize these data in idiograms.

```
data(human_karyotype, package="RIdeogram") #reload the karyotype data
ideogram(karyotype = human_karyotype, overlaid = gene_density, label = LTR_density, colorset1 = c("#f7f7f7", "#e34a33"), colorset2 = c("#f7f7f7", "#2c7fb8")) #use the arguments 'colorset1' and 'colorset2' to set the colors for gene and LTR heatmaps, separately.
convertSVG("chromosome.svg", device = "png")
```

<img src="figures/example10.png" width="100%" />

In addition, you can use the argument "device" (default value is "png")to set the format of output file, such as, "tiff", "pdf", "jpg", etc. And, you can use the argument "dpi" (default value is "300") to set the resolution of the output image file.

```r
convertSVG("chromosome.svg", device = "tiff", dpi = 600)
```

Also, there are four shortcuts to convert the SVG images to these optional image formats with no necessary to set the argument "device", such as
```
svg2tiff("chromosome.svg")
svg2pdf("chromosome.svg")
svg2jpg("chromosome.svg")
svg2png("chromosome.svg")
```
