Address joss paper comments

.all-contributorsrc

@@ -57,7 +57,8 @@
         "bug",
         "doc",
         "tutorial",
-        "code"
+        "code",
+        "test"
       ]
     },
     {

CONTRIBUTING.md

@@ -0,0 +1,18 @@
+# Contribution guide
+Contributions are very welcome. These could be typos, bug reports, feature requests, speed optimization, better code, and better documentation.
+You are very welcome to raise issues and start pull requests.
+
+## Bug reports
+If you notice any bugs, such as crashing code, incorrect results or speed issues, please raise a GitHub issue. The issue should contain a short description of the problem, (optimally) a minimal working example to reproduce the bug and which UnfoldSim.jl version you are using.
+
+## Code contributions (Pull requests)
+When opening a pull request, please add a short but meaningful description of the changes/features you implemented. Moreover, please add tests (where appropriate) to ensure that your code is working as expected.
+
+## Adding documentation
+1. We recommend to write a Literate.jl document and place it in `docs/literate/FOLDER/FILENAME.jl` with `FOLDER` being `HowTo`, `Explanation`, `Tutorial` or `Reference` ([recommended reading on the 4 categories](https://documentation.divio.com/)).
+2. Literate.jl converts the `.jl` file to a `.md` automatically and places it in `docs/src/generated/FOLDER/FILENAME.md`.
+3. Edit [make.jl](https://github.com/unfoldtoolbox/Unfold.jl/blob/main/docs/make.jl) with a reference to `docs/src/generated/FOLDER/FILENAME.md`.
+
+## Formatting (Beware of reviewdog :dog:)
+We use the [julia-format](https://github.com/julia-actions/julia-format) Github action to ensure that the code follows the formatting rules defined by [JuliaFormatter.jl](https://github.com/domluna/JuliaFormatter.jl).
+When opening a pull request [reviewdog](https://github.com/reviewdog/reviewdog) will automatically make formatting suggestions for your code.

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022 Luis Lips, Benedikt Ehinger, Judith Schepers
+Copyright (c) 2022-2024: Benedikt Ehinger, Judith Schepers, Luis Lips, Maanik Marathe and other contributors: https://github.com/unfoldtoolbox/UnfoldSim.jl?tab=readme-ov-file#contributors.
 
 
 Permission is hereby granted, free of charge, to any person obtaining a copy

Project.toml

@@ -1,7 +1,7 @@
 name = "UnfoldSim"
 uuid = "ed8ae6d2-84d3-44c6-ab46-0baf21700804"
 authors = ["Benedikt Ehinger", "Luis Lips", "Judith Schepers", "Maanik Marathe"]
-version = "0.1.7"
+version = "0.3.2"
 
 [deps]
 Artifacts = "56f22d72-fd6d-98f1-02f0-08ddc0907c33"

README.md

@@ -13,9 +13,9 @@
 A Julia package to simulate multivariate time series, e.g. model-based ERPs, fMRI activity, pupil dilation etc.
 UnfoldSim.jl provides multi-channel support via EEG-forward models. Moreover, it is possible to simulate overlapping event-related activity and to add noise of a certain type e.g. Pink noise.
 
-Many Tutorials, Guides, How-Tos and References available in the [documentation](https://unfoldtoolbox.github.io/UnfoldSim.jl/dev/)!
+Many tutorials, guides, how-tos and references are available in the [documentation](https://unfoldtoolbox.github.io/UnfoldSim.jl/dev/)!
 
-![grafik](https://user-images.githubusercontent.com/10183650/213565922-90feec23-3b51-4602-b50c-31561dbfc261.png)
+![readme_figure](https://github.com/unfoldtoolbox/UnfoldSim.jl/assets/22366977/b69d186c-fd3d-4449-9f2e-03d7e01b8cb3)
 
 ## Install
 
@@ -41,46 +41,45 @@ AppStore -> JuliaUp,  or `winget install julia -s msstore` in CMD
 
 ```julia
 using Pkg
-Pkg.add("https://github.com/unfoldtoolbox/UnfoldSim.jl/tree/main")
+Pkg.add("UnfoldSim")
 ```
 
-Once the toolbox is registered this will translate to ```Pkg.add("UnfoldSim")```
-
-
 # Quickstart
 ```julia
-data,evts = UnfoldSim.predef_eeg(;n_repeats=1,noiselevel=0.8)
+using UnfoldSim
+data, events = UnfoldSim.predef_eeg(; n_repeats = 1, noiselevel = 0.8)
 ```
-Produces continuous "EEG" with PinkNoise and some Overlap between 20 events (2 conditions * 10 levels of continuous variable).
+Produces continuous "EEG" with PinkNoise and some overlap between 20 events (2 conditions * 10 levels of the continuous variable).
 
 ## Slightly longer
 ```julia
-# start by defining the design / event-table
-design = SingleSubjectDesign(;conditions=Dict(:condA=>["levelA","levelB"])) |> d->RepeatDesign(d,10);
-# next define a ground-truth signal + relation to events/design with Wilkinson Formulas
+using UnfoldSim
+using Random
+
+# Start by defining the design / events data frame
+design =
+    SingleSubjectDesign(; conditions = Dict(:condA => ["levelA", "levelB"])) |>
+    d -> RepeatDesign(d, 10);
+
+# Next define a ground truth signal + relation to events/design with Wilkinson formulas
 signal = LinearModelComponent(;
-        basis=[0,0,0,0.5,1,1,0.5,0,0],
-        formula = @formula(0~1+condA),
-        β = [1,0.5]
-        );
-# finally, define some Onset Distribution and Noise, and simulate!
-data,events = simulate(Random.MersenneTwister(1),design, signal,  UniformOnset(;offset=5,width=4), PinkNoise());        
+    basis = [0, 0, 0, 0.5, 1, 1, 0.5, 0, 0],
+    formula = @formula(0 ~ 1 + condA),
+    β = [1, 0.5],
+);
+# finally, define some inter-onset distribution and noise, and simulate data!
+data, events = simulate(
+    Random.MersenneTwister(1),
+    design,
+    signal,
+    UniformOnset(; offset = 5, width = 4),
+    PinkNoise(),
+);    
 ```
 All components (design, components, onsets, noise) can be easily modified and you can simply plugin your own!
 
 ## Contributions
-
-Contributions are very welcome. These could be typos, bugreports, feature-requests, speed-optimization, new solvers, better code, better documentation.
-
-### How-to Contribute
-
-You are very welcome to raise issues and start pull requests!
-
-### Adding Documentation
-
-1. We recommend to write a Literate.jl document and place it in `docs/literate/FOLDER/FILENAME.jl` with `FOLDER` being `HowTo`, `Explanation`, `Tutorial` or `Reference` ([recommended reading on the 4 categories](https://documentation.divio.com/)).
-2. Literate.jl converts the `.jl` file to a `.md` automatically and places it in `docs/src/generated/FOLDER/FILENAME.md`.
-3. Edit [make.jl](https://github.com/unfoldtoolbox/Unfold.jl/blob/main/docs/make.jl) with a reference to `docs/src/generated/FOLDER/FILENAME.md`.
+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.
 
 ## Contributors
 <!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
@@ -92,7 +91,7 @@ You are very welcome to raise issues and start pull requests!
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/maanikmarathe"><img src="https://avatars.githubusercontent.com/u/66105649?v=4?s=100" width="100px;" alt="Maanik Marathe"/><br /><sub><b>Maanik Marathe</b></sub></a><br /><a href="#doc-maanikmarathe" title="Documentation">📖</a> <a href="#code-maanikmarathe" title="Code">💻</a></td>
       <td align="center" valign="top" width="14.28%"><a href="http://www.benediktehinger.de"><img src="https://avatars.githubusercontent.com/u/10183650?v=4?s=100" width="100px;" alt="Benedikt Ehinger"/><br /><sub><b>Benedikt Ehinger</b></sub></a><br /><a href="#bug-behinger" title="Bug reports">🐛</a> <a href="#code-behinger" title="Code">💻</a> <a href="#doc-behinger" title="Documentation">📖</a> <a href="#ideas-behinger" title="Ideas, Planning, & Feedback">🤔</a> <a href="#infra-behinger" title="Infrastructure (Hosting, Build-Tools, etc)">🚇</a> <a href="#maintenance-behinger" title="Maintenance">🚧</a> <a href="#review-behinger" title="Reviewed Pull Requests">👀</a> <a href="#test-behinger" title="Tests">⚠️</a> <a href="#tutorial-behinger" title="Tutorials">✅</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/llips"><img src="https://avatars.githubusercontent.com/u/38983684?v=4?s=100" width="100px;" alt="Luis"/><br /><sub><b>Luis</b></sub></a><br /><a href="#bug-llips" title="Bug reports">🐛</a> <a href="#code-llips" title="Code">💻</a> <a href="#doc-llips" title="Documentation">📖</a> <a href="#ideas-llips" title="Ideas, Planning, & Feedback">🤔</a></td>
-      <td align="center" valign="top" width="14.28%"><a href="https://github.com/jschepers"><img src="https://avatars.githubusercontent.com/u/22366977?v=4?s=100" width="100px;" alt="Judith Schepers"/><br /><sub><b>Judith Schepers</b></sub></a><br /><a href="#ideas-jschepers" title="Ideas, Planning, & Feedback">🤔</a> <a href="#bug-jschepers" title="Bug reports">🐛</a> <a href="#doc-jschepers" title="Documentation">📖</a> <a href="#tutorial-jschepers" title="Tutorials">✅</a> <a href="#code-jschepers" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/jschepers"><img src="https://avatars.githubusercontent.com/u/22366977?v=4?s=100" width="100px;" alt="Judith Schepers"/><br /><sub><b>Judith Schepers</b></sub></a><br /><a href="#ideas-jschepers" title="Ideas, Planning, & Feedback">🤔</a> <a href="#bug-jschepers" title="Bug reports">🐛</a> <a href="#doc-jschepers" title="Documentation">📖</a> <a href="#tutorial-jschepers" title="Tutorials">✅</a> <a href="#code-jschepers" title="Code">💻</a> <a href="#test-jschepers" title="Tests">⚠️</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/vladdez"><img src="https://avatars.githubusercontent.com/u/33777074?v=4?s=100" width="100px;" alt="Vladimir Mikheev"/><br /><sub><b>Vladimir Mikheev</b></sub></a><br /><a href="#bug-vladdez" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://reboreexplore.github.io/"><img src="https://avatars.githubusercontent.com/u/43548330?v=4?s=100" width="100px;" alt="Manpa Barman"/><br /><sub><b>Manpa Barman</b></sub></a><br /><a href="#infra-ReboreExplore" title="Infrastructure (Hosting, Build-Tools, etc)">🚇</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://reneskukies.de/"><img src="https://avatars.githubusercontent.com/u/57703446?v=4?s=100" width="100px;" alt="René Skukies"/><br /><sub><b>René Skukies</b></sub></a><br /><a href="#doc-ReneSkukies" title="Documentation">📖</a></td>
@@ -108,13 +107,12 @@ You are very welcome to raise issues and start pull requests!
 
 
 This project follows the [all-contributors](https://allcontributors.org/docs/en/specification) specification. 
-
-Contributions of any kind welcome!
+Please reach out, if you have contributed to UnfoldSim.jl but we have not listed you as a contributor yet.
 
 ## Citation
 
 TBA
 
 ## Acknowledgements
 
-Funded by Deutsche Forschungsgemeinschaft (DFG, German Research Foundation) under Germany´s Excellence Strategy – EXC 2075 – 390740016
+Funded by Deutsche Forschungsgemeinschaft (DFG, German Research Foundation) under Germany´s Excellence Strategy – EXC 2075 – 390740016. Furthermore, the authors thank the International Max Planck Research School for Intelligent Systems (IMPRS-IS) for supporting Judith Schepers.

docs/literate/HowTo/newComponent.jl

@@ -30,24 +30,24 @@ Base.length(c::TimeVaryingComponent) = length(c.maxlength)
 
 # While we could have put the TimeVaryingComponent.basisfunction directly into the simulate function, I thought this is a bit more modular
 function UnfoldSim.simulate(rng, c::TimeVaryingComponent, design::AbstractDesign)
-    evts = generate(design)
+    evts = generate_events(design)
     return c.basisfunction(evts, c.maxlength)
 end
 
 # finally, the actual function that does the shifting + duration
 function basis_shiftduration(evts, maxlength)
     basis = hanning.(Int.(round.(evts.duration))) ## hanning as long as duration
     if "shift" ∈ names(evts)
-        basis = padarray.(basis, Int.(round.(.-evts.shift)), 0) ## shift by adding 0 in front
+        basis = pad_array.(basis, Int.(round.(.-evts.shift)), 0) ## shift by adding 0 in front
     end
     ## we should make sure that all bases have maxlength by appending / truncating
     difftomax = maxlength .- length.(basis)
     if any(difftomax .< 0)
         @warn "basis longer than max length in at least one case. either increase maxlength or redefine function. Trying to truncate the basis"
-        basis[difftomax.>0] = padarray.(basis[difftomax.>0], difftomax[difftomax.>0], 0)
+        basis[difftomax.>0] = pad_array.(basis[difftomax.>0], difftomax[difftomax.>0], 0)
         return [b[1:maxlength] for b in basis]
     else
-        return padarray.(basis, difftomax, 0)
+        return pad_array.(basis, difftomax, 0)
     end
 end
 
@@ -57,4 +57,4 @@ erp = UnfoldSim.simulate(
     TimeVaryingComponent(basis_shiftduration, 50),
     design,
 )
-plot_erpimage(hcat(erp...), sortvalues = generate(design).shift)
+plot_erpimage(hcat(erp...), sortvalues = generate_events(design).shift)

docs/literate/HowTo/newDesign.jl

@@ -24,8 +24,8 @@ end;
 size(design::ImbalanceSubjectDesign) = (design.nTrials,);
 
 # #### 3) `generate`
-# We need a type `generate(design::ImbalanceSubjectDesign)` function. This function should return the actual table as a `DataFrame`
-function generate(design::ImbalanceSubjectDesign)
+# We need a type `generate_events(design::ImbalanceSubjectDesign)` function. This function should return the actual table as a `DataFrame`
+function generate_events(design::ImbalanceSubjectDesign)
     nA = Int(round.(design.nTrials .* design.balance))
     nB = Int(round.(design.nTrials .* (1 - design.balance)))
     @assert nA + nB ≈ design.nTrials
@@ -35,7 +35,7 @@ end;
 
 # Finally, we can test the function and see whether it returns a Design-DataFrame as we requested
 design = ImbalanceSubjectDesign(; nTrials = 6, balance = 0.2)
-generate(design)
+generate_events(design)
 
 # !!! warning "Important"
 #       It is the users task to ensure that each run is reproducible. So if you have a random process (e.g. shuffling), be sure to 

docs/literate/HowTo/predefinedData.jl

@@ -0,0 +1,53 @@
+# # Use existing experimental designs & onsets in the simulation
+
+# 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.
+
+using UnfoldSim
+using DataFrames
+using Random
+using CairoMakie # for plotting
+
+# 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])
+
+# To use exactly these values, we can generate a new `AbstractDesign`, which will always return this event dataframe
+struct MyManualDesign <: AbstractDesign
+    my_events::Any
+end
+UnfoldSim.generate_events(d::MyManualDesign) = deepcopy(d.my_events) ## generate function which is called internally in UnfoldSim
+UnfoldSim.size(d::MyManualDesign) = size(d.my_events, 1); ## necessary function to tell what the dimensionality of the experimental design is
+# !!! note
+#     Note the `UnfoldSim.generate_events` which tells Julia to "overload" the `generate_events` function as defined in UnfoldSim.
+
+
+# Next we generate a `MyManualDesign`
+mydesign = MyManualDesign(my_events);
+
+# We could already use this "solo" and simulate some data, for example:
+signal = LinearModelComponent(;
+    basis = [1, 1, 0.5, 0, 0],
+    formula = @formula(0 ~ 1 + condition),
+    β = [1, 0.5],
+);
+
+data, events =
+    simulate(MersenneTwister(1), mydesign, signal, UniformOnset(; width = 10, offset = 5))
+lines(data) # plotting 
+vlines!(my_events.latency; linestyle = :dash)
+current_figure()
+# Looks good, but the events don't match our custom onsets yet.
+
+# ## Custom Timings
+# Finally, we want to use our custom timings as well. For this we define a new `AbstractOnset`. Again, it simply returns our manually provided latencies
+struct MyManualOnset <: AbstractOnset end
+UnfoldSim.simulate_onsets(rng, onset::MyManualOnset, simulation::Simulation) =
+    generate_events(simulation.design).latency
+# !!! hint
+#     This is a bit of a trick, it relies that `MyManualOnset` is always used in combination with `MyManualDesign`. You could of course repeat the structure from `MyManualDesign` also for `MyManualOnset` and have an explicit field in the structure containing the onsets.
+
+# And that's it
+data, events = simulate(MersenneTwister(1), mydesign, signal, MyManualOnset())
+lines(data) # plotting 
+vlines!(my_events.latency, linestyle = :dash)
+current_figure()
+# now everything matches, lovely!

docs/literate/HowTo/repeatTrials.jl

@@ -16,7 +16,7 @@ designOnce = MultiSubjectDesign(;
 );
 
 design = RepeatDesign(designOnce, 4);
-generate(design)
+generate_events(design)
 
 # As you can see, the design was simply repeated.
 

docs/literate/reference/basistypes.jl

@@ -26,11 +26,11 @@ f
 f = Figure()
 plotConfig = (
     :peak => 1:3:10,
-    :psUnder => 10:5:30,
+    :post_undershoot => 10:5:30,
     :amplitude => 2:5,
     :shift => 0:3:10,
     :peak_width => 0.1:0.5:1.5,
-    :psUnder_width => 0.1:0.5:1.5,
+    :post_undershoot_width => 0.1:0.5:1.5,
 )
 
 for (ix, pl) in enumerate(plotConfig)

docs/literate/reference/noisetypes.jl

@@ -7,13 +7,27 @@ import StatsBase.autocor
 # There are several noise-types directly implemented. Here is a comparison:
 
 f = Figure()
-ax_sig = f[1, 1:2] = Axis(f; title = "1.000 samples of noise")
-ax_spec = f[2, 1] = Axis(f; title = "Welch Periodigram")
-ax_auto = f[2, 2] = Axis(f; title = "Autocorrelogram (every 10th lag)")
+ax_sig =
+    f[1, 1:3] =
+        Axis(f; title = "1.000 samples of noise", xlabel = "Time", ylabel = "Amplitude")
+ax_spec =
+    f[2, 1:2] = Axis(
+        f;
+        title = "Welch Periodogram",
+        xlabel = "Normalized frequency",
+        ylabel = "log(Power)",
+    )
+ax_auto =
+    f[2, 3:4] = Axis(
+        f;
+        title = "Autocorrelogram (every 10th lag)",
+        xlabel = "Lag",
+        ylabel = "Autocorrelation",
+    )
 for n in [PinkNoise RedNoise WhiteNoise NoNoise ExponentialNoise]
 
     ## generate
-    noisevec = gen_noise(StableRNG(1), n(), 10000)
+    noisevec = simulate_noise(StableRNG(1), n(), 10000)
 
     ## plot 1000 samples
     lines!(ax_sig, noisevec[1:1000]; label = string(n))
@@ -29,7 +43,7 @@ for n in [PinkNoise RedNoise WhiteNoise NoNoise ExponentialNoise]
     lines!(ax_auto, lags, autocor_vec)
 
 end
-f[1:2, 3] = Legend(f, ax_sig, "NoiseType")
+f[1, 4] = Legend(f, ax_sig, "Noise type", tellheight = true)
 f