sweetbean
AssetStimulusSpec
Bases: _BaseStimulusSpec
Rendered visual asset stimulus (image/gif/other browser image asset).
Source code in sweetbean/stimulus_spec/spec.py
170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 | |
Block
A block of stimuli (for example, an instruction, training, or test block)
Source code in sweetbean/block.py
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 | |
__init__(stimuli, timeline=None)
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
stimuli
|
a list of stimuli |
required | |
timeline
|
a list of dictionaries with the name of the timeline variables |
None
|
Source code in sweetbean/block.py
46 47 48 49 50 51 52 53 54 55 56 | |
to_image(path, data, sequence=True, timeline_idx='random', zoom_factor=3)
Create an image of the stimuli sequence of the block Arguments: path: the path to save the image data: if needed data can be passed in for the stimuli (for example, correct if the sequence contains a feedback stimulus) sequence: if True, the images are combined into one image else they are stored separately timeline_idx: the index of the timeline element to use, if "random" a random timeline element is chosen, if none, the whole timeline is shown zoom_factor: the factor by which the images are zoomed (can be a list if different zoom factors for each stimulus are needed)
Source code in sweetbean/block.py
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 | |
to_js(template_timeline_token=None)
Build jsPsych trial source for this block.
If template_timeline_token is set (see :meth:Experiment.compile), the
timeline data is omitted here and injected later via
:meth:Experiment.to_js_string_from_template for faster multi-condition builds.
Source code in sweetbean/block.py
58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 | |
BotDetection
Bases: Protection
Bot/agent detection layer.
Source code in sweetbean/protection/bot_detection.py
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 | |
__init__(enable_countermeasures=True, track_sliders=True)
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
enable_countermeasures
|
bool
|
when False, only passive logging runs — no honeypot DOM, no clipboard/devtools blocking, no inline traps. Useful for pilots / debugging. |
True
|
track_sliders
|
bool
|
when True, install a document-level |
True
|
Source code in sweetbean/protection/bot_detection.py
36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 | |
Experiment
An experiment consisting of blocks
Source code in sweetbean/experiment.py
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 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 | |
__init__(blocks, protections=None)
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
blocks
|
List[Block]
|
a list of blocks |
required |
protections
|
optional list of :class: |
None
|
Source code in sweetbean/experiment.py
30 31 32 33 34 35 36 37 38 39 40 41 | |
compile(as_function=True, is_async=True)
Build JavaScript once: stimulus graphs and jsPsych setup are emitted;
each block's timeline_variables is a placeholder string that
:meth:to_js_string_from_template replaces with per-condition data.
Use when multiple conditions share the same stimulus structure (e.g. Firebase payloads) so timelines are "injected" without re-running Transcrypt per condition.
Source code in sweetbean/experiment.py
191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 | |
run_on_language(get_input=input, multi_turn=False, preamble='', data=None, response_open_token='<<', response_close_token='>>')
Run the experiment in a language
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
get_input
|
a function to get input from the response (for example, a function that prompts language model and returns the response) |
input
|
|
multi_turn
|
a boolean to allow multi-turn input. If True, the prompts are not concatenated. |
False
|
|
preamble
|
a string to be added before the prompts |
''
|
|
data
|
a list of dictionaries with the data. This will rerun the experiment with the data as input. If the data is not provided for the full experiment, the rest of it will be simulated with the get_input function. |
None
|
|
response_open_token
|
token used in prompt templates for "answer starts here". |
'<<'
|
|
response_close_token
|
token appended after model/user answer in stored prompts. |
'>>'
|
Source code in sweetbean/experiment.py
261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 | |
to_html(path, path_local_download=None)
Save the experiment to an HTML file
Source code in sweetbean/experiment.py
131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 | |
to_js_string(as_function=True, is_async=True)
Return the experiment as a JavaScript string
Source code in sweetbean/experiment.py
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 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 | |
to_js_string_from_template(template, timelines)
staticmethod
Replace each __SB_TIMELINE_PLACEHOLDER_i__ in template with the JS literal
for timelines[i] (from :func:sweetbean.util.parse.to_js).
timelines must have one entry per block that used a placeholder in
:meth:compile (same order as Experiment.blocks). Blocks compiled with
:class:~sweetbean.variable.CodeVariable timelines embed real JS and are not
listed here — pass the full list of block timelines, including those unchanged.
Source code in sweetbean/experiment.py
237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 | |
KeyboardPressResponseSpec
Bases: _SpecBaseModel
Keyboard response definition.
Source code in sweetbean/response_spec/spec.py
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 | |
MouseClickResponseSpec
Bases: _SpecBaseModel
Mouse click response definition.
Source code in sweetbean/response_spec/spec.py
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 | |
Protection
Base class — see module docstring for the hook contract.
Source code in sweetbean/protection/protection.py
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 | |
head_assets()
Extra HTML injected into <head>. Used by Experiment.to_html.
Source code in sweetbean/protection/protection.py
36 37 38 | |
init_js()
JS source run after initJsPsych but before trials run. Typical
use: call the library's initialize and register global handlers.
Source code in sweetbean/protection/protection.py
45 46 47 48 | |
on_finish_for_stimulus(stimulus)
Per-trial JS injected into the stimulus's on_finish callback.
data is in scope and refers to the trial's data row — mutate it
directly to attach per-trial signals.
Source code in sweetbean/protection/protection.py
64 65 66 67 68 69 70 | |
on_load_for_stimulus(stimulus)
Per-trial JS injected into the stimulus's on_load callback.
Return "" to no-op for this stimulus type. Implementations may
inspect stimulus (e.g. isinstance) to specialize.
Source code in sweetbean/protection/protection.py
56 57 58 59 60 61 62 | |
runtime_js()
JS source emitted before initJsPsych. Typically the protection
library (IIFE) being inlined into the page.
Source code in sweetbean/protection/protection.py
40 41 42 43 | |
summary_js()
JS expression that evaluates to a summary object. Empty disables.
Wired into the experiment's on_finish so it lands on every row of
saved data via jsPsych.data.addProperties.
Source code in sweetbean/protection/protection.py
50 51 52 53 54 | |
RectangleSpec
Bases: _SpecBaseModel
Normalized rectangular placement in viewport coordinates.
Source code in sweetbean/stimulus_spec/spec.py
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 | |
SymbolStimulusSpec
Bases: _BaseStimulusSpec
Rendered geometric symbol stimulus.
Source code in sweetbean/stimulus_spec/spec.py
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 | |
TextStimulusSpec
Bases: _BaseStimulusSpec
Rendered text stimulus.
Source code in sweetbean/stimulus_spec/spec.py
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 | |
TrialSpec
Bases: _SpecBaseModel
One rendered trial containing layered stimuli and response handlers.
Source code in sweetbean/stimulus_spec/spec.py
234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 | |
build_html_from_files(spec_json_path, timeline_csv_path, out_html_path)
Compile and write a runnable jsPsych HTML from declarative files.
Source code in sweetbean/stimulus_spec/io.py
108 109 110 111 112 113 114 115 116 117 118 119 | |
build_prompt_schema_markdown(*, verbosity=1)
Return markdown documentation for SweetBean trial-spec models.
verbosity is passed to auto_prompt.build_prompt when available;
higher values include fields marked with prompt_verbosity_min.
Source code in sweetbean/stimulus_spec/prompt_schema.py
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 | |
check_java()
Ensure that Java is installed.
Source code in sweetbean/__init__.py
27 28 29 30 31 32 33 34 35 | |
compile_trial(spec)
Compile one declarative trial spec into a SweetBean stimulus object.
Source code in sweetbean/stimulus_spec/render.py
279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 | |
write_prompt_schema_markdown(out_path, *, verbosity=1)
Generate and write markdown docs for Trial/Stimulus/Response specs.
Source code in sweetbean/stimulus_spec/io.py
122 123 124 125 126 127 128 129 130 131 | |