Merge pull request #112 from NeurodataWithoutBorders/update_conversio…

…n_guide

update conversion guide

docs/source/conversion_tutorial/01_core_nwb.rst

@@ -1,20 +1,24 @@
-1. Core NWB
-===========
+1. NWB Conversions
+==================
 
-First, we need to understand what types of data go into NWB. The goal of NWB
-is to package all of the data in a particular session into a single file.
+The goal of NWB is to package experiment data with the metadata necessary to
+analyze the data. All of the data in a particular session goes into a single file.
 This includes the neurophysiology data itself, but also includes other data such
 as information about the data acquisition, experiment design, experimental subject,
 and behavior of that subject. The NWB core schema defines data containers for
-the most common data objects in neurophysiology data. The NWB core currently covers
-the following experiment types: intracellular electrophysiology (e.g. patch clamping), extracellular
-electrophysiology (e.g. Neuropixel probes), and optical physiology (e.g. two-photon imaging).
+common data objects in neurophysiology data, including: intracellular
+electrophysiology (e.g. patch clamping), extracellular electrophysiology
+(e.g. Neuropixel probes), and optical physiology (e.g. two-photon imaging), and behavior.
 
 .. image:: /img/nwb_overview.png
 
-All of these data types and relationships are defined using
-`HDMF <https://hdmf-schema-language.readthedocs.io/en/latest/>`_,
-a specification language for describing complex structures of data. NWB is faced with the challenge
-of supporting a large variety of different experiment types, so the data types and relationships
-can get quite complex. For this reason the NWB development team provides APIs to help users easily
-and efficiently read and write NWB files. These APIs are described in the next section.
+All of these data types and relationships are defined in the
+`NWB Schema <https://nwb-schema.readthedocs.io/>`_ using the
+`HDMF specification language <https://hdmf-schema-language.readthedocs.io/en/latest/>`_.
+NWB is faced with the challenge of supporting a large variety of different experiment
+types, so the data types and relationships can get quite complex. For this reason the
+NWB development team provides APIs to help users easily and efficiently read and
+write NWB files.
+
+The following sections start with the most automated and convenient approaches
+and proceed to more involved and customizable solutions.

docs/source/conversion_tutorial/02_format_conversions.md

@@ -0,0 +1,17 @@
+# 2. Automatic NWB Conversions using NeuroConv
+
+[NeuroConv](https://neuroconv.readthedocs.io/) is a library for automatic conversions from proprietary formats to NWB.
+A gallery of all supported formats can be found
+[here](https://neuroconv.readthedocs.io/en/main/conversion_examples_gallery/conversion_example_gallery.html).
+If NeuroConv supports your source data format, this is the recommended approach, because it is easiest to
+implement and automatically helps you adhere to best practices. For advanced usage of NeuroConv, including creating
+conversions of ensembles of multiple data streams, see the
+[NeuroConv User Guide](https://neuroconv.readthedocs.io/en/main/user_guide/user_guide.html).
+
+Although NeuroConv supports many common formats, it may not support every type of source data you need.
+If your source format is likely to be a common need in the community, for example the output of an acquisition
+system or a popular data processing package, please use
+[this form](https://github.com/catalystneuro/neuroconv/issues/new?assignees=&labels=enhancement%2Cdata+interfaces&template=format_request.yml&title=%5BNew+Format%5D%3A+)
+to request support for this format. On the other hand, some data formats can be ad-hoc, particularly data about task and
+behavior. In this case, proceed to the next section for detailed tutorials on using the PyNWB API to manually add this
+data to the NWB file.

docs/source/conversion_tutorial/02_nwb_apis.rst → docs/source/conversion_tutorial/03_nwb_apis.rst

@@ -1,4 +1,4 @@
-2. NWB APIs: PyNWB & MatNWB
+3. NWB APIs: PyNWB & MatNWB
 ===========================
 
 The NWB team develops and supports APIs in Python

docs/source/conversion_tutorial/user_guide.rst

@@ -13,8 +13,8 @@ automated tools for converting formats.
     :maxdepth: 2
 
     01_core_nwb
-    02_nwb_apis
-    03_format_conversions
+    02_format_conversions
+    03_nwb_apis
     04_using_extensions
     05_validation
     06_dandi