What is Jupyter?¶ Jupyter is a web-based interactive computing system. It is most well known for having the notebook file format and Jupyter Notebook / Jupyter Lab. A notebook format contains both the input and the output of the code along documentation, all interleaved to create what is called a computational narrative. Jupyter is good for data exploration and interactive work, and making. Working with the Python Interactive window. Jupyter (formerly IPython Notebook) is an open-source project that lets you easily combine Markdown text and executable Python source code on one canvas called a notebook.Visual Studio Code supports working with Jupyter Notebooks natively, as well as through Python code files.This topic covers the support offered through Python code files. Work With Python Code and Markdown Cells in Jupyter Notebook. Recall that a Jupyter Notebook file consists of a set of cells that can store text or code. Text Cells: Text cells allow you to write and render Markdown syntax. This is where you can describe and document your workflow. Creating Markdown Documents in Jupyter Notebook. In this tutorial, we learned that notebooks are basically enhanced REPL shells, we learned how to download and install Jupyter Notebook through the Python package manager, pip, and we also learned how we can use the notebook to run Python code. I hope you enjoyed reading this tutorial. The Python Markdown extension allows displaying output produced by the current kernel in markdown cells. The extensions is basically agnostic to the kernel language, however most testing has been done using Python. For example: If you set variable a in Python a = 1.23.

1. Python Markdown Jupyter
2. Jupyter For Python
3. Python Markdown Jupiter Project
4. Python Jupyter Markdown Table
5. Markdown Jupyter Notebook Reference

Learning Objectives

• Explain what the Markdown format is.
• Describe the role of Markdown for documentation of earth data science workflows.
• Use Markdown syntax in Jupyter Notebook to:
  • Create headers and lists
  • Bold and italicize bold text
  • Render images and create hyperlinks to web pages

What is Markdown?

Markdown is a human readable syntax (also referred to as a markup language) for formatting text documents. Markdown can be used to produce nicely formatted documents including PDFs and web pages.

When you format text using Markdown in a document, it is similar to using the format tools (e.g. bold, heading 1, heading 2) in a word processing tool like Microsoft Word or Google Docs. However, instead of using buttons to apply formatting, you use syntax such as **this syntax bolds text in markdown** or # Here is a heading.

Markdown syntax allows you to format text in many ways, such as making headings, bolding and italicizing words, creating bulleted lists, adding links, formatting mathematical symbols and making tables. These options allow you to format text in visually appealing and organized ways to present your ideas.

You can use Markdown to format text in many different tools including GitHub.com, R using RMarkdown, and Jupyter Notebook, which you will learn more about this page.

Data Tip: Learn more about how you can use Markdown to format text and document workflows in a variety of tools.

Markdown in Jupyter Notebook

A great benefit of Jupyter Notebook is that it allows you to combine both code (e.g. Python) and Markdown in one document, so that you can easily document your workflows.

A Jupyter Notebook file uses cells to organize content, and it can contain both cells that render text written using the Markdown syntax as well as cells that contain and run Python code.

Thus, you can use a combination of Markdown and Python code cells to organize and document your Jupyter Notebook for others to easily read and follow your workflow.

Data Tip: Learn more about Markdown for Jupyter Notebook.

If you render your Jupyter Notebook file to HTML or PDF, this Markdown will appear as formatted text in the output document.

Data Tip: In fact, this web page that you are reading right now is generated from a Markdown document! On this page, you will learn the basic syntax of Markdown.

Benefits of Markdown for Earth Data Science

Being able to include both Markdown and code (e.g. Python) cells in a Jupyter Notebook file supports reproducible science by allowing you to:

• Document your workflow: You can add text to the document that describes the steps of your processing workflow (e.g. how data is being processed and what results are produced).
• Describe your data: You can describe the data that you are using (e.g. source, pre-processing, metadata).
• Interpret code outputs: You can add some text that interprets or discusses the outputs.

all in one document!

When used effectively, Markdown documentation can help anyone who opens your Jupyter Notebook to follow, understand and even reproduce your workflow.

Format Text in Jupyter Notebook with Markdown

Markdown Cells in Jupyter Notebook

In the previous chapter on Jupyter Notebook, you learned how to add new Markdown cells to your Jupyter Notebook files using Menu tools and Keyboard Shortcuts to create new cells.

You also learned how to change the default type of the cell by clicking in the cell and selecting a new cell type (e.g. Markdown) in the cell type menu in the toolbar. Furthermore, you learned that in a Jupyter Notebook file, you can double-click in any Markdown cell to see the syntax, and then run the cell again to see the Markdown formatting.

Note: if you type text in a Markdown cell with no additional syntax, the text will appear as regular paragraph text. You can add additional syntax to that text to format it in different ways.

On this page, you will learn basic Markdown syntax that you can use to format text in Jupyter Notebook files.

Section Headers

You can create a heading using the pound (#) sign. For the headers to render properly, there must be a space between the # and the header text.

Heading one is denoted using one # sign, heading two is denoted using two ## signs, etc, as follows:

Here is a sample of the rendered Markdown:

Heading Three

Heading Four

Note: the titles on this page are actually formatted using Markdown (e.g. the words Section Headers above are formatted as a heading two).

Lists

You can also use Markdown to create lists using the following syntax:

It will render as follows:

• This is a bullet list
• This is a bullet list
• This is a bullet list

1. And you can also create ordered lists
2. by using numbers
3. and listing new items in the lists
4. on their own lines

Notice that you have space between the * or 1. and the text. The space triggers the action to create the list using Markdown.

Python Markdown Jupyter

Bold and Italicize

You can also use ** to bold or * to italicize words. To bold and italicize words, the symbols have to be touching the word and have to be repeated before and after the word using the following syntax:

It will render as follows:

These are italicized words, not a bullet listThese are bold words, not a bullet list

• This is a bullet item with bold words
• This is a bullet item with italicized words

Highlight Code

If you want to highlight a function or some code within a plain text paragraph, you can use one backtick on each side of the text like this:

which renders like this:

Here is some code!

The symbol used is the backtick, or grave; not an apostrophe (on most US keyboards, it is on the same key as the tilde (~)).

Horizontal Lines (Rules)

You can also create a horizontal line or rule to highlight a block of Markdown syntax (similar to the highlighting a block of code using the backticks):

which renders like this:

Here is some important text!

Hyperlinks

You can also use HTML in Markdown cells to create hyperlinks to websites using the following syntax:

<a href='url' target='_blank'>hyperlinked words</a>

You can identify the words that will be hyperlinked (i.e. prompt a web page to open when clicked) by replacing hyperlinked words in the example above.

For example, the following syntax:

Our program website can be found at <a href='http://earthdatascience.org' target='_blank'>this link</a>.

will render as follows with this link as the hyperlinked words:

Our program website can be found at this link.

Render Images

You can also use Markdown to link to images on the web using the following syntax:

![alt text here](url-to-image-here)

The alt text is the alternative text that appears if an image fails to load on webpage; it is also used by screen-reading tools to identify the image to users of the screen-reading tools.

For example, the following syntax:

![Markdown Logo is here.](https://www.fullstackpython.com/img/logos/markdown.png)

will render as follows with an alt text of Markdown Logo is here.:

Local Images Using Relative Computer Paths

You can also add images to a Markdown cell using relative paths to files in your directory structure using:

![alt text here](path-to-image-here)

For relative paths (images stored on your computer) to work in Jupyter Notebook, you need to place the image in a location on your computer that is RELATIVE to your .ipynb file. This is where good file management becomes extremely important.

For a simple example of using relative paths, imagine that you have a subdirectory named images in your earth-analytics directory (i.e. earth-analytics/images/).

If your Jupyter Notebook file (.ipynb) is located in root of this directory (i.e. earth-analytics/notebook.ipynb), and all images that you want to include in your report are located in the images subdirectory (i.e. earth-analytics/images/), then the path that you would use for each image is:

images/image-name.png

If all of your images are in the images subdirectory, then you will be able to easily find them. This also follows good file management practices because all of the images that you use in your report are contained within your project directory.

Data tip: There are many free Markdown editors out there! The atom.io editor is a powerful text editor package by GitHub, that also has a Markdown renderer that allows you to preview the rendered Markdown as you write.

Additional Resources

Practice Your Markdown Skills

1. Open or create a new Jupyter Notebook file.

2. Add a new Markdown cell and include:
   • A title for the notebook (e.g. Intro to Earth Analytics - Chapter Four)
   • A bullet list with:
     • A bold word for Author: and then add text for your name.
     • A bold word for Date: and then add text for today’s date.
3. Add another Markdown cell and include:
   • A list of your top three favorite foods (e.g. blueberries, chocolate bars, avocados).
     • Italicize the first item in your list.
     • Add a hyperlink (i.e. webpages) for the second item in your list (include the name of the food in the title of the hyperlink).
     • Add an image for the last item in your list (include the name in the alt text of the image).

Jupyter (formerly IPython Notebook) is an open-source project that lets you easily combine Markdown text and executable Python source code on one canvas called a notebook. Visual Studio Code supports working with Jupyter Notebooks natively, as well as through Python code files. This topic covers the support offered through Python code files and demonstrates how to:

• Work with Jupyter-like code cells
• Run code in the Python Interactive Window
• View, inspect, and filter variables using the Variable explorer and data viewer
• Connect to a remote Jupyter server
• Debug a Jupyter notebook
• Export a Jupyter notebook

To work with Jupyter notebooks, you must activate an Anaconda environment in VS Code, or another Python environment in which you've installed the Jupyter package. To select an environment, use the Python: Select Interpreter command from the Command Palette (⇧⌘P (Windows, Linux Ctrl+Shift+P)).

Once the appropriate environment is activated, you can create and run Jupyter-like code cells, connect to a remote Jupyter server for running code cells, and export Python files as Jupyter notebooks.

Jupyter code cells

You define Jupyter-like code cells within Python code using a # %% comment:

Note: Make sure to save the code shown above in a file with a .py extension.

When the Python extension detects a code cell, it adds Run Cell and Debug Cell CodeLens adornments. The first cell also includes Run Below and all subsequent cells include Run Above:

Note: By default, Debug Cell just steps into user code. If you want to step into non-user code, you need to uncheck Data Science: Debug Just My Code in the Python extension settings (⌘, (Windows, Linux Ctrl+,)).

Run Cell applies to only the one code cell. Run Below, which appears on the first cell, runs all the code in the file. Run Above applies to all the code cells up to, but not including, the cell with the adornment. You would use Run Above, for example, to initialize the state of the runtime environment before running that specific cell.

Selecting a command starts Jupyter (if necessary, which might take a minute), then runs the appropriate cell(s) in the Python Interactive window:

You can also run code cells using (Ctrl+Enter) or the Python: Run Selection/Line in Python Terminal command (Shift+Enter). After using this command, the Python extension automatically moves the cursor to the next cell. If you're in the last cell in the file, the extension automatically inserts another # %% delimiter for a new cell, mimicking the behavior of a Jupyter notebook.

You can also click in the margin to the left of line numbers to set breakpoints. Then you can use Debug Cell to start a debugging session for that code cell. The debugger stops execution at breakpoints and allows you to step through code one line at a time and inspect variables (see Debugging for details).

Additional commands and keyboard shortcuts

The following table lists additional commands and keyboard shortcuts supported when working with code cells.

Python Interactive window

The Python Interactive window, mentioned in the previous section, can be used as a standalone console with arbitrary code (with or without code cells). To use the window as a console, open it with the Jupyter: Create Interactive Window command from the Command Palette. You can then type in code, using Enter to go to a new line and Shift+Enter to run the code.

To use the window with a file, use the Jupyter: Run Current File in Python Interactive Window command from the Command Palette.

IntelliSense

The Python Interactive window has full IntelliSense – code completions, member lists, quick info for methods, and parameter hints. You can be just as productive typing in the Python Interactive window as you are in the code editor.

Plot Viewer

The Plot Viewer gives you the ability to work more deeply with your plots. In the viewer you can pan, zoom, and navigate plots in the current session. You can also export plots to PDF, SVG, and PNG formats.

Within the Python Interactive window, double-click any plot to open it in the viewer, or select the expand button on the upper left corner of the plot.

Note: The Python Interactive window supports rendering plots created with matplotlib and Altair.

Live Share for Python Interactive

Jupyter For Python

The Python Interactive window also supports Visual Studio Live Share for real-time collaboration. Live Share lets you co-edit and co-debug while sharing audio, servers, terminals, diffs, comments, and more.

Python Markdown Jupiter Project

This feature requires the Live Share extensions to be installed on both host and guest machines.

Variable explorer and data viewer

Within the Python Interactive window, it's possible to view, inspect, and filter the variables within your current Jupyter session. By expanding the Variables section after running code and cells, you'll see a list of the current variables, which will automatically update as variables are used in code.

For additional information about your variables, you can also double-click on a row or use the Show variable in data viewer button to see a more detailed view of a variable in the Data Viewer. Once open, you can filter the values by searching over the rows.

Note: Variable explorer is enabled by default, but can be turned off in settings (Python > Data Science: Show Jupyter Variable Explorer).

Connect to a remote Jupyter server

You can offload intensive computation in a Jupyter notebook to other computers by connecting to a remote Jupyter server. Once connected, code cells run on the remote server rather than the local computer.

To connect to a remote Jupyter server:

1. Run the Jupyter: Specify local or remote Jupyter server for connections command from the Command Palette (⇧⌘P (Windows, Linux Ctrl+Shift+P)).

2. Select how you would like to connect to a Jupyter server.

3. If working remotely, provide the server's URI (hostname) with the authentication token included with a ?token= URL parameter when prompted. (If you start the server in the VS Code terminal with an authentication token enabled, the URL with the token typically appears in the terminal output from where you can copy it.) Alternatively, you can specify a username and password after providing the URI.

4. The Python Interactive window indicates where code is run by displaying the URI (which is blurred out in the image below):

Python Jupyter Markdown Table

Note: For added security, Microsoft recommends configuring your Jupyter server with security precautions such as SSL and token support. This helps ensure that requests sent to the Jupyter server are authenticated and connections to the remoter server are encrypted. For guidance about securing a notebook server, see the Jupyter docs.

Convert Jupyter notebooks to Python code file

When you've activated an environment with Jupyter installed, you can open a Jupyter notebook file (.ipynb) in VS Code and then convert it to Python code. Once you've converted the file, you can run the code as you would with any other Python file and also use the VS Code debugger. Opening and debugging notebooks in VS Code is a convenient way to find and resolve code bugs, which is difficult to do directly in a Jupyter notebook.

When you open a notebook file, Visual Studio Code will open it in the Notebook Editor automatically. Use the convert icon on the toolbar to convert the Notebook (.ipynb) file to a Python file (.py).

Select the convert icon followed by 'Python Script', wait a few seconds, and then VS Code opens the converted notebook in an untitled file. The notebook's cells are delimited in the Python file with # %% comments; Markdown cells are converted wholly to comments preceded with # %% [markdown], and render as HTML in the interactive window alongside code and output such as graphs:

Note: The first time you run code cells in a Python file, the Python extension starts a Jupyter server. It may take some time for the server to start up and for the Python Interactive window to appear with the results of the code.

Debug a Jupyter notebook

The Visual Studio Code debugger lets you step through your code, set breakpoints, examine state, and analyze problems. Using the debugger is a helpful way to find and correct issues in notebook code.

1. In VS Code, activate a Python environment in which Jupyter is installed, as described at the beginning of this article.

2. Import the notebook's .ipynb file into VS Code as described in the previous section. (Download the file first if you're using a cloud-based Jupyter environment such as Azure Notebooks.)

3. To start the debugger, use one of the following options:

   • For the whole notebook, open the Command Palette (⇧⌘P (Windows, Linux Ctrl+Shift+P)) and run the Jupyter: Debug Current File in Python Interactive Window command.
   • For an individual cell, use the Debug Cell adornment that appears above the cell. The debugger specifically starts on the code in that cell. By default, Debug Cell just steps into user code. If you want to step into non-user code, you need to uncheck Data Science: Debug Just My Code in the Python extension settings (⌘, (Windows, Linux Ctrl+,)).

4. To familiarize yourself with the general debugging features of VS Code, such as inspecting variables, setting breakpoints, and other activities, review VS Code debugging.

5. As you find issues, stop the debugger, correct your code, save the file, and start the debugger again.

6. When you're satisfied that all your code is correct. Save the file, then export the notebook as described in the following section. You can then upload the notebook to your normal Jupyter environment.

Export a Jupyter notebook

In addition to opening a Jupyter notebook, you can also use one of the following commands from the Command Palette (⇧⌘P (Windows, Linux Ctrl+Shift+P)) to export content from a Python file in VS Code to a Jupyter notebook (with the .ipynb extension).

Markdown Jupyter Notebook Reference

• Jupyter: Export Current Python File as Jupyter Notebook: creates a Jupyter notebook from the contents of the current file, using the # %% and # %% [markdown] delimiters to specify their respective cell types.
• Jupyter: Export Current Python File and Output as Jupyter Notebook: creates a Jupyter notebook from the contents of the current file and includes output from code cells.
• Jupyter: Export Interactive Window as Jupyter Notebook: creates a Jupyter notebook from the contents of the Python Interactive window.

After exporting the contents, VS Code displays a prompt through which you can open the notebook in a browser.