erp and butterfly plots

docs/literate/tutorials/erp.jl

@@ -1,6 +1,6 @@
 # ## [Line Plot Visualization](@id lp_vis)
 
-# Here we discuss line plot visualization. 
+# Here we discuss ERP plot visualization. 
 # Make sure you have looked into the [installation instructions](@ref install_instruct).
 
 # ## Include used Modules
@@ -15,7 +15,7 @@ using UnfoldSim
 using UnfoldMakie
 
 # ## Setup
-# Let's generate some data and fit a model of a 2-level categorical and a continuous predictor with interaction.
+# Let's generate some data. We'll fit a model with a 2 level categorical predictor and a continuous predictor with interaction.
 data, evts = UnfoldSim.predef_eeg(; noiselevel = 12, return_epoched = true)
 data = reshape(data, (1, size(data)...))
 f = @formula 0 ~ 1 + condition + continuous
@@ -40,7 +40,7 @@ plot_erp(results; :stderror => true,)
 # `plot_erp` use a `DataFrame` as an input, the library needs to know the names of the columns used for plotting.
 
 # There are multiple default values, that are checked in that order if they exist in the `DataFrame`, a custom name can be chosen using
-# `plot_erp(...;mapping=(; :y=:myEstimate)`
+# `plot_erp(...; mapping=(; :y=:my_estimate)`
 
 # :x Default is `(:x, :time)`.
 # :y Default is `(:y, :estimate, :yhat)`.
@@ -50,10 +50,11 @@ plot_erp(results; :stderror => true,)
 
 # ## key values
 # `plot_erp(...; <name>=<value>,...)`.
-# - categoricalColor (boolean, true) - in case of numeric `:color` column, is color a continuous or categorical variable?
-# - categoricalGroup (boolean, true) - in case of numeric `:group` column, treat `:group` as categorical variable by default
-# - stderror (boolean, false) - add an error-ribbon based on the `:stderror` column
-# - pvalue (see below)
+# - categorical_color (boolean, true) - in case of numeric `:color` column, treat `:color` as continuous or categorical variable.
+# - categorical_group (boolean, true) - in case of numeric `:group` column, treat `:group` as categorical variable by default.
+# - `topolegend` (bool, `false`): add an inlay topoplot with corresponding electrodes.
+# - `stderror` (bool, `false`): add an error ribbon, with lower and upper limits based on the `:stderror` column.
+# - `pvalue` (Array, `[]`): show a pvalue (see below). 
 
 # Using some general configurations we can pretty up the default visualization. Here we use the following configuration:
 
@@ -62,12 +63,10 @@ plot_erp(
     mapping = (; y = :yhat, color = :continuous, group = :continuous),
     legend = (; nbanks = 2),
     layout = (; showLegend = true, legendPosition = :right),
-    categoricalColor = false, categoricalGroup = true,
+    categorical_color = false, categorical_group = true,
 )
 
 
-
-
 # In the following we will use this "pretty" line plot as a basis for looking into configuration options.
 
 # ## pvalue (array)
@@ -77,11 +76,11 @@ plot_erp(
 #
 # Is an array of p-values. If array not empty, plot shows colored lines under the plot representing the p-values. 
 # Default is `[]` (an empty array).
-# Shown below is an example in which `pvalue` are given:
+# Below is an example in which `pvalue` are given:
 # pvals = DataFrame(
 #		from=[0.1,0.3],
 #		to=[0.5,0.7],
-#		coefname=["(Intercept)","condition: face"] # if coefname not specified, line should be black
+#		coefname=["(Intercept)", "condition: face"] # if coefname not specified, line should be black
 #	)
 #
 # plot_erp(results; :pvalue=>pvals)

docs/src/how_to/mult_vis_in_fig.md

@@ -26,7 +26,7 @@ This section discusses how users can incorporate multiple plots into a single fi
 
 By using the !-version of the plotting function and inserting a grid position instead of an entire figure, we can create multiple coordinated views.
 
-We start by creating a figure with Makie.Figure. 
+We will start by creating a figure with Makie.Figure. 
 
 `f = Figure()`
 
@@ -60,8 +60,8 @@ pvals = DataFrame(
     coefname=["(Intercept)", "category: face"]
 )
 plot_erp!(f[2, 1:2], results, 
-    categoricalColor=false,
-    categoricalGroup=false,
+    categorical_color=false,
+    categorical_group=false,
     pvalue=pvals,
     stderror=true)
 
@@ -73,7 +73,7 @@ plot_topoplotseries!(f[4, 1:3], d_topo, 0.1; positions=positions, mapping=(; lab
 
 res_effects = effects(Dict(:continuous => -5:0.5:5), uf_deconv)
 
-plot_erp!(f[2, 4:5], res_effects; categoricalColor=false, categoricalGroup=true,
+plot_erp!(f[2, 4:5], res_effects; categorical_color=false, categorical_group=true,
     mapping=(; y=:yhat, color=:continuous, group=:continuous),
     legend=(; nbanks=2),
     layout=(; showLegend=true, legendPosition=:right))

docs/src/tutorials/butterfly.md

@@ -37,7 +37,7 @@ plot_butterfly(df; positions=pos)
 
 ## Column Mappings for Butterfly Plots
 
-Since butterfly plots use a `DataFrame` as input, the library needs to know the names of the columns used for plotting. You can set these mapping values by calling `plot_butterfly(...; mapping=(; :x=:time,))`, that is, by specifying a `NamedTuple` (note the `;` right after the opening parentheses).
+Since butterfly plots use a `DataFrame` as input, the library needs to know the names of the columns used for plotting. You can set these mapping values by calling `plot_butterfly(...; mapping=(; :x=:time))`, that is, by specifying a `NamedTuple` (note the `;` right after the opening parentheses).
 
 While there are several default values that will be checked in that order if they exist in the `DataFrame`, a custom name may need to be chosen:
 
@@ -54,21 +54,17 @@ Default is `(:labels, :label, :topoLabels, :sensor, :nothing)`
 
 ## Configurations for Butterfly Plots
 
-
 Here we look into possible options for configuring the butterfly plot visualization using `(...; <name>=<value>, ...)`.
-This is the list of unique configuration (key values):
-
-
-- topoLegend (boolean)
-
-### topoLegend (boolean)
-Indicating whether the topo legend is displayed.
-Default is `true`.
-
 
-For more general options look into the `Plot Configuration` section of the documentation.
+## key values
+- `butterfly` (bool, `true`): create a butterfly plot.
+- `topolegend` (bool, `true`): show an inlay topoplot with corresponding electrodes.
+- `topomarkersize` (Real, `10`): change the size of the markers, topoplot-inlay electrodes.
+- `topowidth` (Real, `0.25`): change the size of the inlay topoplot width.
+- `topoheigth` (Real, `0.25`): change the size of the inlay topoplot height.
+- `topopositions_to_color` (function, ´x -> posToColorRomaO(x)´).
 
 
-Since the configurations for line plots can be applied to butterfly plots as well.
-[Here](@ref lp_vis) you can find the configurations for line plots, 
+Since the configurations for ERP plots can be applied to butterfly plots as well.
+[Here](@ref lp_vis) you can find the configurations for ERP plots.
 

src/plot_erp.jl

@@ -9,17 +9,18 @@ Plot an ERP plot.
 
 ## Arguments:
 
-- `f::Union{GridPosition, GridLayout, Figure}`: Figure or GridPosition that the plot should be drawn into
+- `f::Union{GridPosition, GridLayout, Figure}`: Figure, GridLayout or GridPosition that the plot should be drawn into.
 - `plotData::DataFrame`: Data for the line plot visualization.
-- `kwargs...`: Additional styling behavior. Often used: `plot_erp(df; mapping=(; color=:coefname, col=:conditionA))`
+- `kwargs...`: Additional styling behavior. Often used: `plot_erp(df; mapping=(; color=:coefname, col=:conditionA))`.
 
 ## kwargs (...; ...):
 
-- `categoricalColor` (bool, `true`) - Indicates whether the column referenced in mapping.color should be used nonnumerically.
-- `categoricalGroup` (bool, `true`) - Indicates whether the column referenced in mapping.group should be used nonnumerically.
-- `topoLegend` (bool, `false`) - Indicating whether a topo plot is used as a legend.
-- `stderror` (bool, `false`) - Indicating whether the plot should show a colored band showing lower and higher estimates based on the stderror. 
-- `pvalue` (Array, `[]`) - example: `DataFrame(from=[0.1,0.3], to=[0.5,0.7], coefname=["(Intercept)", "condition:face"])` -  if coefname not specified, the lines will be black
+- `categorical_color` (bool, `true`): in case of numeric `:color` column, treat `:color` as continuous or categorical variable.
+- `categorical_group` (bool, `true`): in case of numeric `:group` column, treat `:group` as categorical variable by default.
+- `topolegend` (bool, `false`): add an inlay topoplot with corresponding electrodes.
+- `stderror` (bool, `false`): add an error ribbon, with lower and upper limits based on the `:stderror` column.
+- `pvalue` (Array, `[]`): show a pvalue.
+    - example: `DataFrame(from=[0.1, 0.3], to=[0.5, 0.7], coefname=["(Intercept)", "condition:face"])` -  if coefname is not specified, the lines will be black
 
 
 $(_docstring(:erp))
@@ -32,16 +33,18 @@ $(_docstring(:erp))
 plot_erp(plotData::DataFrame; kwargs...) = plot_erp!(Figure(), plotData, ; kwargs...)
 
 """
-Plot Butterfly
+Plot a butterfly plot
 
-$(_docstring(:butterfly))
-
-## key-word arguments
+## kwargs (...; ...):
 
-- `topomarkersize` (Real, `10`) - change the size of the markers, topoplot-inlay electrodes
-- `topowidth` (Real, `0.25`) - change the size of the inlay topoplot width
-- `topoheigth` (Real, `0.25`) - change the size of the inlay topoplot height
+- `butterfly` (bool, `true`): create a butterfly plot.
+- `topolegend` (bool, `true`): show an inlay topoplot with corresponding electrodes.
+- `topomarkersize` (Real, `10`): change the size of the markers, topoplot-inlay electrodes.
+- `topowidth` (Real, `0.25`): change the size of the inlay topoplot width.
+- `topoheigth` (Real, `0.25`): change the size of the inlay topoplot height.
+- `topopositions_to_color` (function, ´x -> posToColorRomaO(x)´).
 
+$(_docstring(:butterfly))
 see also [`plot_erp`](@Ref)
 """
 plot_butterfly(plotData::DataFrame; kwargs...) =
@@ -55,11 +58,11 @@ plot_butterfly!(
     f,
     plotData;
     butterfly = true,
-    topoLegend = true,
+    topolegend = true,
     topomarkersize = 10,
     topowidth = 0.25,
     topoheigth = 0.25,
-    topoPositionToColorFunction = x -> posToColorRomaO(x),
+    topopositions_to_color = x -> posToColorRomaO(x),
     kwargs...,
 )
 
@@ -70,16 +73,16 @@ function plot_erp!(
     plotData::DataFrame;
     positions = nothing,
     labels = nothing,
-    categoricalColor = true,
-    categoricalGroup = true,
+    categorical_color = true,
+    categorical_group = true,
     stderror = false, # XXX if it exists, should be plotted
     pvalue = [],
     butterfly = false,
-    topoLegend = nothing,
+    topolegend = nothing,
     topomarkersize = nothing,
     topowidth = nothing,
     topoheigth = nothing,
-    topoPositionToColorFunction = nothing,
+    topopositions_to_color = nothing,
     kwargs...,
 )
     config = PlotConfig(:erp)
@@ -117,26 +120,26 @@ function plot_erp!(
     # Get topocolors for butterfly
     if (butterfly)
         if isnothing(positions) && isnothing(labels)
-            topoLegend = false
+            topolegend = false
             #colors = config.visual.colormap# get(colorschemes[config.visual.colormap],range(0,1,length=nrow(plotData)))
             colors = nothing
             #config.mapping = merge(config.mapping,(;color=config.))
         else
             allPositions = getTopoPositions(; positions = positions, labels = labels)
-            colors = getTopoColor(allPositions, topoPositionToColorFunction)
+            colors = getTopoColor(allPositions, topopositions_to_color)
         end
 
 
     end
     # Categorical mapping
     # convert color column into string, so no wrong grouping happens
-    if categoricalColor && (:color ∈ keys(config.mapping))
+    if categorical_color && (:color ∈ keys(config.mapping))
         config.mapping =
             merge(config.mapping, (; color = config.mapping.color => nonnumeric))
     end
 
     # converts group column into string
-    if categoricalGroup && (:group ∈ keys(config.mapping))
+    if categorical_group && (:group ∈ keys(config.mapping))
         config.mapping =
             merge(config.mapping, (; group = config.mapping.group => nonnumeric))
     end
@@ -175,9 +178,9 @@ function plot_erp!(
     f_grid = f[1, 1]
     # butterfly plot is drawn slightly different
     if butterfly
-        # add topoLegend
+        # add topolegend
 
-        if (topoLegend)
+        if (topolegend)
             topoAxis = Axis(
                 f_grid,
                 width = Relative(topowidth),
@@ -189,7 +192,7 @@ function plot_erp!(
             topoplotLegend(
                 topoAxis,
                 topomarkersize,
-                topoPositionToColorFunction,
+                topopositions_to_color,
                 allPositions,
             )
         end
@@ -227,14 +230,14 @@ function eegHeadMatrix(positions, center, radius)
     )
 end
 
-function topoplotLegend(axis, topomarkersize, topoPositionToColorFunction, allPositions)
+function topoplotLegend(axis, topomarkersize, topopositions_to_color, allPositions)
     allPositions = unique(allPositions)
 
     topoMatrix = eegHeadMatrix(allPositions, (0.5, 0.5), 0.5)
 
     # colorscheme where first entry is 0, and exactly length(positions)+1 entries
     specialColors = ColorScheme(
-        vcat(RGB(1, 1, 1.0), [topoPositionToColorFunction(pos) for pos in allPositions]...),
+        vcat(RGB(1, 1, 1.0), [topopositions_to_color(pos) for pos in allPositions]...),
     )
 
     xlims!(low = -0.2, high = 1.2)