tutorial_notebook-basics.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Notebook basics\n",
    "\n",
    "This notebook covers the minimal information one needs in order to execute code in an existing notebook.  \n",
    "If you already know notebooks even a tiny bit, no need to dwell here, you won't learn anything new :-) \n",
    "\n",
    "\n",
    "--- \n",
    "\n",
    "- [What is a notebook?](#What-is-a-notebook?)\n",
    "- [Executing code cells](#Executing-code-cells)\n",
    "- [State sharing and persistence](#State-sharing-and-persistence)\n",
    "- [Creating new cells](#Creating-new-cells)\n",
    "- [Going further](#Going-further)\n",
    "    - [Generic tutorials](#Generic-tutorials)\n",
    "    - [Useful pages from the official Jupyter documentation](#Useful-pages-from-the-official-Jupyter-documentation)\n",
    "\n",
    "---\n",
    "\n",
    "\n",
    "## What is a notebook?\n",
    "\n",
    "> A notebook integrates code and its output into a single document that combines visualizations,   \n",
    "narrative text, mathematical equations, and other rich media.  \n",
    "In other words: it's a single document where you can run code, display the output, and also add explanations,  \n",
    "formulas, charts, and make your work more transparent, understandable, repeatable, and shareable.\n",
    "\n",
    "--- from [How to Use Jupyter Notebook in 2020: A Beginner’s Tutorial](https://www.dataquest.io/blog/jupyter-notebook-tutorial/)\n",
    "\n",
    "That's about it. A notebook is a mean to interleave executable code with some documentation, which can be text, image...   \n",
    "pretty much anything! \n",
    "Notebooks support [many programming languages](https://github.com/jupyter/jupyter/wiki/Jupyter-kernels). In this tutorial, we write Python code. \n",
    "\n",
    "The notebook content is divided into _cells,_ which are independent block of either code or documentation.  \n",
    "- The text you read now has been written in a markdown cell (documentation)\n",
    "- Right below, you can see a simple code cell containing only a `print` statement."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(\"Hi there, I'm a code cell!\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As you can see, the rendering of the code cell is different.  \n",
    "(Note: the exact rendering depends on the software used to visualize and interact with the notebook)\n",
    "\n",
    "One important difference with the documentation cell is the `[  ]` showing up on the left-side of the cell.  \n",
    "While the brackets are empty, it indicates that the code in that cell has not been executed yet. \n",
    "\n",
    "## Executing code cells\n",
    "\n",
    "Let go ahead and execute it! \n",
    "- Click on the code cell above (or navigate to it with the keyboard up and down arrows);\n",
    "- Execute the code by either\n",
    "  - Clicking the `Run` button from the task bar, or\n",
    "  - Using the Ctrl+Enter keyboard shortcut.\n",
    "\n",
    "Tada! You can now see the output of your code cell displayed below the cell, if any.  \n",
    "In our case, the output is a simple string.\n",
    "\n",
    "Notice that the brackets now indicate `[1]`. If you execute the cell again, it will show `[2]`, and so on.  \n",
    "Thus, as you might have got it already, the number in the brackets indicate the sequence number of the cell execution;  \n",
    "every time a cell (any cell) is executed in the notebook, this number is incremented and displayed next to the cell. \n",
    "\n",
    "> **Note.** The same commands also render documentation cells.  \n",
    "E.g., if you edit a Markdown cell (i.e., you see the source code displayed), you can render it with Ctrl+Enter.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## State sharing and persistence\n",
    "\n",
    "One important observation is that the code cell share their state!   \n",
    "That is, variables or functions that are created in one executed cell can be used in other cells.\n",
    "\n",
    "Let illustrate that real quick."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Let's instantiate a variable here...\n",
    "myVar = 42"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Once the cell above has been executed, `myVar` is globally defined and accessible anywhere in the notebook."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# ... we can access it there\n",
    "print(myVar)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Finally, state is _persistent,_ that is, even if you change the content of a cell and re-execute it,  \n",
    "the output of past executions are still kept in memory. For example, if you update the cell above  \n",
    "to change the variable name from `myVar` to `my_var` and re-execute, a new variable will be created,  \n",
    "but **the old one remains too!** \n",
    "\n",
    "Try-it out, you'll see you can still run `print(myVar)`.\n",
    "\n",
    "If you want to clean up the state of a notebook, you can either\n",
    "- restart the kernel by clicking the circled arrow in the task bar, or\n",
    "- go to `Kernel` and select `Restart` or `Restart & Clear Output`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Creating new cells\n",
    "\n",
    "At some point, you may want to create new cells. There are many ways to do this,  \n",
    "here are some of the most convenient ones:\n",
    "- Click the `+` button in the task bar (`Insert cell below`);\n",
    "- Use the Alt+Enter shortcut, which both executes the current cell and inserts a new cell below."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Going further\n",
    "\n",
    "This was a really minimalistic introduction into how to interact with a Jupyter notebook.  \n",
    "Naturally, it barely scratched the surface of what there is to know about notebooks! \n",
    "\n",
    "If you want to dig a little deeper, there are plenty of good tutorials for beginners throughout the web.  \n",
    "Here is a short selection.\n",
    "\n",
    "### Generic tutorials\n",
    "- [How to Use Jupyter Notebook in 2020: A Beginner’s Tutorial](https://www.dataquest.io/blog/jupyter-notebook-tutorial/)\n",
    "- [Jupyter Notebook Tutorial: The Definitive Guide](https://www.datacamp.com/community/tutorials/tutorial-jupyter-notebook)\n",
    "\n",
    "### Useful pages from the official Jupyter documentation\n",
    "- [Notebook user interface and Document structure](https://jupyter-notebook.readthedocs.io/en/stable/notebook.html#notebook-user-interface)\n",
    "- [Basic wokflow](https://jupyter-notebook.readthedocs.io/en/stable/notebook.html#basic-workflow)\n",
    "- [User interface components](https://jupyter-notebook.readthedocs.io/en/stable/ui_components.html) "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "Next step: [Data Analysis](live_exp-sizing.ipynb)  \n",
    "[Back to repo](.)"
   ]
  }
 ],
 "metadata": {
  "interpreter": {
   "hash": "684f90775fb1f43db0d8eed0780ba829f42a97c2f4b9a1bd592c18e47e5c272e"
  },
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.9.6"
  },
  "metadata": {
   "interpreter": {
    "hash": "684f90775fb1f43db0d8eed0780ba829f42a97c2f4b9a1bd592c18e47e5c272e"
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}