notebooks/SpecvizExample.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Specviz Demonstration Notebook\n",
    "This notebook demonstrates the Specviz API in the Notebook setting. UI equivalents for these actions, as well as additional documentation about Specviz, can be found here: https://jdaviz.readthedocs.io/en/latest/specviz/\n",
    "\n",
    "## Setup"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "import warnings\n",
    "import tempfile\n",
    "\n",
    "import astropy.units as u\n",
    "from astroquery.mast import Observations\n",
    "\n",
    "# Suppress warnings\n",
    "with warnings.catch_warnings():\n",
    "    warnings.simplefilter(\"ignore\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Create Specviz via Helper"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "from jdaviz import Specviz\n",
    "specviz = Specviz()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Display Specviz\n",
    "\n",
    "Note: you probably want to pick one of the three options below depending on preference. Also not the latter two will only work in JupyterLab, not the \"classic\" notebook interface."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This will show Specviz inline in the notebook"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "specviz.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Load a file to Specviz\n",
    "\n",
    "Here we download a JWST spectrum from [MAST](https://masttest.stsci.edu/) using `astroquery`. \n",
    "By default the downloaded file goes to your temp directory, and thus may eventually be \n",
    "garbage collected (deleted) by your system. If you would like to have the file permanently, \n",
    "simply uncomment the second line below and provide the directory path on your system where \n",
    "you would like the file stored.\n",
    "\n",
    "One other thing to note about retrieving MAST data through astroquery is that it caches\n",
    "the data by default. It is possible for files to be updated in MAST with more recent calibrations\n",
    "but remain the same size, in which case your local cached file would not be replaced by the new\n",
    "version. You can turn off caching by setting `cache=False` in the `download_file` call to\n",
    "force it to re-download the file if desired."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "data_dir = tempfile.gettempdir()\n",
    "#data_dir = \"/User/username/Data/\"\n",
    "\n",
    "fn = \"jw02732-o004_t004_miri_ch1-shortmediumlong_x1d.fits\"\n",
    "result = Observations.download_file(f\"mast:JWST/product/{fn}\", local_path=f'{data_dir}/{fn}')\n",
    "\n",
    "specviz.load_data(f'{data_dir}/{fn}', \"myfile\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Alternatively, the data and the configuration can be autodetected and loaded simultaneously by calling `jdaviz.open(f'{data_dir}/{fn}')`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Subset Retrieval\n",
    "User Task: Select a subset in the viewer above\n",
    "\n",
    "After defining regions in your spectra, you can retrieve your subsets through different means. To retrieve your subset by name:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# Returns a version of the whole spectra, with a mask applied\n",
    "specviz.get_data(data_label='myfile', spectral_subset='Subset 1')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Or, if you've defined multiple regions, you can retrieve all defined regions/subsets via:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "specviz.get_spectra()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Screenshot Saving"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "specviz.app.get_viewer(\"spectrum-viewer\").figure.save_png()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Panning/Zooming in Specviz\n",
    "### Limit Methods\n",
    "You can use the methods x_limits() and y_limits() to modify the field of view of Specviz. You can provide it a scalar (which assumes the units of the loaded spectra), an Astropy Quantity, or 'auto' to automatically scale."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "specviz.x_limits()\n",
    "specviz.x_limits(7*u.um,7.2*u.um)\n",
    "specviz.y_limits('auto', 170.0)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Disable Scientific Notation\n",
    "Scientific notation is used in the axes of the viewers by default. To deactivate it, run the following code:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# axis 1 corresponds to the Y-axis and axis 0 to the X-axis\n",
    "# fmt can be '0.1e' to set scientific notation or '0.2f' to turn it off\n",
    "specviz.set_spectrum_tick_format(fmt=\"0.2f\", axis=1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Autoscale Methods\n",
    "You can also quickly return to the default zoom using autoscale_x() and autoscale_y()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "specviz.autoscale_x()\n",
    "specviz.autoscale_y()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Extracting Models\n",
    "If models were added using the model fitting plugin, they can be extracted using the following property"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "specviz.fitted_models"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If the name of a particular model is known, it can be extracted from the fitted_models property"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "specviz.fitted_models['Model']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Alternatively, the following getter can be used"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "models = specviz.get_models()\n",
    "models"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.10.10"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}