forked from ropensci/DataSpaceR
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREADME.Rmd
173 lines (111 loc) · 6.34 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
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, echo = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "README-"
)
```
# DataSpaceR <img src="man/figures/logo.png" align="right" />
<!-- badges: start -->
[](https://github.com/ropensci/DataSpaceR/actions)
[](https://codecov.io/gh/ropensci/DataSpaceR/branch/master)
[](https://cran.r-project.org/package=DataSpaceR)
[](https://www.rpackages.io/package/DataSpaceR)
[](https://www.rpackages.io/package/DataSpaceR)
[](https://www.repostatus.org/#active)
[](https://www.tidyverse.org/lifecycle/#maturing)
[](https://github.com/ropensci/software-review/issues/261)
<!-- badges: end -->
`DataSpaceR` is an R interface to [the CAVD DataSpace](https://dataspace.cavd.org), a data sharing and discovery tool that facilitates exploration of HIV immunological data from pre-clinical and clinical HIV vaccine studies.
The package is intended for use by immunologists, bioinformaticians, and statisticians in HIV vaccine research, or anyone interested in the analysis of HIV immunological data across assays, studies, and time.
This package simplifies access to the database by taking advantage of the standardization of the database to hide all the [Rlabkey](https://cran.r-project.org/package=Rlabkey) specific code away from the user, and it allows the users to access the study-specific datasets via [an object-oriented paradigm](https://cran.r-project.org/package=R6/readme/README.html).
## Examples & Documentation
For more detailed examples and detailed documentation, see [the introductory vignette](https://docs.ropensci.org/DataSpaceR/articles/DataSpaceR.html) and [the pkgdown site](https://docs.ropensci.org/DataSpaceR/).
## Installation
Install from CRAN:
```{r, eval=FALSE}
install.packages("DataSpaceR")
```
You can install the latest development version from [GitHub](https://github.com/ropensci/DataSpaceR) with [devtools](https://cran.r-project.org/package=devtools):
```{r, eval=FALSE}
# install.packages("devtools")
devtools::install_github("ropensci/DataSpaceR")
```
## Register and set DataSpace credential
The database is accessed with the user's credentials. A netrc file storing
login and password information is ***required***.
1. [Create an account](https://dataspace.cavd.org/) and read the terms of use
1. On your R console, create a netrc file using a function from `DataSpaceR`:
```{r, eval=FALSE}
library(DataSpaceR)
writeNetrc(
login = "yourEmail@address.com",
password = "yourSecretPassword",
netrcFile = "/your/home/directory/.netrc" # use getNetrcPath() to get the default path
)
```
This will create a netrc file in your home directory.
***Alternatively***, you can manually create a netrc file in the computer running R.
* On Windows, this file should be named `_netrc`
* On UNIX, it should be named `.netrc`
* The file should be located in the user's home directory, and the permissions on the file should be unreadable for everybody except the owner
* To determine home directory, run `Sys.getenv("HOME")` in R
The following three lines must be included in the `.netrc` or `_netrc` file either separated by white space (spaces, tabs, or newlines) or commas. Multiple such blocks can exist in one file.
```
machine dataspace.cavd.org
login myuser@domain.com
password supersecretpassword
```
See [here](https://www.labkey.org/wiki/home/Documentation/page.view?name=netrc) for more information about `netrc`.
## Usage
The general idea is that the user:
1. creates an instance of `DataSpaceConnection` class via `connectDS`
1. browses available studies and groups in the instance via `availableStudies` and `availableGroups`
1. creates a connection to a specific study via `getStudy` or a group via `getGroup`
1. retrieves datasets by name via `getDataset`
### for example:
```{r}
library(DataSpaceR)
con <- connectDS()
con
```
`connectDS()` will create a connection to DataSpace.
### available studies can be listed by `availableStudies` field
```{r}
knitr::kable(head(con$availableStudies))
```
### available groups can be listed by `availableGroups` field
```{r}
knitr::kable(con$availableGroups)
```
***Note***: A group is a curated collection of participants from filtering of treatments, products, studies, or species, and it is created in [the DataSpace App](https://dataspace.cavd.org/cds/CAVD/app.view).
Check out [the reference page](https://docs.ropensci.org/DataSpaceR/reference/DataSpaceConnection.html) of `DataSpaceConnection` for all available fields and methods.
### create an instance of `cvd408`
```{r}
cvd408 <- con$getStudy("cvd408")
cvd408
class(cvd408)
```
### available datasets can be listed by `availableDatasets` field
```{r}
knitr::kable(cvd408$availableDatasets)
```
which will print names of available datasets.
### Neutralizing Antibody dataset (`NAb`) can be retrieved by:
```{r}
NAb <- cvd408$getDataset("NAb")
dim(NAb)
colnames(NAb)
```
Check out [the reference page](https://docs.ropensci.org/DataSpaceR/reference/DataSpaceStudy.html) of `DataSpaceStudy` for all available fields and methods.
***Note***: The package uses a [R6](https://cran.r-project.org/package=R6) class to represent the connection to a study and get around some of R's copy-on-change behavior.
## Meta
* Please [report any issues or bugs](https://github.com/ropensci/DataSpaceR/issues).
* License: GPL-3
* Get citation information for `DataSpaceR` in R doing `citation(package = 'DataSpaceR')`
* Please note that this project is released with a [Contributor Code of Conduct](https://github.com/ropensci/DataSpaceR/blob/master/CONDUCT.md). By participating in this project you agree to abide by its terms.
[](https://ropensci.org)