Contents

Getting Started with JupyterLab¶

While many software developers will often use an integrated development environment (IDE) or a text editor to create and edit their Python programs we will be using [JupyterLab][jupyterlab] during this lesson.

JupyterLab is an application with a web-based user interface from [Project Jupyter][jupyter] that enables one to work with documents and activities such as Jupyter notebooks, text editors, terminals, and even custom components in a flexible, integrated, and extensible manner. JupyterLab requires a reasonably up-to-date browser (ideally a current version of Chrome, Safari, or Firefox); Internet Explorer versions 9 and below are not supported.

JupyterLab is included as part of the Anaconda Python distribution. If you have not already installed the Anaconda Python distribution, see [the setup instructions]({% link setup.md %}) for installation instructions.

Even though JupyterLab is a web-based application, JupyterLab runs locally on your machine and does not require an internet connection.

  • The JupyterLab server sends messages to your web browser.

  • The JupyterLab server does the work and the web browser renders the result.

  • You will type code into the browser and see the result when the web page talks to the JupyterLab server.

Note

JupyterLab? What about Jupyter notebooks?

JupyterLab is the next stage in the evolution of the Jupyter Notebook. If you have prior experience working with Jupyter notebooks, then you will have a a good idea of what to expect from JupyterLab. Experienced users of Jupyter notebooks interested in a more detailed discussion of the similarities and differences between the JupyterLab and Jupyter notebook user interfaces can find more information in the JupyterLab user interface documentation.

Starting JupyterLab¶

Mac OS X¶

To start the JupyterLab server you will need to access the command line through the Terminal. There are two ways to open Terminal on Mac.

  1. In your Applications folder, open Utilities and double-click on Terminal

  2. Press Command + spacebar to launch Spotlight. Type Terminal and then double-click the search result or hit Enter

After you have launched Terminal, type the command to launch the JupyterLab server.

$ jupyter lab

Windows Users¶

To start the JupyterLab server you will need to access the open Anaconda Prompt.

Press Windows Logo Key and search for Anaconda Prompt, click the result or press enter.

After you have launched the Anaconda Prompt, type the command:

$ jupyter lab

Below is a screenshot of a similar JupyterLab landing page to the one that should open in your default web browser after starting the JupyterLab server on either Mac OS X or Windows.

The JupyterLab Interface¶

JupyterLab has many features found in traditional integrated development environments (IDEs) but is focused on providing flexible building blocks for interactive, exploratory computing.

The JupyterLab Interface consists of the Menu Bar, a collapsable Left Side Bar, and the Main Work Area which contains tabs of documents and activities.

Main Work Area¶

The main work area in JupyterLab enables you to arrange documents (notebooks, text files, etc.) and other activities (terminals, code consoles, etc.) into panels of tabs that can be resized or subdivided. A screenshot of the default Menu Bar is provided below.

Drag a tab to the center of a tab panel to move the tab to the panel. Subdivide a tab panel by dragging a tab to the left, right, top, or bottom of the panel. The work area has a single current activity. The tab for the current activity is marked with a colored top border (blue by default).

Creating a Python script¶

  • To start writing a new Python program click the Text File icon under the Other header in the Launcher tab of the Main Work Area.

    • You can also create a new plain text file by selecting the New -> Text File from the File menu in the Menu Bar.

  • To convert this plain text file to a Python program, select the Save File As action from the File menu in the Menu Bar and give your new text file a name that ends with the .py extension.

    • The .py extension lets everyone (including the operating system) know that this text file is a Python program.

    • This is convention, not a requirement.

Creating a Jupyter Notebook¶

To open a new notebook click the Python 3 icon under the Notebook header in the Launcher tab in the main work area. You can also create a new notebook by selecting New -> Notebook from the File menu in the Menu Bar.

Additional notes on Jupyter notebooks.

  • Notebook files have the extension .ipynb to distinguish them from plain-text Python programs.

  • Notebooks can be exported as Python scripts that can be run from the command line.

Below is a screenshot of a Jupyter notebook running inside JupyterLab. If you are interested in more details, then see the [official notebook documentation][jupyterlab-notebook-docs].

Note

How It’s Stored

  • The notebook file is stored in a format called JSON.

  • Just like a webpage, what’s saved looks different from what you see in your browser.

  • But this format allows Jupyter to mix source code, text, and images, all in one file.

First, create a text file, Python console, and terminal window and arrange them into three panels in the main work area. Next, create a notebook, terminal window, and text file and arrange them into three panels in the main work area. Finally, create your own combination of panels and tabs. What combination of panels and tabs do you think will be most useful for your workflow?

Arranging Documents into Panels of Tabs¶

In the JupyterLab Main Work Area you can arrange documents into panels of tabs. Here is an example from the [official documentation][jupyterlab].

Solution¶

After creating the necessary tabs, you can drag one of the tabs to the center of a panel to move the tab to the panel; next you can subdivide a tab panel by dragging a tab to the left, right, top, or bottom of the panel. {: .solution} {: .challenge}

Use the Jupyter Notebook for editing and running Python.¶

  • While it’s common to write Python scripts using a text editor, we are going to use the [Jupyter Notebook][jupyter] for the remainder of this workshop.

  • This has several advantages:

    • You can easily type, edit, and copy and paste blocks of code.

    • Tab complete allows you to easily access the names of things you are using and learn more about them.

    • It allows you to annotate your code with links, different sized text, bullets, etc. to make it more accessible to you and your collaborators.

    • It allows you to display figures next to the code that produces them to tell a complete story of the analysis.

  • Each notebook contains one or more cells that contain code, text, or images.

Note

Code vs. Text

Jupyter mixes code and text in different types of blocks, called cells. We often use the term “code” to mean “the source code of software written in a language such as Python”. A “code cell” in a Notebook is a cell that contains software; a “text cell” is one that contains ordinary prose written for human beings.

The Notebook has Command and Edit modes.¶

  • If you press Esc and Return alternately, the outer border of your code cell will change from gray to blue.

  • These are the Command (gray) and Edit (blue) modes of your notebook.

  • Command mode allows you to edit notebook-level features, and Edit mode changes the content of cells.

  • When in Command mode (esc/gray),

    • The b key will make a new cell below the currently selected cell.

    • The a key will make one above.

    • The x key will delete the current cell.

    • The z key will undo your last cell operation (which could be a deletion, creation, etc).

  • All actions can be done using the menus, but there are lots of keyboard shortcuts to speed things up.

Command Vs. Edit¶

In the Jupyter notebook page are you currently in Command or Edit mode?
Switch between the modes. Use the shortcuts to generate a new cell. Use the shortcuts to delete a cell. Use the shortcuts to undo the last cell operation you performed.

Solution¶

Command mode has a grey border and Edit mode has a blue border. Use Esc and Return to switch between modes. You need to be in Command mode (Press Esc if your cell is blue). Type b or a. You need to be in Command mode (Press Esc if your cell is blue). Type x. You need to be in Command mode (Press Esc if your cell is blue). Type z. {: .solution} {: .challenge}

Use the keyboard and mouse to select and edit cells.¶

  • Pressing the Return key turns the border blue and engages Edit mode, which allows you to type within the cell.

  • Because we want to be able to write many lines of code in a single cell, pressing the Return key when in Edit mode (blue) moves the cursor to the next line in the cell just like in a text editor.

  • We need some other way to tell the Notebook we want to run what’s in the cell.

  • Pressing Shift+Return together will execute the contents of the cell.

  • Notice that the Return and Shift keys on the right of the keyboard are right next to each other.

The Notebook will turn Markdown into pretty-printed documentation.¶

  • Notebooks can also render [Markdown][markdown].

    • A simple plain-text format for writing lists, links, and other things that might go into a web page.

    • Equivalently, a subset of HTML that looks like what you’d send in an old-fashioned email.

  • Turn the current cell into a Markdown cell by entering the Command mode (Esc/gray) and press the M key.

  • In [ ]: will disappear to show it is no longer a code cell and you will be able to write in Markdown.

  • Turn the current cell into a Code cell by entering the Command mode (Esc/gray) and press the y key.

Equations¶

Standard Markdown (such as we’re using for these notes) won’t render equations, but the Notebook will. Create a new Markdown cell and enter the following:

$\sum_{i=1}^{N} 2^{-i} \approx 1$

(It’s probably easier to copy and paste.) What does it display? What do you think the underscore, _, circumflex, ^, and dollar sign, $, do?

Solution¶

The notebook shows the equation as it would be rendered from LaTeX equation syntax. The dollar sign, $, is used to tell Markdown that the text in between is a LaTeX equation. If you’re not familiar with LaTeX, underscore, _, is used for subscripts and circumflex, ^, is used for superscripts. A pair of curly braces, { and }, is used to group text together so that the statement i=1 becomes the subscript and N becomes the superscript. Similarly, -i is in curly braces to make the whole statement the superscript for 2. \sum and \approx are LaTeX commands for “sum over” and “approximate” symbols. {: .solution} {: .challenge}

Closing JupyterLab¶

  • From the Menu Bar select the “File” menu and the choose “Quit” at the bottom of the dropdown menu. You will be prompted to confirm that you wish to shutdown the JupyterLab server (don’t forget to save your work!). Click “Confirm” to shutdown the JupyterLab server.

  • To restart the JupyterLab server you will need to re-run the following command from a shell.

$ jupyter lab
DAY 1 EXERCISES DAY 1