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

@@ -19,6 +19,7 @@ Creates example data. Currently, 7 datasets are available.
 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)...))
@@ -32,6 +33,38 @@ function example_data(example = "TopoPlots.jl")
             data;
             solver = se_solver,
         )
+    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 == "UnfoldLinearModelMultiChannel"
         # load and generate a simulated Unfold Design
         cAll = DataFrame()

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/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,9 +87,7 @@ 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),
 )

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/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
 
@@ -54,8 +54,6 @@ 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
 )
 
 # ## Significance lines
@@ -68,8 +66,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)

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/make.jl

@@ -40,7 +40,7 @@ makedocs(;
             "Plot types" => "generated/intro/plot_types.md",
             "Code principles" => "generated/intro/code_principles.md",
         ],
-        "Visualization Types" => [
+        "ERP Visualizations" => [
             "ERP plot" => "generated/tutorials/erp.md",
             "Butterfly plot" => "generated/tutorials/butterfly.md",
             "Topoplot" => "generated/tutorials/topoplot.md",
@@ -49,9 +49,12 @@ makedocs(;
             "ERP image" => "generated/tutorials/erpimage.md",
             "Channel image" => "generated/tutorials/channel_image.md",
             "Parallel coordinates" => "generated/tutorials/parallelcoordinates.md",
-            "Design matrix" => "generated/tutorials/designmatrix.md",
             "Circular topoplots" => "generated/tutorials/circ_topo.md",
         ],
+        "Unfold-specific Visualisations" => [
+            "Design matrix" => "generated/tutorials/designmatrix.md",
+            "Spline plot" => "generated/tutorials/splines.md",
+        ],
         "How To" => [
             "Change colormap of Butterfly plot" => "generated/how_to/position2color.md",
             "Hide decorations and axis spines" => "generated/how_to/hide_deco.md",

docs/src/index.md

@@ -8,7 +8,7 @@ This is the documentation of the UnfoldMakie.jl package for the Julia programmin
 
 ## Highlights of UnfoldMakie.jl
 
-- **10 plot functions for displaying ERPs.**
+- **11 plot functions for displaying ERPs.**
 Each plot emphasizes certain dimensions while collapsing others.
 - **Fast plotting**
 Plot one figure with 20 topoplots in 1 second? No problemo!
@@ -17,6 +17,6 @@ The package is primarily based on [Unfold.jl](https://github.com/unfoldtoolbox/u
 - **Many usage examples**
 You can find many user-friendly examples of how to use and adapt the plots in this documentation.
 - **Scientific colormaps by default**
-According to our study [(Mikheev, 2024)](https://apertureneuro.org/article/116386-the-art-of-brainwaves-a-survey-on-event-related-potential-visualization-practices), 40% of EEG researchers do not know about the issue of scientific color maps. By default, we use `Reverse(:RdBu)` (based on [colorbrewer](https://colorbrewer2.org/#type=sequential&scheme=BuGn&n=3)) and `Roma` (based on [Sceintific Colormaps](https://www.fabiocrameri.ch/colourmaps/) by Fabio Crameri) as default color maps. 
+According to our study [(Mikheev, 2024)](https://apertureneuro.org/article/116386-the-art-of-brainwaves-a-survey-on-event-related-potential-visualization-practices), 40% of EEG researchers do not know about the issue of scientific color maps. As default color maps we use `Reverse(:RdBu)` (based on [colorbrewer](https://colorbrewer2.org/#type=sequential&scheme=BuGn&n=3)) and `Roma` (based on [Sceintific Colormaps](https://www.fabiocrameri.ch/colourmaps/) by Fabio Crameri).
 - **Interactivity** 
 Several plots make use of `Observables.jl` which allows fast updating of the underlying data. Several plots already have predefined interactive features, e.g. you can click on labels to enable / disable them. See `plot_topoplotseries` and `plot_erpimage` for examples.

src/UnfoldMakie.jl

@@ -55,6 +55,7 @@ include("plot_topoplotseries.jl")
 include("plot_erp.jl")
 include("plot_butterfly.jl")
 include("plot_designmatrix.jl")
+include("plot_splines.jl")
 include("plot_topoplot.jl")
 include("plot_erpimage.jl")
 include("plot_parallelcoordinates.jl")
@@ -71,6 +72,8 @@ export PlotConfig
 
 export plot_designmatrix
 export plot_designmatrix!
+export plot_splines
+export plot_splines!
 export plot_erp
 export plot_erp!
 export plot_erpimage
@@ -95,4 +98,7 @@ export to_positions
 export eeg_array_to_dataframe
 export eeg_topoplot_series
 export nonnumeric # reexport from AoG
+
+export config_kwargs!
+export update_axis!
 end

src/docstring_template.jl

@@ -14,6 +14,7 @@ function _docstring(cfg_symb::Symbol)
         :circtopos => `Topoplot.eeg_topoplot`,
         :topoplot => `Topoplot.eeg_topoplot`,
         :topoplotseries => `Topoplot.eeg_topoplot`,
+        :splines => `Makie.series`,
     )
     visuallink2 = Dict(
         :erp => "https://docs.makie.org/stable/reference/plots/lines/",
@@ -26,6 +27,7 @@ function _docstring(cfg_symb::Symbol)
         :circtopos => "https://makieorg.github.io/TopoPlots.jl/stable/eeg/",
         :topoplot => "https://makieorg.github.io/TopoPlots.jl/stable/eeg/",
         :topoplotseries => "https://makieorg.github.io/TopoPlots.jl/stable/eeg/",
+        :splines => "https://docs.makie.org/stable/reference/plots/series",
     )
     cbarstring =
         (cfg_symb == :erp || cfg_symb == :butterfly) ?

src/layout_helper.jl

@@ -9,43 +9,12 @@ function apply_layout_settings!(
     hm = nothing,
     drawing = nothing,
     ax = nothing,
-    plotArea = (1, 1),
+    plot_area = (1, 1),
 )
     if isnothing(ax)
         ax = current_axis()
     end
 
-    if (config.layout.show_legend)
-        if isnothing(fig)
-            @error "Legend needs `Figure` parameter"
-        else
-            # set f[] position depending on legend_position
-            legend_position =
-                config.layout.legend_position == :right ?
-                fig[1:plotArea[1], plotArea[2]+1] : fig[plotArea[1]+1, 1:plotArea[2]]
-            if isnothing(drawing)
-                if (config.layout.use_colorbar) #not sure this line is useful
-                    if isnothing(hm)
-                        Colorbar(
-                            legend_position;
-                            colormap = config.visual.colormap,
-                            config.colorbar...,
-                        )
-                    else
-                        Colorbar(legend_position, hm; config.colorbar...)
-                    end
-                else # for PCP
-                    title_pcp = getproperty.(Ref(config.legend), :title) # pop title
-                    config.legend = dropnames(config.legend, (:title,)) # delete title
-                    Legend(legend_position, ax, title_pcp; config.legend...)
-                end
-            else
-                legend!(legend_position, drawing; config.legend...)
-                colorbar!(legend_position, drawing; config.colorbar...)
-            end
-        end
-    end
-
     if :hidespines ∈ keys(config.layout) && !isnothing(config.layout.hidespines)
         Makie.hidespines!(ax, config.layout.hidespines...)
     end
@@ -58,6 +27,4 @@ Makie.hidedecorations!(ax::Matrix{AxisEntries}; kwargs...) =
     Makie.hidedecorations!.(ax; kwargs...)
 Makie.hidespines!(ax::Matrix{AxisEntries}, args...) = Makie.hidespines!.(ax, args...)
 
-#hidedecorations!(ax::AxisEntries;kwargs...) = Makie.hidedecorations!.(ax.axis;kwargs...)
 Makie.hidespines!(ax::AxisEntries, args...) = Makie.hidespines!.(ax.axis, args...)
-#hidespinses!(ax:Axis,args...) = hiespines!.(Ref(ax),args...)