Merge branch 'main' into units-table

NeurodataWithoutBorders · Mar 29, 2024 · e28e6b2 · e28e6b2
2 parents 7c3f044 + eac9e23
commit e28e6b2
Show file tree

Hide file tree

Showing 30 changed files with 842 additions and 570 deletions.
diff --git a/...tutorials/screenshots/dataset-created.png → docs/assets/tutorials/dataset-created.png b/...tutorials/screenshots/dataset-created.png → docs/assets/tutorials/dataset-created.png
diff --git a/...utorials/screenshots/dataset-creation.png → docs/assets/tutorials/dataset-creation.png b/...utorials/screenshots/dataset-creation.png → docs/assets/tutorials/dataset-creation.png
diff --git a/docs/assets/tutorials/home-page.png b/docs/assets/tutorials/home-page.png
diff --git a/docs/assets/tutorials/single/all-interfaces-added.png b/docs/assets/tutorials/single/all-interfaces-added.png
diff --git a/docs/assets/tutorials/single/conversion-results-page.png b/docs/assets/tutorials/single/conversion-results-page.png
diff --git a/docs/assets/tutorials/single/fail-name.png b/docs/assets/tutorials/single/fail-name.png
diff --git a/docs/assets/tutorials/single/format-options.png b/docs/assets/tutorials/single/format-options.png
diff --git a/docs/assets/tutorials/single/formats-page.png b/docs/assets/tutorials/single/formats-page.png
diff --git a/docs/assets/tutorials/single/home-page-complete.png b/docs/assets/tutorials/single/home-page-complete.png
diff --git a/docs/assets/tutorials/single/info-page.png b/docs/assets/tutorials/single/info-page.png
diff --git a/docs/assets/tutorials/single/inspect-page.png b/docs/assets/tutorials/single/inspect-page.png
diff --git a/docs/assets/tutorials/single/interface-added.png b/docs/assets/tutorials/single/interface-added.png
diff --git a/docs/assets/tutorials/single/intro-page.png b/docs/assets/tutorials/single/intro-page.png
diff --git a/docs/assets/tutorials/single/metadata-ecephys.png b/docs/assets/tutorials/single/metadata-ecephys.png
diff --git a/docs/assets/tutorials/single/metadata-nwbfile.png b/docs/assets/tutorials/single/metadata-nwbfile.png
diff --git a/docs/assets/tutorials/single/metadata-page.png b/docs/assets/tutorials/single/metadata-page.png
diff --git a/docs/assets/tutorials/single/metadata-subject-complete.png b/docs/assets/tutorials/single/metadata-subject-complete.png
diff --git a/docs/assets/tutorials/single/preview-page.png b/docs/assets/tutorials/single/preview-page.png
diff --git a/docs/assets/tutorials/single/search-behavior.png b/docs/assets/tutorials/single/search-behavior.png
diff --git a/docs/assets/tutorials/single/sourcedata-page-specified.png b/docs/assets/tutorials/single/sourcedata-page-specified.png
diff --git a/docs/assets/tutorials/single/sourcedata-page.png b/docs/assets/tutorials/single/sourcedata-page.png
diff --git a/docs/assets/tutorials/single/valid-name.png b/docs/assets/tutorials/single/valid-name.png
diff --git a/docs/assets/tutorials/single/workflow-page.png b/docs/assets/tutorials/single/workflow-page.png
diff --git a/docs/tutorials/dataset.rst b/docs/tutorials/dataset.rst
@@ -11,38 +11,47 @@ To get you started as quickly as possible, we’ve created a way to generate thi
 
 Navigate to the **Settings** page using the main sidebar. Then press the **Generate** button in the top-right corner to initiate the dataset creation.
 
-.. figure:: ./screenshots/dataset-creation.png
+.. figure:: ../assets/tutorials/dataset-creation.png
   :align: center
   :alt: Dataset Creation Screen
 
   Press the Generate button on the Settings page to create the dataset.
 
-The generated dataset will be organized as follows:
+The generated data will populate in the `~/NWB_GUIDE/test_data` directory and include a `data` folder with the original data as well as a `dataset` folder that duplicates this `data` across multiple subjects and sessions.
 
 .. code-block:: bash
 
-    dataset/
-    ├── mouse1/
-    │   ├── mouse1_Session1/
-    │   │   ├── mouse1_Session1_g0/
-    │   │   │   ├── mouse1_Session1_g0_imec/
-    │   │   │   │   ├── mouse1_Session1_g0_imec.ap.bin
-    │   │   │   │   ├── mouse1_Session1_g0_imec.ap.meta
-    │   │   │   │   ├── mouse1_Session1_g0_imec.lf.bin
-    │   │   │   │   └── mouse1_Session1_g0_imec.lf.meta
-    │   │   │   └── mouse1_Session1_phy/
-    │   │   │
-    │   │   └── mouse1_Session2/
-    │   │       ├── mouse1_Session2_g0/
-    │   │       │   ...
-    │   │       └── mouse1_Session2_phy/
-    │   │           ...
-    │   │
-    └── mouse2/
-        ├── mouse2_Session1/
-        │   ...
-        │
-        └── mouse2_Session2/
-            ...
+  test-data/
+  ├── data/
+  │   ├── spikeglx/
+  │   │   ├── Session1_g0/
+  │   │   │   ├── Session1_g0_imec0/
+  │   │   │   │   ├── Session1_g0_t0.imec0.ap.bin
+  │   │   │   │   ├── Session1_g0_t0.imec0.ap.meta
+  │   │   │   │   ├── Session1_g0_t0.imec0.lf.bin
+  │   │   │   │   └── Session1_g0_t0.imec0.lf.meta
+  │   │   └── phy/
+  ├── dataset/
+  │   ├── mouse1/
+  │   │   ├── mouse1_Session1/
+  │   │   │   ├── mouse1_Session1_g0/
+  │   │   │   │   ├── mouse1_Session1_g0_imec0/
+  │   │   │   │   │   ├── mouse1_Session1_g0_t0.imec0.ap.bin
+  │   │   │   │   │   ├── mouse1_Session1_g0_t0.imec0.ap.meta
+  │   │   │   │   │   ├── mouse1_Session1_g0_t0.imec0.lf.bin
+  │   │   │   │   │   └── mouse1_Session1_g0_t0.imec0.lf.meta
+  │   │   │   │   └── mouse1_Session1_phy/
+  │   │   │   └── mouse1_Session2/
+  │   │   │       ├── mouse1_Session2_g0/
+  │   │   │       │   ...
+  │   │   │       └── mouse1_Session2_phy/
+  │   │   │           ...
+  │   ├── mouse2/
+  │   │   ├── mouse2_Session1/
+  │   │   │   ...
+  │   │   └── mouse2_Session2/
+  │   │       ...
+
+
 
 Now you’re ready to start your first conversion using the NWB GUIDE!
diff --git a/docs/tutorials/single_session.rst b/docs/tutorials/single_session.rst
@@ -1,3 +1,169 @@
 Converting a Single Session
-=======================================
-Coming soon...
+===========================
+
+As a researcher, you’ve just completed an experimental session and you’d like to convert your data to NWB right away.
+
+Upon launching the GUIDE, you'll begin on the Conversions page. If you’re opening the application for the first time, there should be no pipelines listed on this page.
+
+.. figure:: ../assets/tutorials/home-page.png
+  :align: center
+  :alt: Home page
+
+Press the **Create a new conversion pipeline** button to start the conversion process.
+
+Project Structure
+-----------------
+
+Project Setup
+^^^^^^^^^^^^^
+
+The Project Setup page will have you define two pieces of information about your pipeline: the **name** and, optionally, the **output location** for your NWB files.
+
+.. note::
+   Choosing a good output location is important for two reasons, namely **conversion speed** and **disk space**.
+
+   1. SSDs will be much faster than HDDs. We’d recommend moving the output location to an SSD if available.
+   2. If you don’t have much disk space available on your main drive, we recommend changing the output location to a drive that has ample space.
+
+
+You’ll notice that the name property has a red asterisk next to it, which identifies it as a required property.
+
+.. figure:: ../assets/tutorials/single/info-page.png
+  :align: center
+  :alt: Project Setup page with no name (invalid)
+
+
+After specifying a unique project name, the colored background and error message will disappear, allowing you to advance to the next page.
+
+.. figure:: ../assets/tutorials/single/valid-name.png
+  :align: center
+  :alt: Project Setup page with valid name
+
+Workflow Configuration
+^^^^^^^^^^^^^^^^^^^^^^
+On this page, you’ll specify the type of **workflow** you’d like to follow for this conversion pipeline.
+
+Since this is a single-session workflow, you’ll need to specify a **Subject ID** and **Session ID** to identify the data you’ll be converting.
+
+.. figure:: ../assets/tutorials/single/workflow-page.png
+  :align: center
+  :alt: Workflow page
+
+Additionally, we’ll turn off the option to upload to the DANDI Archive and approach this in a later tutorial.
+
+Data Formats
+^^^^^^^^^^^^
+Next, you’ll specify the data formats you’re working with on the Data Formats page. The GUIDE supports 40+ total neurophysiology formats. A full registry of available formats is available :doc:`here </format_support>`.
+
+.. figure:: ../assets/tutorials/single/formats-page.png
+  :align: center
+  :alt: Date Formats page
+
+The tutorial we're working with uses the SpikeGLX and Phy formats, a common output for NeuroPixel recordings and subsequent spike sorting. To specify that your pipeline will handle these files, you’ll press the “Add Format” button.
+
+.. figure:: ../assets/tutorials/single/format-options.png
+  :align: center
+  :alt: Format pop-up on the Data Formats page
+
+Then, select the relevant formats—in this case, **SpikeGLX Recording** and **Phy Sorting**—from the pop-up list. Use the search bar to filter for the format you need.
+
+
+.. figure:: ../assets/tutorials/single/search-behavior.png
+  :align: center
+  :alt: Searching for SpikeGLX in the format pop-up
+
+The selected formats will then display above the button.
+
+
+.. figure:: ../assets/tutorials/single/interface-added.png
+  :align: center
+  :alt: Data Formats page with SpikeGLX Recording added to the list
+
+Advance to the next page when you have **SpikeGLX Recording** and **Phy Sorting** selected.
+
+.. figure:: ../assets/tutorials/single/all-interfaces-added.png
+  :align: center
+  :alt: Data Formats page with both SpikeGLX Recording and Phy Sorting added to the list
+
+Data Entry
+-----------
+
+Source Data Information
+^^^^^^^^^^^^^^^^^^^^^^^
+On this page, specify the relevant **.bin** (Spikeglx) file and **phy** folder so that the GUIDE can find this source data to complete the conversion.
+
+As discussed in the :doc:`Dataset Generation </tutorials/dataset>` tutorial, these can be found in the `~/NWB_GUIDE/test-data/data` directory.
+
+You can either click the file selector to navigate to the file or drag-and-drop into the GUIDE from your file navigator.
+
+.. figure:: ../assets/tutorials/single/sourcedata-page-specified.png
+  :align: center
+  :alt: Source Data page with source locations specified
+
+
+Session Metadata
+^^^^^^^^^^^^^^^^
+The file metadata page is a great opportunity to add rich annotations to the file, which will be read by anyone reusing your data in the future!
+
+The Session Start Time in the General Metadata section is already specified because this field was automatically extracted from the SpikeGLX source data.
+
+.. figure:: ../assets/tutorials/single/metadata-nwbfile.png
+  :align: center
+  :alt: Metadata page with invalid Subject information
+
+
+However, we still need to add the Subject information—as noted by the red accents around that item. Let’s say that our subject is a male mouse with an age of P30D.
+
+.. figure:: ../assets/tutorials/single/metadata-subject-complete.png
+  :align: center
+  :alt: Metadata page with valid Subject information
+
+  The status of the Subject information will update in real-time as you fill out the form.
+
+
+This dataset will also have **Ecephys** metadata extracted from the SpikeGLX source data.
+
+.. figure:: ../assets/tutorials/single/metadata-ecephys.png
+  :align: center
+  :alt: Ecephys metadata extracted from the SpikeGLX source data
+
+
+Let's leave this as-is and advance to the next page.
+
+The next step generates a preview file and displays real-time progress throughout the conversion process.
+
+File Conversion
+---------------
+
+Inspector Report
+^^^^^^^^^^^^^^^^
+
+The Inspector Report page allows you to validate the preview file against the latest Best Practices and make suggestions to improve the content or representations.
+
+.. figure:: ../assets/tutorials/single/inspect-page.png
+  :align: center
+  :alt: NWB Inspector report
+
+
+
+Conversion Preview
+^^^^^^^^^^^^^^^^^^
+On the Conversion Preview, Neurosift allows you to explore the structure of the NWB file and ensure the packaged data matches your expectations.
+
+
+.. figure:: ../assets/tutorials/single/preview-page.png
+  :align: center
+  :alt: Neurosift preview visualization
+
+Advancing from this page will trigger the full conversion of your data to the NWB format, a process that may take some time depending on the dataset size.
+
+Conversion Review
+^^^^^^^^^^^^^^^^^
+
+Congratulations on finishing your first conversion of neurophysiology files using the NWB GUIDE!
+
+.. figure:: ../assets/tutorials/single/conversion-results-page.png
+  :align: center
+  :alt: Conversion results page with a list of converted files
+
+This was a straightforward workflow with only a single session... But what if you have multiple sessions to convert?