-
Notifications
You must be signed in to change notification settings - Fork 1
/
README.Rmd
194 lines (126 loc) · 6.97 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
---
output:
github_document:
html_preview: false
---
```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE, fig.width = 9, fig.height = 10)
```
# mitovizR
[![Project Status: WIP – Initial development is in progress, but there has not yet been a stable, usable release suitable for the public.](https://www.repostatus.org/badges/latest/wip.svg)](https://www.repostatus.org/#wip) [![Build Status](https://travis-ci.com/robertopreste/mitovizR.svg?branch=master)](https://travis-ci.com/robertopreste/mitovizR) [![codecov](https://codecov.io/gh/robertopreste/mitovizR/branch/master/graph/badge.svg)](https://codecov.io/gh/robertopreste/mitovizR)
Plot variants on the human mitochondrial genome. Currently supports plotting variants contained in dataframes, VCF or JSON files.
___
## Overview
mitovizR is a simple R package to plot human mitochondrial variants on a graphical representation of the human mitochondrial genome. It currently supports plotting variants stored in a dataframe or a VCF or JSON file, although other options are being developed (if you want to contribute, you're welcome!).
### Features
* Plot variants from a dataframe
* Plot variants from a VCF file
- with a single sample
- with multiple samples (multiple facets will be produced in the same plot)
- showing Heteroplasmic Fraction of each variant
* Plot variants from a JSON file
- from a list of variants
- from a list with a dictionary for each variant
___
## Installation
mitovizR can be installed in R from GitHub using `devtools`:
```{r, eval=FALSE}
devtools::install_github("robertopreste/mitovizR")
```
It is suggested to also build the package vignette when installing `mitovizR`, where all the functionalities are better explained:
```{r, eval=FALSE}
devtools::install_github("robertopreste/mitovizR", build_vignettes = TRUE)
```
Official installation from CRAN/Bioconductor coming soon!
## Usage
First of all, load the `mitovizR` package:
```{r, eval=FALSE}
library(mitovizR)
```
The `mitovizR` package offers three main functions to plot variants from three different sources:
```{r, eval=FALSE}
plot_df() # to plot variants from a dataframe
plot_vcf() # to plot variants from a VCF file
plot_json() # to plot variants from a JSON file
```
Further details about their usage and options may be found in the package vignette, which can be built using `devtools::install_github("robertopreste/mitovizR", build_vignettes = TRUE)`.
**Under construction!**
### Plot variants from a dataframe
The simplest example is when you already have a dataframe with a set of mitochondrial variants.
```{r, echo=FALSE}
load("tests/testthat/sample_df.RData")
knitr::kable(sample_df)
```
In this case, a call to `plot_df()` will plot all mitochondrial variants.
```{r, eval=FALSE}
plot_df(sample_df)
```
![](man/figures/mitoviz_plot_df.png)
It is possible to show a label on each variant with its position, reference and alternate allele, using the `show_var_labels` option. In this case, by default the `plot_df()` function will look for columns named `POS`, `REF` and `ALT`, containing respectively variant positions, reference alleles and alternate alleles; you can specify different column names using respectively the `pos_col`, `ref_col` and `alt_col` options.
```{r, eval=FALSE}
plot_df(sample_df, show_var_labels = TRUE)
# specify the variant positions, reference and alternate alleles column names
plot_df(sample_df, show_var_labels = TRUE,
pos_col = "POS", ref_col = "REF", alt_col = "ALT")
```
![](man/figures/mitoviz_plot_df_labels.png)
Variants are shown according to their heteroplasmic fraction (HF), plotting variants with HF = 1.0 on the outer border of the mitochondrial circle, those with HF = 0.0 on the inner border and all the others according to their actual HF value. This is done automatically if a column with heteroplasmic fraction values is present (by default `HF`, if not set differently using the `hf_col` option); otherwise, variants will simply be shown in the middle of the circular plot (as if they all had HF = 0.5).
`plot_df()` deal with a dataframe with multiple samples easily, creating a separate plot for each sample listed in the `SAMPLE` column (this default can be changed using the `sample_col` option).
```{r, eval=FALSE}
plot_df(sample_multi_df)
# specify the sample column name
plot_df(sample_multi_df, sample_col = "sample_column")
```
![](man/figures/mitoviz_plot_multi_df.png)
By default, the plot will be returned and shown; if you want to save the plot to a file, just use the `save_plot` option, which will save the current plot to `./mitoviz_plot.png`. You can specify a custom output path and filename using the `save_to` option.
```{r, eval=FALSE}
plot_df(sample_df, save_plot = TRUE)
# specify a custom output path
plot_df(sample_df, save_plot = TRUE, save_to = "../my_dir/my_plot.png")
```
### Plot variants from a VCF file
The `plot_vcf()` function allows to plot human mitochondrial variants contained in a VCF file.
```{r, eval=FALSE}
plot_vcf("sample_vcf.vcf")
```
![](man/figures/mitoviz_plot_vcf.png)
Multiple plots are automatically created from a multi-sample VCF file.
```{r, eval=FALSE}
plot_vcf("sample_multi.vcf")
```
![](man/figures/mitoviz_plot_multi_vcf.png)
### Plot variants from a JSON file
Some tools will output mitochondrial variants in a JSON-formatted file; in this case, the `plot_json()` function is what you need. JSON files can usually be in two different formats:
- vector format, where variant positions are simply stored in a vector
- dataframe format, where each variant is stored in its own entry
The `plot_json()` function can handle both cases, using a different argument for its `json_format` option.
#### Vector-formatted JSON files
An example of a vector-formatted JSON file is the following:
```{r, eval=FALSE}
# content of json_vector.json
["420", "1000", "3000", "5000", "10000"]
```
Using `json_format = "vector"` allows to plot variants from this file.
```{r, eval=FALSE}
plot_json("json_vector.json", json_format = "vector")
```
![](man/figures/mitoviz_plot_json_vector.png)
#### Dataframe-formatted JSON files
An example of a dataframe-formatted JSON file is the following:
```{r, eval=FALSE}
# content of json_dataframe.json
[
{"feat1": "snp", "position": 420},
{"feat1": "snp", "position": 1000},
{"feat1": "snp", "position": 3000},
{"feat1": "snp", "position": 5000},
{"feat1": "snp", "position": 10000}
]
```
In this case, just set `json_format = "dataframe"`. By default, the `plot_json()` function will look for a `POS` column with variant positions, but you can specify a different column name using the `pos_col` option.
```{r, eval=FALSE}
plot_json("json_dataframe.json", json_format = "dataframe", pos_col = "position")
```
![](man/figures/mitoviz_plot_json_dataframe.png)
## Help
If you found a bug, or want to suggest an improvement, please feel free to open an [issue](https://github.com/robertopreste/mitovizR/issues).