-
Notifications
You must be signed in to change notification settings - Fork 1
/
api_analysis-definition.Rmd
173 lines (121 loc) · 5.28 KB
/
api_analysis-definition.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
---
title: "Analysis Definition"
---
.a.yaml files
## Header
the analysis definition is a yaml file in the `jamovi/` directory, with the extension `.a.yaml`. the analysis definition describes the analysis, the way it appears in menus, and the options it requires. the file is named to match the name of the analysis it describes, but converted to lowercase. an example is `ttestis.a.yaml`:
```
---
name: TTestIS
title: Independent Samples T-Test
menuGroup: T-Tests
version: '1.0.0'
jas: '1.0'
options:
- name: ...
type: ...
- name: ...
type: ...
```
property | function
-------------|-----------------------------------------
name | the name of the analysis. camel case. underscores are discouraged, dots are verboten.
title | the title of the analysis in title case.
version | the version of the analysis. should make use of [semantic versioning](http://semver.org).
jas | the `jamovi analysis spec`. should be '1.0'. must be wrapped in quotes to prevent it being interpretted as a number.
menuGroup | the name of the top level menu where the analysis should appear.
menuSubgroup | (optional) places the menu entry under a subheading.
menuTitle | (optional) the title to be used in the menu. if unspecified, then the `title` is used.
menuSubtitle | (optional) additional text placed to the lower right of the menu entry.
options | an array of options that the analysis requires. these are described in greater detail below.
## Options
options represent the options that an analysis requires in order to run. when a jamovi module is used as an R package, they represent the arguments to the function. when used in jamovi itself, they represent the user interface (UI) options presented to the user.
each option has a name, a type, and some additional properties which are described in greater detail below.
when a value is specified by the user (either through the jamovi user interface, or through a function argument), the option checks the value and produces an error if the value is not suitable. the checks performed by each option are also detailed below.
the different option types are as follows:
### Data
`Data` is used for analyses which require data (almost all of them). if used, it should be the first of the options, and should always be called `data`. it has no additional properties.
#### example
```
- name: data
type: Data
```
### Bool
`Bool` is used for true/false values, and is typically represented in the UI as a checkbox.
#### properties
- title
- default: `false`
#### example
```
- name: bf
type: Bool
title: Bayes factor
default: false
```
#### checks
- the value must be `true` or `false`
### Integer
`Integer` is used for values which need to be whole numbers. For 'floating point' numbers, use `Number` instead.
#### properties
- title
- default: `0`
- min: `-Inf`
- max: `Inf`
#### checks
- the value must be a whole number
- the value must fall between the `min` and the `max`
### Number
`Number` is used for values which need to be numeric. For whole numbers, use `Integer` instead.
#### properties
- title
- default: `0.0`
- min: `-Inf`
- max: `Inf`
#### example
```
- name: ciWidth
type: Number
title: Confidence level
min: 50
max: 99.9
default: 95
```
#### checks
- the value must be a number
- the value must fall between the `min` and the `max`
### List
`List` is used where only one of several values may be specified, and only one at a time. In the UI, these are typically represented as either a listbox, or a set of radio buttons.
#### properties
- title
- options
- default: `<the first of options>`
`options` must be specified as an array of strings
#### checks
- the value must be one of the options
### Variable
`Variable` is used where a variable/column from the data set needs to be specified. In the UI, these are typically represented as a 'drop box', where variables can be dragged and dropped.
- title
- suggested: `[]`
- permitted: `[continuous, ordinal, nominal, nominaltext]`
- rejectInf: `true`
- rejectMissing: `false`
The value of `Variable` is a string (in R, a character vector of length 1) containing the assigned variable name. If nothing is assigned it has a value of `null`.
#### checks
- whether the value is a string
- whether the variable exists in the data set
- whether the variable type is permitted
- whether the variable contains non-finite values (if `rejectInf` is true)
- whether the variable contains missing values (if `rejectMissing` is true)
### Variables
`Variables` is used where multiple variables/columns from the data set need to be specified. In the UI, these are typically represented as a 'drop box', where variables can be dragged and dropped.
- title
- suggested: `[]`
- permitted: `[continuous, ordinal, nominal, nominaltext]`
- rejectInf: `true`
- rejectMissing: `false`
The value is an array of strings (in R, a character vector). If nothing is assigned to `Variables` it's value is an empty array (in R, a character vector of length 0).
#### checks
- whether the variable exists in the data set
- whether the variable type is permitted
- whether the variable contains non-finite values (if `rejectInf` is true)
- whether the variable contains missing values (if `rejectMissing` is true)