README.md 8.97 KB
Newer Older
jlopez's avatar
jlopez committed
1
## genepop
jlopez's avatar
jlopez committed
2

jlopez's avatar
jlopez committed
3
Le projet genepop a pour but la mise en place d'un package R qui permet l'utilisation
jlopez's avatar
jlopez committed
4
des fonctionnalités de l'outil [Genepop](http://kimura.univ-montp2.fr/~rousset/Genepop.htm) directement depuis l'environnement R.
jlopez's avatar
jlopez committed
5

jlopez's avatar
jlopez committed
6
Ainsi chacune des fonctionnalités fournies par l'outil Genepop est ici présente sous forme de fonction R.
jlopez's avatar
jlopez committed
7
8
9

L'outil Genepop étant développé en C++, la librairie Rcpp est utilisée afin de faire communiquer R et C++.

jlopez's avatar
jlopez committed
10
## Philosophie
jlopez's avatar
jlopez committed
11
L'idée derrière ce projet était d'identifier chacune des fonctionnalités de l'outil Genepop,
jlopez's avatar
jlopez committed
12
qui était utilisé en ligne de commandes ou à l'aide d'un menu interactif, et d'en extraire un ensemble
jlopez's avatar
jlopez committed
13
de fonctions ainsi que leurs signatures correspondantes.
14
Permettant ainsi à un utilisateur qui a installé notre package R, d'appeler directement ces fonctions depuis R.
jlopez's avatar
jlopez committed
15

jlopez's avatar
jlopez committed
16
17
18
19
20
## Architecture

```
├── genepop/
│   ├── man/
jlopez's avatar
Update    
jlopez committed
21
│   ├── inst/
jlopez's avatar
jlopez committed
22
23
│   │   ├── doc/
│   │   ├── genepop-shiny/
24
│   │   ├── extdata/
jlopez's avatar
jlopez committed
25
26
│   │   ├── extdoc/
│   │   ├── make-exe/
jlopez's avatar
jlopez committed
27
28
29
30
│   ├── R/
│   │   ├── Genepop.R
│   │   ├── RcppExports.R
│   ├── src/
jlopez's avatar
jlopez committed
31
32
│   │   ├── *.cpp
│   │   ├── *.h
jlopez's avatar
jlopez committed
33
34
35
│   ├── test/
│   │   ├── test-all.R
│   │   ├── testthat/
jlopez's avatar
jlopez committed
36
37
```

jlopez's avatar
jlopez committed
38
## Travail accompli
jlopez's avatar
jlopez committed
39
  - Réalisation des fonctions C++ qui représentent chaque fonctionnalité
jlopez's avatar
jlopez committed
40
  - Remplacement des appels à la fonction "exit" en C++ qui faisait planter R/RStudio
jlopez's avatar
jlopez committed
41
  - Initialisation/libération des variables globales
jlopez's avatar
jlopez committed
42
    - Afin d'initialiser et libérer correctement les variables globales pour utiliser plusieurs fonctionnalités successivement.
jlopez's avatar
jlopez committed
43
  - Mise à disposition d'un application web : genepop-shiny
jlopez's avatar
jlopez committed
44

jlopez's avatar
jlopez committed
45
## Dépendance
jlopez's avatar
jlopez committed
46
  Rcpp : Cette librairie permet d'utiliser les fonctions C++ depuis R
jlopez's avatar
jlopez committed
47

jlopez's avatar
jlopez committed
48
49
## Installation

jlopez's avatar
jlopez committed
50
51
    Installation depuis RStudio

jlopez's avatar
jlopez committed
52
53
54
55
   ```R
   library(devtools)
   library(git2r)

jlopez's avatar
jlopez committed
56
57
58
59
   devtools::install_git("http://gitlab.mbb.univ-montp2.fr/jlopez/Genepop.git")

   #ou

jlopez's avatar
jlopez committed
60
61
   devtools::install_git("http://gitlab.mbb.univ-montp2.fr/jlopez/Genepop.git", credentials = git2r::cred_user_pass ("your_login", "your_password"))
   ````
jlopez's avatar
jlopez committed
62

jlopez's avatar
jlopez committed
63

jlopez's avatar
jlopez committed
64
## Utilisation classique
jlopez's avatar
jlopez committed
65

jlopez's avatar
jlopez committed
66
Une fois que votre package genepop est installé.<br/>
jlopez's avatar
jlopez committed
67
Il suffit de choisir une fonctionnalité que l'on veut effectuer et de l'appeler avec les bons arguments.<br/>
jlopez's avatar
jlopez committed
68

jlopez's avatar
jlopez committed
69
Exemple pour un test de Hardy-Weinberg.<br/>
jlopez's avatar
jlopez committed
70
En entrée un [fichier](http://gitlab.mbb.univ-montp2.fr/jlopez/Genepop/blob/master/inst/extdata/sample.txt) au format Genepop<br/>
jlopez's avatar
jlopez committed
71
En sortie un fichier au format texte <br/>
jlopez's avatar
jlopez committed
72

jlopez's avatar
jlopez committed
73
  ```R
jlopez's avatar
jlopez committed
74
75
76
77
78
79
80
81
82
83
84
85
86
  #' @name Hardy-Weinberg
  #' @title Tests of Hardy-Weinberg genotypic proportions
  #' @description Compute variants of the exact conditional test for Hardy-Weinberg genotypic proportions.  The tests differ by their test statistics. \code{HWtable_analysis} handles a single table of genotype counts, and \code{test_HW} requires a standard genepop input file. See \href{../doc/all-menu-options.html#option-1-hardy-weinberg-hw-exact-tests}{this section} of the Genepop executable documentation for more information on the statistical methods.
  #' @param inputFile character: The path of the input file, in Genepop format
  #' @param which character: \code{'Proba'}, \code{'excess'}, and \code{'deficit'} to perform the probability test, score test for excess, and score tests for deficit, respectively, in each population and for each locus. \code{test_HW} additionally handles \code{'global excess'} and  \code{'global deficit'} for global tests for all loci and/or all populations, and \code{HWtable_analysis} additionally handles \code{'Fis'} to report basic information (allele frequencies and Fis).
  #' @param outputFile character: The path of the output file
  #' @param settingsFile character: The path of the settings file
  #' @param enumeration logical: whether to compute the complete enumeration test for samples with less than 5 alleles
  #' @param dememorization integer: length of dememorization step of Markov chain algorithm
  #' @param batches integer: Number of batches
  #' @param iterations integer: Iterations per batch
  #' @param verbose logical: whether to print some information
  #' @return The path of the output file is returned invisibly.
francois's avatar
francois committed
87
  #' @examples locinfile <- genepopExample('sample.txt')
jlopez's avatar
jlopez committed
88
89
90
  #' test_HW(locinfile, which='deficit', 'sample.txt.D')
  test_HW(inputFile, which = "Proba", outputFile = "", enumeration = FALSE, dememorization = 10000, batches = 20, iterations = 5000, verbose = interactive()

jlopez's avatar
jlopez committed
91
  ```
jlopez's avatar
jlopez committed
92

jlopez's avatar
jlopez committed
93
94
## Utilisation avec fichier de paramètres

jlopez's avatar
jlopez committed
95
Certain fonction peuvent être utilisée avec un fichier de paramètres.<br/>
jlopez's avatar
jlopez committed
96
97

Une fois que votre package genepop est installé.<br/>
jlopez's avatar
jlopez committed
98
99
100
Il suffit de choisir une fonctionnalité que l'on veut effectuer avec un fichier de paramètres correcte.<br/>

Exemple pour un test de Hardy-Weinberg.<br/>
jlopez's avatar
jlopez committed
101
En entrée un [fichier](http://gitlab.mbb.univ-montp2.fr/jlopez/Genepop/blob/master/inst/extdata/sample.txt) au format Genepop et un fichier de [paramètres](http://gitlab.mbb.univ-montp2.fr/jlopez/Genepop/blob/master/inst/extdata/setting.txt)<br/>
jlopez's avatar
jlopez committed
102
En sortie un fichier au format texte <br/>
jlopez's avatar
jlopez committed
103
104
105
106

  ```R
  library(genepop)

jlopez's avatar
jlopez committed
107
108
  test_HW(inputFile, which = "Proba", outputFile = "", settingsFile = "", verbose = interactive())

jlopez's avatar
jlopez committed
109
  ```
jlopez's avatar
jlopez committed
110

jlopez's avatar
jlopez committed
111
112
## Sample

113
Le package genepop contient plusieurs [sample](http://gitlab.mbb.univ-montp2.fr/jlopez/Genepop/tree/master/inst/extdata) qui vous aiderons à tester les différentes fonctionnalités si vous n'avez pas de fichier d'entrée conforme au format genepop.
jlopez's avatar
jlopez committed
114
115
116

  ```R
  #Permet de recupérer sous R, le chemin des différents fichier sample présent
117
  fpath <- system.file("extdata", "sample.txt", package="genepop")
jlopez's avatar
jlopez committed
118
  ```
jlopez's avatar
jlopez committed
119

jlopez's avatar
jlopez committed
120
## Documentation
jlopez's avatar
jlopez committed
121

jlopez's avatar
jlopez committed
122
Pour plus de détails concernent chaque fonction, vous référez à la [documentation](http://gitlab.mbb.univ-montp2.fr/jlopez/Genepop/tree/master/man) R ou à la documentation de [genepop](http://gitlab.mbb.univ-montp2.fr/jlopez/Genepop/tree/master/inst/doc)
jlopez's avatar
jlopez committed
123
124
<br/>

jlopez's avatar
jlopez committed
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
- **test_HW** : Tests of Hardy-Weinberg genotypic proportions ([man](http://gitlab.mbb.univ-montp2.fr/jlopez/Genepop/blob/master/man/Hardy-Weinberg.Rd))

- **test_LD** : Tables and exact test for genotypic linkage disequilibrium ([man](http://gitlab.mbb.univ-montp2.fr/jlopez/Genepop/blob/master/man/Linkage.Rd))

- **test_diff** : Tests of genic and genotypic differentiation ([man](http://gitlab.mbb.univ-montp2.fr/jlopez/Genepop/blob/master/man/Differentiation.Rd))

- **struc** : Exact test on a single contingency table ([man](http://gitlab.mbb.univ-montp2.fr/jlopez/Genepop/blob/master/man/Contingency-test.Rd))

- **Nm_private** : Private allele method ([man](http://gitlab.mbb.univ-montp2.fr/jlopez/Genepop/blob/master/man/Nm_private.Rd))

- **basic_info** : Allele and genotype frequencies ([man](http://gitlab.mbb.univ-montp2.fr/jlopez/Genepop/blob/master/man/basic_info.Rd))

- **genedivFis** : Gene diversities and Fis (or rho_IS) ([man](http://gitlab.mbb.univ-montp2.fr/jlopez/Genepop/blob/master/man/genedivFis.Rd))

- **Fst** : Fst (or rho_ST) estimation ([man](http://gitlab.mbb.univ-montp2.fr/jlopez/Genepop/blob/master/man/Fst.Rd))

- **ibd** : Isolation by distance ([man](http://gitlab.mbb.univ-montp2.fr/jlopez/Genepop/blob/master/man/IBD.Rd))

- **conversion** : File conversions ([man](http://gitlab.mbb.univ-montp2.fr/jlopez/Genepop/blob/master/man/conversion.Rd))

- **nulls** : Estimation of allele frequencies under genotyping failure. ([man](http://gitlab.mbb.univ-montp2.fr/jlopez/Genepop/blob/master/man/nulls.Rd))

jlopez's avatar
jlopez committed
147
- **diploidize** : Various data manipulation utilities ([man](http://gitlab.mbb.univ-montp2.fr/jlopez/Genepop/blob/master/man/manipulation.Rd))
jlopez's avatar
jlopez committed
148

jlopez's avatar
jlopez committed
149

jlopez's avatar
jlopez committed
150
## Développement
jlopez's avatar
jlopez committed
151

jlopez's avatar
jlopez committed
152
153
154
155
156
- **Comment ajouter une fonctionnalité au package genepop** : <br/>
    Une fois que vous avez rajouté votre nouvelle fonctionnalité dans le code C++ de genepop, il va falloir la rendre disponible aux utilisateurs du package R. Pour cela il suffit de rajouter une fonction dans les fichiers [src/RGenepop.cpp](http://gitlab.mbb.univ-montp2.fr/jlopez/Genepop/blob/master/src/RGenepop.cpp) et [src/RGenepop.h](http://gitlab.mbb.univ-montp2.fr/jlopez/Genepop/blob/master/src/RGenepop.h), en respectant le principe de fonctionnement des autres fonctions qui sont présentes , ainsi que la convention de nommage. <br/>

    L'étape suivante consiste à build votre package R. Une fois le build terminé, une fonction R est automatiquement créée dans le fichier R/RcppExports.R. Si votre fonction doit avoir des paramètres par défaut alors il faut la rajouter dans le fichier R/Genepop.R en lui rajoutant manuellement les valeurs par défauts de chaque paramètres. <br/> En respectant la aussi les conventions de nommage.

jlopez's avatar
jlopez committed
157
158
- **Utiliser genepop avec un fichier exécutable et non un package R** : <br/>
    Il suffit pour cela d'utiliser le fichier Makefile
jlopez's avatar
jlopez committed
159

jlopez's avatar
jlopez committed
160
161
## Shiny

jlopez's avatar
jlopez committed
162
Le package genepop propose aussi à ses utilisateurs un application web,  [genepop-shiny](http://gitlab.mbb.univ-montp2.fr/jlopez/Genepop/tree/master/inst/genepop-shiny), qui utilise [shiny](https://shiny.rstudio.com/) afin d'offrir une interface au package R