diff --git a/doc/import.rst b/doc/import.rst new file mode 100644 index 0000000000..be3f7d5afb --- /dev/null +++ b/doc/import.rst @@ -0,0 +1,81 @@ +Importing SpikeInterface +======================== + +SpikeInterface allows for the generation of powerful and reproducible spike sorting pipelines. +Flexibility is built into the package starting from import to maximize the productivity of +the developer and the scientist. Thus there are three ways that SpikeInterface and its components +can be imported: + + +Importing by Module +------------------- + +Since each spike sorting pipeline involves a series of often repeated steps, many of the developers +working on SpikeInterface recommend importing in a module by module fashion. This will allow you to +keep track of your processing steps (preprocessing, postprocessing, quality metrics, etc.). This can +be accomplished by: + +.. code-block:: python + + import spikeinterface.core as si + +to import the :code:`core` module followed by: + +.. code-block:: python + + import spikeinterface.extractors as se + import spikeinterface.preprocessing as spre + import spikeinterface.sorters as ss + import spikinterface.postprocessing as spost + import spikeinterface.qualitymetrics as sqm + import spikeinterface.exporters as sexp + import spikeinterface.comparsion as scmp + import spikeinterface.curation as scur + import spikeinterface.sortingcomponents as sc + import spikeinterface.widgets as sw + +to import any of the other modules you wish to use. + +The benefit of this approach is that it is lighter than importing the whole library as a flat module and allows +you to choose which of the modules you actually want to use. It also reminds you what step of the pipeline each +submodule is meant to be used for. If you don't plan to export the results out of SpikeInterface then you +don't have to :code:`import spikeinterface.exporters`. Additionally the documentation of SpikeInterface is set-up +in a modular fashion, so if you have a problem with the submodule :code:`spikeinterface.curation`,you will know +to go to the :code:`curation` section of this documention. The disadvantage of this approach is that you have +more aliases to keep track of. + + +Flat Import +----------- + +A second option is to import the SpikeInterface package in :code:`full` mode. +To accomplish this one does: + + +.. code-block:: python + + import spikeinterface.full as si + + +This import statement will import all of the SpikeInterface modules as one flattened module. +We recommend this approach for advanced (or lazy) users, since it requires a deeper knowledge of the API. The advantage +being that users can access all functions using one alias without the need of memorizing all aliases. + + +Importing Individual Functions +------------------------------ + +Finally, some users may find it useful to have extremely light imports and only import the exact functions +they plan to use. This can easily be accomplished by importing functions directly into the name space. + +For example: + +.. code-block:: python + + from spikeinterface.preprocessing import bandpass_filter, common_reference + from spikeinterface.core import extract_waveforms + from spikeinterface.extractors import read_binary + +As mentioned this approach only imports exactly what you plan on using so it is the most minimalist. It does require +knowledge of the API to know which module to pull a function from. It could also lead to naming clashes if pulling +functions directly from other scientific libraries. Type :code:`import this` for more information. diff --git a/doc/index.rst b/doc/index.rst index df76a1a4c2..57ce14ed44 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -40,6 +40,7 @@ SpikeInterface is made of several modules to deal with different aspects of the overview installation + import modules/index how_to/index modules_gallery/index diff --git a/doc/installation.rst b/doc/installation.rst index acc5117249..08f9077a1d 100644 --- a/doc/installation.rst +++ b/doc/installation.rst @@ -14,7 +14,7 @@ To install the current release version, you can use: The :code:`[full]` option installs all the extra dependencies for all the different sub-modules. -Note that if using Z shell (:code:`zsh` - the default shell on mac), you will need to use quotes (:code:`pip install "spikeinterface[full]"`). +Note that if using Z shell (:code:`zsh` - the default shell on macOS), you will need to use quotes (:code:`pip install "spikeinterface[full]"`). To install all interactive widget backends, you can use: @@ -63,14 +63,14 @@ as :code:`spikeinterface` strongly relies on these packages to interface with va It is also sometimes useful to have local copies of :code:`neo` and :code:`probeinterface` to make changes to the code. To achieve this, repeat the first set of commands, -replacing `https://github.com/SpikeInterface/spikeinterface.git` with the appropriate repository in the first code block of this section. +replacing :code:`https://github.com/SpikeInterface/spikeinterface.git` with the appropriate repository in the first code block of this section. For beginners ------------- We provide some installation tips for beginners in Python here: -https://github.com/SpikeInterface/spikeinterface/tree/master/installation_tips +https://github.com/SpikeInterface/spikeinterface/tree/main/installation_tips @@ -89,12 +89,16 @@ Requirements Sub-modules have more dependencies, so you should also install: * zarr + * h5py * scipy * pandas * xarray - * sklearn + * scikit-learn * networkx * matplotlib + * numba + * distinctipy + * cuda-python (for non-macOS users) All external spike sorters can be either run inside containers (Docker or Singularity - see :ref:`containerizedsorters`) diff --git a/doc/modules/core.rst b/doc/modules/core.rst index 4c03950b1d..b25648a7a0 100644 --- a/doc/modules/core.rst +++ b/doc/modules/core.rst @@ -22,37 +22,6 @@ All classes support: * multiple segments, where each segment is a contiguous piece of data (recording, sorting, events). -Import rules ------------- - -Importing the SpikeInterface module - -.. code-block:: python - - import spikeinterface as si - -will only import the :code:`core` module. Other submodules must be imported separately: - -.. code-block:: python - - import spikeinterface.extractors as se - import spikeinterface.sorters as ss - import spikeinterface.widgets as sw - - -A second option is to import the SpikeInterface package in :code:`full` mode: - -.. code-block:: python - - import spikeinterface.full as si - -This import statement will import all of SpikeInterface modules as a flattened module. -Note that importing :code:`spikeinterface.full` will take a few extra seconds, because some modules use -just-in-time :code:`numba` compilation performed at the time of import. -We recommend this approach to advanced users, since it requires a deeper knowledge of the API. - - - Recording ---------