{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/worldbank/OpenNightLights/blob/master/onl/tutorials/mod2_3_introduction_to_Jupyter_notebooks.ipynb)\n", "\n", "\n", "# Introduction to Jupyter notebooks (10 min)\n", "\n", "
\n", "A Jupyter notebook is a web-based interactive computational environment. A Jupyter notebook is basically a JSON document that can be displayed in a browser and contains input/ output cells that can be used to enter markdown text, contain executable code, or display plots or rich media.
\n", "\n", "Jupyter notebooks have gained a lot of popularity in the scientific computing community, largely because of the ease with which users can integrate executable code with written text and plots interactively, making it a powerful tool for conducting data exploration and communicating analytical insights.\n", "\n", "## Getting started\n", "Per {doc}`mod2_2_getting_started_with_Python` you should already have `jupyter` installed in your environment.\n", "\n", "By default the notebook uses a Python kernel (whatever Python version is in your current environment), so we dont need to worry about changing the language since we’re working in Python.\n", "\n", "First, activate your virtual environment by opening a CLI (terminal) window (remember we named our environment \"onl\"):\n", "`$ conda activate onl`\n", "\n", "Now within your active environment, enter:\n", "`$ jupyter notebook`\n", "\n", "This launches the web server and your default browser (Chrome, Safari, Firefox, etc.) will open a tab showing a file directory based on your current location {numref}`jupyter-tree`. You can navigate to existing notebook files (which contain the .ipynb extension) and open them in a new tab simply by clicking on them.\n", "\n", "```{figure} img/mod1-jupyter_tree.png\n", "---\n", "name: jupyter-tree\n", "---\n", "Jupyter tree\n", "```\n", "\n", "
\n", "There is a lot of helpful documentation on Jupyter notebooks available.\n", "
\n", "\n", "
\n", "And some helpful examples here
\n", "\n", "We encourage you to explore the documentation and examples to see what is capable with Jupyter notebooks. Here, we’ll just cover some basic concepts that allow you to use this tutorial.\n", "\n", "As noted, Jupyter notebooks contain cells. You can select what sort of content the cell contains, such as markdown text or executable code.\n", "\n", "```{figure} img/mod1-jupyter_cells.png\n", "---\n", "name: jupyter-cells\n", "---\n", "Select the type of cell you want, e.g. markdown or code.\n", "```\n", "\n", "This very text you’re reading now is actually a markdown cell in a notebook.\n", "\n", "And here is an example of executable code which produces an output:" ] }, { "cell_type": "code", "execution_count": 1, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "hello world\n" ] } ], "source": [ "print(\"hello world\")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Which you could also wrap in a simple function and define that in one cell:" ] }, { "cell_type": "code", "execution_count": 2, "metadata": {}, "outputs": [], "source": [ "def sayHello():\n", " print(\"hello world\")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "...And then execute in a later cell:" ] }, { "cell_type": "code", "execution_count": 3, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "hello world\n" ] } ], "source": [ "sayHello()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The menu bar provides an option to run the cell (keyboard shortcut: SHIFT + ENTER). You can also run all the cells in the notebook.\n", "\n", "```{figure} img/mod1-jupyter_runall.png\n", "---\n", "name: jupyter-runall\n", "---\n", "Running cells independently allows for interactive code execution that can be useful for exploring and plotting data.\n", "```\n", "\n", "You can also restart your kernel:\n", "\n", "```{figure} img/mod1-jupyter_restart.png\n", "---\n", "name: jupyter-restart\n", "---\n", "Warning: restarting your kernel resets your memory, so you'll lose all created variables and dump any data loaded in memory.\n", "```\n", "\n", "Restarting can help resolve some issues if you’ve accidentally clobbered variables....which brings us to a public service announcement:\n", "\n", "### Notebook limitations\n", "\n", "While their capabilities are expanding, there are a number of limitations to notebooks. It’s easy to get into bad habits, especially if you’re a novice programmer. There can also be limits to managing large amounts of data using Jupyter notebooks -- a consideration with image data, such as nighttime lights, and they don’t facilitate writing modular, reusable code.\n", "\n", "The blend of analytics, simple programming concepts, and visualization used in this tutorial makes notebooks a useful tool, so we should be O.K. But as you grow in your programming skills you may consider using a full IDE, like PyCharm.\n", "\n", "## Using notebooks for this tutorial\n", " \n", "We mentioned this tutorial was written in notebooks, right? That means you can download these pages directly from your browser and save them locally.\n", " \n", "To do this\n", "1. open your terminal in the directory where you want to work on this project\n", "2. activate your virtual environment: `$ conda activate onl`\n", "3. launch a notebook instance like shown above: `$ jupyter notebook`\n", " \n", "Then, on this webpage, download this page as a notebook (.ipynb extension) and save it within the directory you launched the notebook from. You can do this from the icon at the upper right-hand side of this page:\n", " \n", "```{figure} img/mod1-jupyter_download.png\n", "---\n", "name: jupyter-download\n", "---\n", "```\n", " \n", "Now, in the Jupyter home tab, you can navigate to where you’ve stored this file, click on the link, and open this notebook in your browser, where you can edit and execute this notebook as you wish.\n", " \n", "```{figure} img/mod1-jupyter_getbook.png\n", "---\n", "name: jupyter-getbook\n", "---\n", "```\n", "\n", " \n", "## Google Colab notebooks\n", "\n", "In addition to using Jupyter notebooks on your local machine, Google Colab is a helpful platform. By hosting notebooks on Google's cloud infrastructure, you do not need to have your local computer set up with Python or any libraries and dependencies. You just need (good!) internet access and a Google account. You can also access computer processing resources, such as Graphics Processing Units (GPUs) for machine learning or image processing work.\n", "\n", "
\n", "Google Colab has a lot of helpful overview material and documentation. Here's another notebook guide on some basic features of notebooks.\n", "
\n", "\n", "
\n", "Notebooks in this tutorial are also available in Colab where you see the button (as above). To run this notebook in Google Colab, you must have a Google account (free) but can execute a notebook simply by clicking that button.

\n", "PLEASE NOTE that due to the complex nature of interactive plots, some funcationality is limited in Colab. Also, conda is not installed natively and while we could install it, it is easier to use pip for Colab, so our import method will use pip as package manager rather than conda.
" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [] } ], "metadata": { "hide_input": false, "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.7.9" }, "toc": { "base_numbering": 1, "nav_menu": {}, "number_sections": false, "sideBar": true, "skip_h1_title": false, "title_cell": "Table of Contents", "title_sidebar": "Contents", "toc_cell": false, "toc_position": {}, "toc_section_display": true, "toc_window_display": false } }, "nbformat": 4, "nbformat_minor": 4 }