add: comment amd more user-friendly varibales to explore.jl

Author: vladdez

src/ERPExplorer.jl

@@ -21,7 +21,7 @@ include("explore.jl")
 include("functions_preprocessing.jl")
 include("functions_formular.jl")
 include("functions_plotting.jl")
-include("define_scatter_linestyle.jl")
+include("functions_scatter_linestyle.jl")
 include("widgets_short.jl")
 include("widgets_long.jl")
 

src/explore.jl

@@ -4,89 +4,97 @@ Run the dashboard for explorative ERP analysis.
 
 Arguments:\\
 - `model::UnfoldLinearModel{Float64}` - Unfold linear model with categorical and continuous terms.\\
-- `positions::Vector{Point{2, Float32}}` - x an y coordinates of the channels.\\
+- `positions::Vector{Point{2, Float32}}` - x an y coordinates of the channels on topoplot.\\
 - `size::Tuple{Float64, Float64}` - size of the topoplot panel.\\
 
-Actions:\\
-- Extract formula terms and itheir features.\\
-- Create interactive formula with checkboxes.\\
-- Arrange and map dropdown menus.\\
-- Create interactive topoplot.\\
-- Create Observable DataFrame with predicted values (yhats) and more.\\
-- Create `GridLayout`.\\
-- Use `Base.ReentrantLock`, a synchronization primitive_ to manage concurrent access to shared resources in multi-threaded programs\\
-- Create Figure.\\
-- Translate into into HTML code using DOMs.
-
 **Return Value:** `Hyperscript.Node{Hyperscript.HTMLSVG}` - final HTML code of the dashboard.
 """
 function explore(model::UnfoldModel; positions = nothing, size = (700, 600))
+    # Initialize the App from Bonito. App allows to wrap all interactive elements and to deploy them
     myapp = App() do
+        # Extract formula terms and their features from the model.
         variables = extract_variables(model)
-        widget_checkbox, widget_signal, widget_dom, value_ranges =
+        # Create formula widgets for each term.
+        formula_defaults, formula_toggle, formula_DOM, formula_values =
             formular_widgets(variables)
 
+        # Extract variable names and types from the model.
         var_types = map(x -> x[2][3], variables)
-        varnames = first.(variables)
+        var_names = first.(variables)
 
-        mapping, mapping_dom = mapping_dropdowns(varnames, var_types)
+        # Create dropdown menues on the left panel of the dashboard.
+        mapping, mapping_dom = mapping_dropdowns(var_names, var_types)
 
-        if isnothing(positions)
-            channel = Observable(1)
+        # Create interactive topoplot widget on the lower left panel of the dashboard.
+        channel_chosen = Observable(1)
+        if isnothing(positions)   
             topo_widget = nothing
         else
-            topo_widget, channel = topoplot_widget(positions; size = size .* 0.5)
+            topo_widget = topoplot_widget(positions, channel_chosen; size = size .* 0.5)
+ # Problem: does it update?
         end
 
-        yhats_sig = yhats_signal(model, widget_signal, channel)
-        on(mapping) do m
-            ws = widget_signal.val
+        # Create Observable DataFrame with predicted values (yhats) of the model.
+        ERP_data = get_ERP_data(model, formula_toggle, channel_chosen)
+
+        # when m changes update formula_defaults
+        on(mapping) do m 
+            ft = formula_toggle.val
             ks_m = values(m)
-            ks_ws = [w.first for w in ws]
-            for k in ks_ws
-                widget_checkbox[k][] = k ∈ ks_m
+            ks_ft = [t.first for t in ft]
+            for k in ks_ft
+                formula_defaults[k][] = k ∈ ks_m
+                @debug "x" formula_defaults[k][]
             end
         end
 
-        obs = Observable(S.GridLayout())
+        # Create a new empty grid layout
+        plot_layout = Observable(S.GridLayout())
+       
+        # Create a new reentrant mutex (mutual exclusion) lock for safe thread synchronization during plot updates
+        # mutex - allows only one thread to access protected code at a time
+        # reentrant - allows the same thread to acquire the lock multiple times without causing a deadlock
+        # When multiple events occur nearly simultaneously, the lock ensures that:
+        # Only one plot update happens at a time and Plot data calculations complete fully before starting new ones
+        lk = Base.ReentrantLock()
 
-        l = Base.ReentrantLock()
-
-        Makie.onany_latest(yhats_sig, mapping; update = true) do eff, mapping # update = true means only, that it is run once immediately
-            lock(l) do
-                _tmp = plot_data(
-                    eff,
-                    value_ranges,
-                    varnames[var_types.==:CategoricalTerm],
-                    varnames[var_types.==:ContinuousTerm],
+        # Update the the grid layout
+        Makie.onany_latest(ERP_data, mapping; update = true) do ERP_data, mapping # `update = true` means that it will run once immediately
+            lock(lk) do
+                _tmp = update_grid(
+                    ERP_data,
+                    formula_values,
+                    var_names[var_types.==:CategoricalTerm],
+                    var_names[var_types.==:ContinuousTerm],
                     mapping,
                 )
-
-                #try 
-                obs[] = _tmp
-                #catch
-                #end
+                plot_layout[] = _tmp
             end
             return
         end
+
         css = Asset(joinpath(@__DIR__, "..", "style.css"))
-        fig = plot(obs; figure = (size = size,))
+        fig = plot(plot_layout; figure = (size = size,))
+
+        # Create header, sidebar, topo and content (figure) panels
+        cards = Grid(
+            Card(formula_DOM, style = Styles("grid-area" => "header")),
+            Card(mapping_dom, style = Styles("grid-area" => "sidebar")),
+            Card(topo_widget, style = Styles("grid-area" => "topo")),
+            Card(fig, style = Styles("grid-area" => "content"));
+            columns = "5fr 1fr",
+            rows = "1fr 6fr 4fr",
+            areas = """
+                'header header'
+                'content sidebar'
+                'content topo'
+            """,
+        )
+        # Translate the cards and css into HTML code using DOMs 
         res = DOM.div(
             css,
             Bonito.TailwindCSS,
-            Grid(
-                Card(widget_dom, style = Styles("grid-area" => "header")),
-                Card(mapping_dom, style = Styles("grid-area" => "sidebar")),
-                Card(topo_widget, style = Styles("grid-area" => "topo")),
-                Card(fig, style = Styles("grid-area" => "content"));
-                columns = "5fr 1fr",
-                rows = "1fr 6fr 4fr",
-                areas = """
-'header header'
-'content sidebar'
-'content topo'
-""",
-            );
+            cards;
             style = Styles(
                 "height" => "$(1.2*size[2])px",
                 "width" => "$(size[1])px",

src/functions_formular.jl

@@ -1,6 +1,6 @@
 """
-    formular_widgets(variables)
-Creates widgets to control each variable of a model.\\
+    formula_DOMs(variables)
+Create widgets to control all model variables.\\
 
 Arguments:\\
 - `variables::Vector{Pair{Symbol}}` - vector of key-value pairs with information about the model formula terms.
@@ -12,15 +12,15 @@ Actions:
 - Convert checkboxes to Observables.\\ 
 
 **Return Values:**\\
-- `widget_checkbox`: Dictionary with the current values of the widgets (term => values).\\
-- `widget_signal`: widget_checkbox but as Observable, a signal that emits a dictionary with the current values of the widgets.\\
-- `formular_widget`: The HTML element that can be displayed to interact with the the widgets.\\
-- `value_ranges`: A dictionary containing the value ranges of each formula term.\\
+- `formula_defaults::Dict{Symbol, Observable{Bool}}` - formula widgets with default values.\\
+- `formula_toggle::Observable{Vector{Any}}` - formula widgets with all values and toggle value.\\
+- `formula_DOM::Hyperscript.Node{Hyperscript.HTMLSVG}` - HTML element that can be displayed to interact with the the formula.\\
+- `formula_values::Vector{Pair{Symbol}}` - formula widgets with all values.\\
 """
 function formular_widgets(variables)
-    value_ranges = [k => value_range(v) for (k, v) in variables]
-    widgets = [k => widget(v) for (k, v) in value_ranges]
-    checkboxes = [Bonito.Checkbox(false) for k in value_ranges]
+    formula_values = [k => value_range(v) for (k, v) in variables]
+    widgets = [k => widget(v) for (k, v) in formula_values]
+    checkboxes = [Bonito.Checkbox(false) for k in formula_values]
     widget_names = [formular_text("0 ~ 1")]
 
     for k = 1:length(widgets)
@@ -35,11 +35,11 @@ function formular_widgets(variables)
         )
     end
 
-    formular_widget = Row(widget_names...)
+    formula_DOM = Row(widget_names...)
     widget_values = map(nw -> nw[2].value, widgets)
     checkbox_values = map(c -> c.value, checkboxes)
 
-    widget_signal =
+    formula_toggle =
         lift(widget_values..., checkbox_values...; ignore_equal_values = true) do args...
             result = []
             for i = 1:length(args[1:end/2])
@@ -49,13 +49,13 @@ function formular_widgets(variables)
             end
             return result
         end
-    widget_checkbox = Dict(k => c for (c, (k, v)) in zip(checkbox_values, variables))
+    formula_defaults = Dict(k => c for (c, (k, v)) in zip(checkbox_values, variables))
 
-    return widget_checkbox, widget_signal, formular_widget, value_ranges
+    return formula_defaults, formula_toggle, formula_DOM, formula_values
 end
 
 """
-    yhats_signal(model, widget_signal, channel)
+    get_ERP_data(model, widget_signal, channel)
 Creates a dictionary with yhat values and more.\\
 
 Arguments:\\
@@ -70,7 +70,7 @@ Actions:\\
 
 **Return Value:** `yhats_signal::Observable{Any}` containing DataFrame with yhats. 
 """
-function yhats_signal(model, widget_signal, channel)
+function get_ERP_data(model, widget_signal, channel)
 
     yhats_signal = Observable{Any}(nothing; ignore_equal_values = true)
 

src/functions_plotting.jl

@@ -1,7 +1,7 @@
 
 """
-    plot_data(data, value_ranges, categorical_vars, continuous_vars, mapping_obs)
-Plotting an interactive dashboard.
+    update_grid(data, value_ranges, categorical_vars, continuous_vars, mapping_obs)
+Plotting and updating an interactive dashboard.
 
  Arguments:\\
 - `data::DataFrame` - the result of `effects(Dict(...), model) ` with columns: yhat, channel, dummy, time, eventname and unique columns for each formula term.\\
@@ -19,14 +19,14 @@ Action:\\
 
 **Return Value:** `Makie.GridLayoutSpec`.
 """
-function plot_data(data, value_ranges, cat_terms, continuous_vars, mapping_obs)
+function update_grid(data, value_ranges, cat_terms, continuous_vars, mapping_obs)
     # Convert observable mapping to values
     mapping = to_value(mapping_obs)
 
     # Identify activated categorical and continuous variables
     cat_active = Dict(cat => data[1, cat] != "typical_value" for cat in cat_terms)
     cont_active = Dict(cont => data[1, cont] != "typical_value" for cont in continuous_vars)
-
+#@debug cat_active
     # Retrieve unique categorical levels
     cat_levels = [unique(data[!, cat]) for cat in cat_terms]
 
@@ -93,7 +93,6 @@ function plot_data(data, value_ranges, cat_terms, continuous_vars, mapping_obs)
             axes[r_ix, c_ix] = S.Axis(; plots = plots)
         end
     end
-
     palettes = merge(line_styles, scatter_styles)
 
     legends = Union{Nothing,Makie.BlockSpec}[]

src/define_scatter_linestyle.jl renamed to src/functions_scatter_linestyle.jl

@@ -44,13 +44,13 @@ function define_scatter_line_style!(
         line_cmap = []
         line_crange = []
         line_color = args
-        if isempty(args) || !any(x -> x[1] .== :color, args)
+        if isempty(args) || !any(x -> x[1] == :color, args)
             push!(args, :color => :black) # default color for lines
         end
 
     else
-        line_cmap = [kw => cmap for (name, (kw, (lims, cmap))) in line_styles]
-        line_crange = [:colorrange => lims for (name, (kw, (lims, cmap))) in line_styles]
+        line_cmap = [kw => cmap for (_, (kw, (_, cmap))) in line_styles]
+        line_crange = [:colorrange => lims for (_, (_, (lims, _))) in line_styles]
         line_color = [:color => sub[!, name] for name in continuous_vars]
 
     end

src/widgets_long.jl

@@ -16,7 +16,7 @@ Actions:\\
 - Arrange containers on the panel using Col() and Row(). Specify their styling.\\
 
 **Return Values:**\\
-- `mapping::Observable{Dict{Symbol, Symbol}}` - interactive dictionary with menus and their default value.\\
+- `mapping::Observable{Dict{Symbol, Symbol}}` - interactive dictionary with menues and their default value.\\
 - `mapping_dom::Hyperscript.Node{Hyperscript.HTMLSVG}` - dropdown menus in HTML code with styling and layout.\\
 """
 function mapping_dropdowns(varnames, var_types)
@@ -79,20 +79,20 @@ Actions:\\
 - Hide decorations and spines.\\
 
 **Return Values:**\\
-- `h_topo::Makie.FigureAxisPlot` - topoplot widget.\\
-- `interactive_scatter::Observable{Int64}` - number of the selected channel.\\
+- `topo_widget::Makie.FigureAxisPlot` - topoplot widget.\\
+- `channel_chosen::Observable{Int64}` - number of the selected channel.\\
 """
-function topoplot_widget(positions; size = ())
+function topoplot_widget(positions, channel_chosen; size = ())
     strokecolor = Observable(repeat([:red], length(to_value(positions)))) # crashing
-    interactive_scatter = Observable(1)
+    #channel_chosen = Observable(1)
 
     colorrange = vcat(0, 1)
     colormap = vcat(Gray(0.5), Gray(1))
 
     data_obs = Observable(zeros(length(to_value(positions))))
     data_obs.val[1] = 1
 
-    h_topo = eeg_topoplot(
+    topo_widget = eeg_topoplot(
         data_obs,
         nothing;
         positions = positions,
@@ -104,20 +104,20 @@ function topoplot_widget(positions; size = ())
         label_scatter = (; strokecolor = :black, strokewidth = 1.0, markersize = 20.0),
     )
 
-    on(events(h_topo).mousebutton) do event
+    on(events(topo_widget).mousebutton) do event
         if event.button == Mouse.left && event.action == Mouse.press
-            plt, p = pick(h_topo)
+            plt, p = pick(topo_widget)
             if isa(plt, Makie.Scatter)
                 data_obs[] .= 0
                 data_obs[][p] = 1
                 notify(data_obs)
-                interactive_scatter[] = p
+                channel_chosen[] = p
             end
 
         end
     end
-    hidedecorations!(h_topo.axis)
-    hidespines!(h_topo.axis)
-    return h_topo, interactive_scatter
+    hidedecorations!(topo_widget.axis)
+    hidespines!(topo_widget.axis)
+    return topo_widget
 
 end