This repository has been archived by the owner on Feb 23, 2024. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathREADME.Rmd
141 lines (109 loc) · 6.41 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
---
title: "param6"
output: github_document
---
```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
library(param6)
set6::useUnicode(TRUE)
ref <- function(val) sprintf("[%s](https://xoopr.github.io/param6/reference/%s.html)",
as.character(substitute(val)),
as.character(substitute(val)))
cran <- function(val) sprintf("**[%s](https://CRAN.R-project.org/package=%s)**",
as.character(substitute(val)),
as.character(substitute(val)))
gh <- function(org, repo) sprintf("**[%s](https://github.com/%s/%s)**", repo, org, repo)
pkg <- function(pkg) sprintf("**%s**", as.character(substitute(pkg)))
p6 <- "**param6**"
```
<img src="man/figures/logo.png" align="right" alt="" width="120" />
[](https://raphaels1.r-universe.dev)
[](https://github.com/xoopR/param6/actions/workflows/check-covr.yml)
[](https://github.com/xoopR/param6)
[](https://github.com/xoopR/param6)
[](https://cran.r-project.org/package=param6)
[](https://app.codecov.io/gh/xoopR/param6)
[](https://CRAN.R-project.org/package=param6)
[](https://opensource.org/licenses/MIT)
## What is param6?
`r p6` is an R6 parameter set interface for storing multiple parameters that may be used in other R6 (or other paradigm) objects. Key use-cases for R6 parameter sets have been seen in packages such as:
1. `r cran(distr6)` - In which R6 distribution objects require parameter sets in order to parametrise a given probability distribution. Parameters as objects allows efficient getting and setting of parameters, as well as composition of distributions.
2. `r cran(mlr3)` - In which R6 learners require parameter sets for passing parameters to machine learning models. Storing parameter set objects allows efficient tuning over these parameters.
## Main Features
Some main features/key use-cases of `r p6` includes:
* Construction of parameter sets
```{r construction}
prms <- list(
prm(id = "a", support = "reals", value = 1),
prm(id = "b", support = "naturals")
)
ParameterSet$new(prms)
```
* Tagging parameters with properties
```{r tags}
prms <- list(
prm(id = "a", support = "reals", value = 1, tags = "t1"),
prm(id = "b", support = "nnaturals", tags = "t2")
)
ParameterSet$new(prms,
list(required = "t1", unique = "t2"))
```
* Getting and setting parameter values
```{r values}
prms <- list(
prm(id = "a", support = "reals", value = 1, tags = "t1"),
prm(id = "b", support = "naturals", tags = "t2")
)
p <- ParameterSet$new(prms)
p$values$b <- 2
p$values
p$get_values(tags = "t1", simplify = FALSE)
```
* Transform parameters
```{r trafo}
p <- ParameterSet$new(
list(prm(id = "a", support = "naturals", value = 4))
)
p$trafo <- function(x, self) {
x$a <- 2^x$a
x
}
p$get_values("a", simplify = FALSE)
```
* Parameter dependencies
```{r deps, error=TRUE}
p <- ParameterSet$new(list(
prm(id = "a", support = "naturals"),
prm(id = "b", support = "naturals")
))
p$add_dep("a", "b", cnd("eq", 4))
p$values$b <- 5
p$values$a <- 1 # fails as b != 4
p$values$b <- 4
p$values$a <- 1 # now works
p$get_values()
```
## Why param6?
`r p6` began as the `ParameterSet` object in `r cran(distr6)`. However this initial attempt at an R6 parameter set interface, had massive bottlenecks that were causing substantial problems in dependencies. `r p6` is an abstracted parameter set interface that draws influence from this initial design. `r p6` achieves faster run-times and smaller object-sizes than other parameter set packages by making the following design decisions:
* `data.table` objects are minimised and only used when absolutely necessary, instead `list` objects are utilised.
* Symbolic representation of sets is utilised via the `r cran(set6)` package in order to store sets as characters, thereby reducing object sizes. Additionally, `r p6` includes a `r ref(support_dictionary)` which stores constructed sets that can then be accessed via a string representation, thereby preventing the same set needing to be constructed multiple times.
* `r cran(Rcpp)` is utilised via `r cran(set6)` in order to allow very fast containedness checks when checking values lie within a parameter support.
* S3 is embraced for simple objects, such as the `r ref(prm)` object in order to increase speed in construction times.
* Parameters are grouped internally by their supports, and not individually, allowing for a further increase in efficiency of both storage and runtimes in containedness checks
* The notion of 'parameter set collections' is removed in favour of automated methods for setting and getting prefixes in parameter IDs
## Installation
For the latest release on [CRAN](https://CRAN.R-project.org/package=param6), install with
```{r eval=FALSE}
install.packages("param6")
```
Otherwise for the latest stable build
```{r eval=FALSE}
remotes::install_github("xoopR/param6")
```
## Future Plans
The `r p6` API is still experimental and may be subject to major changes.
To understand if `r p6` fulfills it's initial use-case correctly, the next step will be to incorporate the package in `r cran(distr6)`, which may involve minor or major changes to the current API. From there, Rcpp will be embraced more fully in `r cran(set6)` and then in `r p6` to improve package speed.
## Package Development and Contributing
`r p6` is released under the [MIT licence](https://opensource.org/licenses/MIT). We welcome and appreciate all [new issues](https://github.com/xoopR/param6/issues) relating to bug reports, questions and suggestions. You can also [start a discussion](https://github.com/xoopR/param6/discussions) for more extensive feedback or feature suggestion.
## Acknowledgements
As well as building on the work of `r cran(distr6)`, the designs and some method names of `r p6` are based on the work of `r cran(paradox)`. Additionally, some decisions were based on designs in `r gh("mrc-ide", "mcstate")`.