101.1. How to use the JupyterLab¶
101.1. A template tutorial notebook¶
For the Rubin Science Platform at data.lsst.cloud.
Data Release: DPX or DRX
Container Size: size here
LSST Science Pipelines version: Weekly yyyy_xx
Last verified to run: yyyy-mm-dd
How to use this template.
Italics text is instructional or placeholder text. It should be removed or replaced with non-italicized text, as appropriate.
Most of the text in bold or regular should either stay as-is, or is an example of what a real tutorial would say.
Use the CST's Guidelines for Tutorial Notebooks.
While developing, execute the code cell below to use flake8 to ensure code cells conform to standards.
When the tutorial is done, delete this cell and the one below.
%load_ext pycodestyle_magic
%flake8_on
import logging
logging.getLogger("flake8").setLevel(logging.FATAL)
Learning objective: Very brief description of notebook's learning objective.
LSST data products: List the catalogs and images used.
Packages: List the python packages that are relevant to the learning objective. E.g., include afwDisplay and lsst.daf.butler for a notebook about retrieving and displaying images. E.g., standard supporting packages like os, glob, or numpy usually don't need to be listed here.
Credit: E.g., "Originally developed by" or "Based on notebooks developed by" and then people's names, including journal article or software release citations if appropriate. 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¶
Provide a light narrative about this notebook, e.g., "This notebook demonstrates...".
For How To tutorials, the narrative should be very light and the tutorial should be very short and focused on the one functionality (no science motivation/context needed). Only about 10 minutes to work through.
For Data Products tutorials, the narrative should be very light and the tutorial should be focused on demonstrating access to, on contents of, the data product (and any metadata; no science motivation/context needed).
For Science Demo tutorials, more narrative will be needed to describe key scientific concepts and demonstrate their analysis with the Rubin data. Cite or link to any relevant external information, documentation, or papers.
Related tutorials: If applicable, mention other relevant tutorials by name but do not link to them. Tutorials evolve continuously, there is no linkchecker for the notebook repo, and tutorial hotlinks will go stale quickly. It is not necessary to mention the preceding/subsequent tutorials in the same series as this one - those are trivial for the user to find. But do use this section to mention related tutorials in other series.
1.1. Import packages¶
All package imports must be done in the first code cell.
Do not import packages unless they are used.
Describe the packages being imported, and provide external links to package documentation.
Import numpy, a fundamental package for scientific computing with arrays in Python
(numpy.org), and
matplotlib, a comprehensive library for data visualization
(matplotlib.org;
matplotlib gallery).
From the lsst package, import modules for accessing the Table Access Protocol (TAP) service,
the butler, and image display functions from the LSST Science Pipelines (pipelines.lsst.io).
import numpy as np
import matplotlib.pyplot as plt
from lsst.rsp import get_tap_service, retrieve_query
import lsst.daf.butler as dafButler
import lsst.afw.display as afwDisplay
1.2. Define parameters and functions¶
All functions and global parameters must be defined here.
Do not define a function unless it will be used multiple times throughout the notebook; it is better for users to see code in context.
If no functions/parameters are defined, it is ok to rename or remove this section, as appropriate.
It is also ok to use sub-sub-sections if many parameters or functions are needed. E.g., "#### 1.2.1. Define global cosmological parameter values" or "#### 1.2.2. Define a function to make an image cutout".
For example, one or both of the following color definitions should be used for plotting. Instances of the butler or TAP services should be created in this section.
Define parameters to use colorblind-friendly colors with matplotlib.
plt.style.use('tableau-colorblind10')
Define colors, symbols, and linestyles to represent the six LSST filters, $ugrizy$.
filter_names = ['u', 'g', 'r', 'i', 'z', 'y']
filter_colors = {'u': '#0c71ff', 'g': '#49be61', 'r': '#c61c00',
'i': '#ffc200', 'z': '#f341a2', 'y': '#5d0000'}
filter_symbols = {'u': 'o', 'g': '^', 'r': 'v', 'i': 's', 'z': '*', 'y': 'p'}
filter_linestyles = {'u': '--', 'g': ':', 'r': '-', 'i': '-.',
'z': (0, (3, 5, 1, 5, 1, 5)), 'y': (0, (3, 1, 1, 1))}
Get an instance of the TAP service, and assert that it exists.
service = get_tap_service("tap")
assert service is not None
Functions must have a preceding markdown cell with a brief explanation and they must contain docstrings formatted as in this example.
Define a function to calculate the semi-major axis of an asteroid's orbit.
def calc_semimajor_axis(q, e):
"""
Given a perihelion distance and orbital eccentricity,
calculate the semi-major axis of the orbit.
Parameters
----------
q: float
Distance at perihelion, in au.
e: float
Orbital eccentricity.
Returns
-------
a: float
Semi-major axis of the orbit, in au.
q = a(1-e), so a = q/(1-e)
"""
return q / (1.0 - e)
2. Section heading¶
Use numbers for sections, sub-sections, and sub-sub-sections to enable referencing. E.g., so that users can say "I'm having trouble with the second code cell in Section 2.3."
Use section titles that actively describe what is being done, e.g., "Create a color-magnitude diagram". Do not use ambiguous section headings like "Plot". Descriptive headings make the auto-generated table of contents easier for users to navigate.
2.1. Warnings¶
Use indented text to attract users attention to common mistakes, known warnings, etc.
Warning: use indented text preceded with Warning to attract attention to particular information.
If a code cell produces a warning or error that is safe to ignore, it must be preceded with an explanation. Here is an example.
Warning: Pink "RuntimeWarning" errors will appear due to a few of the measured fluxes in the denominator being zero. It is safe to ignore this warning in the context of this demonstration, which is not doing any scientific analysis.
2.1.1. Images and plots¶
Drag-and-drop to embed images. The code below is automatically generated by drag-and-drop. All figures must have captions: both embedded and code-generated images. Format captions as shown.
Figure 1: Value 2 as a function of Value 1 for Case A as black open circles and Case B as grey open triangles. This figure shows that in Case B the power law has a higher exponent.
2.1.2. Provide instruction in the imperative mood¶
Jupyter Notebook tutorials alternate between markdown cells with instructional statements written in the imperative mood, and code cells to be executed by the user.
As an example, here is a set of markdown and code cells to execute an asynchronous TAP query.
This ADQL query defined below is designed to retrieve the coord_ra and coord_dec columns for all Objects that are within 0.01 degrees of the coordinate defined by Right Ascension (RA) = 62 deg, and Declination (Dec) = -37 deg, and for which the detect_isPrimary flag is True (= 1).
Create the query string.
query = "SELECT coord_ra, coord_dec "\
"FROM dp02_dc2_catalogs.Object "\
"WHERE CONTAINS(POINT('ICRS', coord_ra, coord_dec), "\
"CIRCLE('ICRS', 62, -37, 0.01)) = 1 "\
"AND detect_isPrimary = 1"
Submit the query as a job to the TAP service.
job = service.submit_job(query)
print('Job URL is', job.url)
print('Job phase is', job.phase)
Job URL is https://data.lsst.cloud/api/tap/async/tbxc2mkbcjifc8gv Job phase is PENDING
Run the job and wait until the job phase is either "COMPLETED" or "ERROR", then print the job phase.
job.run()
job.wait(phases=['COMPLETED', 'ERROR'])
print('Job phase is', job.phase)
Job phase is COMPLETED
Optional: If the status returned was "ERROR", uncomment and execute this cell to print the error messages.
# job.raise_if_error()
If the status returned was "COMPLETED", execute this cell to retrieve the query results as an astropy table using the to_table method, and assert that the table length is 173 as expected.
results = job.fetch_result().to_table()
assert len(results) == 173
Save space in memory by deleting the job and the retrieved results.
job.delete()
del results