Splines and plot_erp

Project.toml

@@ -5,6 +5,7 @@ version = "0.5.7"
 
 [deps]
 AlgebraOfGraphics = "cbdf2221-f076-402e-a563-3d30da359d67"
+BSplineKit = "093aae92-e908-43d7-9660-e50ee39d5a0a"
 CategoricalArrays = "324d7699-5711-5eae-9e2f-1d82baa6b597"
 ColorSchemes = "35d6a980-a343-548e-a6ea-1d62b119f2f4"
 ColorTypes = "3da002f7-5984-5a60-b8a6-cbb66c0b333f"
@@ -34,6 +35,7 @@ UnfoldMakiePyMNEExt = "PyMNE"
 
 [compat]
 AlgebraOfGraphics = "0.7, 0.8"
+BSplineKit = "0.16, 0.17"
 CategoricalArrays = "0.10"
 ColorSchemes = "3"
 ColorTypes = "0.11"

docs/Project.toml

@@ -1,5 +1,6 @@
 [deps]
 AlgebraOfGraphics = "cbdf2221-f076-402e-a563-3d30da359d67"
+BSplineKit = "093aae92-e908-43d7-9660-e50ee39d5a0a"
 CSV = "336ed68f-0bac-5ca0-87d4-7b16caf5d00b"
 CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0"
 ColorSchemes = "35d6a980-a343-548e-a6ea-1d62b119f2f4"
@@ -23,4 +24,5 @@ UnfoldSim = "ed8ae6d2-84d3-44c6-ab46-0baf21700804"
 XML2_jll = "02c8fc9c-b97f-50b9-bbe4-9be30ff0a78a"
 
 [compat]
-AlgebraOfGraphics = "0.7, 0.8"
+AlgebraOfGraphics = "0.7, 0.8"
+BSplineKit = "0.16, 0.17"

docs/example_data.jl

@@ -6,24 +6,34 @@ using Random
 """
     example_data(String) 
 
-Creates example data. Currently, 7 datasets are available.
-- `TopoPlots.jl` (default) - tidy DataFrame from `TopoPlots.jl` with 2 conditions, 64 channels and 800 ms time range. 
-- `UnfoldLinearModel`
-- `UnfoldLinearModelMultiChannel`
-- `UnfoldLinearModelContinuousTime`
-- `7channels`
-- `UnfoldTimeExpanded`
-- `sort_data` - includes DataFrame EEG recordings `dat` and `evts` with event variables occured during experiment. `evts` could be used for sorting EEG data in ERP image. 
+Creates example data or model. Currently, 3 datasets and 6 models are available.
+
+Datasets:
+- `TopoPlots.jl` (default) - 2 DataFrames from `TopoPlots.jl`:\\
+    - DataFrame with estimate, time, 64 channels, topopositions, sterror and pvalue and 800 ms time range.\\
+    - Posiions for 64 electrodes.
+- `UnfoldLinearModelMultiChannel` - DataFrame with 5 channels, 3 coefnames, sterror, time and estimate.
+- `sort_data` - 2 DataFrames: 
+    - `dat` for EEG recordings  and `evts` with event variables occured during experiment.\\
+    - `evts` could be used for sorting EEG data in ERP image. 
+
+Models:
+- `UnfoldLinearModel` - Model with formula `1 + condition + continuous`.
+- `UnfoldLinearModelContinuousTime` - Model with formula `timeexpand(1 + condition + continuous)` for times [0.0, 0.01 ... 0.5].
+- `UnfoldLinearModelwith1Spline` - Model with formula `1 + condition + spl(continuous, 4)`.
+- `UnfoldLinearModelwith2Splines` - Model with formula ` 1 + condition + spl(continuous, 4) + spl(continuous2, 6)`.
+- `7channels` - Model with formula `timeexpand(1 + condA)` for times [-0.1, -0.09 ... 0.5].
+- `UnfoldTimeExpanded` - Model with formula `timeexpand(1 + condition + continuous)` for times [-0.4, -0.39 ... 0.8].
+
 **Return Value:** `DataFrame`.
 """
 function example_data(example = "TopoPlots.jl")
-
     if example == "UnfoldLinearModel"
         # load and generate a simulated Unfold Design
         data, evts = UnfoldSim.predef_eeg(; noiselevel = 12, return_epoched = true)
         data = reshape(data, (1, size(data)...))
         f = @formula 0 ~ 1 + condition + continuous
-        # generate ModelStruct
+        # generate ModelStruct 
         se_solver = (x, y) -> Unfold.solver_default(x, y, stderror = true)
         return fit(
             UnfoldModel,
@@ -72,6 +82,38 @@ function example_data(example = "TopoPlots.jl")
         basis = firbasis([0, 0.5], 100)
         # generate ModelStruct
         return fit(UnfoldModel, [Any => (f, basis)], evts, data)
+    elseif example == "UnfoldLinearModelwith1Spline"
+        # load and generate a simulated Unfold Design
+        data, evts = UnfoldSim.predef_eeg(; noiselevel = 12, return_epoched = true)
+        data = reshape(data, (1, size(data)...))
+        evts.continuous2 .=
+            log10.(6 .+ rand(MersenneTwister(1), length(evts.continuous))) .^ 2
+        f = @formula 0 ~ 1 + condition + spl(continuous, 4)
+        # generate ModelStruct
+        se_solver = (x, y) -> Unfold.solver_default(x, y, stderror = true)
+        return fit(
+            UnfoldModel,
+            [Any => (f, range(0, length = size(data, 2), step = 1 / 100))],
+            evts,
+            data;
+            solver = se_solver,
+        )
+    elseif example == "UnfoldLinearModelwith2Splines"
+        # load and generate a simulated Unfold Design
+        data, evts = UnfoldSim.predef_eeg(; noiselevel = 12, return_epoched = true)
+        data = reshape(data, (1, size(data)...))
+        evts.continuous2 .=
+            log10.(6 .+ rand(MersenneTwister(1), length(evts.continuous))) .^ 2
+        f = @formula 0 ~ 1 + condition + spl(continuous, 4) + spl(continuous2, 6)
+        # generate ModelStruct
+        se_solver = (x, y) -> Unfold.solver_default(x, y, stderror = true)
+        return fit(
+            UnfoldModel,
+            [Any => (f, range(0, length = size(data, 2), step = 1 / 100))],
+            evts,
+            data;
+            solver = se_solver,
+        )
     elseif example == "7channels"
         design =
             SingleSubjectDesign(conditions = Dict(:condA => ["levelA", "levelB"])) |>
@@ -89,7 +131,6 @@ function example_data(example = "TopoPlots.jl")
         f = @formula 0 ~ 1 + condA
         bf_dict = [Any => (f, basisfunction)]
         return fit(UnfoldModel, bf_dict, evnts, df)
-
     elseif example == "UnfoldTimeExpanded"
         df, evts = UnfoldSim.predef_eeg()
         f = @formula 0 ~ 1 + condition + continuous

docs/literate/explanations/positions.jl

@@ -4,7 +4,7 @@
 using UnfoldMakie
 using CairoMakie
 using TopoPlots
-using PyMNE
+using PyMNE;
 
 # # Get positions from MNE
 

docs/literate/how_to/hide_deco.jl

@@ -32,17 +32,15 @@ plot_butterfly!(
     data;
     positions = pos,
     topomarkersize = 10,
-    topoheight = 0.4,
-    topowidth = 0.4,
+    topo_axis = (; height = Relative(0.4), width = Relative(0.4)),
     axis = (; title = "With decorations"),
 )
 plot_butterfly!(
     f[2, 1],
     data;
     positions = pos,
     topomarkersize = 10,
-    topoheight = 0.4,
-    topowidth = 0.4,
+    topo_axis = (; height = Relative(0.4), width = Relative(0.4)),
     axis = (; title = "Without decorations"),
     layout = (; hidedecorations = (:label => true, :ticks => true, :ticklabels => true)),
 )

docs/literate/how_to/mult_vis_in_fig.jl

@@ -69,14 +69,7 @@ pvals = DataFrame(
     to = [0.2, 0.5], # if coefname not specified, line should be black
     coefname = ["(Intercept)", "category: face"],
 )
-plot_erp!(
-    f[2, 1:2],
-    results,
-    categorical_color = false,
-    categorical_group = false,
-    significance = pvals,
-    stderror = true,
-)
+plot_erp!(f[2, 1:2], results, significance = pvals, stderror = true)
 
 plot_designmatrix!(f[2, 3], designmatrix(uf))
 
@@ -94,18 +87,14 @@ res_effects = effects(Dict(:continuous => -5:0.5:5), uf_deconv)
 plot_erp!(
     f[2, 4:5],
     res_effects;
-    categorical_color = false,
-    categorical_group = true,
-    mapping = (; y = :yhat, color = :continuous, group = :continuous),
+    mapping = (; y = :yhat, color = :continuous, group = :continuous => nonnumeric),
     legend = (; nbanks = 2),
-    layout = (; show_legend = true, legend_position = :right),
 )
 
 plot_parallelcoordinates(
     f[3, 2:3],
     uf_5chan;
     mapping = (; color = :coefname),
-    layout = (; legend_position = :right),
 )
 
 plot_erpimage!(f[1, 4:5], times, d_singletrial)
@@ -157,8 +146,7 @@ plot_butterfly!(
     d_topo;
     positions = pos,
     topomarkersize = 10,
-    topoheight = 0.4,
-    topowidth = 0.4,
+    topo_axis = (; height = Relative(0.4), width = Relative(0.4)),
 )
 hlines!(0, color = :gray, linewidth = 1)
 vlines!(0, color = :gray, linewidth = 1)

docs/literate/how_to/position2color.jl

@@ -2,6 +2,7 @@
 
 # You want to change the colors of the lines and markers on the inserted topoplot.
 # To do that you need to change the color scheme (aka color map) of the butterfly plot. 
+# You can find th elist of colormaps for Makie [here](https://docs.makie.org/v0.21/explanations/colors). 
 
 # # Setup
 
@@ -19,15 +20,15 @@ plot_butterfly(results; positions = positions)
 # # Color schemes
 # ## MNE style
 
-#= 
-We can change the color scale by specifying a function that maps from an `(x, y)` tuple to a color. UnfoldMakie currently provides three different color scales: 
-- `pos2colorRGB` (same as MNE-Python), 
-- `pos2colorHSV` (HSV color space), 
-- `pos2colorRomaO`. 
+# We can change the color scale by specifying a function that maps from an `(x, y)` tuple to a color. 
+# `UnfoldMakie` currently provides three different color scales: 
+# - `pos2colorRGB` (same as MNE-Python), 
+# - `pos2colorHSV` (HSV color space), 
+# - `pos2colorRomaO`. 
+
+# While `RGB` & `HSV` have the advantage of being 2D color maps, `Roma0` has the advantage of being perceptually uniform.
+# Also you can specify a uniform color.
 
-While `RGB` & `HSV` have the advantage of being 2D color maps, `Roma0` has the advantage of being perceptually uniform.
-Also you can specify a uniform color.
-=#
 
 plot_butterfly(
     results;

docs/literate/intro/code_principles.jl

@@ -3,9 +3,9 @@
 
 # Here we will write about principles which we developed through our publication.
 
-#- Code should be clear and concise
-#- Variables inside the code should have meaningful names
-#- Every function exposed to the user should have documentation that specifies all parameters, types, input and output arguments.
-#- Most people will not look at the defaults, so it is very important to nudge users to show important details with a picture or text.
-#- Function naming should be based on some theory and naming conventions.
-#- You should avoid functions longer 50 lines 
+# - Code should be clear and concise.
+# - Variables inside the code should have meaningful names.
+# - Every function exposed to the user should have documentation that specifies all parameters, types, input and output arguments.
+# - Most people will not look at the defaults, so it is very important to nudge users to label important details of the plot.
+# - Function naming should be based on some theory and naming conventions.
+# - You should avoid functions longer 50 lines. 

docs/literate/tutorials/butterfly.jl

@@ -38,7 +38,12 @@ plot_butterfly(df; positions = pos)
 
 # You want to change size of topomarkers and size of topoplot:
 
-plot_butterfly(df; positions = pos, topomarkersize = 10, topoheight = 0.4, topowidth = 0.4)
+plot_butterfly(
+    df;
+    positions = pos,
+    topomarkersize = 10,
+    topo_axis = (; height = Relative(0.4), width = Relative(0.4)),
+)
 
 # You want to add vline and hline:
 

docs/literate/tutorials/designmatrix.jl

@@ -11,7 +11,7 @@ using CairoMakie
 # Data
 
 include("../../../example_data.jl")
-uf = example_data("UnfoldLinearModel")
+uf = example_data("UnfoldLinearModel");
 
 # # Plot Designmatrices
 

docs/literate/tutorials/erp.jl

@@ -13,7 +13,7 @@ using CairoMakie
 using DataFramesMeta
 using UnfoldSim
 using UnfoldMakie
-include("../../../example_data.jl")
+include("../../../example_data.jl");
 
 # Data generation
 
@@ -36,6 +36,9 @@ res_effects = effects(Dict(:continuous => -5:0.5:5), m);
 # ## Figure plotting
 plot_erp(results)
 
+# To change legend title use `mapping.color`:
+plot_erp(results, mapping = (; color = :coefname => "Conditions"))
+
 # # Additional features
 
 # ## Effect plot
@@ -53,9 +56,7 @@ plot_erp(results)
 plot_erp(
     res_effects;
     mapping = (; y = :yhat, color = :continuous, group = :continuous),
-    layout = (; show_legend = false),
-    categorical_color = false, # perceives color (here: continuous) as contionus 
-    categorical_group = true, # separates lines, if `false` all lines will be connected
+    layout = (; use_colorbar = false),
 )
 
 # ## Significance lines
@@ -68,8 +69,8 @@ plot_erp(
 m = example_data("UnfoldLinearModel")
 results = coeftable(m)
 significancevalues = DataFrame(
-    from = [0.1, 0.3],
-    to = [0.5, 0.7],
+    from = [0.01, 0.2],
+    to = [0.3, 0.4],
     coefname = ["(Intercept)", "condition: face"], # if coefname not specified, line should be black
 )
 plot_erp(results; :significance => significancevalues)
@@ -110,7 +111,7 @@ text!(0.98, 0.2, text = "* Confidence\nintervals", align = (:right, :top))
 f
 
 # There are two ways to implement it.
-# First is using `:stderror = true' after `;`.
+# First is using `:stderror = true` after `;`.
 
 results.se_low = results.estimate .- 0.5
 results.se_high = results.estimate .+ 0.15

docs/literate/tutorials/splines.jl

@@ -0,0 +1,31 @@
+# # [Spline plot](@id spline_vis)
+# **Spline plot** is a plot type for visualisation of  terms in an UnfoldModel. 
+# Two subplots are generated for each spline term: 1) the basis function of the spline; 2) the density of the underlying covariate.
+
+# Multiple spline terms are arranged across columns.
+# Dashed lines indicate spline knots.
+
+# # Setup
+# Package and data loading
+
+using Unfold, UnfoldMakie
+using BSplineKit, DataFrames
+
+
+include("../../../example_data.jl")
+df, pos = example_data("TopoPlots.jl")
+m1 = example_data("UnfoldLinearModelwith1Spline");
+m2 = example_data("UnfoldLinearModelwith2Splines");
+
+
+# Spline plot with one spline term:
+plot_splines(m1)
+
+# Spline plot with two spline terms:
+plot_splines(m2)
+
+# # Configurations of Spline plot
+
+# ```@docs
+# plot_splines
+# ```

docs/literate/tutorials/topoplot.jl

@@ -95,4 +95,4 @@ f
 
 # ```@docs
 # plot_topoplot
-# ```
+# ```

docs/literate/tutorials/topoplotseries.jl

@@ -25,11 +25,21 @@ nothing #hide
 # `bin_width` - specify the interval between topoplots
 
 bin_width = 80
-plot_topoplotseries(df; bin_width, positions = positions)
+plot_topoplotseries(
+    df;
+    bin_width,
+    positions = positions,
+    axis = (; xlabel = "Time windows [s]"),
+)
 
 # `bin_num` - specify the number of topoplots
 
-plot_topoplotseries(df; bin_num = 5, positions = positions)
+plot_topoplotseries(
+    df;
+    bin_num = 5,
+    positions = positions,
+    axis = (; xlabel = "Time windows [s]"),
+)
 
 # # Categorical and contionous x-values
 # By deafult x-value is `time`, but it could be any contionous (i.g. saccade amplitude) or categorical (any experimental variable) value.