Merge branch 'dev' into 'master'

Dev

See merge request it/syncopy!92

README.rst

@@ -1,16 +1,43 @@
-.. image:: doc/source/syncopy_logo.png
+.. image:: doc/source/_static/syncopy_logo.png
 
 Systems Neuroscience Computing in Python
 ========================================
-
-Syncopy is going to be a user-friendly analysis toolkit for large-scale
-electrophysiology data. The goals of the project are:
+Syncopy is going to be a user-friendly toolkit for large-scale
+electrophysiology data-analysis in Python. We strive to achieve the following goals:
 
 1. Syncopy is a *fully open source Python* environment for electrophysiology
    data analysis. 
-2. Syncopy is *scalable* for large datasets. It will automatically make use of the
-   available computing resources by being developed with built-in parallelism. 
+2. Syncopy is *scalable* and built for *very large datasets*. It will automatically 
+   make use of available computing resources and is developed with built-in 
+   parallelism in mind. 
 3. Syncopy is *compatible with FieldTrip*. 
-    - data and results can loaded into MATLAB and Python
+    - data and results can be loaded into MATLAB and Python
     - parameter names and function call syntax are as similar as possible
 
+Syncopy is developed at the
+`Ernst Strüngmann Institute (ESI) gGmbH for Neuroscience in Cooperation with Max Planck Society <https://www.esi-frankfurt.de/>`_
+and released free of charge under the 
+`BSD 3-Clause "New" or "Revised" License <https://en.wikipedia.org/wiki/BSD_licenses#3-clause_license_(%22BSD_License_2.0%22,_%22Revised_BSD_License%22,_%22New_BSD_License%22,_or_%22Modified_BSD_License%22)>`_. 
+
+Contact
+-------
+To report bugs or ask questions please use our GitHub issue tracker. For
+general inquiries please contact syncopy (at) esi-frankfurt.de. 
+
+Installation
+============
+Syncopy is available on pip
+
+.. code-block:: bash
+
+   pip install syncopy
+
+To get the latest development version, simply clone our GitHub repository:
+
+.. code-block:: bash
+
+   git clone https://github.com/path/to/syncopy
+
+Getting Started
+===============
+Please visit our `online documentation <http://monitor/syncopy/quickstart.html>`. 

doc/source/README.rst

@@ -1,38 +1,132 @@
-.. Syncopy documentation master file, created by
+.. Syncopy documentation master file
 
 .. title:: Syncopy Documentation
 
-.. image:: syncopy_logo.png
+.. image:: _static/syncopy_logo.png
     :alt: Syncopy logo
     :height: 200px
     :align: center
 
-Welcome to Syncopy's Documentation!
-===================================
 
-Syncopy (Systems Neuroscience COmputing in Python) is a Python toolkit for
-user-friendly, large-scale electrophysiology data analysis. The goals of the
-project are:
+Welcome to the Documentation of SyNCoPy!
+========================================
 
-1. Syncopy provides a fully *open source* Python environment for reproducable
+SyNCoPy (**Sy**\stems **N**\euroscience **Co**\mputing in **Py**\thon, spelled Syncopy in the following) 
+is a Python toolkit for user-friendly, large-scale electrophysiology data analysis. 
+We strive to achieve the following goals:
+
+1. Syncopy provides a full *open source* Python environment for reproducible
    electrophysiology data analysis.
-2. Syncopy is *scalable* for large datasets. It automatically makes use of the
-   available computing resources by being developed with built-in parallelism.
-3. Syncopy is *compatible* with the MATLAB toolbox FieldTrip.
+2. Syncopy is *scalable* to accommodate *very large* datasets. It automatically 
+   makes use of available computing resources and is developed with built-in 
+   parallelism in mind.
+3. Syncopy is *compatible* with the MATLAB toolbox `FieldTrip <http://www.fieldtriptoolbox.org/>`_.
+
+.. contents:: Contents
+    :local:
+    :depth: 1
+
+Getting Started
+---------------
+Our :doc:`Quickstart Guide <quickstart>` covers installation and basic usage. 
+More in-depth information relevant to every user of Syncopy can be found in our 
+:doc:`User Guide <user/users>`. Want to contribute or just curious how the sausage 
+is made? Take a look at our :doc:`Developer Guide <developer/developers>`. Once again
+in order of brevity:
+
+* :doc:`Quickstart Guide <quickstart>`
+* :doc:`User Guide <user/users>`
+* :doc:`Developer Guide <developer/developers>`
+
+Resources by Topic 
+^^^^^^^^^^^^^^^^^^
+Looking for information regarding a specific analysis method? The table below 
+might help. 
+
+.. cssclass:: table-hover
+
++-------------------+-----------------------+---------------------------+
+| **Topic**         | **Resources**         | **Description**           |
++-------------------+-----------------------+---------------------------+
+| |TnW|             | |Spy4FT|              | |Spy4FTDesc|              |
+|                   +-----------------------+---------------------------+
+|                   | |SpyData|             | |SpyDataDesc|             |
+|                   +-----------------------+---------------------------+
+|                   | |UG|                  | |UGDesc|                  |
++-------------------+-----------------------+---------------------------+
+| |RDoc|            | |UsrAPI|              | |UsrAPIDesc|              |
+|                   +-----------------------+---------------------------+
+|                   | |DevAPI|              | |DevAPIDesc|              |
+|                   +-----------------------+---------------------------+
+|                   | |DevTools|            | |DevToolsDesc|            |
+|                   +-----------------------+---------------------------+
+|                   | |Indx|                | |IndxDesc|                |
++-------------------+-----------------------+---------------------------+
+| |Spec|            | |SpecTut|             | |SpecTutDesc|             |
+|                   +-----------------------+---------------------------+
+|                   | |SpecEx|              | |SpecExDesc|              |
+|                   +-----------------------+---------------------------+
+|                   | |SpecAdv|             | |SpecAdvDesc|             |
++-------------------+-----------------------+---------------------------+
+| |Con|             | |ConTut|              | |ConTutDesc|              |
+|                   +-----------------------+---------------------------+
+|                   | |ConEx|               | |ConExDesc|               |
+|                   +-----------------------+---------------------------+
+|                   | |ConAdv|              | |ConAdvDesc|              |
++-------------------+-----------------------+---------------------------+
+
+.. |TnW| replace:: *Tutorials & Walkthroughs*
+.. |RDoc| replace:: *Reference Documentation*
+.. |Spec| replace:: *Spectral Estimation*
+.. |Con| replace:: *Connectivity*
 
+.. |Spy4FT| replace:: :doc:`Syncopy for FieldTrip Users <user/fieldtrip>`
+.. |Spy4FTDesc| replace:: Quick introduction to Syncopy from a FieldTrip user's perspective
+.. |SpyData| replace:: :doc:`Data Handling in Syncopy <user/data_handling>`
+.. |SpyDataDesc| replace:: Overview of Syncopy's data management
+.. |UG| replace:: :doc:`Syncopy User Guide <user/users>`
+.. |UGDesc| replace:: Syncopy's user manual
 
-Contents
-========
+.. |UsrAPI| replace:: :doc:`User API <user/user_api>`
+.. |UsrAPIDesc| replace:: The subset of Syncopy's interface relevant to users
+.. |DevAPI| replace:: :doc:`Developer API <developer/developer_api>`
+.. |DevAPIDesc| replace:: The parts of Syncopy mostly interesting for developers
+.. |Indx| replace:: :ref:`Package Index <genindex>`
+.. |IndxDesc| replace:: Index of all functions/classes
+.. |DevTools| replace:: :doc:`Syncopy Developer Tools <developer/tools>`
+.. |DevToolsDesc| replace:: Tools for contributing new functionality to Syncopy
+
+.. |SpecTut| replace:: Spectral Estimation Tutorial
+.. |SpecTutDesc| replace:: An introduction to the available spectral estimation methods in Syncopy
+.. |SpecEx| replace:: Spectral Estimation Examples
+.. |SpecExDesc| replace:: Example scripts and notebooks illustrating spectral estimation in Syncopy
+.. |SpecAdv| replace:: Advanced Topics in Spectral Estimation
+.. |SpecAdvDesc| replace:: Technical details and notes for advanced users/developers
+
+.. |ConTut| replace:: Connectivity Tutorial
+.. |ConTutDesc| replace:: An introduction to connectivity estimation in Syncopy
+.. |ConEx| replace:: Connectivity Examples
+.. |ConExDesc| replace:: Example scripts and notebooks illustrating the use of connectivity metrics in Syncopy
+.. |ConAdv| replace:: Advanced Topics in Connectivity 
+.. |ConAdvDesc| replace:: Technical details and notes for advanced users/developers
+
+Still no luck finding what you're looking for? Try using the :ref:`search <search>` function. 
+
+Sitemap
+-------
 .. toctree::
    :maxdepth: 2
 
    quickstart
    user/users.rst    
    developer/developers.rst   
 
-
 Indices and tables
-==================
-
+^^^^^^^^^^^^^^^^^^
 * :ref:`genindex`
 * :ref:`search`
+
+Contact
+-------
+To report bugs or ask questions please use our GitHub issue tracker. For
+general inquiries please contact syncopy (at) esi-frankfurt.de. 

doc/source/developer/datatype.rst

@@ -1,6 +1,6 @@
 .. _syncopy-data-classes:
 
-Syncopy data classes
+Syncopy Data Classes
 ====================
 
 The data structure in Syncopy is based around the idea that all
@@ -9,7 +9,7 @@ example, a multi-channel local field potential can be stored as a
 two-dimensional `float` array with the dimensions being time (sample) and
 channel. Hence,
 
-.. note:: Each Syncopy data object is simply an anotated multi-dimensional array.
+.. note:: Each Syncopy data object is simply an annotated multi-dimensional array.
 
 This array is always stored in the :attr:`data` property and can be
 indexed using `NumPy indexing
@@ -29,10 +29,9 @@ classes (see also `Wikipedia
 
 The bottom classes in the class tree are for active use in analyses.
 
-The usable Syncopy data classes
--------------------------------
-
-The classes that
+Usable Syncopy Data Classes
+----------------------------
+The following classes can be instanced at the package-level (``spy.AnalogData(...)`` etc.)
 
 .. autosummary::
 

doc/source/developer/developer_api.rst

@@ -16,16 +16,13 @@ syncopy.datatype
     syncopy.datatype.discrete_data.DiscreteData
 
 
-syncopy.specest
-^^^^^^^^^^^^^^^
+syncopy.misc
+^^^^^^^^^^^^
 
 .. autosummary::
     :toctree: _stubs
 
-    syncopy.specest.mtmfft.mtmfft
-    syncopy.specest.mtmfft.MultiTaperFFT
-    syncopy.specest.wavelet.wavelet
-    syncopy.specest.wavelet.WaveletTransform
+    syncopy.tests.misc.generate_artificial_data
 
 
 syncopy.shared
@@ -39,3 +36,15 @@ syncopy.shared
     syncopy.shared.errors.SPYTypeError
     syncopy.shared.errors.SPYValueError
     syncopy.shared.errors.SPYIOError
+
+
+syncopy.specest
+^^^^^^^^^^^^^^^
+
+.. autosummary::
+    :toctree: _stubs
+
+    syncopy.specest.mtmfft.mtmfft
+    syncopy.specest.mtmfft.MultiTaperFFT
+    syncopy.specest.wavelet.wavelet
+    syncopy.specest.wavelet.WaveletTransform

doc/source/developer/io.rst

@@ -1,32 +1,32 @@
-Reading from and writing data to disk
-=====================================
+Reading and Writing Data
+=========================
 
 .. contents::
     Contents
     :local:
 
 
-The Syncopy data format (``*.spy``)
+The Syncopy Data Format (``*.spy``)
 -----------------------------------
 
-As each Syncopy data object is nothing more than an anotated multi-dimensional
-array each object is usually stored in 
+As each Syncopy data object is simply an annotated multi-dimensional
+array every object is stored as
 
 1. a binary file for the data arrays and
 2. a human-readable file for metadata.
 
 Syncopy aims to be scalable for very large files that don't fit into memory. To
-cope with those kinds of files, it is usually necessary to stream data from and
-to disk only on demand. A file format that is well-established for this 
-purpose is `HDF5 <https://www.hdfgroup.org/>`_, which is therefore the default
+cope with such files, it is usually necessary to perform on-demand streaming 
+of data from and to disk. A file format that is well-established for this 
+purpose is `HDF5 <https://www.hdfgroup.org/>`_, which is, therefore, the default
 storage backend of Syncopy. In addition, metadata are stored in `JSON
-<https://en.wikipedia.org/wiki/JSON>`_, which is both easily human-readable 
+<https://en.wikipedia.org/wiki/JSON>`_, which is both easily human- 
 and machine-readable.
 
-The data files are usually stored in a folder called ``<basename>.spy``, which
-can contain multiple data of different data classes that have been recorded
-simulatenously, e.g. spikes and local field potentials. The standard naming
-pattern of the data files is the following
+By default, Syncopy's data files are stored in a folder called ``<basename>.spy``, which
+can contain the on-disk representations of multiple objects of different classes
+(e.g., spikes and local field potentials that have been recorded simultaneously). 
+The standard naming pattern of Syncopy's data files is as follows:
 
 :: 
 
@@ -40,8 +40,8 @@ pattern of the data files is the following
 The ``<dataclass>`` specifies the type of data that is stored in the file, i.e.
 one of the :ref:`syncopy-data-classes`. The ``<tag>`` part of the filename is
 user-defined to distinguish data of the same data class, that should be kept
-separate, e.g. data from separate electrode arrays. The data can be loaded into
-Python using the :func:`syncopy.load` function.
+separate, e.g. data from separate electrode arrays. Data can be loaded using 
+the :func:`syncopy.load` function.
 
 
 **Example folder**
@@ -66,13 +66,13 @@ Python using the :func:`syncopy.load` function.
 
 
 
-Structure of the data file (HDF5)
+Structure of the Data File (HDF5)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The HDF5 file contains some metadata (`HDF5 attributes
 <http://docs.h5py.org/en/stable/high/attr.html>`_) in its header (partially
-redundant with JSON file), the ``data`` array in binary form (`HDF5 dataset
-<http://docs.h5py.org/en/stable/high/dataset.html>`_), and a ``[nTrials x
+redundant with the corresponding JSON file), the ``data`` array in binary form 
+(`HDF5 dataset <http://docs.h5py.org/en/stable/high/dataset.html>`_), and a ``[nTrials x
 3+k]``-sized ``trialdefinition`` array containing information about the trials
 defined on the data (trial_start, trial_stop, trial_triggeroffset, trialinfo_1,
 trialinfo_2, ..., trialinfo_k).
@@ -99,7 +99,7 @@ the data directly include `HDFView
 <https://github.com/HDFGroup/hdf-compass>`_.
 
 
-Structure of the metadata file (JSON)
+Structure of the Metadata File (JSON)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The JSON file contains all metadata relevant to the data object. The required fields
@@ -177,7 +177,7 @@ Example JSON file:
 
     
 
-Reading other data formats
+Reading Other File Formats
 --------------------------
 
 Reading and writing other data formats is currently not supported. Getting your
@@ -189,4 +189,4 @@ empty data object (e.g. :class:`syncopy.AnalogData`) and fills the ``data``
 property with an index-able array as well as all relevant metadata properties.
 
 In future releases of Syncopy, example reading routines and/or exporting
-functions will be provided.
+functions will be provided.