add docs for example_data (#42)

* add docs for `example_data`

* formatting tweak

* CI update

* add to rendered docs

.github/workflows/CI.yml

@@ -13,7 +13,7 @@ concurrency:
   cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }}
 jobs:
   test:
-    name: Julia ${{ matrix.version }} - ${{ matrix.os }} - ${{ matrix.arch }} - ${{ github.event_name }}
+    name: Julia ${{ matrix.version }} - ${{ matrix.os }} - ${{ matrix.arch }}
     runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
@@ -25,7 +25,7 @@ jobs:
         arch:
           - x64
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
       - uses: julia-actions/setup-julia@v1
         with:
           version: ${{ matrix.version }}
@@ -40,14 +40,14 @@ jobs:
         env:
           PERCY_TOKEN: ${{ secrets.PERCY_TOKEN }}
       - uses: julia-actions/julia-processcoverage@v1
-      - uses: codecov/codecov-action@v2
+      - uses: codecov/codecov-action@v4
         with:
           files: lcov.info
   docs:
     name: Documentation
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
       - uses: julia-actions/setup-julia@v1
         with:
           version: '1'

Project.toml

@@ -1,7 +1,7 @@
 name = "TopoPlots"
 uuid = "2bdbdf9c-dbd8-403f-947b-1a4e0dd41a7a"
 authors = ["Benedikt Ehinger", "Simon Danisch", "Beacon Biosignals, Inc."]
-version = "0.1.6"
+version = "0.1.7"
 
 [deps]
 CloughTocher2DInterpolation = "b70b374f-000b-463f-88dc-37030f004bd0"

docs/Project.toml

@@ -8,4 +8,4 @@ TopoPlots = "2bdbdf9c-dbd8-403f-947b-1a4e0dd41a7a"
 
 [compat]
 # other bits of compat are handled by TopoPlots compat
-Documenter = "1"
+Documenter = "1.3"

docs/src/eeg.md

@@ -20,8 +20,11 @@ TopoPlots.eeg_topoplot(rand(19), labels; axis=(aspect=DataAspect(),), label_text
 If the channels aren't 10/20, one can still plot them, but then the positions need to be passed as well:
 
 ```@example 1
-
 data, positions = TopoPlots.example_data()
 labels = ["s$i" for i in 1:size(data, 1)]
 TopoPlots.eeg_topoplot(data[:, 340, 1], labels; positions=positions, axis=(aspect=DataAspect(),))
 ```
+
+```@docs
+TopoPlots.example_data
+```

src/TopoPlots.jl

@@ -16,6 +16,25 @@ using CloughTocher2DInterpolation  # pure julia implementation
 
 assetpath(files...) = normpath(joinpath(dirname(@__DIR__), "assets", files...))
 
+"""
+    example_data()
+
+Load EEG example data.
+
+Returns a two-tuple:
+  - data: a (64, 400, 3) Float32 array of channel x timepoint x stat array.
+    Timepoints correponds to samples at 500Hz from -0.3s to 0.5s relative to stimulus onset.
+    Stats are mean over subjects, standard errors over subjects, and associated p-value from a t-test.
+    For demonstration purposes, the first stat dimension is generally the most applicable.
+  - positions: a length-64 Point2f vector of positions for each channel in data.
+
+
+# Data source
+
+Ehinger, B. V., König, P., & Ossandón, J. P. (2015).
+Predictions of Visual Content across Eye Movements and Their Modulation by Inferred Information.
+The Journal of Neuroscience, 35(19), 7403–7413. https://doi.org/10.1523/JNEUROSCI.5114-14.2015
+"""
 function example_data()
     data = Array{Float32}(undef, 64, 400, 3)
     read!(TopoPlots.assetpath("example-data.bin"), data)