feat: save WIP on tutorials

fix: swap from info to tips

fix: add to index

fix: add to index

Author: CodyCBakerPhD

docs/index.rst

@@ -4,6 +4,7 @@
    :hidden:
 
    user_guide
+   tutorials
    developer_guide
    api/index
 

docs/tutorials.rst

@@ -0,0 +1,125 @@
+:html_theme.sidebar_secondary.remove:
+
+.. _tutorials:
+
+Tutorials
+=========
+
+**nwb2bids** comes pre-packaged with some demonstrative tools to help showcase its functionality on various types of
+NWB file contents. No additional requirements, knowledge, or experience are necessary to run these tutorials!
+
+
+
+Tutorial 1 - Converting a single file
+-------------------------------------
+
+In case you don't have any NWB files handy, or perhaps you've never worked with NWB files before, you can generate a
+toy example through the command line interface (CLI) as follows:
+
+.. code-block:: bash
+
+    nwb2bids tutorial generate ephys
+
+This created an NWB file with contents typical of an extracellular electrophysiology experiment in your home
+directory for **nwb2bids**: ``~/.nwb2bids/tutorials/ephys/nwb2bids_tutorial_ephys.nwb``.
+
+.. note::
+
+    Don't like overwhelming your home directory with lots of small files?
+
+    You can control where tutorial data is generated by using the ``--output-directory`` flag (or ``-o`` for short):
+
+    .. code-block:: bash
+
+        nwb2bids tutorial generate ephys --output-directory path/to/some/directory
+
+NWB files like this contain a lot of metadata about the probes and electrode structure, which will be useful later
+when we compare the source file to the sidecar tables found in BIDS. You can explore these file contents through
+`neurosift.app <neurosift.app>`_ by following this link: TODO
+
+.. tip::
+
+    The link above actually points to a similar file published on the DANDI Archive, which should be identical to
+    what what written on your system. You can explore and visualize your local file contents and structure
+    in many other ways, such as the
+    `NWB GUIDE <https://nwb-guide.readthedocs.io/en/stable/installation.html>`_,
+    `HDFView <https://www.hdfgroup.org/download-hdfview/>`_, or the
+    `PyNWB library <https://pynwb.readthedocs.io/en/stable/tutorials/general/plot_read_basics.html#reading-and-exploring-an-nwb-file>`_.
+
+Now that we have an NWB file, we can convert it to BIDS using the following command:
+
+.. code-block:: bash
+
+    nwb2bids convert ~/.nwb2bids/tutorials/ephys/nwb2bids_tutorial_ephys.nwb --bids-directory ~/.nwb2bids/tutorials/ephys/bids_dataset
+
+Notice how we explicitly specified the output BIDS directory using the ``--bids-directory`` flag. We will cover the
+implicit (current working directory) approach in TODO: crossref to later tutorial.
+
+
+Tutorial 2 - Converting multiple files
+--------------------------------------
+
+
+
+.. tip::
+
+    Lost in the CLI? Can't remember the exact phrase to type when navigating through the command groups? No worries!
+    Simply add the ``--help`` to any command to see detailed descriptions, expected inputs, and optional flags.
+
+    You can also see a layout of the command structure by calling each level at a time, for example ``nwb2bids``,
+    ``nwb2bids tutorial``, and so on.
+
+    Try it out on ``nwb2bids tutorial generate`` to see all the types of tutorial data we can generate for you.
+
+This command assumes you are located within either an empty directory or a BIDS dataset, informing you accordingly if
+these conditions are not met.
+
+To specify a specific location other than your current working directory, use the ``--bids-directory``
+flag (or ``-o`` for short):
+
+.. code-block:: bash
+
+   nwb2bids convert [path to NWB files] --bids-directory [path to BIDS directory]
+
+The main input to the interface can be any combination of directories containing NWB files or individual NWB files:
+
+.. code-block:: bash
+
+   nwb2bids convert path/to/many/nwb single.nwb another.nwb
+
+
+
+Application Programming Interface (API)
+---------------------------------------
+
+A more advanced usage of **nwb2bids** is through its Python library. A thorough description of all publicly exposed
+functions and classes can be found in the :ref:`API <api>` section of the documentation.
+
+The core function is the ``convert_nwb_to_bids`` function, which can be used as follows:
+
+.. code-block:: python
+
+   import nwb2bids
+
+   nwb2bids.convert_nwb_to_bids(
+       nwb_paths=["path/to/many/nwb", "single.nwb", "another.nwb"],
+       bids_directory="path/to/bids/directory"  # Optional, defaults to current working directory
+   )
+
+Essentially, this function is direct wrapper used by the CLI and behaves in the same way.
+
+One key programmatic difference however is the ability to interact with the notifications returned by the operation:
+
+.. code-block:: python
+
+   import nwb2bids
+
+   notifications = nwb2bids.convert_nwb_to_bids(
+       nwb_paths=["path/to/many/nwb", "single.nwb", "another.nwb"],
+       bids_directory="path/to/bids/directory"
+   )
+
+   for notification in notifications:
+       print(notification)
+
+More examples to follow soon...

src/nwb2bids/_command_line_interface/_main.py

@@ -4,6 +4,7 @@
 import rich_click
 
 from .._core._convert_nwb_dataset import convert_nwb_dataset
+from ..testing import generate_ephys_tutorial
 
 
 # nwb2bids
@@ -79,3 +80,27 @@ def _run_convert_nwb_dataset(
         )
         console_notification = rich_click.style(text=text, fg="yellow")
         rich_click.echo(message=console_notification)
+
+
+# nwb2bids tutorial
+@_nwb2bids_cli.group(name="tutorial")
+def _nwb2bids_tutorial_cli():
+    pass
+
+
+# nwb2bids tutorial ephys
+@_nwb2bids_tutorial_cli.command(name="ephys")
+@rich_click.option(
+    "--output-directory",
+    "-o",
+    help="Path to the folder where the tutorial files will be created (default: user home directory).",
+    required=False,
+    type=rich_click.Path(writable=True),
+    default=None,
+)
+def _nwb2bids_tutorial_ephys_cli(output_directory: str | None = None) -> None:
+    file_path = generate_ephys_tutorial(output_directory=output_directory)
+
+    text = f"Example single session NWB file generated successfully at {file_path}."
+    message = rich_click.style(text=text, fg="green")
+    rich_click.echo(message=message)

src/nwb2bids/testing/__init__.py

@@ -1,8 +1,10 @@
 from ._assert_subdirectory_structure import assert_subdirectory_structure
 from ._mocks._mock_neurodata_objects import mock_time_intervals, mock_epochs_table, mock_trials_table
+from ._mocks._mock_files import generate_ephys_tutorial
 
 __all__ = [
     "assert_subdirectory_structure",
+    "generate_ephys_tutorial",
     "mock_epochs_table",
     "mock_time_intervals",
     "mock_trials_table",

src/nwb2bids/testing/_mocks/_mock_files.py

@@ -0,0 +1,36 @@
+import pathlib
+
+import pydantic
+import pynwb
+import pynwb.testing.mock.ecephys
+import pynwb.testing.mock.file
+
+
+@pydantic.validate_call
+def generate_ephys_tutorial(output_directory: pydantic.DirectoryPath | None) -> pathlib.Path:
+    if output_directory is None:
+        # TODO: update to common home/config utility
+        tutorial_dir = pathlib.Path.home() / ".nwb2bids" / "tutorials"
+        tutorial_dir.mkdir(parents=True, exist_ok=True)
+        output_directory = tutorial_dir / "ephys"
+        output_directory.mkdir(exist_ok=True)
+
+    nwbfile = pynwb.testing.mock.file.mock_NWBFile(
+        session_description="An example NWB file containing ephys neurodata types - for use in the nwb2bids tutorials."
+    )
+
+    electrical_series = pynwb.testing.mock.ecephys.mock_ElectricalSeries(
+        name="ExampleElectricalSeries",
+        description=(
+            "An example electrical series that represents data which could have been "
+            "read off of the channels of an ephys probe."
+        ),
+        nwbfile=nwbfile,
+    )
+    nwbfile.add_acquisition(electrical_series)
+
+    nwbfile_path = output_directory / "ephys.nwb"
+    with pynwb.NWBHDF5IO(name=nwbfile_path, mode="w") as file_stream:
+        file_stream.write(nwbfile)
+
+    return nwbfile_path