Implement JOSS doc suggestions

README.md

@@ -76,7 +76,7 @@ data, events = simulate(
     PinkNoise(),
 );    
 ```
-All components (design, components, onsets, noise) can be easily modified and you can simply plugin your own!
+All simulation ingredients (design, components, onsets, noise) can be easily modified and you can simply plugin your own!
 
 ## Contributions
 Contributions of any kind are very welcome. Please have a look at [CONTRIBUTING.md](https://github.com/unfoldtoolbox/UnfoldSim.jl/blob/main/CONTRIBUTING.md) for guidance on contributing to UnfoldSim.jl.

docs/literate/HowTo/multichannel.jl

@@ -1,10 +1,22 @@
+# # Generate multi channel data
 
+# Here you will learn how to simulate EEG data for multiple channels/electrodes.
+# The idea is to specify a signal on source level and then use a head model or a manual projection matrix to project the source signal to a number of electrodes.
+
+# ### Setup
+# ```@raw html
+# <details>
+# <summary>Click to expand</summary>
+# ```
+## Load required packages
 using UnfoldSim
 using UnfoldMakie
 using CairoMakie
 using DataFrames
 using Random
-
+# ```@raw html
+# </details >
+# ```
 
 # ## Specifying a design
 
@@ -17,7 +29,7 @@ c2 = LinearModelComponent(; basis = p300(), formula = @formula(0 ~ 1), β = [1])
 
 
 # ## The multichannel component
-# next similar to the nested design above, we can nest the component in a `MultichannelComponent`. We could either provide the projection marix manually, e.g.:
+# Next, similar to the nested design above, we can nest the component in a `MultichannelComponent`. We could either provide the projection matrix manually, e.g.:
 mc = UnfoldSim.MultichannelComponent(c, [1, 2, -1, 3, 5, 2.3, 1])
 
 # or maybe more convenient: use the pair-syntax: Headmodel=>Label which makes use of a headmodel (HaRTmuT is currently easily available in UnfoldSim)
@@ -26,7 +38,7 @@ mc = UnfoldSim.MultichannelComponent(c, hart => "Left Postcentral Gyrus")
 mc2 = UnfoldSim.MultichannelComponent(c2, hart => "Right Occipital Pole")
 
 # !!! hint
-#     You could also specify a noise-specific component which is applied prior to projection & summing with other components
+#     You could also specify a noise-specific component which is applied prior to projection & summing with other components.
 # 
 # finally we need to define the onsets of the signal
 onset = UniformOnset(; width = 20, offset = 4);

docs/literate/HowTo/newComponent.jl

@@ -1,13 +1,22 @@
-# # New component: Duration + Shift
+# # Define a new component (with variable duration and shift)
 
-# We want a new component that changes its duration and shift depending on a column in the event-design. This is somewhat already implemented in the HRF + Pupil bases
+# We want a new component that changes its duration and shift depending on a column in the event design. This is somewhat already implemented in the HRF + Pupil bases.
+
+# ### Setup
+# ```@raw html
+# <details>
+# <summary>Click to expand</summary>
+# ```
 using UnfoldSim
 using Unfold
 using Random
 using DSP
 using CairoMakie, UnfoldMakie
 
 sfreq = 100;
+# ```@raw html
+# </details >
+# ```
 
 # ## Design
 # Let's generate a design with two columns, shift + duration
@@ -19,7 +28,8 @@ design = UnfoldSim.SingleSubjectDesign(;
 )
 
 
-# We also need a new AbstractComponent
+# ## Implement a new AbstractComponent
+# We also need a new `AbstractComponent`
 struct TimeVaryingComponent <: AbstractComponent
     basisfunction::Any
     maxlength::Any
@@ -51,7 +61,7 @@ function basis_shiftduration(evts, maxlength)
     end
 end
 
-
+# ## Simulate data with the new component type
 erp = UnfoldSim.simulate(
     MersenneTwister(1),
     TimeVaryingComponent(basis_shiftduration, 50),

docs/literate/HowTo/newDesign.jl

@@ -1,13 +1,24 @@
+# # Define a new (imbalanced) design
+
+# A design specifies how much data is generated, and how the event-table(s)
+# should be generated. Already implemented examples are `MultiSubjectDesign` and `SingleSubjectDesign`.
+
+# We need 3 things for a new design: a `struct<:AbstractDesign`, a `size` and a `generate` function.
+
+# ### Setup
+# ```@raw html
+# <details>
+# <summary>Click to expand</summary>
+# ```
 using UnfoldSim
 using StableRNGs
 using DataFrames
 using Parameters
-# ## Define a new Design
-# A design specifies how much data is generated, and how the event-table(s)
-# should be generated. Already implemented examples are `MultiSubjectDesign` and `SingleSubjectDesign`
-#
-# We need 3 things for a new design: a `struct<:AbstractDesign`, a `size` and a `generate` function
-#
+# ```@raw html
+# </details>
+# <br />
+# ```
+
 # #### 1) `type`
 # We need a `ImbalanceSubjectDesign` struct. You are free to implement it as you wish, as long as the other two functions are implemented
 #

docs/literate/HowTo/predefinedData.jl

@@ -2,10 +2,20 @@
 
 # Let's say you want to use the events data frame (containing the levels of the experimental variables and the event onsets (latencies)) from a previous study in your simulation.
 
+# ### Setup
+# ```@raw html
+# <details>
+# <summary>Click to expand</summary>
+# ```
+## Load required packages
 using UnfoldSim
 using DataFrames
 using Random
 using CairoMakie # for plotting
+# ```@raw html
+# </details >
+# <br />
+# ```
 
 # From a previous study, we (somehow, e.g. by using [pyMNE.jl](https://unfoldtoolbox.github.io/Unfold.jl/dev/HowTo/pymne/)) imported an event data frame like this:
 my_events = DataFrame(:condition => [:A, :B, :B, :A, :A], :latency => [7, 13, 22, 35, 41])

docs/literate/HowTo/repeatTrials.jl

@@ -1,12 +1,10 @@
-using UnfoldSim
-
-
-# ## Repeating Design entries
+# # [Get multiple trials with identical subject/item combinations](@id howto_repeat_design)
 # Sometimes we want to repeat a design, that is, have multiple trials with identical values, but it is not always straight forward to implement. 
 # For instance, there is no way to easily modify `MultiSubjectDesign` to have multiple identical subject/item combinations,
 # without doing awkward repetitions of condition-levels or something.
 
 # If you struggle with this problem `RepeatDesign` is an easy tool for you:
+using UnfoldSim
 
 designOnce = MultiSubjectDesign(;
     n_items = 2,

docs/literate/reference/basistypes.jl

@@ -1,16 +1,25 @@
-using UnfoldSim
-using CairoMakie
-using DSP
-using StableRNGs
-
-# ## Basistypes
+# # Overview: Basis function (component) types
 # There are several basis types directly implemented. They can be easily used for the `components`.
 #
 # !!! note
 #       You can use any arbitrary shape defined by yourself! We often make use of `hanning(50)` from the DSP.jl package.
 
+# ### Setup
+# ```@raw html
+# <details>
+# <summary>Click to expand</summary>
+# ```
+## Load required packages
+using UnfoldSim
+using CairoMakie
+using DSP
+using StableRNGs
+# ```@raw html
+# </details >
+# ```
+
 # ## EEG
-# By default, the EEG bases assume a sampling rate of 100, which can easily be changed by e.g. p100(;sfreq=300)
+# By default, the EEG bases assume a sampling rate of 100, which can easily be changed by e.g. p100(; sfreq=300)
 f = Figure()
 ax = f[1, 1] = Axis(f)
 for b in [p100, n170, p300, n400]

docs/literate/reference/designtypes.jl

@@ -0,0 +1,107 @@
+# # 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
+# ```@raw html
+# <details>
+# <summary>Click to expand</summary>
+# ```
+## Load required packages
+using UnfoldSim
+using Random
+# ```@raw html
+# </details >
+# ```
+
+# ## 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)
+
+# 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 = x -> shuffle(MersenneTwister(42), x),
+);
+# ```@raw html
+# <details>
+# <summary>Click to expand event table </summary>
+# ```
+generate_events(design_single_shuffled)
+# ```@raw html
+# </details >
+# ```
+
+# ## 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](https://github.com/RePsychLing/MixedModelsSim.jl).
+# 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)),
+);
+
+# ```@raw html
+# <details>
+# <summary>Click to expand event table </summary>
+# ```
+generate_events(design_multi)
+# ```@raw html
+# </details >
+# <br />
+# ```
+
+# 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:
+# ```@raw html
+# <details>
+# <summary>Click to expand event table </summary>
+# ```
+generate_events(design_single)
+# ```@raw html
+# </details >
+# <br />
+# ```
+
+
+# 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)
+
+# [Here](@ref howto_repeat_design) one can find another example of how to repeat design entries for multi-subject designs.

docs/literate/reference/noisetypes.jl

@@ -1,10 +1,16 @@
+# # Overview: Noise types
+
+# There are different types of noise signals which differ in their power spectra.
+# If you are not familiar with different types/colors of noise yet, have a look at this [source](https://en.wikipedia.org/wiki/Colors_of_noise).
+
+# There are several noise types directly implemented in UnfoldSim.jl. Here is a comparison:
+
+
 using UnfoldSim
 using CairoMakie
 using DSP
 using StableRNGs
 import StatsBase.autocor
-# ## What's the noise?
-# There are several noise-types directly implemented. Here is a comparison:
 
 f = Figure()
 ax_sig =

docs/literate/reference/onsettypes.jl

@@ -1,13 +1,13 @@
-# # Onset types
+# # Overview: Onset types
 # The onset types determine the distances between event onsets in the continuous EEG signal. The distances are sampled from a certain probability distribution.
 # Currently, there are two types of onset distributions implemented: `UniformOnset` and `LogNormalOnset`.
 
-# ## Setup
+# ### Setup
 # ```@raw html
 # <details>
 # <summary>Click to expand</summary>
 # ```
-
+## Load required packages
 using UnfoldSim
 using CairoMakie
 using Random
@@ -58,11 +58,11 @@ let # hide
                 design, # hide
             ) # hide
 
-            hist!(
-                ax,
-                distances,
-                bins = range(0, 100, step = 1),
-                label = "($width, $offset)",
+            hist!( # hide
+                ax, # hide
+                distances, # hide
+                bins = range(0, 100, step = 1), # hide
+                label = "($width, $offset)", # hide
             ) # hide
 
             if label == "offset" && offset != 0 # hide 

docs/literate/reference/overview.jl

@@ -1,7 +1,17 @@
 # # Overview of functionality
 # UnfoldSim has many modules, here we try to collect them to provide you with an overview.
+
+# ### Setup
+# ```@raw html
+# <details>
+# <summary>Click to expand</summary>
+# ```
+## Load required packages
 using UnfoldSim
 using InteractiveUtils
+# ```@raw html
+# </details>
+# ```
 
 # ## Design
 # Designs define the experimental design. They can be nested, e.g. `RepeatDesign(SingleSubjectDesign,10)` would repeat the generated design-dataframe 10x.

docs/literate/tutorials/multisubject.jl

@@ -1,10 +1,23 @@
+# # Multi-subject simulation
+
+# In this tutorial, you will learn how to simulate data for multiple subjects. In particular, you will learn how to specify fixed and random effects and what their influence on the simulated data looks like.
+
+# ### Setup
+# ```@raw html
+# <details>
+# <summary>Click to expand</summary>
+# ```
+## Load required packages
 using UnfoldSim
 using Unfold
 using CairoMakie
 using UnfoldMakie
 using DataFrames
+# ```@raw html
+# </details >
+# <br />
+# ```
 
-# # Multi-subject simulation
 # Similar to the single subject case, multi-subject simulation depends on:
 # - `Design` (typically a `MultiSubjectDesign`)
 # - `Components` (typically a `MixedModelComponent`)