Markdown improvements in tutorial

Author: kushalbakshi

notebooks/tutorial.ipynb

@@ -7,19 +7,21 @@
    "source": [
     "# DataJoint Element Tutorial: Array Electrophysiology\n",
     "\n",
-    "Welcome to the DataJoint Element tutorial for Array Electrophysiology! Dive into the world of automated analyses and organization of extracellular array electrophysiology data.\n",
+    "Welcome to the tutorial for DataJoint's open-source data pipeline for NeuroPixels Array\n",
+    "Electrophysiology. This tutorial aims to provide a comprehensive understanding of the\n",
+    "open-source data pipeline created using `element-array-ephys` for processing\n",
+    "and analyzing extracellular electrophysiology datasets. \n",
     "\n",
     "**In this tutorial, we will cover:**\n",
     "- The basics:\n",
-    "  - Differentiating between an Element and a pipeline.\n",
-    "  - How to plot the pipeline with `dj.Diagram`.\n",
+    "  - Differentiating between an Element, module, schema, table, and pipeline.\n",
+    "  - How to plot an overview of the pipeline with `dj.Diagram`.\n",
     "- Hands-on interactions with the pipeline:\n",
-    "  - Inserting data into tables.\n",
+    "  - Inserting real data into tables.\n",
     "  - Querying table contents.\n",
     "  - Fetching table contents.\n",
-    "  - Running the pipeline for your experiments.\n",
     "- A walk-through:\n",
-    "  - Processing NeuroPixels ephys data acquired with OpenEphys and sorted with Kilosort.\n",
+    "  - Processing NeuroPixels ephys data acquired with OpenEphys and spike sorted with Kilosort.\n",
     "\n",
     "**Additional Resources:**\n",
     "- [Interactive Tutorials](https://github.com/datajoint/datajoint-tutorials) on `datajoint-python`: Dive deep into DataJoint's fundamentals.\n",
@@ -51,10 +53,13 @@
     "Each DataJoint Element is a modular set of tables that can be combined into a complete\n",
     "pipeline. Here are the definitions for clarity:\n",
     "\n",
-    "+ **Element**: A modular chunk of related tables.\n",
     "+ **Module**: In Python, a module is a file containing definitions and statements. In the context of DataJoint, modules often define and structure related database tables.\n",
+    "+ **Table**: A structured set of data held within the database. It consists of rows and\n",
+    "  columns, much like an Excel spreadsheet.\n",
     "+ **Schema**: Think of a schema as a container or namespace within the database where related tables are grouped together. It helps organize and manage the database structure.\n",
-    "+ **Table**: A structured set of data held within the database. It consists of rows and columns, much like an Excel spreadsheet.\n",
+    "+ **Element**: A modular set of related tables. \n",
+    "\n",
+    "---\n",
     "\n",
     "Each Element contains 1 or more modules, and each module declares its own schema in the database.\n",
     "\n",
@@ -67,7 +72,9 @@
     "| Element Session | [Link](https://github.com/datajoint/element-session) | [Link](https://datajoint.com/docs/elements/element-session) | General information of experimental sessions. |\n",
     "| Element Array Ephys | [Link](https://github.com/datajoint/element-array-ephys) | [Link](https://datajoint.com/docs/elements/element-array-ephys) |  NeuroPixels Array Electrophysiology analysis with Kilosort. |\n",
     "\n",
-    "By importing the modules for the first time, the schemas and tables will be created in the database.  Once created, importing modules will not create schemas and tables again, but the existing schemas/tables can be accessed.\n",
+    "By importing the modules for the first time, the schemas and tables will be created in\n",
+    "the database.  Once created, importing modules will not create schemas and tables\n",
+    "again, but will allow access to existing schemas/tables.\n",
     "\n",
     "The Elements are imported and activated within the `tutorial_pipeline` script."
    ]
@@ -622,7 +629,7 @@
    "source": [
     "## Understanding Table Types in DataJoint\n",
     "\n",
-    "In the previous section, we visualized the relationships between various tables in our pipeline using `dj.Diagram`. As you might have noticed, tables have different colors and shapes. This is because, in DataJoint, tables can be of different types, each serving a unique purpose.\n",
+    "In the previous cell, we visualized the relationships between various tables in our pipeline using `dj.Diagram`. As you might have noticed, tables have different colors and shapes. This is because, in DataJoint, tables can be of different types, each serving a unique purpose.\n",
     "\n",
     "| Table tier | Color and shape | Description | Practical Example |\n",
     "| -- | -- | -- | -- |\n",
@@ -650,7 +657,7 @@
     "DataJoint offers a powerful set of commands that allow us to interact with the pipeline:\n",
     "\n",
     "- **Insert**: Manually add data to a table.\n",
-    "- **Populate**: Automatically compute and add data based on existing data.\n",
+    "- **Populate**: Automatically compute and insert data.\n",
     "- **Query**: Search and filter data.\n",
     "- **Fetch**: Retrieve data for further analysis or visualization.\n",
     "\n",
@@ -692,7 +699,7 @@
     }
    ],
    "source": [
-    "subject.Subject.describe()"
+    "print(subject.Subject.describe())"
    ]
   },
   {
@@ -1399,7 +1406,7 @@
     "\n",
     "- **Part Tables**: If a table has part tables associated with it, calling `populate()` on the main table will also populate its part tables. This is especially useful in cases like `ephys.EphysRecording` and its part table `ephys.EphysRecording.EphysFile`, as they are closely linked in terms of data lineage.\n",
     "\n",
-    "- **Restriction**: The `populate()` method can be restricted to specific entries. For instance, by providing a `session_key`, we're ensuring the method only operates on the data relevant to that particular session. This is both efficient and avoids unnecessary operations on unrelated data.\n",
+    "- **Restriction**: The `populate()` method can be restricted to specific entries. For instance, by providing a `session_key`, we're ensuring the method only operates on the data relevant to that particular session. This is both efficient and avoids unnecessary operations.\n",
     "\n",
     "In the upcoming cells, we'll make use of the `populate()` method to fill the `ephys.EphysRecording` table and its part table. Remember, while this operation is automated, it's essential to understand the underlying logic to ensure accurate and consistent data entry.\n"
    ]
@@ -2448,10 +2455,20 @@
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
+    "## Conclusion\n",
+    "\n",
+    "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",
     "  instructions provide in the repository.\n",
@@ -2471,12 +2488,18 @@
     "dj.conn()\n",
     "```\n",
     "\n",
-    "- Run this code cell and proceed with the rest of the notebook."
+    "- Run this code block above and proceed with the rest of the notebook."
    ]
   },
   {
-   "cell_type": "markdown",
-   "metadata": {},
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "vscode": {
+     "languageId": "plaintext"
+    }
+   },
+   "outputs": [],
    "source": []
   }
  ],