Merge pull request #180 from unfoldtoolbox/issues4

facetting and circular allignment - #49 fixed - #182 fixed - #183 partially fixed - new selling points added - compatibility with new Makie version - attempts to implement plot_dm with hierarchical labels Toposeries - bin_width instead of Δbin, bin_num, nrows as parameters added - code reformatting: big function into smaller functions - col_labels = true as deafult Tests - several tests for error managment - tests for topoplotseries are divided on simple and advanced
unfoldtoolbox · Jun 17, 2024 · 99d6f58 · 99d6f58
2 parents 1ac5b69 + f5598b0
commit 99d6f58
Show file tree

Hide file tree

Showing 36 changed files with 908 additions and 660 deletions.
diff --git a/docs/literate/reference/positions.jl → docs/literate/explanations/positions.jl b/docs/literate/reference/positions.jl → docs/literate/explanations/positions.jl
diff --git a/docs/literate/how_to/hide_deco.jl b/docs/literate/how_to/hide_deco.jl
@@ -28,7 +28,7 @@ plot_butterfly!(
     data;
     positions = pos,
     topomarkersize = 10,
-    topoheigth = 0.4,
+    topoheight = 0.4,
     topowidth = 0.4,
     axis = (; title = "With decorations"),
 )
@@ -37,7 +37,7 @@ plot_butterfly!(
     data;
     positions = pos,
     topomarkersize = 10,
-    topoheigth = 0.4,
+    topoheight = 0.4,
     topowidth = 0.4,
     axis = (; title = "Without decorations"),
     layout = (; hidedecorations = (:label => true, :ticks => true, :ticklabels => true)),

diff --git a/docs/literate/how_to/mult_vis_in_fig.jl b/docs/literate/how_to/mult_vis_in_fig.jl
@@ -83,8 +83,8 @@ plot_designmatrix!(f[2, 3], designmatrix(uf))
 plot_topoplot!(f[3, 1], data[:, 150, 1]; positions = positions)
 plot_topoplotseries!(
     f[4, 1:3],
-    d_topo,
-    0.1;
+    d_topo;
+    bin_width = 0.1,
     positions = positions,
     mapping = (; label = :channel),
 )
@@ -157,7 +157,7 @@ plot_butterfly!(
     d_topo;
     positions = pos,
     topomarkersize = 10,
-    topoheigth = 0.4,
+    topoheight = 0.4,
     topowidth = 0.4,
 )
 hlines!(0, color = :gray, linewidth = 1)
@@ -166,8 +166,8 @@ plot_topoplot!(gc, data[:, 340, 1]; positions = positions, axis = (; xlabel = "[
 
 plot_topoplotseries!(
     gd,
-    df,
-    80;
+    df;
+    bin_width = 80,
     positions = positions,
     visual = (label_scatter = false,),
     layout = (; use_colorbar = true),

diff --git a/docs/literate/how_to/position2color.jl b/docs/literate/how_to/position2color.jl
@@ -54,3 +54,19 @@ plot_butterfly(
     positions = positions,
     topopositions_to_color = x -> Colors.RGB(0.5),
 )
+
+# Transparency
+# Unlike RGB, RGBA has a fourth channel, alpha, which is responsible for transparency.
+# Here are two examples of how to manipulate it.
+
+plot_butterfly(
+    results;
+    positions = positions,
+    topopositions_to_color = x -> (RGBA(UnfoldMakie.pos_to_color_RomaO(x), 1)),
+)
+
+plot_butterfly(
+    results;
+    positions = positions,
+    topopositions_to_color = x -> (GrayA(UnfoldMakie.pos_to_color_RomaO(x), 0.5)),
+)
diff --git a/docs/literate/intro/code_principles.jl b/docs/literate/intro/code_principles.jl
@@ -0,0 +1,11 @@
+# # Code principles
+
+
+# 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 
diff --git a/docs/literate/intro/plot_types.jl b/docs/literate/intro/plot_types.jl
@@ -1,7 +1,7 @@
 # # The Dilemma of Multidimensionality
 
 # !!! note
-#        Please read the paper [The Art of Brainwaves](https://apertureneuro.org/article/116386-the-art-of-brainwaves-a-survey-on-event-related-potential-visualization-practices), if you want to know more about how we come up with these plot types.
+#        Please read the paper [The Art of Brainwaves](https://apertureneuro.org/article/116386-the-art-of-brainwaves-a-survey-on-event-related-potential-visualization-practices), if you want to know how we come up with these plot types.
 #=
 EEG – multidimensional data and could be presented differently.
 

diff --git a/docs/literate/tutorials/butterfly.jl b/docs/literate/tutorials/butterfly.jl
@@ -1,5 +1,5 @@
 # # [Butterfly Plot](@id bfp_vis)
-# Butterfly plot is a plot type for visualisation of Event-related potentials. 
+# **Butterfly plot** is a plot type for visualisation of Event-related potentials. 
 # It can fully represent time and channels dimensions using lines. With addition of topoplot inset it can also represent location of channels.
 # It called "butterfly" because the envelope of channels reminds butterfly wings🦋. 
 
@@ -38,7 +38,7 @@ plot_butterfly(df; positions = pos)
 
 # You want to change size of topomarkers and size of topoplot:
 
-plot_butterfly(df; positions = pos, topomarkersize = 10, topoheigth = 0.4, topowidth = 0.4)
+plot_butterfly(df; positions = pos, topomarkersize = 10, topoheight = 0.4, topowidth = 0.4)
 
 # You want to add vline and hline:
 

diff --git a/docs/literate/tutorials/channel_image.jl b/docs/literate/tutorials/channel_image.jl
@@ -1,6 +1,6 @@
 # # Channel image 
 
-# Channel image is a plot type for visualizing EEG activity for all channels. 
+# **Channel image** is a plot type for visualizing EEG activity for all channels. 
 # It can fully represent time and channel  dimensions using a heatmap. 
 # Y-axis represents all channels, x-axis represents time, while color represents voltage. 
 

diff --git a/docs/literate/tutorials/circ_topo.jl b/docs/literate/tutorials/circ_topo.jl
@@ -1,5 +1,10 @@
 # # Circular Topoplots
 
+# **Circular topoplot series** is a plot type for visualizing EEG activity in relation to some continous variable arranged on a circluar line. 
+# It can fully represent channel and channel location dimensions using contour lines. It can also partially represent the varaible dimension.
+# Variable could be for instance accadic amplitude or degrees of visual angle. 
+# Basically, it is a series of Topoplots arranged on a circle.
+
 # # Setup
 # ## Package loading
 

diff --git a/docs/literate/tutorials/erp.jl b/docs/literate/tutorials/erp.jl
@@ -1,6 +1,6 @@
 # # [ERP Plot](@id erp_vis)
 
-# ERP plot is plot type for visualisation of [Event-related potentials](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC3016705/). 
+# **ERP plot** is plot type for visualisation of [Event-related potentials](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC3016705/). 
 # It can fully represent time and experimental condition dimensions using lines.
 
 # # Setup

diff --git a/docs/literate/tutorials/erp_grid.jl b/docs/literate/tutorials/erp_grid.jl
@@ -1,4 +1,8 @@
 # # ERP grid 
+# **ERP grid** is a plot type for visualisation of Event-related potentials. 
+# It can fully represent time, channel, and layout (channel locations) dimensions using lines. It can also partially represent condition dimensions.
+# Lines are displayed on a grid. The location of each axis represents the location of the electrode.
+# This plot type is not as popular because it is too cluttered. 
 
 # # Setup
 # ## Package loading

diff --git a/docs/literate/tutorials/erpimage.jl b/docs/literate/tutorials/erpimage.jl
@@ -1,6 +1,6 @@
 # # ERP image
 
-# ERP image is a plot type for visualizing EEG activity for all trials. 
+# **ERP image** is a plot type for visualizing EEG activity for all trials. 
 # It can fully represent time and trial dimensions using a heatmap. 
 # Y-axis represents all trials, x-axis represents time, while color represents voltage. 
 # The ERP image can also be sorted by specific experimental variables, which helps to reveal important correlations. 

diff --git a/docs/literate/tutorials/parallelcoordinates.jl b/docs/literate/tutorials/parallelcoordinates.jl
@@ -1,6 +1,6 @@
 # # Parallel Coordinates
 
-# Parallel Coordinates Plot (PCP) is a plot type used to visualize EEG activity for some channels. 
+# **Parallel Coordinates Plot** (PCP) is a plot type used to visualize EEG activity for some channels. 
 # It can fully represent state and channel dimensions using lines. It can also partially represent time or trials
 # Y-axis represents time points, vertical axes represent channels, while lines show voltage changes. 
 

diff --git a/docs/literate/tutorials/topoplot.jl b/docs/literate/tutorials/topoplot.jl
@@ -1,5 +1,5 @@
 # # [Topoplot](@id topo_vis)
-# Topoplot (aka topography plot) is a plot type for visualisation of EEG activity in a specific time stemp or time interval. 
+# **Topoplot** (aka topography plot) is a plot type for visualisation of EEG activity in a specific time stemp or time interval. 
 # It can fully represent channel and channel location dimensions using contour lines.
 
 # The topoplot is a 2D projection and interpolation of the 3D distributed sensor activity. The name stems from physical geography, but instead of height, the contour lines represent voltage levels. 

diff --git a/docs/literate/tutorials/topoplotseries.jl b/docs/literate/tutorials/topoplotseries.jl
@@ -1,6 +1,6 @@
 # # Topoplot Series
 
-# Topoplot Series is a plot type for visualizing EEG activity in a given time frame or time interval. 
+# **Topoplot series** is a plot type for visualizing EEG activity in a given time frame or time interval. 
 # It can fully represent channel and channel location dimensions using contour lines. It can also partially represent the time dimension.
 # Basically, it is a series of Topoplots.
 
@@ -23,39 +23,39 @@ nothing #hide
 
 # # Plotting
 
-Δbin = 80
-plot_topoplotseries(df, Δbin; positions = positions)
+bin_width = 80
+plot_topoplotseries(df; bin_width, positions = positions)
 
 # # Additional features
 
 # ## Disabling colorbar
 
-plot_topoplotseries(df, Δbin; positions = positions, layout = (; use_colorbar = false))
+plot_topoplotseries(df; bin_width, positions = positions, layout = (; use_colorbar = false))
 
 # ## Aggregating functions
 # In this example `combinefun` is specified by `mean`, `median` and `std`. 
 
 f = Figure(size = (500, 500))
 plot_topoplotseries!(
     f[1, 1],
-    df,
-    Δbin;
+    df;
+    bin_width,
     positions = positions,
     combinefun = mean,
-    axis = (; title = "combinefun = mean"),
+    axis = (; xlabel = "", title = "combinefun = mean"),
 )
 plot_topoplotseries!(
     f[2, 1],
-    df,
-    Δbin;
+    df;
+    bin_width,
     positions = positions,
     combinefun = median,
-    axis = (; title = "combinefun = median"),
+    axis = (; xlabel = "", title = "combinefun = median"),
 )
 plot_topoplotseries!(
     f[3, 1],
-    df,
-    Δbin;
+    df;
+    bin_width,
     positions = positions,
     combinefun = std,
     axis = (; title = "combinefun = std"),
@@ -66,36 +66,54 @@ f
 
 #=
 If you need to plot many topoplots, you should display them in multiple rows. 
-
-Here you can specify:
-- Grouping condition using `mapping.row`.
-- Label the y-axis with `axis.ylabel`.
-- Hide electrode markers with `visual.label_scatter`.
-- Change the color map with `visual.colormap`. The default is `Reverse(:RdBu)`.
-- Adjust the limits of the topoplot boxes with `axis.xlim_topo` and `axis.ylim_topo`. By default both are `(-0.25, 1.25)`.
-- Adjust the size of the figure with `Figure(size = (x, y))`.
-- Adjust the padding between topoplot labels and axis labels using `xlabelpadding` and `ylabelpadding`.
 =#
+
+f = Figure()
 df1 = UnfoldMakie.eeg_matrix_to_dataframe(data[:, :, 1], string.(1:length(positions)))
-df1.condition = repeat(["A", "B", "C", "D", "E"], size(df, 1) ÷ 5)
+plot_topoplotseries!(
+    f[1, 1:5],
+    df1;
+    bin_num = 14,
+    nrows = 4,
+    positions = positions,
+    visual = (; label_scatter = false),
+)
+f
+
+# ## Categorical topoplots
+
+#=
+If you decide to use categorical values instead of time intvervals for sepration of topoplots do this:
+- Do not specify `bin_width` or `bin_num`
+- Put categorical value in `mapping.col`
+=#
+
+df2 = UnfoldMakie.eeg_matrix_to_dataframe(data[:, 1:5, 1], string.(1:length(positions)))
+df2.condition = repeat(["A", "B", "C", "D", "E"], size(df2, 1) ÷ 5)
 
 f = Figure(size = (600, 500))
 
 plot_topoplotseries!(
-    f[1:2, 1:2],
-    df1,
-    Δbin;
+    f[1, 1],
+    df2;
     col_labels = true,
-    mapping = (; row = :condition),
-    axis = (; ylabel = "Conditions"),
+    mapping = (; col = :condition),
+    axis = (; xlabel = "Conditions"),
     positions = positions,
-    visual = (label_scatter = false,),
-    layout = (; use_colorbar = true),
 )
 f
 
 # # Configurations of Topoplot series
 
+#=
+Also you can specify:
+- Label the x-axis with `axis.xlabel`.
+- Hide electrode markers with `visual.label_scatter`.
+- Change the color map with `visual.colormap`. The default is `Reverse(:RdBu)`.
+- Adjust the limits of the topoplot boxes with `axis.xlim_topo` and `axis.ylim_topo`. By default both are `(-0.25, 1.25)`.
+- Adjust the size of the figure with `Figure(size = (x, y))`.
+- Adjust the padding between topoplot labels and axis labels using `xlabelpadding` and `ylabelpadding`.
+=#
 # ```@docs
 # plot_topoplotseries
 # ```
diff --git a/docs/make.jl b/docs/make.jl
@@ -15,7 +15,7 @@ using Glob
 
 GENERATED = joinpath(@__DIR__, "src", "generated")
 SOURCE = joinpath(@__DIR__, "literate")
-for subfolder ∈ ["how_to", "intro", "tutorials", "reference"]
+for subfolder ∈ ["how_to", "intro", "tutorials", "explanations"]
     local SOURCE_FILES = Glob.glob(subfolder * "/*.jl", SOURCE)
     foreach(fn -> Literate.markdown(fn, GENERATED * "/" * subfolder), SOURCE_FILES)
 end
@@ -38,6 +38,7 @@ makedocs(;
         "Intro" => [
             "Installation" => "generated/intro/installation.md",
             "Plot types" => "generated/intro/plot_types.md",
+            "Code principles" => "generated/intro/code_principles.md",
         ],
         "Visualization Types" => [
             "ERP plot" => "generated/tutorials/erp.md",
@@ -56,8 +57,8 @@ makedocs(;
             "Hide Decorations and Axis Spines" => "generated/how_to/hide_deco.md",
             "Include multiple figures in one" => "generated/how_to/mult_vis_in_fig.md",
         ],
-        "Reference" => [
-            "Convert electrode positions from 3D to 2D" => "generated/reference/positions.md",
+        "Explanations" => [
+            "Convert electrode positions from 3D to 2D" => "generated/explanations/positions.md",
         ],
         "API / DocStrings" => "api.md",
         "Utilities" => "helper.md",

diff --git a/docs/src/index.md b/docs/src/index.md
@@ -4,17 +4,19 @@
 <img src="assets/complex_plot.png" width="300" align="right"/>
 ```
 
-This is the documentation of the UnfoldMakie.jl module (aka library) for the Julia programming language. 
+This is the documentation of the UnfoldMakie.jl package for the Julia programming language. 
 
-## Benefits of UnfoldMakie.jl
+## Highlights of UnfoldMakie.jl
 
 - **10 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!
 - **Highly adaptable.**
-The module is based on the [Unfold](https://github.com/unfoldtoolbox/unfold.jl/) and [Makie](https://makie.juliaplots.org/stable/) modules, so you can use configurations from these modules to add new features to your figures.
+The package is primarily based on [Unfold.jl](https://github.com/unfoldtoolbox/unfold.jl/) and [Makie.jl](https://makie.juliaplots.org/stable/).
 - **Many usage examples**
-Here in documentation you can find user-friendly examples of how to use plots.
-- **Scientific colormaps as default**
-According to our study (Mikheev, 2024), 40% of EEG researchers do not know about the issue of scientific color maps. To protect the scientific integrity, we used `Reverse(:RdBu)` and `Roma` as default color maps. 
+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. 
 - **Interactivity** 
-Several plots use Observables and have interactive mode so you can click on them and change their layout. Check `plot_topoplotseries` and `plot_erpimage`.
+Several plots make use of `Observables.jl` which allows fast updating of the underlying data. Several plots already have predfined interactive features, e.g. you can click on labels to enable / disable them. See `plot_topoplotseries` and `plot_erpimage` for examples.