01_Intro_to_DP0_Notebooks.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "749b0ddf",
   "metadata": {},
   "source": [
    "<img align=\"left\" src = https://project.lsst.org/sites/default/files/Rubin-O-Logo_0.png width=250 style=\"padding: 10px\"> \n",
    "<b>Introduction to Jupyter Notebooks for Data Preview 0</b> <br>\n",
    "Last verified to run on 2021-10-12 with LSST Science Pipelines release w_2021_40 <br>\n",
    "Contact author: Melissa Graham <br>\n",
    "Target audience: All DP0 delegates, especially those new to Notebooks. <br>\n",
    "Container Size: medium <br>\n",
    "Questions welcome at <a href=\"https://community.lsst.org/c/support/dp0\">community.lsst.org/c/support/dp0</a> <br>\n",
    "Find DP0 documentation and resources at <a href=\"https://dp0-1.lsst.io\">dp0-1.lsst.io</a> <br>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8f72b27f",
   "metadata": {},
   "source": [
    "**Credit:** Originally developed by Melissa Graham in the context of the Rubin DP0.1. Please consider acknowledging Melissa Graham if this notebook is used for the preparation of journal articles or software releases."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cfc73be0",
   "metadata": {},
   "source": [
    "### 1.0 Introduction\n",
    "This Jupyter Notebook will illustrate how notebooks work, introduce you to a few Python packages, and show off a bit of the functionality of the Rubin Science Platform (RSP) and the DESC's Data Challenge 2 (DC2) simulated data set for Data Preview 0 (DP0). \n",
    "\n",
    "This notebook will teach you how to execute a Jupyter Notebook (including importing and using Python packages), query a DP0.1 catalog and retrieve desired columns of data (Section 2), and retrieve a DP0.1 image at a given coordinate (Section 3). **This notebook does not go into much detail - it's more of an appetizer than an entree!**"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "dc36f107",
   "metadata": {},
   "source": [
    "**Table of Contents** <br>\n",
    "If you want to see a ToC for this notebook, click on the icon of a bullet list in the leftmost vertical menu bar, and an automatically-generated ToC will appear at left. Click on the icon of the file folder at the top of the leftmost verticle menu bar to return to a directory view.\n",
    "\n",
    "<!---\n",
    "1. Introduction<br>\n",
    " 1.1 What is a Jupyter Notebook?<br>\n",
    " 1.2 Emergency Stop a Notebook<br>\n",
    " 1.3 Importing Python packages<br>\n",
    "2. Catalog Access<br>\n",
    " 2.1 Table Access Protocol (TAP) Service<br>\n",
    " 2.2 Exploring catalog tables and columns with TAP<br>\n",
    " 2.3 Retrieving data with TAP<br>\n",
    " 2.4 Making a color-magnitude diagram<br>\n",
    "3. Image Access<br>\n",
    " 3.1 Finding and retrieving an image with the butler<br>\n",
    " 3.2 Displaying an image with afwDisplay<br>\n",
    "-->"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c3507e32",
   "metadata": {},
   "source": [
    "<!---\n",
    "This is a markdown cell. Press shift-enter to execute, and see the formatted text appear.\n",
    "-->\n",
    "#### 1.1 What is a Jupyter Notebook?\n",
    "Jupyter Notebooks are documents that contain a mix of code, output, visualizations, and narrative text. The most comprehensive source for documentation about Jupyter Notebooks is https://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 -- and if you're not already familiar with <a href=\"https://stackoverflow.com/\">StackOverflow</a>, you may find yourself to be soon. 😄\n",
    "\n",
    "Most briefly, a notebook is a series of cells. There are three types of cells: markdown, code, and raw. This text was generated from a markdown cell. Double click on these words and you can see the markdown source code used to create it. Up in the menu bar you will find a drop-down menu to set the cell type.\n",
    "\n",
    "*Action: Click in the following code cell. When your cursor is in a cell, press \"shift\" and \"enter\" (or \"return\") simultaneously to execute the cell code.*"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ba94de19",
   "metadata": {},
   "outputs": [],
   "source": [
    "# This is a code cell. Press shift-enter to execute.\n",
    "# The # makes these lines comments, not code. They are not executed.\n",
    "print('Hello, world!')"
   ]
  },
  {
   "cell_type": "raw",
   "id": "a3449766",
   "metadata": {},
   "source": [
    "# This is a raw cell. You can press shift-enter, but nothing will execute.\n",
    "# The # symbol isn't doing anything here.\n",
    "print('Hello, world!')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a34975f6",
   "metadata": {},
   "source": [
    "All of the remaining cells in this notebook are markdown or code. \n",
    "\n",
    "**It is important that all of the code cells in a notebook are executed in the order that they appear.** \n",
    "\n",
    "Not all of the code cells produce output like the one above, which has a print statement, but they are all doing something (e.g., importing packages, defining variables). If you want to execute all of the cells in a notebook, in order, go to Kernel --> Restart Kernel and Run All Cells.\n",
    "\n",
    "**Kernel:** The kernel is the computational engine for the notebook. In this case, we are using a Python3 kernel. You can think of the kernel as a live compiler, if that's helpful. Restarting the kernel means that all defined variables or functions are removed from memory, and all code cells revert to an \"unexecuted\" state."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "374fd0a2",
   "metadata": {},
   "source": [
    "#### 1.2 Emergency Stop a Notebook\n",
    "If a code cell is taking a long time to execute (for example you accidentally tried to retrieve an entire catalog or tried to print 100,000 rows) and you need to kill it, go to Kernel --> Restart Kernel and Clear All Outputs. It might still take a few tens of seconds but it will stop the process."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "245d2838",
   "metadata": {},
   "source": [
    "#### 1.3 Importing Python packages\n",
    "You will find that many Jupyter Notebooks start out by importing all the packages they will need, usually in the first code cell.\n",
    "\n",
    "You do not need to know anything about these packages to complete this tutorial, but here is a bit of extra information about numpy and matplotlib for new users. \n",
    "\n",
    "The **numpy** package is a fundamental package for scientific computing with arrays in Python.\n",
    "Its comprehensive documentation is available at <a href=\"https://numpy.org\">numpy.org</a>, and it includes quickstart beginner guides.\n",
    "\n",
    "The **matplotlib** package is a comprehensive library for creating static, animated, and interactive visualizations in Python.\n",
    "Its comprehensive documentation is at <a href=\"https://matplotlib.org/\">matplotlib.org</a>.\n",
    "The <a href=\"https://matplotlib.org/stable/gallery/index.html\">matplotlib gallery</a> is a great place to start and leads directly to copy-and-pastable code."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e8106313",
   "metadata": {},
   "source": [
    "*Action: Import all of the required packages for this notebook.*"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "cddc1458",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Import general python packages used by scientists\n",
    "import numpy\n",
    "print( 'numpy version: ', numpy.__version__ )\n",
    "import matplotlib\n",
    "print( 'matplotlib version: ', matplotlib.__version__ )\n",
    "import matplotlib.pyplot as plt\n",
    "\n",
    "# Import packages for Section 2.0 Catalog Access\n",
    "import pandas\n",
    "pandas.set_option('display.max_rows', 1000)\n",
    "from IPython.display import Markdown as md\n",
    "from lsst.rsp import get_tap_service, retrieve_query\n",
    "\n",
    "# Import packages for Section 3.0 Image Access\n",
    "import lsst.daf.butler as dafButler\n",
    "import lsst.geom\n",
    "import lsst.afw.display as afwDisplay"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f5ca54f6",
   "metadata": {},
   "source": [
    "<br> Whatever packages are imported, you can make a list of all their methods pop up on your screen by typing into a code cell: the package name, followed by a period, and then pressing tab. Try it! Put your cursor after the period and press tab. The # symbol is there because `numpy.` and `plt.` are not executable code statements. The # symbol makes those lines comments, not code. If the # were not there, this cell would fail to execute. Try it! Remove the #, press shift-enter, and watch it fail."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "9ff354c2",
   "metadata": {},
   "outputs": [],
   "source": [
    "# numpy.\n",
    "# plt."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8a4a559b",
   "metadata": {},
   "source": [
    "You can also print the help documentation to screen. These help outputs are pretty long, so we've \"commented out\" most of the examples. Remove the # symbol for one of them, press shift-enter to execute the cell, and you will see the help documentation appear below the cell."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c2d31bd7",
   "metadata": {},
   "outputs": [],
   "source": [
    "# help(numpy)\n",
    "# help(matplotlib)\n",
    "# help(numpy.abs)\n",
    "# help(matplotlib.pyplot)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d9236a2e",
   "metadata": {},
   "source": [
    "Most tutorial notebooks will include this code cell so that users can check which version of the LSST Science Pipelines they are using. It should match the verified version listed in the notebook's header."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ef1f20e7",
   "metadata": {},
   "outputs": [],
   "source": [
    "# What version of the LSST Science Pipelnes are we using?\n",
    "! echo $IMAGE_DESCRIPTION\n",
    "! eups list -s | grep lsst_distrib"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ec51ac0b",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "### 2.0 Catalog Access\n",
    "\n",
    "#### 2.1 Table Access Protocol (TAP) Service\n",
    "\n",
    "Table Access Procotol (TAP) provides standardized access to the catalog data for discovery, search, and retrieval. Full <a href=\"http://www.ivoa.net/documents/TAP\">documentation for TAP</a> is provided by the International Virtual Observatory Alliance (IVOA).\n",
    "\n",
    "The TAP service uses a query language similar to SQL (Structured Query Langage) called ADQL (Astronomical Data Query Language). The <a href=\"http://www.ivoa.net/documents/latest/ADQL.html\">documentation for ADQL</a> includes more information about syntax and keywords.\n",
    "\n",
    "**Hazard Warning:** Not all ADQL functionality is supported yet in the DP0 RSP. "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4936e520",
   "metadata": {},
   "source": [
    "*Action: Start your TAP service. (This cell produces no output, unlike the cells above that have print statements. If a \"Patching auth into...\" warning is returned, it is safe to ignore it.)* "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f0a530b9",
   "metadata": {},
   "outputs": [],
   "source": [
    "service = get_tap_service()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "10804bb0",
   "metadata": {},
   "source": [
    "#### 2.2 Exploring catalog tables and columns with TAP\n",
    "For this example we use the DESC DC2's `object` catalog, which contains sources detected in the coadded images (also called stacked or combined images). The `object` catalog is described in the <a href=\"https://arxiv.org/abs/2101.04855\">DESC's DC2 data release note</a>, and more information about the simulated data can be found in the <a href=\"https://ui.adsabs.harvard.edu/abs/2021ApJS..253...31L/abstract\">DESC's DC2 paper</a>.\n",
    "\n",
    "Results from a TAP service search are best displayed using one of two functions:<br>\n",
    ".to_table() --> an astropy table (astropy is a python package of useful astronomy tools; <a href=\"http://docs.astropy.org/en/stable/_modules/astropy/table/table.html\">AstroPy Documentation</a>). <br>\n",
    ".to_table().to_pandas() --> a pandas dataframe (pandas is a python package for dealing with tabular data; <a href=\"https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.html\">Pandas Documentation</a>).\n",
    "\n",
    "**Hazard Warning:** do not use the .to_table().show_in_notebook() method. This can cause issues in the RSP Jupyterlab environment that make your notebook hang indefinitely.\n",
    "\n",
    "The next three executable cells give the barest of introductions for how to use the TAP service to discover what catalogs exist and which columns they contain. These cells are optional. Remove all of the # in order to execute the code in the cell. Replace all of the # and re-execute to make the output go away."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "beef6193",
   "metadata": {},
   "source": [
    "*Action: Retrieve the table names and descriptions of available tables. Show the results as an AstroPy table.*"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "75ba75e6",
   "metadata": {},
   "outputs": [],
   "source": [
    "# results = service.search(\"SELECT description, table_name FROM TAP_SCHEMA.tables\")\n",
    "# results_tab = results.to_table()\n",
    "# results_tab"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "723cbe86",
   "metadata": {},
   "source": [
    "*Action: Print all of the field names (columns names) in the DP0.1 DC2 `object` catalog's TAP schema.*"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "88711ca7",
   "metadata": {},
   "outputs": [],
   "source": [
    "# results = service.search(\"SELECT * from TAP_SCHEMA.columns WHERE table_name = 'dp01_dc2_catalogs.object'\")\n",
    "# print(results.fieldnames)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "de30cca5",
   "metadata": {},
   "source": [
    "*Action: Retrieve the names, data types, description, and units for all columns in the `object` catalog. This time, show the results as a pandas dataframe.*"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5129c644",
   "metadata": {},
   "outputs": [],
   "source": [
    "# results = service.search(\"SELECT column_name, datatype, description, unit from TAP_SCHEMA.columns \"\\\n",
    "#                          \"WHERE table_name = 'dp01_dc2_catalogs.object'\")\n",
    "# results.to_table().to_pandas()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8ced15d7",
   "metadata": {},
   "source": [
    "#### 2.3 Retrieving data with TAP\n",
    "\n",
    "To quickly demonstrate how to retrive data from the `object` catalog, we use a cone search and request just 10 records. \n",
    "\n",
    "<b> Hazard Warning: </b> The DC2 `object` catalog contains ~147 million rows. Searches that do not specify a region and/or a maximum number of records can take a long time, and return far too many rows to display in a notebook.\n",
    "\n",
    "Figure 2 of the <a href=\"https://ui.adsabs.harvard.edu/abs/2021ApJS..253...31L/abstract\">DESC's DC2 paper</a> shows the sky region covered by DC2 simulation contains coordinates RA,Dec = 62,-37.\n",
    "<br>\n",
    "\n",
    "*Action: Retrieve coordinates and g,r,i magnitudes for 10 objects within a radius 0.5 degrees of 62,-37. Show the results as an AstroPy table.*"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "355a5cb2",
   "metadata": {},
   "outputs": [],
   "source": [
    "results = service.search(\"SELECT ra, dec, mag_g, mag_r, mag_i \"\\\n",
    "                         \"FROM dp01_dc2_catalogs.object \"\\\n",
    "                         \"WHERE CONTAINS(POINT('ICRS', ra, dec), CIRCLE('ICRS', 62.0, -37.0, 0.5)) = 1 \", maxrec=10)\n",
    "results_tab = results.to_table()\n",
    "results_tab"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e1f5b222",
   "metadata": {},
   "source": [
    "#### 2.4 Making a color-magnitude diagram\n",
    "As described in the <a href=\"https://arxiv.org/abs/2101.04855\">DESC's DC2 data release note</a>, the DC2 `object` catalog contains two quality flags: the `good` and `clean` columns are true if the source had no bad pixels and was not skipped by the deblender. It also has a star/galaxy parameter, `extendedness`, which is 0 for stars (and 1 for extended objects). In addition to searching the catalog by coordinate, here we apply conditions for these parameters and search only for bright objects with low magnitude errors.\n",
    "\n",
    "*Action: Retrieve magnitudes and their uncertainties for 10000 bright objects that are likely to be stars. (No output).* "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e9989da7",
   "metadata": {},
   "outputs": [],
   "source": [
    "results = service.search(\"SELECT ra, dec, mag_g, mag_r, mag_i, magerr_g, magerr_r, magerr_i \"\\\n",
    "                         \"FROM dp01_dc2_catalogs.object \"\\\n",
    "                         \"WHERE CONTAINS(POINT('ICRS', ra, dec), CIRCLE('ICRS', 62.0, -37.0, 1.0)) = 1 \"\\\n",
    "                         \"AND good = 1 AND clean = 1 AND extendedness = 0 \"\\\n",
    "                         \"AND magerr_g < 0.1 AND magerr_r < 0.1 AND magerr_i < 0.1\", maxrec=10000)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "41b68c33",
   "metadata": {},
   "source": [
    "*Action: Put the results into a `pandas` dataframe for easy access to contents. (No output).*"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "798b0809",
   "metadata": {},
   "outputs": [],
   "source": [
    "data = results.to_table().to_pandas()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3e1dc71c",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "**A brief demo of some pandas package functionality.**\n",
    "If you're unfamiliar with pandas, a python package for dealing with tabular data (<a href=\"https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.html\">Pandas Documentation</a>), here are some optional lines of code that demonstrate how to print the column names, the 'ra' column info, or the 'ra' column values. Uncomment (remove #) and execute the cell to view the demo output."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "fd0f247a",
   "metadata": {},
   "outputs": [],
   "source": [
    "# data.columns"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a3dd33a7",
   "metadata": {},
   "outputs": [],
   "source": [
    "# data['ra']"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a72e6ecd",
   "metadata": {},
   "outputs": [],
   "source": [
    "# data['ra'].values"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cd5b98bc",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "To make our diagram, we use the `plot` task of the matplotlib.pyplot package, which we imported as `plt`.\n",
    "The `plot` task parameters are described in full at <a href=\"https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.plot.html#matplotlib.pyplot.plot\">this matplotlib website</a>, but briefly they are: x values, y values, symbol shape ('o' is circle), marker size (`ms`), and marker transparency (`alpha`).\n",
    "\n",
    "*Action: Use `plt.plot` to display a color magnitude diagram.*"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "98b2c106",
   "metadata": {},
   "outputs": [],
   "source": [
    "plt.plot( data['mag_r'].values-data['mag_i'].values, data['mag_g'].values, 'o', ms=2, alpha=0.2 )\n",
    "\n",
    "# Label the axes.\n",
    "plt.xlabel( 'mag_r - mag_i' )\n",
    "plt.ylabel( 'mag_g' )\n",
    "\n",
    "# Limit the x-axis.\n",
    "plt.xlim([-0.5,2.0])\n",
    "\n",
    "# Flip the y-axis.\n",
    "plt.ylim([26.5,16.5])\n",
    "\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8c2c40f7",
   "metadata": {},
   "source": [
    "Wow, maybe not what was expected? This plot generates many questions. Why are the colors quantized? Are those all really stars? All beyond the scope of this notebook tutorial, and left as topics of DP0 scientific analysis with the simulated DC2 data set, to be pursued by the delegate."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "56baaa33",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "### 3.0 Image Access\n",
    "The two most common types of images that DP0 delegates will interact with are `calexps` and `deepCoAdds`:\n",
    " * `calexp` -- a single image in a single filter\n",
    " * `deepCoadd` -- a combination of single images into a deep stack or CoAdd\n",
    " \n",
    "The LSST Science Pipelines processes and stores images in `tracts` and `patches`:\n",
    " * `tract` -- a portion of sky within the LSST all-sky tessellation (sky map); divided into patches\n",
    " * `patch` -- a quadrilateral sub-region of a tract, of a size that fits easily into memory on desktop computers\n",
    " \n",
    "To retrieve and display an image at a desired coordinate, users will have to specify their image type and the tract and patch they want. This tutorial demonstrates how to do that."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6758b295",
   "metadata": {},
   "source": [
    "#### 3.1 Finding and retrieving an image with the `butler`\n",
    "For DP0.1, images can only be accessed via the `butler` (<a href=\"https://pipelines.lsst.io/modules/lsst.daf.butler/index.html\">documentation</a>), an LSST Science Pipelines software package to fetch the LSST data you want without you having to know its location or format.\n",
    "\n",
    "The `butler` can also be used to explore and discover what data exists, and decide which images you want, as well as to  fetch the same type of catalog data that we used the TAP service for, above. Other DP0 tutorials will demonstrate the full butler functionality."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3b640a69",
   "metadata": {},
   "source": [
    "*Action: Define the data repository and collection. (No output).* These will be the same for all DP0.1 data sets."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2122a1fb",
   "metadata": {},
   "outputs": [],
   "source": [
    "repo = 's3://butler-us-central1-dp01'  \n",
    "collection='2.2i/runs/DP0.1'"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "eb0cd221",
   "metadata": {},
   "source": [
    "*Action: Create an instance of the `butler` using the repo and collection. (No output, though you may see a report that your butler access credentials were found.)*"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "cfb317d6",
   "metadata": {},
   "outputs": [],
   "source": [
    "butler = dafButler.Butler(repo,collections=collection)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b0519417",
   "metadata": {},
   "source": [
    "For this example, let's retrieve an image of a cool-looking DC2 galaxy cluster that we already know is at coordinates: <br>RA = 03h42m59.0s, Dec = -32d16m09s. In decimal degrees these coordinates are 55.745834, -32.269167.\n",
    "\n",
    "*Action: Use `lsst.geom` to define a SpherePoint for your coordinates.* (Full `lsst.geom` package <a href=\"https://pipelines.lsst.io/modules/lsst.geom/index.html\">documentation</a>.)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "56ea8e01",
   "metadata": {},
   "outputs": [],
   "source": [
    "my_spherePoint = lsst.geom.SpherePoint(55.745834*lsst.geom.degrees, -32.269167*lsst.geom.degrees)\n",
    "print(my_spherePoint)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "789fb4ff",
   "metadata": {},
   "source": [
    "*Action: Get the sky map from the `butler` and use `findTract` and `findPatch`.* (Full `skymap` <a href=\"http://doxygen.lsst.codes/stack/doxygen/x_masterDoxyDoc/skymap.html\">documentation</a>.)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1796f237",
   "metadata": {},
   "outputs": [],
   "source": [
    "skymap = butler.get('skyMap')\n",
    "my_tract = skymap.findTract(my_spherePoint)\n",
    "my_patch = my_tract.findPatch(my_spherePoint)\n",
    "my_patch_id = my_tract.getSequentialPatchIndex(my_patch)\n",
    "print('my_tract = ', my_tract)\n",
    "print('my_patch = ', my_patch)\n",
    "print('my_patch_id = ',my_patch_id)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "084ab1fb",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "**Hazard/Warning:** Patch formats changed recently. The \"(3,2)\" tuple format for patches is is part of the \"Generation 2\" (\"Gen 2\") Bulter and is formally deprecated. The new \"Gen 3\" format is a single integer. To convert from the \"Gen 2\" format of (i,j) to the \"Gen 3\" format, use (7 x j) + i. In this case, (7 x 2) + 3 = 17."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "63c0e237",
   "metadata": {},
   "source": [
    "*Action: Use the butler to retrieve the deep i-band CoAdded image for the tract and patch. (No Output).*"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "460e1df6",
   "metadata": {},
   "outputs": [],
   "source": [
    "dataId = {'band': 'i', 'tract': 4431, 'patch':17}\n",
    "my_deepCoadd = butler.get('deepCoadd',dataId=dataId)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d4e2c4d1",
   "metadata": {},
   "source": [
    "#### 3.2 Displaying an image with `afwDisplay`.\n",
    "Image data retrieved with the butler can be displayed several different ways. A simple option is to use the LSST Science Pipelines package `afwDisplay`. There is some <a href=\"https://pipelines.lsst.io/modules/lsst.afw.display/index.html\">documentation for afwDisplay</a> available, and other DP0 tutorials go into more detail about all the display options (e.g., overlaying mask data to show bad pixels).\n",
    "\n",
    "*Action: Set the backend of `afwDisplay` to `matplotlib`. (No output).*"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d4ebe015",
   "metadata": {},
   "outputs": [],
   "source": [
    "afwDisplay.setDefaultBackend('matplotlib') "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4f1ab1a8",
   "metadata": {},
   "source": [
    "*Action: Use afwDisplay to show the image data retrieved.* (Pateince; this takes a couple of seconds to render)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "dd46970e",
   "metadata": {},
   "outputs": [],
   "source": [
    "fig = plt.figure(figsize=(10,8))      # create a matplotlib.pyplot figure\n",
    "afw_display = afwDisplay.Display(1)   # create an alias for the lsst.afw.display.Display() method\n",
    "afw_display.scale('asinh', 'zscale')  # set the algorithm and scale for the pixel shading\n",
    "afw_display.mtv(my_deepCoadd.image)   # display the image data you retrieved with the butler\n",
    "plt.gca().axis('off')                 # turn off the x and y axes labels"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2a318232",
   "metadata": {},
   "source": [
    "<br>\n",
    "To learn more about the `afwDisplay` package and its tasks, use the help function."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "4e9a1ee0",
   "metadata": {},
   "outputs": [],
   "source": [
    "# help(afw_display.scale)\n",
    "# help(afw_display.mtv)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "LSST",
   "language": "python",
   "name": "lsst"
  },
  "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.8.8"
  },
  "toc-autonumbering": false
 },
 "nbformat": 4,
 "nbformat_minor": 5
}