Overview: Experimental design types

The experimental design specifies the experimental conditions and other variables that are supposed to have an influence on the simulated data. Currently, there are three types of designs implemented: SingleSubjectDesign, MultiSubjectDesign and RepeatDesign.

Setup

Click to expand

# Load required packages
using UnfoldSim
using Random

Single-subject designs

As the name suggests, the SingleSubjectDesign type can be used to specify the experimental design for a single subject. Using the conditions arguments, the user can specify all relevant conditions or predictors and their levels or value range.

The current implementation assumes a full factorial design (also called fully crossed design) in which each level of a factor occurs with each level of the other factors. Moreover, in the current implementation, there is exactly one instance of each of these factor combinations.

Example:

design_single = SingleSubjectDesign(;
    conditions = Dict(
        :stimulus_type => ["natural", "artificial"],
        :contrast_level => range(0, 1, length = 3),
    ),
);

In order to inspect the design, we can use the generate_events function to create an event table based on the design we specified.

generate_events(design_single)

6×2 DataFrame

Row	contrast_level	stimulus_type
	Float64	String
1	0.0	natural
2	0.5	natural
3	1.0	natural
4	0.0	artificial
5	0.5	artificial
6	1.0	artificial

To change the order of the trials e.g. to sort or shuffle them, one can use the event_order_function argument. Example: Randomize the order of trials

design_single_shuffled = SingleSubjectDesign(;
    conditions = Dict(
        :stimulus_type => ["natural", "artificial"],
        :contrast_level => range(0, 1, length = 3),
    ),
    event_order_function = shuffle,
);

Click to expand event table

generate_events(design_single_shuffled)

6×2 DataFrame

Row	contrast_level	stimulus_type
	Float64	String
1	1.0	artificial
2	0.5	natural
3	0.0	artificial
4	0.0	natural
5	1.0	natural
6	0.5	artificial

Multi-subject designs

The MultiSubjectDesign type can be used to simulate data for an experiment with multiple subjects. Internally, it uses the MixedModelsSim.jl package. One needs to specify the number of subjects n_subjects and the number of items n_items i.e. stimuli. In addition, one needs to decide for every experimental factor whether it should be between- or within-subject (and item).

Note

For factors that are not listed in items_between it is assumed that they vary within-item (accordingly for subjects_between).

design_multi = MultiSubjectDesign(
    n_subjects = 6,
    n_items = 4,
    items_between = Dict(:colour => ["red", "blue"]),
    subjects_between = Dict(:age_group => ["young", "old"]),
    both_within = Dict(:luminance => range(0, 1, length = 3)),
);

Click to expand event table

generate_events(design_multi)

72×5 DataFrame

Row	subject	age_group	item	colour	luminance
	String	String	String	String	Float64
1	S1	young	I1	red	0.0
2	S1	young	I2	blue	0.0
3	S1	young	I3	red	0.0
4	S1	young	I4	blue	0.0
5	S1	young	I1	red	0.5
6	S1	young	I2	blue	0.5
7	S1	young	I3	red	0.5
8	S1	young	I4	blue	0.5
9	S1	young	I1	red	1.0
10	S1	young	I2	blue	1.0
11	S1	young	I3	red	1.0
12	S1	young	I4	blue	1.0
13	S2	old	I1	red	0.0
14	S2	old	I2	blue	0.0
15	S2	old	I3	red	0.0
16	S2	old	I4	blue	0.0
17	S2	old	I1	red	0.5
18	S2	old	I2	blue	0.5
19	S2	old	I3	red	0.5
20	S2	old	I4	blue	0.5
21	S2	old	I1	red	1.0
22	S2	old	I2	blue	1.0
23	S2	old	I3	red	1.0
24	S2	old	I4	blue	1.0
25	S3	young	I1	red	0.0
26	S3	young	I2	blue	0.0
27	S3	young	I3	red	0.0
28	S3	young	I4	blue	0.0
29	S3	young	I1	red	0.5
30	S3	young	I2	blue	0.5
31	S3	young	I3	red	0.5
32	S3	young	I4	blue	0.5
33	S3	young	I1	red	1.0
34	S3	young	I2	blue	1.0
35	S3	young	I3	red	1.0
36	S3	young	I4	blue	1.0
37	S4	old	I1	red	0.0
38	S4	old	I2	blue	0.0
39	S4	old	I3	red	0.0
40	S4	old	I4	blue	0.0
41	S4	old	I1	red	0.5
42	S4	old	I2	blue	0.5
43	S4	old	I3	red	0.5
44	S4	old	I4	blue	0.5
45	S4	old	I1	red	1.0
46	S4	old	I2	blue	1.0
47	S4	old	I3	red	1.0
48	S4	old	I4	blue	1.0
49	S5	young	I1	red	0.0
50	S5	young	I2	blue	0.0
51	S5	young	I3	red	0.0
52	S5	young	I4	blue	0.0
53	S5	young	I1	red	0.5
54	S5	young	I2	blue	0.5
55	S5	young	I3	red	0.5
56	S5	young	I4	blue	0.5
57	S5	young	I1	red	1.0
58	S5	young	I2	blue	1.0
59	S5	young	I3	red	1.0
60	S5	young	I4	blue	1.0
61	S6	old	I1	red	0.0
62	S6	old	I2	blue	0.0
63	S6	old	I3	red	0.0
64	S6	old	I4	blue	0.0
65	S6	old	I1	red	0.5
66	S6	old	I2	blue	0.5
67	S6	old	I3	red	0.5
68	S6	old	I4	blue	0.5
69	S6	old	I1	red	1.0
70	S6	old	I2	blue	1.0
71	S6	old	I3	red	1.0
72	S6	old	I4	blue	1.0

As with the SingleSubjectDesign one can use the event_order_function argument to determine the order of events/trials.

Important

The number of subjects/items has to be a divisor of the number of factor level combinations, i.e. it is assumed that the design is balanced which means that there is an equal number of observations for all possible factor level combinations.

Repeat designs

The RepeatDesign type is a functionality to encapsulate single- or multi-subject designs. It allows to repeat a generated event table multiple times. In other words, the RepeatDesign type allows to have multiple instances of the same item/subject/factor level combination.

Example: Assume, we have the following single-subject design from above:

Click to expand event table

generate_events(design_single)

6×2 DataFrame

Row	contrast_level	stimulus_type
	Float64	String
1	0.0	natural
2	0.5	natural
3	1.0	natural
4	0.0	artificial
5	0.5	artificial
6	1.0	artificial

But instead of having only one instance of the factor combinations e.g. stimulus_type: natural and contrast_level: 0, we will repeat the design three times such that there are three occurrences of each combination.

design_repeated = RepeatDesign(design_single, 3);
generate_events(design_repeated)

18×2 DataFrame

Row	contrast_level	stimulus_type
	Float64	String
1	0.0	natural
2	0.5	natural
3	1.0	natural
4	0.0	artificial
5	0.5	artificial
6	1.0	artificial
7	0.0	natural
8	0.5	natural
9	1.0	natural
10	0.0	artificial
11	0.5	artificial
12	1.0	artificial
13	0.0	natural
14	0.5	natural
15	1.0	natural
16	0.0	artificial
17	0.5	artificial
18	1.0	artificial

Here one can find another example of how to repeat design entries for multi-subject designs.

This page was generated using Literate.jl.