add markdown in setup

Author: MilagrosMarin

notebooks/tutorial.ipynb

@@ -33,7 +33,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The package is designed to **process NeuroPixels ephys data** with **OpenEphys** and spike sorted with **Kilosort**."
+    "The package is designed to **process NeuroPixels ephys data** with **OpenEphys** and spike sorted with **Kilosort**. The following Diagram corresponds to the `ephys_acute` module:"
    ]
   },
   {
@@ -73,7 +73,7 @@
     "\n",
     "**- Step 4: Curate the Clustering Results (Optional)**\n",
     "\n",
-    "**- Step 4: Visualize the Results**"
+    "**- Step 5: Visualize the Results**"
    ]
   },
   {
@@ -83,6 +83,17 @@
     "### **Setup**"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "This tutorial examines the `ephys_acute` module applied to physiological recordings and automatic ingestion of spike sorting results.\n",
+    "\n",
+    "The goal is to store, track and manage different curations of the spike sorting results and unit-level visualization results.\n",
+    "\n",
+    "The results of this Element example can be combined with other modalities to create a complete customizable data pipeline for your specific lab or study. For instance, you can combine `element-array-ephys` with `element-calcium-imaging` and `element-deeplabcut` to characterize the neural activity."
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -603,6 +614,13 @@
     "ephys.Clustering.populate(session_key, display_progress=True)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### **Step 4: Curate the Clustering Results (Optional)**"
+   ]
+  },
   {
    "attachments": {},
    "cell_type": "markdown",
@@ -657,54 +675,25 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Now that we've populated the tables in this workflow, there are one of\n",
-    "several next steps. If you have an existing workflow for\n",
+    "Now that we've populated the tables in this DataJoint pipeline, there are one of\n",
+    "several next steps. If you have an existing pipeline for\n",
     "aligning waveforms to behavior data or other stimuli, you can easily\n",
     "invoke `element-event` or define your custom DataJoint tables to extend the\n",
-    "pipeline.\n",
-    "\n",
-    "In this tutorial, we will do some exploratory analysis by fetching the data from the database and creating a few plots.\n",
-    "\n",
-    "## Querying Data\n",
-    "\n",
-    "DataJoint provides a powerful querying system, allowing you to retrieve and work with data stored in your database seamlessly. In this section, we'll explore the fundamental querying concepts.\n",
-    "\n",
-    "#### What is a Query?\n",
-    "\n",
-    "- A query is essentially a request for data. With DataJoint, you can craft specific queries to fetch data that meets your criteria from the database.\n",
-    "\n",
-    "#### The `fetch()` Method\n",
-    "\n",
-    "- The primary method for retrieving data from a DataJoint table is `fetch()`.\n",
-    "- **Default Behavior**: Without any arguments, `fetch()` returns a list of dictionaries. Each dictionary corresponds to an entry in the table.\n",
-    "  \n",
-    "#### The `fetch1()` Method\n",
-    "\n",
-    "- For tables with a single entry or when you're only interested in the first entry, use `fetch1()`.\n",
-    "- **Default Behavior**: It returns a dictionary of attributes for that one entry.\n",
-    "\n",
-    "#### Specific Attributes\n",
-    "\n",
-    "- Both `fetch()` and `fetch1()` can be made more specific by providing attributes.\n",
-    "- Example: `fetch1('fps')` will retrieve only the `fps` attribute from the first entry.\n",
-    "\n",
-    "#### Restricting Queries\n",
-    "\n",
-    "- Often, you don't want to fetch everything. Instead, you might want data related to a specific subject or session.\n",
-    "- DataJoint uses the `&` operator to restrict queries.\n",
-    "- Example: To get all session times for `subject5`, you might use:\n",
-    "  ```python\n",
-    "  subject1_times = (session.Session & \"subject = 'subject1'\").fetch(\"session_datetime\")\n",
-    "  ```\n",
-    "\n",
-    "#### Fetching Primary Keys\n",
-    "\n",
-    "- Sometimes, you just need the primary keys of entries.\n",
-    "- Use the `fetch(\"KEY\")` syntax for this. For instance, `(session.Session).fetch(\"KEY\")`.\n",
-    "\n",
-    "#### Let's Dive In!\n",
-    "\n",
-    "Now that we've established the basics, let's delve deeper into querying with some practical examples."
+    "pipeline."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### **Step 5: Visualization of Results**"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "In this tutorial, we will do some exploratory analysis by fetching the data from the database and creating a few plots."
    ]
   },
   {
@@ -825,16 +814,61 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Conclusion\n",
+    "## Summary\n",
     "\n",
+    "Following this tutorial, we've efficiently: \n",
+    "- covered the essential functionality of `element-array-ephys`\n",
+    "- acquired the skills to register the electrophysiology recordings for each probe in each experimental session\n",
+    "- insert data into tables\n",
+    "- execute the spike sort with Kilosort\n",
+    "- visualize the results "
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "#### Documentation and DataJoint tutorials"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "For detailed documentation on `element-array-ephys`:\n",
+    "\n",
+    "[`DataJoint Element for Extracellular Electrophysiology  - Documentation`](https://datajoint.com/docs/elements/element-array-ephys/)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "For detailed documentation and tutorials on general DataJoint principles that support collaboration, automation, reproducibility, and visualizations:\n",
+    "\n",
+    "[`DataJoint for Python - Interactive Tutorials`](https://github.com/datajoint/datajoint-tutorials) covers fundamentals, including table tiers, query operations, fetch operations, automated computations with the make function, and more.\n",
+    "\n",
+    "[`DataJoint for Python - Documentation`](https://datajoint.com/docs/core/datajoint-python/0.14/)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "#### Run this tutorial on your own data"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
     "Throughout this notebook, we've used DataJoint to work with database tables and keep\n",
     "data organized and automate analyses to increase efficiency of data processing. We've\n",
     "inserted data into tables, used queries to retrieve, manipulate, and visualize ephys data.\n",
     "\n",
     "Remember, this is just the beginning. As you grow familiar with DataJoint, you'll\n",
     "uncover even more ways to harness its capabilities for your specific research needs. \n",
     "\n",
-    "---\n",
     "\n",
     "To run this tutorial notebook on your own data, please use the following steps:\n",
     "- Download the mysql-docker image for DataJoint and run the container according to the\n",
@@ -857,18 +891,6 @@
     "\n",
     "- Run this code block above and proceed with the rest of the notebook."
    ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "**Additional Resources:**\n",
-    "- [Interactive Tutorials](https://github.com/datajoint/datajoint-tutorials) on `datajoint-python`: Dive deep into DataJoint's fundamentals.\n",
-    "- [*`datajoint-python`* Documentation](https://datajoint.com/docs/core/datajoint-python/): Comprehensive documentation on DataJoint for Python.\n",
-    "- [Element Array Electrophysiology Documentation](https://datajoint.com/docs/elements/element-array-ephys/): Detailed guide on the DataJoint Element for Array Electrophysiology.\n"
-   ]
   }
  ],
  "metadata": {