-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREADME.Rmd
135 lines (103 loc) · 9.24 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
---
output: github_document
---
# grur <a href='https://thierrygosselin.github.io/grur/'><img src='man/figures/logo.png' align="right" height="139" /></a>
```{r, echo = FALSE}
description <- readLines("DESCRIPTION")
rvers <- stringr::str_match(grep("R \\(", description, value = TRUE), "[0-9]{1,4}\\.[0-9]{1,4}\\.[0-9]{1,4}")[1,1]
version <- gsub(" ", "", gsub("Version:", "", grep("Version:", description, value = TRUE)))
```
<!-- badges: start -->
[](https://tidyverse.org/lifecycle/#experimental)
[](http://cran.r-project.org/package=grur)
[](http://www.repostatus.org/#active)
[](https://cran.r-project.org/)
[](commits/master)
[)`-brightgreen.svg)](/commits/master)
[](https://github.com/thierrygosselin/grur/actions)
[](https://zenodo.org/badge/latestdoi/87596763)
<!-- badges: end -->
```{r setup, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "README-"
)
```
https://thierrygosselin.github.io/grur/
The name **grur** |ɡro͞oˈr| was chosen because the missing genotypes dilemma with
RADseq data reminds me of the cheese paradox.
Here, I don't want to sustain a
[war](http://www.lefigaro.fr/flash-eco/2012/12/07/97002-20121207FILWWW00487-le-gruyere-francais-doit-avoir-des-trous.php)
or the controversy of cheese with holes,
so choose as you like, the *French Gruyère* or the *Swiss Emmental*.
The paradox is that the more cheese you have the more holes you'll get.
But, the more holes you have means the less cheese you have...
So, someone could conclude, the more cheese = the less cheese ?
I'll leave that up to you, back to genomics...
Numerous genomic analysis are vulnerable to missing values,
don't get trapped by missing genotypes in your RADseq dataset.
Use **grur** to **visualize patterns of missingness** and
**perform map-independent imputations of missing genotypes**
(see [features](https://github.com/thierrygosselin/grur#features) below).
## Installation
```r
if (!require("remotes")) install.packages("remotes")
remotes::install_github("thierrygosselin/grur")
library(grur)
```
Note: not all the packages used for imputations inside **grur** are installed automatically, why?
* Not all methods will be of interest.
* Some modules used for imputations are more complicated to install, and depending
on OS, it will definitely test your R skills and patience.
* By default, you'll be able to run `grur::missing_visualization` to check for
pattern of missingness (the first step...)
## Installation details for additonal imputation options
Please follow additional instructions in the [vignette](http://thierrygosselin.github.io/grur/articles/rad_genomics_computer_setup.html) to install the required packages for the imputation options you want to conduct:
| imputation options | package | installation difficulty | install instructions |
|:---------|:---------:|:---------:|:---------|
|**imputation.method = "lightgbm"**|`lightgbm`|difficult|[vignette](http://thierrygosselin.github.io/grur/articles/rad_genomics_computer_setup.html)|
|**imputation.method = "xgboost"**|`xgboost`|moderate|[vignette](http://thierrygosselin.github.io/grur/articles/rad_genomics_computer_setup.html)|
|**imputation.method = "rf"**|`randomForestSRC`|moderate|[vignette](http://thierrygosselin.github.io/grur/articles/rad_genomics_computer_setup.html)|
|**imputation.method = "rf_pred"**|`ranger`|easy|`install.packages("ranger")`|
|**if using pmm > 0**|`missRanger`|easy|`install.packages("missRanger")`|
web site and additional info: [https://thierrygosselin.github.io/grur/](https://thierrygosselin.github.io/grur/)
* [Computer setup - installation - troubleshooting](http://thierrygosselin.github.io/grur/articles/rad_genomics_computer_setup.html)
* [Function's documentation](http://thierrygosselin.github.io/grur/reference/index.html)
* [grur's features](https://thierrygosselin.github.io/grur/index.html#features)
* [Vignettes](http://thierrygosselin.github.io/grur/articles/index.html)
* How to cite grur: inside R type `citation("grur")`
## Life cycle
**grur** is still experimental, in order to make the package better, changes are
inevitable. Experimental functions will change, argument names will change.
Your codes and workflows might break from time to time **until grur is stable**.
Consequently, depending on your tolerance to change, **grur** might not be for you.
* Philosophy, major changes and deprecated functions/arguments are documented in
life cycle section of functions.
* [changelog, versions, new features and bug history](https://thierrygosselin.github.io/grur/news/index.html)
* [issues](https://github.com/thierrygosselin/grur/issues/new/choose) and [contributions](https://github.com/thierrygosselin/grur/issues/new/choose)
## Assumptions before imputing your dataset
1. **Filtered data**: Please don't try **grur** with raw data consisting of > 100K SNPs,
you will generate all sorts of bias and you'll be disapointed. **Filter your data first!**
[radiator](https://thierrygosselin.github.io/radiator/) was designed for this.
2. **Correlations**: Machine learning algorithms will work better and
faster if correlations are reduced to a minimum. If you used
[filter_rad](https://thierrygosselin.github.io/radiator/reference/filter_rad.html)
to filter your dataset, you should be ok. If not, check your dataset for
[short and long LD](https://thierrygosselin.github.io/radiator/reference/filter_ld.html).
3. **Pattern of individual heterozygosity**: If you have individual
heterozygosity patterns and/or correlation of individual heterozygosity with
missingness, you might want to skip imputation and go back to filter your data.
Please check out [radiator::detect_mixed_genomes](https://thierrygosselin.github.io/radiator/reference/detect_mixed_genomes.html) and [radiator::detect_het_outliers](https://thierrygosselin.github.io/radiator/reference/detect_het_outliers.html).
4. **Patterns of missingness**: Look for patterns of missingness [(vignette)](https://thierrygosselin.github.io/grur/articles/vignette_missing_data_analysis.html) to better understand the reasons for their presence and tailor the arguments inside grur's imputation module.
5. **Default arguments**: Defaults are there for testing, please, please, please, don't use
grur's defaults for publications!
## Features
| Caracteristics | Description |
|:-------------------|:--------------------------------------------------------|
|**Simulate RADseq data**|`simulate_rad`: simulate populations of RADseq data following island or stepping stone models. Inside the function, allele frequency can be created with [fastsimcoal2](http://cmpg.unibe.ch/software/fastsimcoal2/) and then used inside [rmetasim](https://github.com/stranda/rmetasim) simulation engine. *Vignette coming soon*.|
|**Patterns of missingness**|`missing_visualization`: visualize patterns of missing data associated with different variables of your study (lanes, chips, sequencers, populations, sample sites, reads/samples, homozygosity, etc). Similar to PLINK's identify-by-missingness analysis (IBM), **grur** is more powerful because it generates more analysis and automatically creates tables and figures ([see vignette](https://thierrygosselin.github.io/grur/articles/vignette_missing_data_analysis.html)). <br><br>`generate_missing`: allows to generate missing genotypes in dataset [simulated] based on a compound Dirichlet-multinomial distribution. *Vignette coming soon*.|
|**Imputations** `grur_imputations`|**Map-independent** imputations of missing genotypes with several algorithms (including machine leaning):<br>* **Random Forests** (on-the-fly-imputations with randomForestSRC or using predictive modelling using ranger and missRanger),<br>* **Extreme Gradient Tree Boosting** (using XGBoost or LightGBM),<br>* **Bayesian PCA** (using bpca in pcaMethods),<br>* **Classic Strawman:** the most frequently observed, non-missing, genotypes is used for imputation.<br><br>**Hierarchy:** algorithm's model can account for *strata* groupings, e.g. if patterns of missingness is found in the data.<br><br>**Haplotypes:** automatically detect SNPs on the same LOCUS (read/haplotype) to impute the SNPs jointly, reducing imputation artifacts. *Vignette coming soon*.|
| **Input/Output** | **grur** uses [radiator](https://thierrygosselin.github.io/radiator/index.html) input and output modules. Check out the [overview](https://thierrygosselin.github.io/radiator/articles/get_started.html#overview) of supported file format.|
|**[ggplot2](https://ggplot2.tidyverse.org)-based plotting**|Visualization: publication-ready figures of important metrics and statistics.|
|**Parallel**|Codes designed and optimized for fast computations with, sometimes, progress bars. Works with all OS: Linux, Mac and yes PC!|