Docs update: better navigation, clearer examples, added demo GIF

- The docs navigation was reorganized for clarity, grouping theory pages and renaming some sections.
- Comments and section headers in example files were revised for clearer explanations.
- Example scripts now use the new examples_data function for loading datasets.
- Code in topoplots_example.jl was reorganized and cleaned up; new helper functions were added.
- Removed or updated unnecessary includes/imports (such as WGLMakie).
- Deleted the unused examples/setup.jl file.
- A demo GIF (ERRgnostics_inaction.gif) was added to the documentation.
- Renamed example_data to examples_data for better clarity.

Author: vladdez

assets/ERRgnostics_inaction.gif

@@ -1,21 +1,21 @@
 using CairoMakie
 using DataFrames
 using UnfoldMakie
-using JLD2
+using JLD2, CSV
 using ERPgnostics
 
 CairoMakie.activate!()
 
 # Data input
 path = dirname(dirname(Base.current_project()))
-include(path * "/docs/example_data.jl")
 evts = DataFrame(CSV.File(path * "/data/events.csv"))
 positions_128 = JLD2.load_object(path * "/data/positions_128.jld2")
 erps_fix_32 = JLD2.load_object(path * "/data/erps_fix_32.jld2")
-pattern_detection_values_32 = example_data("pattern_detection_values_32");
+pattern_detection_values_32 = ERPgnostics.examples_data("pattern_detection_values_32");
 desired_conditions = ["duration", "fix_avgpos_x", "fix_avgpos_y", "fix_avgpupilsize"]
 
-# Plotting
+# ERPgnostics in action
+# *Static version*
 
 inter_toposeries_image(
     filter(row -> row.condition in desired_conditions, pattern_detection_values_32),
@@ -25,3 +25,7 @@ inter_toposeries_image(
     positions = positions_128[1:32],
     figure_configs = (; size = (1500, 700)),
 )
+
+# *Interactive version*
+
+# ![](ERRgnostics_inaction.gif)

docs/literate/intro/gnostics.jl

@@ -11,22 +11,30 @@ using JLD2
 using ERPgnostics
 CairoMakie.activate!()
 
-# Data input
+# **Data input**
 path = dirname(dirname(Base.current_project()))
-include(path * "/docs/example_data.jl")
 
 positions_128 = JLD2.load_object(path * "/data/positions_128.jld2")
-pattern_detection_values = example_data();
-
-# Interactive topoplot series with one row
-
+pattern_detection_values = ERPgnostics.examples_data("pattern_detection_values");
 desired_conditions = ["duration", "fix_avgpos_x", "fix_avgpos_y", "fix_avgpupilsize"]
-inter_toposeries(
-    filter(row -> row.condition in desired_conditions, pattern_detection_values);
+short_pdvs = filter(row -> row.condition in desired_conditions, pattern_detection_values);
+
+# **Standart topoplot series**
+plot_topoplotseries(
+    short_pdvs;
+    nrows = 2,
+    mapping = (; col = :condition),
+    axis = (; xlabel = "Sorting conditions"),
+    colorbar = (; label = "Pattern detection values"),
+    visual = (; colormap = Reverse(:RdGy_4)),
     positions = positions_128,
 )
 
-# Interactive topoplot series with multiple rows
+
+# **Interactive topoplot series with one row**
+inter_toposeries(short_pdvs; positions = positions_128)
+
+# **Interactive topoplot series with multiple rows**
 inter_toposeries(
     pattern_detection_values;
     positions = positions_128,

docs/literate/intro/toposeries.jl

@@ -34,10 +34,12 @@ makedocs(;
         assets = String[],
     ),
     pages = [
-        "ERPgnostics highlights" => "index.md",
-        "ERP image and patterns" => "generated/intro/patterns.md",
-        "Toposeries with patterns" => "generated/intro/toposeries.md",
-        "Diagnostics" => "generated/intro/gnostics.md",
+        "Homepage" => "index.md",
+        "Theory" => [
+            "ERP image and patterns" => "generated/intro/patterns.md",
+            "Toposeries with patterns" => "generated/intro/toposeries.md",
+            "Diagnostics" => "generated/intro/gnostics.md",
+        ],
         "API / DocStrings" => "api.md",
     ],
 )

docs/make.jl

@@ -6,7 +6,7 @@ begin
     using Unfold
     using CSV, DataFrames
     using Random, Format
-    using WGLMakie, Makie
+    using Makie
     using Statistics, StatsBase
     using HDF5, FileIO
     using Printf

examples/heatmap_example.jl

@@ -5,7 +5,7 @@ begin
     using Revise
     Revise.retry()
     using ERPgnostics
-    include("test/setup.jl")
+    include("$(stub)/test/setup.jl")
     using JuliaFormatter
     ENV["JULIA_DEBUG"] = "ERPgnostics"
     cd("$(stub)/test")

examples/runner.jl

@@ -1,48 +1,52 @@
-includet("setup.jl")
-includet("../src/topoplots.jl")
-
 Makie.inline!(false)
-
+using HDF5
+using DataFrames
+using CSV, JLD2
+using GLMakie
+GLMakie.activate!()
 # data
+function drop_all_nan_columns(df::DataFrame)
+    non_all_nan_cols = names(df)[.!all.(col -> all(x -> x isa Number && isnan(x), col), eachcol(df))]
+    return df[:, non_all_nan_cols]
+end
 begin
-    fid = h5open("data/data_fixations.hdf5", "r")
+    fid = h5open("../data/data_fixations.hdf5", "r")
     erps_fix = read(fid["data"]["data_fixations.hdf5"])
     close(fid)
 
-    evts = DataFrame(CSV.File("data/events.csv"))
-    evts_d = CSV.read("data/evts_d.csv", DataFrame)
-    evts_mf = CSV.read("data/evts_mf.csv", DataFrame)
-    positions_128 = JLD2.load_object("data/positions_128.jld2")
+    evts_raw = DataFrame(CSV.File("../data/events.csv"))
+    evts_d = CSV.read("../data/evts_d.csv", DataFrame)
+    evts_mf = CSV.read("../data/evts_mf.csv", DataFrame)
+    positions_128 = JLD2.load_object("../data/positions_128.jld2")
     timing = -0.5:0.001953125:1.0
+
+    
+    evts = drop_all_nan_columns(evts_raw)
 end
 
 begin
-    pattern_detection_values = stack(evts_d)
-    pattern_detection_values.timing = 1:nrow(pattern_detection_values)
-    pattern_detection_values.label = 1:nrow(pattern_detection_values)
+    evts_d.channel = 1:nrow(evts_d)
+    pattern_detection_values = stack(evts_d[1:32, :])
     rename!(pattern_detection_values, :variable => :condition, :value => :estimate)
-    pattern_detection_values.rows = vcat(
-        repeat(["A"], size(pattern_detection_values, 1) ÷ 4),
-        repeat(["B"], size(pattern_detection_values, 1) ÷ 4),
-        repeat(["C"], size(pattern_detection_values, 1) ÷ 4),
-        repeat(["D"], size(pattern_detection_values, 1) ÷ 4),
-    )
-end
-
-inter_toposeries(filter(x -> x.rows == "A", pattern_detection_values))
-inter_toposeries(filter(x -> x.rows == "B", pattern_detection_values))
-inter_toposeries(filter(x -> x.rows == "C", pattern_detection_values))
-inter_toposeries(filter(x -> x.rows == "D", pattern_detection_values))
 
-inter_toposeries_image(pattern_detection_values1, evts, erps)
-
-inter_toposeries_image(filter(x -> x.rows == "A", pattern_detection_values), evts, erps_fix, timing)
-inter_toposeries_image(filter(x -> x.rows == "B", pattern_detection_values), evts, erps_fix, timing) #fails
-inter_toposeries_image(filter(x -> x.rows == "C", pattern_detection_values), evts, erps_fix, timing)
-inter_toposeries_image(filter(x -> x.rows == "D", pattern_detection_values), evts, erps_fix, timing)
+    valid_conditions = names(evts)
+    filtered_values = filter(row -> row.condition in valid_conditions, pattern_detection_values)
+end
 
+inter_toposeries_image(
+    filtered_values,
+    evts,
+    erps_fix[1:32, :, :],
+    1:769;
+    positions = positions_128[1:32],
+    toposeries_configs = (; nrows = 3),
+    erpimage_configs = (; meanplot_axis = (; xlabel = "Time [s]")),
+    figure_configs = (; size = (1500, 700)),
+)
+
+###################################
 inter_toposeries_image(filter(x -> x.condition == "fix_samebox", pattern_detection_values), evts, erps_fix, timing)
-
+erps_fix[1:32, :, :]
 
 # make that workable
 begin
@@ -51,21 +55,3 @@ begin
 end
 
 inter_toposeries_image(pattern_detection_values, evts_sim, data_all, timing; positions_128 = positions_128)
-
-
-# debugging zone
-
-begin
-    pattern_detection_values2 = stack(evts_mf)
-    pattern_detection_values2.timing = 1:nrow(pattern_detection_values)
-    pattern_detection_values2.label = 1:nrow(pattern_detection_values)
-    rename!(pattern_detection_values2, :variable => :condition, :value => :estimate)
-    pattern_detection_values2.rows = vcat(
-        repeat(["A"], size(pattern_detection_values2, 1) ÷ 4),
-        repeat(["B"], size(pattern_detection_values2, 1) ÷ 4),
-        repeat(["C"], size(pattern_detection_values2, 1) ÷ 4),
-        repeat(["D"], size(pattern_detection_values2, 1) ÷ 4),
-    )
-end
-
-inter_toposeries_image(filter(x -> x.rows == "A", pattern_detection_values2), evts, erps_fix, timing)

examples/setup.jl

@@ -16,14 +16,14 @@ using ComputationalResources
 using Observables
 using DSP
 using JLD2
-using WGLMakie
 using ProgressBars
 
 include("configs.jl")
 include("interactive_heatmap.jl")
 include("interactive_topoplots.jl")
 include("pattern_detection.jl")
 include("pattern_simulation.jl")
+include("example_data.jl")
 include("filters.jl")
 
 export inter_toposeries # or better toposeries_inter
@@ -40,4 +40,5 @@ export complex_pattern_detector
 
 export slow_filter
 export mean_filter
+export example_data
 end

examples/topoplots_example.jl

@@ -16,7 +16,7 @@ Datasets:
 
 **Return Value:** `DataFrame`.
 """
-function example_data(example = "pattern_detection_values"; mode = 1)
+function examples_data(example = "pattern_detection_values"; mode = 1)
     if mode == 1
         datapath = dirname(dirname(Base.current_project())) * "/data/evts_d.csv"
     else