Merge pull request #2 from MilagrosMarin/fix_update_tutorial

Fix the bug with the Jupyter Notebook version before merge

Author: MilagrosMarin

README.md

@@ -1,21 +1,24 @@
 # Welcome to DataJoint tutorials!
 
-DataJoint is an open-source library for science labs to design and build data pipelines for automated data analysis and sharing.
+DataJoint is an open-source library for scientific research labs to design and build
+data pipelines for automated data analysis and sharing.
 
-This document will guide you as a new DataJoint user through interactive tutorials organized in [Jupyter notebooks](https://jupyter-notebook.readthedocs.io/en/stable/) and written in [Python](https://www.python.org/).
+This document will guide you through interactive tutorials written in
+[Python](https://www.python.org/) and organized in [Jupyter
+notebooks](https://jupyter-notebook.readthedocs.io/en/stable/).
 
 *Please note that these hands-on DataJoint tutorials are friendly to non-expert users, and advanced programming skills are not required.* 
 
 
 ## Table of contents 
-- In the [tutorials](./tutorials) folder are interactive Jupyter notebooks to learn DataJoint. The calcium imaging and electrophysiology tutorials provide examples of defining and interacting with data pipelines. In addition, some fill-in-the-blank sections are included for you to code yourself!
+- The [tutorials](./tutorials) folder contains interactive Jupyter notebooks designed to teach DataJoint. The calcium imaging and electrophysiology tutorials provide examples of defining and interacting with data pipelines. In addition, some fill-in-the-blank sections are included for you to code yourself!
     - 01-DataJoint Basics
     - 02-Calcium Imaging Imported Tables
     - 03-Calcium Imaging Computed Tables
     - 04-Electrophysiology Imported Tables
     - 05-Electrophysiology Computed Tables
 
-- In the [completed_tutorials](./completed_tutorials) folder are Jupyter notebooks with the code sections completed and solved.
+- The [completed_tutorials](./completed_tutorials) folder contains Jupyter notebooks with all code sections completed and solved.
 
 - You will find the following notebooks in the [short_tutorials](./short_tutorials) folder:
     - DataJoint in 30min

tutorials/01-DataJoint Basics.ipynb

@@ -51,7 +51,9 @@
     "If you visit the [documentation for DataJoint](https://docs.datajoint.io/introduction/Data-pipelines.html), we define a data pipeline as follows:\n",
     "> A data pipeline is a sequence of steps (more generally a directed acyclic graph) with integrated storage at each step. These steps may be thought of as nodes in a graph.\n",
     "\n",
-    "While this is an accurate description, it may not be the most intuitive definition. Put succinctly, a data pipeline is a listing or a \"map\" of various \"things\" that you work with in a project, with line connecting things to each other to indicate their dependencies. The \"things\" in a data pipeline tends to be the *nouns* you find when describing a project. The \"things\" may include anything from mouse, experimenter, equipment, to experiment session, trial, two-photon scans, electric activities, to receptive fields, neuronal spikes, to figures for a publication! A data pipeline gives you a framework to:\n",
+    ">* Nodes in this graph are represented as database **tables**. Examples of such tables include \"Subject\", \"Session\", \"Implantation\", \"Experimenter\", \"Equipment\", but also \"OptoWaveform\", \"OptoStimParams\", or \"Neuronal spikes\".  \n",
+    "\n",
+    ">* The data pipeline is formed by making these tables interdependent (as the nodes are connected in a network). A **dependency** is a situation where a step of the data pipeline is dependent on a result from a sequentially previous step before it can complete its execution. A dependency graph forms an entire cohesive data pipeline. \n",
     "\n",
     "1. define these \"things\" as tables in which you can store the information about them\n",
     "2. define the relationships (in particular the dependencies) between the \"things\"\n",
@@ -65,7 +67,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Building our first pipeline: "
+    "##### Practical examples"
    ]
   },
   {
@@ -129,21 +131,21 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Just by going though the description, we can start to identify **things** or **entities** that we might want to store and represent in our data pipeline:\n",
-    "\n",
-    "* mouse\n",
-    "* experimental session\n",
-    "\n",
-    "For ephys:\n",
-    "\n",
-    ">* neuron\n",
-    ">* spikes\n",
-    "\n",
-    "For calcium imaging:\n",
-    "\n",
-    ">* scan\n",
-    ">* regions of interest\n",
-    ">* trace"
+   "Just by going through the description, we can start to identify **entities** that needs to be stored and represented in our data pipeline:\n",
+   "\n",
+   "* mouse\n",
+   "* experimental session\n",
+   "\n",
+   "For ephys:\n",
+   "\n",
+   ">* neuron\n",
+   ">* spikes\n",
+   "\n",
+   "For calcium imaging:\n",
+   "\n",
+   ">* scan\n",
+   ">* regions of interest\n",
+   ">* trace"
    ]
   },
   {
@@ -157,16 +159,32 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "In DataJoint data pipeline, we represent these **entities** as **tables**. Different *kinds* of entities become distinct tables, and each row of the table is a single example (instance) of the category of entity. \n",
-    "\n",
-    "For example, if we have a `Mouse` table, then each row in the mouse table represents a single mouse!"
+   "### Schemas and tables"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "##### Concepts"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "When constructing such table, we need to figure out what it would take to **uniquely identify** each entry. Let's take the example of the **mouse** and think about what it would take to uniquely identify a mouse."
+   "In a data pipeline, we represent these **entities** as **tables**. Different *kinds* of entities become distinct tables, and each table row is a single example (instance) of the entity's category. \n",
+   "\n",
+   "For example, if we have a `Mouse` table, each row in the mouse table represents a single mouse. \n",
+   "\n",
+   "It is essential to think about what information will **uniquely identify** each entry. \n",
+   "\n",
+   "In this case, the information that uniquely identifies the `Mouse` table is their **mouse IDs** - a unique ID number assigned to each animal in the lab. This attribute is named the **primary key** of the table.\n",
+   "\n",
+   "| Mouse_ID (*Primary key attribute*)|\n",
+   "|:--------: |                         \n",
+   "| 11234     |\n",
+   "| 11432     |"
    ]
   },
   {
@@ -175,17 +193,21 @@
    "source": [
     "After some thought, we might conclude that each mouse can be uniquely identified by knowing its **mouse ID** - a unique ID number assigned to each mouse in the lab. The mouse ID is then a column in the table or an **attribute** that can be used to **uniquely identify** each mouse. Such attribute is called the **primary key** of the table.\n",
     "\n",
-    "| mouse_id* |\n",
-    "|:--------:|\n",
-    "| 11234    |\n",
-    "| 11432    |"
+    "The mouse ID is then a column in the table or an **attribute** that can be used to **uniquely identify** each mouse. \n",
+    "\n",
+    "Such an attribute is called the **primary key** of the table: the subset of table attributes uniquely identifying each entity in the table. The **secondary attribute** refers to any field in a table, not in the primary key.\n",
+    "\n",
+    "| Mouse_ID (*Primary key attribute*) \n",
+    "|:--------:|  \n",
+    "| 11234      (*Secondary attribute*)\n",
+    "| 11432      (*Secondary attribute*)"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Once we have successfully identified the primary key of the table, we can now think about what other columns, or **non-primary key attributes** that we would want to include in the table. These are additional information **about each entry in the table that we want to store**."
+   "Once we have successfully identified the table's primary key, we can now think about what other columns, or **non-primary key attributes** - additional information **about each entry in the table that need to be stored as well**."
    ]
   },
   {
@@ -199,7 +221,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "| mouse_id* | dob        | sex |\n",
+    "| Mouse_ID | DOB        | sex |\n",
     "|:--------:|------------|--------|\n",
     "| 11234    | 2017-11-17 | M      |\n",
     "| 11432    | 2018-03-04 | F      |"
@@ -209,14 +231,21 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Now we have an idea on how to represent information about mouse, let's create the table using **DataJoint**!"
+   "Now that we have an idea of how to represent information about the mouse, let's create the table using **DataJoint**!"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Create a schema - house for your tables"
+    "##### Practical example"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+   "##### Schema"
    ]
   },
   {
@@ -254,14 +283,14 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Creating your first table"
+   "##### Table"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "In DataJoint, you define each table as a class, and provide the table definition (e.g. attribute definitions) as the `definition` static string property. The class will inherit from the `dj.Manual` class provided by DataJoint (more on this later)."
+   "In DataJoint, you define each table as a `class`, and provide the table definition (e.g., attribute definitions) as the `definition` static string property. The class will inherit from the `dj.Manual` class provided by DataJoint (more on this later)."
    ]
   },
   {
@@ -301,7 +330,14 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Insert entries with `insert1` and `insert` methods"
+   "### Basic relational operators"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "##### Insert operators"
    ]
   },
   {
@@ -441,7 +477,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Data integrity"
+   "##### Data integrity"
    ]
   },
   {
@@ -527,31 +563,31 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "As with mouse, we should think about **what information (i.e. attributes) is needed to uniquely identify an experimental session**. Here is the relevant section of the project description:\n",
-    "\n",
-    "> * As a hard working neuroscientist, you perform experiments every day, sometimes working with **more than one mouse in a day**! However, on an any given day, **a mouse undergoes at most one recording session**.\n",
-    "> * For each experimental session, you would like to record **what mouse you worked with** and **when you performed the experiment**. You would also like to keep track of other helpful information such as the **experimental setup** you worked on."
+   "As with `mouse`, we should consider **what information (i.e., attributes) is needed to identify an `experimental session`** uniquely. Here is the relevant section of the project description:\n",
+   "\n",
+   "> * As a hard working neuroscientist, you perform experiments every day, sometimes working with **more than one mouse in a day**! However, on an any given day, **a mouse undergoes at most one recording session**.\n",
+   "> * For each experimental session, you would like to record **what mouse you worked with** and **when you performed the experiment**. You would also like to keep track of other helpful information such as the **experimental setup** you worked on."
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Based on the above, it appears that you need to know:\n",
-    "\n",
-    "* the date of the session\n",
-    "* the mouse you recorded from in that session\n",
-    "\n",
-    "to uniquely identify a single experimental session."
+   "Based on the above, it seems that you need to know these two data to uniquely identify a single experimental session:\n",
+   "\n",
+   "* the date of the session\n",
+   "* the mouse you recorded from in that session\n",
+   "\n",
+   "to uniquely identify a single experimental session."
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Note that, to uniquely identify an experimental session (or simply a **session**), we need to know the mouse that the session was about. In other words, a session cannot existing without a corresponding mouse! \n",
-    "\n",
-    "With **mouse** already represented as a table in our pipeline, we say that the session **depends on** the mouse! We could graphically represent this in an **entity relationship diagram (ERD)** by drawing the line between two tables, with the one below (**session**) depending on the one above (**mouse**)."
+   "Note that, to uniquely identify an experimental session (or simply a `Session`), we need to know the mouse that the session was about. In other words, a session cannot existing without a corresponding mouse! \n",
+   "\n",
+   "With **mouse** already represented as a table in our pipeline, we say that the session **depends on** the mouse! We could graphically represent this in an **entity relationship diagram (ERD)** by drawing the line between two tables, with the one below (**session**) depending on the one above (**mouse**)."
    ]
   },
   {
@@ -560,7 +596,7 @@
    "source": [
     "Thus we will need both **mouse** and a new attribute **session_date** to uniquely identify a single session. \n",
     "\n",
-    "Remember that a **mouse** is already uniquely identified by its primary key - **mouse_id**. In DataJoint, you can declare that **session** depends on the mouse, and DataJoint will automatically include the mouse's primary key (`mouse_id`) as part of the session's primary key, along side any additional attribute(s) you specify."
+    "Remember that a **mouse** is uniquely identified by its primary key - **mouse_id**. In DataJoint, you can declare that **session** depends on the mouse, and DataJoint will automatically include the mouse's primary key (`mouse_id`) as part of the session's primary key, alongside any additional attribute(s) you specify."
    ]
   },
   {

tutorials/02-Calcium Imaging Imported Tables.ipynb

@@ -73,11 +73,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "In the `data` folder in this `DataJoint-Tutorials`, you can find a small dataset of three different cases of calcium imaging scans:\n",
-    "\n",
-    "- `/workspaces/datajoint-tutorials/data/example_scan_02.tif`\n",
-    "- `/workspaces/datajoint-tutorials/data/example_scan_03.tif`\n",
-    "- `/workspaces/datajoint-tutorials/data/example_scan_01.tif`\n",
+    "In the `data` folder in this `DataJoint-Tutorials`, you can find a small dataset of three different cases of calcium imaging scans: `example_scan_01.tif`, `example_scan_02.tif`and `example_scan_03.tif`.\n",
     "\n",
     "As you might know, calcium imaging scans (raw data) are stored as *.tif* files. \n",
     "\n",
@@ -291,8 +287,7 @@
    "source": [
     "Particularly, this example contains 100 frames. \n",
     "\n",
-    "Let's calculate the average of the images over the frames and plot the result.\n",
-    "\n"
+    "Let's calculate the average of the images over the frames and plot the result.\n"
    ]
   },
   {
@@ -387,7 +382,7 @@
    "source": [
     "In DataJoint, the tier of the table indicates **the nature of the data and the data source for the table**. So far we have encountered two table tiers: `Manual` and `Imported`, and we will encounter the two other major tiers in this session. \n",
     "\n",
-    "DataJoint tables in `Manual` tier, or simply **Manual tables** indicate that its contents are **manually** entered by either experimenters or a recording system, and its content **do not depend on external data files or other tables**.  This is the most basic table type you will encounter, especially as the tables at the beginning of the pipeline. In the Diagram, `Manual` tables are depicted by green rectangles.\n",
+    "DataJoint tables in `Manual` tier, or simply **Manual tables** indicate that its contents are **manually** entered by either experimenters or a recording system, and its content **do not depend on external data files or other tables**. This is the most basic table type you will encounter, especially as the tables at the beginning of the pipeline. In the diagram, `Manual` tables are depicted by green rectangles.\n",
     "\n",
     "On the other hand, **Imported tables** are understood to pull data (or *import* data) from external data files, and come equipped with functionalities to perform this importing process automatically, as we will see shortly! In the Diagram, `Imported` tables are depicted by blue ellipses."
    ]