Add Specviz JWebbinar notebook

jdat_session/Specviz_Webbinar_live.ipynb

@@ -0,0 +1,275 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Introduction to Specviz\n",
+    "\n",
+    "#### Learning Goals\n",
+    "\n",
+    "- Learn to load and display a spectrum in Specviz\n",
+    "- Become familiar with the tools attached to the spectrum viewer\n",
+    "- Become familiar with the data analysis plugins\n",
+    "- Learn how to select a region of interest/subset of the spectrum\n",
+    "- Learn how to overlay spectral lines on the displayed spectrum\n",
+    "- Learn how to extract spectra from the Specviz app for further analysis in the notebook\n",
+    "\n",
+    "#### Historical Note\n",
+    "\n",
+    "Previously, Specviz was one of three separate packages (Specviz, Cubeviz, and Mosviz) for visual data analysis. These packages have now been unified into separate configurations of a single project called Jdaviz and share much of the same codebase. The main relevance this has to you is that you should _not_ try to install Specviz via `pip install specviz`, as this will give you the old, no-longer-maintained package. Instead, always use `pip install jdaviz` to get Specviz and the other configurations.\n",
+    "\n",
+    "#### Further Resources\n",
+    "\n",
+    "The Specviz documentation can be found at https://jdaviz.readthedocs.io/en/latest/specviz/index.html. "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "scrolled": false
+   },
+   "outputs": [],
+   "source": [
+    "# This ensures that our notebook is using the full width of the browser\n",
+    "\n",
+    "from IPython.core.display import display, HTML\n",
+    "display(HTML(\"<style>.container { width:100% !important; }</style>\"))\n",
+    "\n",
+    "# Import the packages and modules we'll need\n",
+    "\n",
+    "from jdaviz import SpecViz\n",
+    "\n",
+    "from astropy.utils.data import download_file\n",
+    "from astropy.table import QTable\n",
+    "import astropy.units as u"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Running the app\n",
+    "\n",
+    "To initialize the Specviz app, we import the `Specviz` class, initialize an instance of it, and invoke the `app` property to display the app. We also import a few more things here that will be useful later."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "scrolled": false
+   },
+   "outputs": [],
+   "source": []
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Loading data into the app\n",
+    "\n",
+    "Loading data is as simple as calling the `load_spectrum` method of the `Specviz` class. Here, we download a spectrum (extracted from a simulated observation of a galaxy through the NIRSpec IFU) and load it into the app, making use of the optional `data_label` argument to give the data a sensible label. Note that `load_spectrum` can also be given `specutils.Spectrum1D` objects as input. "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "scrolled": false
+   },
+   "outputs": [],
+   "source": [
+    "# First, download the file we'll be using. \n",
+    "# This 1D spectrum is extracted from a simulated observation of a galaxy through the NIRSpec IFU.\n",
+    "fn = download_file('https://stsci.box.com/shared/static/b22b1fzhimtdqfp8597m4bg67kovvauu.fits', cache=True)\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Selecting a region of interest\n",
+    "\n",
+    "First, note that before selecting any subsets, the subset selection button in the app-level toolbar reads \"No selection (create new)\". This indicates that using the x-range selection tool will create a new subset, rather than editing an existing subset. To the right of that button you should see a small circle - clicking that circle shows that there are options for what the x-range selection will do. Since we're creating a new subset, the default (\"replace\") is fine.\n",
+    "\n",
+    "Follow these steps to select a new region:\n",
+    "1. Click the \"hammer and screwdriver\" icon in the top left of the viewer. \n",
+    "2. Use any of the pan/zoom tools (the leftmost three icons in the expanded tool tray) to zoom into the feature of interest. We'll investigate the emission feature near 1.25 microns. Zooming works by scrolling with the mouse wheel (see \"Sidebar: zooming from the notebook\" below if you can't scroll to zoom).\n",
+    "3. Click the \"x-range\" selection tool in the expanded tool tray.\n",
+    "4. Click and drag on the viewer to select a region around the feature. Go ahead and include some continuum on either side.\n",
+    "5. Click the \"x-range\" button in the expanded tool tray to deselect the tool.\n",
+    "\n",
+    "You should now see the label \"Subset 1\" with a red triangle in the app-level toolbar where it previously said \"No selection (create new)\". The red triangle indicates that the region of the spectrum you selected in the viewer should be colored red to indicate it is in this subset."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2021-04-23T15:54:28.947755Z",
+     "start_time": "2021-04-23T15:54:28.945394Z"
+    }
+   },
+   "source": [
+    "#### Sidebar: zooming from the notebook\n",
+    "\n",
+    "If you don't have the capability to zoom via scrolling with a zoom tool selected, you can set the limits of the x and y axes manually from the notebook by calling e.g.:\n",
+    "\n",
+    "specviz.x_limits(1.2, 1.3)\n",
+    "\n",
+    "specviz.y_limits('auto', 3)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Creating and fitting models\n",
+    "\n",
+    "Now that we've created let the app know that we're interested in the region around the emission line by creating a subset, we can use the Model Fitting plugin to do some analysis by fitting the line. Follow these steps:\n",
+    "\n",
+    "1. Click the \"lego block\" icon in the top right of the app to open the plugin menu, then click the `Model Fitting` line to expand that plugin.\n",
+    "2. Click the `Data` dropdown menu and select \"Subset 1\".\n",
+    "3. Click the `Model` dropdown and select \"Constant\", then give the component model a label in the `Model ID` field immediately to the right (I'll label it \"C\"). Click `ADD MODEL` and note that an expandable menu appears for model `C` under \"Model Parameters\".\n",
+    "4. Repeat step 3, but this time add a Gaussian component.\n",
+    "5. Expand the model parameter menu for the Gaussian model and give it some reasonable initial guesses for the parameters. I'll use `amplitude=1.5`, `stddev=0.0005`, `mean=1.252`.\n",
+    "6. In the input field in the \"Model Equation Editor\" section, type \"C+G\" (or whatever the two labels you gave to your component models were). This tells the fitter how to combine the component models you've initialized.\n",
+    "7. Update the label for the resulting model, if desired. The default is \"Model\".\n",
+    "8. Click \"FIT\". You should see a the fit model appear in the viewer, overlayed on the original spectrum. "
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Adding line lists via the notebook\n",
+    "\n",
+    "Line lists are expected to be input as an astropy `QTable`, with at minimum \"linename\" and \"rest\" fields. You can optionally specify a \"color\" column if you want each line to be a different color. \n",
+    "\n",
+    "The first step is to load the line list into the specviz instance using `specviz.load_line_list(lines)`. A line list as described as above is required, and there is an optional `replace` parameter that, if set to True, replaces any existing lines with those input. The default behavior is to add newly loaded lines to the existing list.\n",
+    "\n",
+    "Note that the line list functionality is all actually happening under the hood in the spectrum viewer (and thus could also be used in e.g. Cubeviz); the Specviz methods are convenience wrappers. "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Displaying the lines on the plot is as simple as calling the `plot_spectral_lines` function:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "And one can erase all spectral lines from the plot using `erase_spectral_lines`:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Using the Line Lists plugin\n",
+    "\n",
+    "We can also add and remove lines via the Line Lists plugin, including a set of predefined line lists that can be loaded and plotted by the user. These are viewable in the plugin under the \"Available Line Lists\" dropdown. Once a list is added, you can open the list menu and choose to display and hide either individual lines from the list or all the lines in the list. Note that showing more than a dozen or so lines at once can start impacting the performance of the redshift slider."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Retrieving data\n",
+    "\n",
+    "The data from the app can be retrieved into the notebook using the `get_spectra` method of the `Specviz` class. Retrieve the data using that method below. Note that the returned objects are `specutils.Spectrum1D` instances, which you learned about in the previous session."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Exercises\n",
+    "\n",
+    "\n",
+    "1. Use the subset selection tool to add the next feature to the left of the one we already fit to Subset 1. Then use the Model Fitting plugin to fit multiple gaussians at once, one for each emission line. Use the `get_models` method of the `specviz` object to retrieve the fitted models into the notebook.\n",
+    "\n",
+    "    **Reminder**: The \"Model ID\" of any component model you initialize in the Model Fitting plugin needs to be used in the `Model Equation Editor` section of the plugin before pressing the `Fit` button.\n",
+    "\n",
+    "\n",
+    "2. Create a subset that includes only continuum, then use the Model Fitting plugin to fit a model to that subset. Using `specviz.get_spectra()`, retrieve the data from the app and use the continuum fit to normalize the spectrum. Load the normalized spectrum back into the app.\n",
+    "\n",
+    "3. Use the Unit Conversion plugin to change the units of the displayed spectrum. Then use the data selection menu to switch back to the original spectrum."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "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": {
+   "base_numbering": 1,
+   "nav_menu": {},
+   "number_sections": false,
+   "sideBar": false,
+   "skip_h1_title": false,
+   "title_cell": "Table of Contents",
+   "title_sidebar": "Contents",
+   "toc_cell": false,
+   "toc_position": {},
+   "toc_section_display": false,
+   "toc_window_display": false
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}