esi-neuroscience · tensionhead · Dec 23, 2022 · Nov 25, 2022 · Nov 25, 2022 · Nov 25, 2022
diff --git a/doc/source/README.rst b/doc/source/README.rst
@@ -24,48 +24,52 @@ We strive to achieve the following goals:
 
 Getting Started
 ---------------
-- Prerequisites: :doc:`Install Syncopy </setup>`
-- Jumping right in: :doc:`Quickstart Guide <quickstart/quickstart>`
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Getting Started
+
+   Install Syncopy </setup>
+   Quickstart Guide <quickstart/quickstart>
 
 Want to contribute or just curious how the sausage
 is made? Take a look at our :doc:`Developer Guide <developer/developers>`.
 
 
-In depth Guides and Tutorials
------------------------------
-* :doc:`Basic Concepts <user/concepts>`
-* :doc:`Syncopy for FieldTrip Users <user/fieldtrip>`
-* :doc:`Handling Data <user/data>`
-* :doc:`Fooof <tutorials/fooof>`
-* :doc:`Resampling <tutorials/resampling>`
+Tutorials
+---------
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Tutorials
+
+   Resampling <tutorials/resampling>
+   Spectral Analysis <tutorials/freqanalysis>
 
-
-Auto-generate API Docs
------------------------
-* :doc:`User API <user/user_api>`
+In depth Guides
+---------------
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Guides	      
+
+   Basic Concepts <user/concepts>
+   Syncopy for FieldTrip Users <user/fieldtrip>
+   Handling Data <user/data>
+   Parallel Processing <user/parallel>
+   Selections <user/selectdata>
+
+API
+---
+
+.. toctree::
+   :maxdepth: 1
+   :caption: API Reference
+
+   User API <user/user_api>
 
-Navigation
-----------
-* :doc:`Sitemap <sitemap>`
-* :ref:`genindex`
-* :ref:`search`
 
 Contact
 -------
 To report bugs or ask questions please use our `GitHub issue tracker <https://github.com/esi-neuroscience/syncopy/issues>`_.
 For general inquiries please contact syncopy (at) esi-frankfurt.de.
-
-.. Any sections to be included in the Documentation dropdown menu have to be in the toctree
-
-.. toctree::
-   :hidden:
-
-   quickstart/quickstart.rst
-   setup
-   user/concepts.rst
-   user/fieldtrip.rst
-   user/data.rst
-   user/user_api.rst
-   tutorials/fooof.rst
-   tutorials/resampling.rst
-   developer/developers.rst
diff --git a/doc/source/_static/select_example1.png b/doc/source/_static/select_example1.png
diff --git a/doc/source/_static/select_example2.png b/doc/source/_static/select_example2.png
diff --git a/doc/source/_static/synth_data_spec.png b/doc/source/_static/synth_data_spec.png
diff --git a/doc/source/_static/welch_basic_power.png b/doc/source/_static/welch_basic_power.png
diff --git a/doc/source/_static/welch_params.png b/doc/source/_static/welch_params.png
diff --git a/doc/source/_static/welch_params.txt b/doc/source/_static/welch_params.txt
@@ -0,0 +1,48 @@
+#!/usr/bin/env python
+
+import syncopy as spy
+import syncopy.tests.synth_data as synth_data
+import numpy as np
+import matplotlib.pyplot as plt
+
+sig_lengths = np.linspace(1000, 4000, num=4, dtype=int)
+overlaps = np.linspace(0.0, 0.99, num=10)
+variances = np.zeros((sig_lengths.size, overlaps.size), dtype=float)  # Filled in loop below.
+
+foilim = [5, 200]  # Frequency selection, shared between cases.
+f_timwin = 0.2     # Window length in seconds, also shared.
+
+def get_welch_cfg():
+        """
+        Get a reasonable Welch cfg for testing purposes.
+        """
+        cfg = spy.get_defaults(spy.freqanalysis)
+        cfg.method = "welch"
+        cfg.t_ftimwin = 0.5  # Window length in seconds.
+        cfg.toi = 0.0        # Overlap between periodograms (0.5 = 50 percent overlap).
+        return cfg
+
+for sigl_idx, sig_len in enumerate(sig_lengths):
+    for overl_idx, overlap in enumerate(overlaps):
+        wn = synth_data.white_noise(nTrials=20, nChannels=1, nSamples=sig_len, samplerate=1000)
+
+        cfg = get_welch_cfg()
+        cfg.toi = overlap
+        cfg.t_ftimwin = f_timwin
+        cfg.foilim = foilim
+
+        spec = spy.freqanalysis(cfg, wn)
+
+        # We got one Welch estimate per trial so far. Now compute the variance over trials:
+        spec_var = spy.var(spec, dim='trials')
+        mvar = np.mean(spec_var.show(channel=0)) # We get one variance per frequency bin, and average over those.
+        variances[sigl_idx, overl_idx] = mvar
+
+fig = plt.figure()
+ax = fig.add_subplot(projection='3d')
+for row_idx in range(variances.shape[0]):
+    ax.scatter(np.tile(sig_lengths[row_idx], overlaps.size), overlaps, variances[row_idx, :], label=f"Signal len {sig_lengths[row_idx]}")
+ax.set_xlabel('Signal length (number of samples)')
+ax.set_ylabel('Window overlap')
+ax.set_zlabel('var of Welch estimate')
+ax.set_title('Variance of Welsh estimate as a function of signal length and overlap.\nColors represent different signal lengths.')
diff --git a/doc/source/_static/workFlow.png b/doc/source/_static/workFlow.png
diff --git a/doc/source/conf.py b/doc/source/conf.py
@@ -15,14 +15,13 @@
 import os
 import sys
 sys.path.insert(0, os.path.abspath(".." + os.sep + ".." + os.sep))
-import sphinx_bootstrap_theme
 import syncopy
 
 # -- Project information -----------------------------------------------------
 
 project = 'Syncopy'
 copyright = '2020, Joscha Schmiedt and Stefan Fuertinger'
-author = 'Joscha Schmiedt, Stefan Fuertinger and Gregor Mönke'
+author = 'Joscha Schmiedt, Stefan Fuertinger, Tim Schäfer and Gregor Mönke'
 
 # The short X.Y version
 version = syncopy.__version__
@@ -52,6 +51,7 @@
     'sphinx.ext.viewcode',
     'sphinx.ext.inheritance_diagram',
     'sphinx_automodapi.automodapi',
+    'sphinx.ext.graphviz',
 ]
 
 autodoc_default_options = {
@@ -110,34 +110,19 @@ def setup(app):
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-#
-html_theme = 'bootstrap'
 
-html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()
+# see https://sphinx-book-theme.readthedocs.io
+html_theme = 'sphinx_book_theme'
+
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
 #
-html_logo = "_static/syncopy_icon.png"
+html_logo = "_static/syncopy_logo.png"
 html_theme_options = {
-    "navbar_title": "Syncopy",
-    "navbar_site_name": "Documentation",
-    # Render the next and previous page links in navbar. (Default: true)
-    'navbar_sidebarrel': False,
-    # Render the current pages TOC in the navbar. (Default: true)
-    'navbar_pagenav': False,
-    # Tab name for the current pages TOC. (Default: "Page")
-    'navbar_pagenav_name': "Current Page",
-
-    # Global TOC depth for "site" navbar tab. (Default: 1)
-    # Switching to -1 shows all levels.
-    'globaltoc_depth': 2,
-    # Currently, the supported themes are:
-    # - Bootstrap 3: https://bootswatch.com/3
-    'bootswatch_theme': "simplex",
-    'navbar_links': [
-        ("GitHub", "https://www.github.com/esi-neuroscience/syncopy", True),
-    ],
+    "repository_url": "https://github.com/esi-neuroscience/syncopy",
+    "use_issues_button": True,
+
 }
 
 # Add any paths that contain custom static files (such as style sheets) here,
@@ -207,7 +192,7 @@ def setup(app):
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
     (master_doc, 'Syncopy.tex', 'Syncopy Documentation',
-     'Gregor Mönke, Joscha Schmiedt and Stefan Fuertinger', 'manual'),
+     'Gregor Mönke, Tim Schäfer, Joscha Schmiedt and Stefan Fuertinger', 'manual'),
 ]
 
 

diff --git a/doc/source/quickstart/quickstart.rst b/doc/source/quickstart/quickstart.rst
@@ -29,11 +29,15 @@ With this we have a dataset of type :class:`~syncopy.AnalogData`, which is inten
 
 By construction, we made the (white) noise of the same strength as the signal, hence by eye the oscillations present in channel1 are hardly visible. The parameter ``latency`` defines a time-interval selection here.
 
+.. hint::
+   How to plot and work with subsets of Syncopy data is described in :ref:`selections`.
+
 To recap: we have generated a synthetic dataset white noise on both channels, and channel1 additionally carries the damped harmonic signal.
 
 .. hint::
    Further details about artificial data generation can be found at the :ref:`synth_data` section.
 
+
 Data Object Inspection
 ======================
 
@@ -52,7 +56,7 @@ which gives nicely formatted output:
             cfg : dictionary with keys ''
         channel : [2] element <class 'numpy.ndarray'>
       container : None
-           data : 50 trials of length 1000.0 defined on [50000 x 2] float64 Dataset of size 1.14 MB
+           data : 50 trials of length 1000.0 defined on [50000 x 2] float32 Dataset of size 1.14 MB
          dimord : time by channel
        filename : /xxx/xxx/.spy/spy_910e_572582c9.analog
            mode : r+
@@ -231,7 +235,6 @@ To have a synthetic albeit meaningful dataset to illustrate the different method
 
 We also right away calculated the respective power spectra ``spec``.
 We can quickly have a look at a snippet of the generated signals::
-
   data.singlepanelplot(trials=0, latency=[0, 0.5])
 
 

diff --git a/doc/source/scripts/select_example.py b/doc/source/scripts/select_example.py
@@ -0,0 +1,17 @@
+import numpy as np
+import syncopy as spy
+from syncopy.tests import synth_data
+
+# 100 trials of two phase diffusing signals with 40Hz
+adata = synth_data.phase_diffusion(nTrials=100,
+                                   freq=40,
+                                   samplerate=200,
+                                   nSamples=500,
+                                   nChannels=2,
+                                   eps=0.01)
+
+# coherence for full dataset
+coh1 = spy.connectivityanalysis(adata, method='coh')
+
+# plot coherence of channel1 vs channel2
+coh1.singlepanelplot(channel_i='channel1', channel_j='channel2')
diff --git a/doc/source/scripts/synth_data1.py b/doc/source/scripts/synth_data1.py
@@ -7,30 +7,30 @@ def generate_noisy_harmonics(nSamples, nChannels, samplerate):
     f1, f2 = 20, 50 # the harmonic frequencies in Hz
 
     # the sampling times vector
-    tvec = np.arange(nSamples) * 1 / samplerate 
+    tvec = np.arange(nSamples) * 1 / samplerate
 
     # define the two harmonics
-    harm1 = np.cos(2 * np.pi * f1 * tvec)
-    harm2 = np.cos(2 * np.pi * f2 * tvec)
-
+    ch1 = np.cos(2 * np.pi * f1 * tvec)
+    ch2 = np.cos(2 * np.pi * f2 * tvec)
+
+    # concatenate channels to to trial array
+    trial = np.column_stack([ch1, ch2])
+
     # add some white noise
-    trial = 0.5 * np.random.randn(nSamples, nChannels)
-    # add 1st harmonic to 1st channel
-    trial[:, 0] += harm1 
-    # add 2nd harmonic to 2nd channel
-    trial[:, 1] += 0.5 * harm2 
-
+    trial += 0.5 * np.random.randn(nSamples, nChannels)
+
     return trial
 
 
 nTrials = 50
 nSamples = 1000
-nChannels = 3
+nChannels = 2
 samplerate = 500   # in Hz
 
+# collect trials
 trials = []
 for _ in range(nTrials):
     trial = generate_noisy_harmonics(nSamples, nChannels, samplerate)
     trials.append(trial)
-    
+
 synth_data = spy.AnalogData(trials, samplerate=samplerate)
diff --git a/doc/source/setup.rst b/doc/source/setup.rst
@@ -21,7 +21,7 @@ Installing parallel processing engine ACME
 --------------------------------------------
 
 To harness the parallel processing capabilities of Syncopy
-it is necessary to install `ACME <https://github.com/esi-neuroscience/acme>`_.
+it is helpful to install `ACME <https://github.com/esi-neuroscience/acme>`_.
 
 Again either via conda
 
@@ -35,6 +35,8 @@ or pip
 
     pip install esi-acme
 
+.. note::
+   See :ref:`parallel` for details about parallel processing setup
 
 Importing Syncopy
 -----------------
@@ -59,25 +61,6 @@ To display your Syncopy version, run:
 
     spy.__version__
 
-
-.. _start_parallel:
-
-Starting Up Parallel Workers
-----------------------------
-
-In Syncopy all computations are designed to run in parallel taking advantage of
-modern multi-core system architectures. The simplest way to leverage any available
-concurrent processing hardware is to use the `parallel` keyword, e.g.,
-
-.. code-block:: python
-
-    spy.freqanalysis(data, method="mtmfft", parallel=True)
-
-This will allocate a parallel worker for each trial defined in `data`. If your code
-is running on the ESI cluster, Syncopy will automatically use the existing SLURM
-scheduler, in a single-machine setup, any available local multi-processing resources
-will be utilized. More details can be found in the :doc:`Data Analysis Guide <user/data>`
-
 .. _setup_env:
 
 Setting Up Your Python Environment

diff --git a/doc/source/tutorials/fooof.rst b/doc/source/tutorials/fooof.rst
@@ -33,8 +33,8 @@ a single channel here (see :ref:`the Synthetic data tutorial<synth_data>` for de
         nSamples = 1000
         samplerate = 1000
         ar1_part = AR2_network(AdjMat=np.zeros(1), nSamples=nSamples, alphas=[0.9, 0], nTrials=nTrials)
-        pd1 = phase_diffusion(freq=30., eps=.1, fs=samplerate, nChannels=nChannels, nSamples=nSamples, nTrials=nTrials)
-        pd2 = phase_diffusion(freq=50., eps=.1, fs=samplerate, nChannels=nChannels, nSamples=nSamples, nTrials=nTrials)
+        pd1 = phase_diffusion(freq=30., eps=.1, samplerate=samplerate, nChannels=nChannels, nSamples=nSamples, nTrials=nTrials)
+        pd2 = phase_diffusion(freq=50., eps=.1, samplerate=samplerate, nChannels=nChannels, nSamples=nSamples, nTrials=nTrials)
         signal = ar1_part + .8 * pd1 + 0.6 * pd2
         return signal
 
@@ -144,5 +144,33 @@ Once more, we look at the FOOOFed spectrum:
 
 Note that the two tiny peaks have been removed.
 
+
+Programmatically accessing details on the FOOOF fit results
+-----------------------------------------------------------
+
+All fitting results returned by FOOOF can be found in the `metadata` attribute of the returned `SpectralData` instance, which is a `dict`. This
+includes the following entries:
+
+* aperiodic_params
+* error
+* gaussian_params
+* n_peaks
+* r_squared
+
+Please see the `official FOOOF documentation <https://fooof-tools.github.io/fooof/generated/fooof.FOOOF.html#fooof.FOOOF>`_ for the meaning.
+
+Note that in Syncopy, FOOOF can be run several times in a single frontend call (e.g., if you have several trials and `cfg.keeptrials=True`).
+Therefore, you will see one instance of these fitting results *per FOOOF call* in the `metadata` dict. The trials (and chunk indices, if you used a non-default `chan_per_worker` setting)
+are encoded in the keys of the metadata sub dictionaries in format `<result>__<trial>_<chunk>`. E.g., `peak_params__2__0` would be the peak params for trial 2 (and chunk 0).
+
+In the example above, the typical use case of trial averaging (`cfg.keeptrials=False`) was demonstrated, so FOOOF was called on the trial-averaged data (i.e., on a single trial), and only one entry is present:
+
+.. code-block:: python
+    :linenos:
+
+    spec_fooof_tuned.metadata.aperiodic_params
+    # {'aperiodic_params': {'aperiodic_params__0_0': array([[0.8006], [1.4998]])}
+
+
 This concludes the tutorial on using FOOOF from Syncopy. Please do not forget to cite `Donoghue et al. 2020 <https://doi.org/10.1038/s41593-020-00744-x>`_ when using FOOOF.