-
Notifications
You must be signed in to change notification settings - Fork 11
/
Copy pathREADME.Rmd
135 lines (98 loc) · 7.69 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
---
# WORCS <a href="https://cjvanlissa.github.io/worcs/"><img src="man/figures/logo.png" align="right" height="120" alt="worcs website" /></a>
<!-- README.md is generated from README.Rmd. Please edit that file -->
<!-- badges: start --->
[](https://cran.r-project.org/package=worcs)
[](https://r-pkg.org/pkg/worcs)
[](https://lifecycle.r-lib.org/articles/stages.html#maturing)
[](https://github.com/cjvanlissa/worcs/actions/workflows/R-CMD-check.yaml)
[](code_of_conduct.md)
[](https://bestpractices.coreinfrastructure.org/projects/3969)
<!-- badges: end --->
The Workflow for Open Reproducible Code in Science (WORCS) is an easy to adopt approach to ensuring a research project meets the requirements of Open Science from the start. It is based on a "good enough" philosophy, prioritizing user-friendliness over exhaustiveness. It can be used either in absence of, or in parallel to, existing requirements for Open workflows. It can also be enhanced with more elaborate solutions for specific issues.
## Where do I start?
For most users, the recommended starting point is to [read the paper, published in Data Science](https://content.iospress.com/articles/data-science/ds210031),
which introduces the WORCS workflow, explains the underlying tools, and illustrates how the `worcs` package can be used to create a new project that follows the workflow.
The workflow is illustrated below; the [workflow vignette](https://cjvanlissa.github.io/worcs/articles/workflow.html) describes each step in detail.
```{r, echo = FALSE, fig.alt="A diagram of the WORCS workflow."}
knitr::include_graphics("https://github.com/cjvanlissa/worcs/raw/master/paper/workflow_graph/workflow.png")
```
## Installing the package
Before installing the package, please read [this vignette](https://cjvanlissa.github.io/worcs/articles/setup.html), which explains how to set up your computer for `worcs` (using the CRAN version).
If you know what you're doing and you wish to install the development version of the `worcs` package from GitHub instead, you can use:
``` r
if(!requireNamespace("remotes")) install.packages("remotes")
remotes::install_github("cjvanlissa/worcs", dependencies = TRUE, update = "never")
```
## Citing WORCS
You can cite WORCS using the following citation (please use the same citation for either the package, or the paper):
> Van Lissa, C. J., Brandmaier, A. M., Brinkman, L., Lamprecht, A., Peikert, A., , Struiksma, M. E., & Vreede, B. (2021). WORCS: A Workflow for Open Reproducible Code in Science. Data Science. Data Science, vol. 4, no. 1, pp. 29-49. DOI: 10.3233/DS-210031.
## About this repository
This repository contains the following:
1. An R-package called `worcs`, with convenience functions to facilitate the WORCS workflow.
2. In the subfolder `./paper`, the source files for the paper describing the WORCS workflow.
The repository serves two functions: To allow users to install the `worcs` package, and to allow collaborators access to the source code for the package and paper.
## Repository structure
```{r echo = FALSE, results = "asis"}
descripts <- data.frame(matrix(c(
"_pkgdown.yml", "YAML for package website", "do not edit",
"DESCRIPTION", "R-package DESCRIPTION", "do not edit",
"LICENSE.md", "Project license", "do not edit",
"NAMESPACE", "R-package namespace", "machine-written",
"README.md", "Read this file to get started! ", "do not edit",
"README.Rmd", "R-markdown source for readme.md", "human editable",
"worcs.Rproj", "RStudio project file", "do not edit",
"docs/", "Package website", "machine-written",
"inst/", "RStudio project template files ", "human editable",
"man/", "R-package documentation", "do not edit",
"paper/", "WORCS paper source files", "human editable",
"R/", "R-package source code", "human editable",
"vignettes/", "R-package vignettes", "human editable"
), ncol = 3, byrow = TRUE))
names(descripts) <- c("File", "Description", "Usage")
knitr::kable(descripts)
```
<!-- ## Adoption of WORCS by users -->
```{r, eval = FALSE, echo = FALSE, message=FALSE, warning=FALSE}
library(gh)
library(dlstats)
dl <- dlstats::cran_stats("worcs")
dl <- sum(dl$downloads)
# worcs_repo <- gh("/repos/cjvanlissa/worcs")
#
# repos <- gh("GET /search/code", username = "cjvanlissa", q="worcs_version filename:.worcs")
#
# worcs_repos <- data.frame(t(sapply(repos[["items"]], function(x){
# c(owner = x$repository$owner$login,
# name = x$repository$name,
# url = x$repository$html_url
# )
# })))
# worcs_repos <- worcs_repos[!((worcs_repos$owner %in% c("cjvanlissa", "cran") & worcs_repos$name == "worcs")| grepl("(penguin|\\btmp|demo|test)", tolower(worcs_repos$name))), ]
# tmp <- paste0(sapply(unique(worcs_repos$owner), function(x){
# owner_repos <- worcs_repos[worcs_repos$owner == x, , drop = FALSE]
# paste0("\n - ", x, " ",
# paste0("\n + [", owner_repos$name, "](", owner_repos$url, ") ", collapse = ""))
# }),
# collapse = "")
# invited <- read.table("https://raw.githubusercontent.com/cjvanlissa/resume/master/invited.csv", sep = ",", header = TRUE)
# invited <- invited[grepl("(worcs|workflow)", tolower(invited$Topic)), c("Institute", "Year", "City", "Country", "Date")]
# invited <- paste0(apply(invited, 1, function(x){paste0("\n - ", x[1], " (", x[2], ") ")}), collapse = "")
```
<!-- As of `r Sys.Date()`, these are indicators of the adoption of `worcs` by users: -->
<!-- 1. The preprint has been downloaded 1372 times, since being published on 31-05-2020 -->
<!-- 1. The paper in [Data Science](https://content.iospress.com/articles/data-science/ds210031) has been cited 13 times -->
<!-- 1. The `worcs` R-package has been downloaded r dl times from CRAN, since being published on 18-05-2020 -->
<!-- 1. The GitHub project has been forked r worcs_repo$network_count times, watched r worcs_repo$subscribers_count` times, and starred r worcs_repo$watchers times -->
<!-- 1. The lead author has given invited lecturegs on WORCS at: r invited -->
<!-- 1. WORCS is currently used in the following public itHub repositories (sorted by user): r tmp -->
## Contributing and Contact Information
We are always eager to receive user feedback and contributions to help us improve both the workflow and the software. Major contributions warrant coauthorship to the package. Please contact the lead author at [c.j.vanlissa@uu.nl](mailto:c.j.vanlissa@uu.nl), or:
- [File a GitHub issue](https://github.com/cjvanlissa/worcs) for feedback, bug reports or feature requests
- [Make a pull request](https://github.com/cjvanlissa/worcs/pulls) to contribute your code or prose
By participating in this project, you agree to abide by the [Contributor
Code of Conduct v2.0](https://www.contributor-covenant.org/). Contributions to the package must adhere to the [tidyverse style guide](https://style.tidyverse.org/). When contributing code, please add tests for that contribution to the `tests/testthat` folder, and ensure that these tests pass in the [GitHub Actions panel](https://github.com/cjvanlissa/worcs/actions/workflows/R-CMD-check).
## Acknowledgements
The worcs logo is inspired by the Open Science Badges by the Center for Open Science (CC-BY-4.0), and makes use of the gear, services, gears, preferences, settings icon, made by MD Badsha Meah from www.freeicons.io (CC-BY-3.0).