facetting and circular allignment

Project.toml

@@ -23,6 +23,7 @@ MakieThemes = "e296ed71-da82-5faf-88ab-0034a9761098"
 SparseArrays = "2f01184e-e22b-5df5-ae63-d93ebab69eaf"
 StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
 Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
+StatsBase = "2913bbd2-ae8a-5f71-8c99-4fb6c76f3a91"
 TopoPlots = "2bdbdf9c-dbd8-403f-947b-1a4e0dd41a7a"
 Unfold = "181c99d8-e21b-4ff3-b70b-c233eddec679"
 

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),
 )
@@ -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),

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)),
+)

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.
 

docs/literate/tutorials/topoplotseries.jl

@@ -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"),
 )
 plot_topoplotseries!(
     f[2, 1],
-    df,
-    Δbin;
+    df;
+    bin_width,
     positions = positions,
     combinefun = median,
     axis = (; title = "combinefun = median"),
 )
 plot_topoplotseries!(
     f[3, 1],
-    df,
-    Δbin;
+    df;
+    bin_width,
     positions = positions,
     combinefun = std,
     axis = (; title = "combinefun = std"),
@@ -83,8 +83,8 @@ f = Figure(size = (600, 500))
 
 plot_topoplotseries!(
     f[1:2, 1:2],
-    df1,
-    Δbin;
+    df1;
+    bin_width,
     col_labels = true,
     mapping = (; row = :condition),
     axis = (; ylabel = "Conditions"),

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
@@ -56,8 +56,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",

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.

src/UnfoldMakie.jl

@@ -25,6 +25,7 @@ using DataFrames
 using SparseArrays
 using CategoricalArrays # for cut for TopoPlotSeries
 using StaticArrays
+using StatsBase
 
 using CoordinateTransformations # for 3D positions to 2D