101.2. Use a Notebook¶
101.2. Use a Notebook¶
Data Release: Data Preview 1
Container Size: large
LSST Science Pipelines version: r29.1.1
Last verified to run: 2025-06-21
Repository: github.com/lsst/tutorial-notebooks
Learning objective: How to use a Jupyter Notebook.
LSST data products: None.
Packages: None.
Credit: Originally developed by the Rubin Community Science team. Please consider acknowledging them if this notebook is used for the preparation of journal articles, software releases, or other notebooks.
Get Support: Everyone is encouraged to ask questions or raise issues in the Support Category of the Rubin Community Forum. Rubin staff will respond to all questions posted there.
1. Introduction¶
The Notebook Aspect of the Rubin Science Platform is JupyterLab, a browser-based software environment for programmatic data access and analysis. The environment includes the capability to run code from the terminal command line or scripts, or from Jupyter Notebooks.
1.1. Jupyter Notebooks¶
Jupyter Notebooks provide the opportunity to co-locate code, narrative text, and data visualizations in a single file.
The most comprehensive source for documentation about Jupyter Notebooks is jupyter-notebook.readthedocs.io, but there are many great beginner-level tutorials and demos out there. Usually a web search of a question, like "how to make a table in markdown jupyter notebook", will yield several good examples. Often the answers will be found in StackOverflow.
2. Notebook cells¶
A Jupyter Notebook is a series of individual cells. There are three types of cells: mardown, code, and raw.
The type of cell can be changed via the dropdown menu in the menu bar.
2.1. Markdown¶
This text is in a markdown cell. Double-click on this text and it will become an editable cell.
With your cursor in the editable cell, press the shift and enter keys at the same time or the right-pointing triangle in the menu bar to "execute" this cell and it will appear again as rendered markdown.
2.2. Code¶
The following is a code cell. With your cursor in the cell, press shift-enter (or use the triangle icon) to execute the cell. The command to print the words Hello world! will be execute and the output, the words Hello world!, will appear below the cell.
# Text preceded by a # is a comment and is not executed.
print('Hello, world!')
Hello, world!
2.3. Raw¶
3. The kernel¶
The kernel is the computational engine for the notebook (the RSP uses a python3 kernel),
and can be thought of as a live compiler.
From the "Kernel" menu, restarting the kernel and clearning all outputs means that all defined variables or functions are removed from memory, and all code cells revert to an "unexecuted" state.
If the kernel "dies" or becomes unresponsive, and no cells can be executed, a common cause is running out of memory. Reset the kernel. If you are using a small server size, log out and log back in and select large.
3.1. Execute all cells¶
Go to the top menu bar and select "Kernel", then "Restart Kernel and Run All Cells".
3.2. Kill the kernel (emergency stop)¶
If a code cell is taking a long time to execute (e.g., if a process to retrieve an entire catalog was started by accident) kill it by going to "Kernel" in the top menu bar and selecting "Restart Kernel and Clear All Outputs". It might still take a few tens of seconds, but it will stop the process and restart the kernel.
4. Software version¶
The version of the software is set by the "image" selected at log in. Always choose the recommended image unless you know you need a different version of the software.
Look along the bottom bar of this browser window, and find the version of the LSST Science Pipelines that was selected as the "image".
Alternatively, uncomment the two lines in the following code cell and execute the cell.
# ! echo $IMAGE_DESCRIPTION
# ! eups list -s | grep lsst_distrib
5. Import packages¶
Jupyter Notebooks start by importing all the packages they will need in the first code cell.
Complete knowledge of these packages is not required in order to complete this tutorial, but here is a bit of basic information and some links for further learning.
numpy: A fundamental package for scientific computing with arrays in Python. Its comprehensive documentation is available at numpy.org, and it includes quickstart beginner guides. (The numpy package is not used in this notebook, but is imported as a demonstration because it is a very commonly-used package.)
matplotlib: This package is a comprehensive library for creating static, animated, and interactive visualizations in Python. Its comprehensive documentation is at matplotlib.org. The matplotlib gallery is a great place to start and links to examples.
astropy: A Python package of useful astronomy tools. Learn more in the astropy documentation.
lsst: These packages are all from the LSST Science Pipelines.
lsst.rsp.get_tap_service: enables image and catalog access via the TAP service.lsst.daf.butler.Butler: enables image and catalog access via the Butler.lsst.afw.display: enables image display.
import numpy
import astropy
import matplotlib.pyplot as plt
from lsst.rsp import get_tap_service
from lsst.daf.butler import Butler
import lsst.afw.display as afwDisplay
5.1. Get package version¶
Print the version of the numpy and astropy packages
print('numpy version: ', numpy.__version__)
print('matplotlib version: ', astropy.__version__)
numpy version: 2.2.6 matplotlib version: 7.1.0
5.2. Find package modules¶
View a pop-up list of any package's modules by writing the package name, then a period, and then pressing the tab key. Try this in the cell below.
Use the up and down arrows to scroll through the pop-up list. This works whether or not the line is commented-out.
In the cell below, numpy. is commented-out because that is not an executable code statement, and if the # were not there, this cell would fail to execute (try it -- remove the #, press shift-enter, and watch it fail).
# numpy.
5.3. Get package help¶
Use "help" function to view the help documentation for a package. Remove the # symbol to un-comment a line and then execute the cell.
Help documentation can be really long. Re-comment the line by replacing the #, then re-execute the cell and the output will go away.
# help(numpy)
# help(numpy.abs)