manual rebase of main

Author: gibsongreen

notebooks/niriss_imaging/niriss-imaging-tutorial.ipynb

@@ -5,15 +5,17 @@
    "id": "0393e357-9d9d-4516-b28d-4d335fad33a0",
    "metadata": {},
    "source": [
-    "# Baseline: NIRISS Imaging Tutorial Notebook\n",
+    "# Advanced: NIRISS Imaging Tutorial Notebook\n",
     "\n",
     "## Table of Contents\n",
     "1. [Introduction](#intro)\n",
     "2. [Examining uncalibrated data products](#examine)\n",
     "3. [Stage 1 Processing](#det1)\n",
     "4. [Stage 2 Processing](#image2)\n",
     "5. [Stage 3 Processing](#image3)\n",
-    "6. [Visualize Detected Sources](#detections)"
+    "6. [Visualize Detected Sources](#detections)\n",
+    "\n",
+    "Date published: January 24, 2024"
    ]
   },
   {
@@ -62,6 +64,8 @@
    "source": [
     "import os\n",
     "import glob\n",
+    "import zipfile\n",
+    "import urllib.request\n",
     "import numpy as np\n",
     "\n",
     "# for JWST calibration pipeline\n",
@@ -91,9 +95,7 @@
    "id": "459d06b6-4f6a-402c-85a8-d06715a3d9e5",
    "metadata": {},
    "source": [
-    "### Define program parameters\n",
-    "\n",
-    "These will be used for generating the assocation file for Stage 3"
+    "### Download uncalibrated data products"
    ]
   },
   {
@@ -106,7 +108,19 @@
     "# APT program ID number:\n",
     "pid = '01475'\n",
     "\n",
-    "data_dir = '1475_f150w/'"
+    "# Set up directory to download uncalibrated data files:\n",
+    "data_dir = '1475_f150w/'\n",
+    "# Create directory if it does not exist\n",
+    "if not os.path.isdir(data_dir):\n",
+    "    os.mkdir(data_dir)\n",
+    "\n",
+    "# Download uncalibrated data from Box into current directory:\n",
+    "boxlink = 'https://data.science.stsci.edu/redirect/JWST/jwst-data_analysis_tools/niriss_imaging/1475_f150w.zip'\n",
+    "boxfile = os.path.join(data_dir, '1475_f150w.zip')\n",
+    "urllib.request.urlretrieve(boxlink, boxfile)\n",
+    "\n",
+    "zf = zipfile.ZipFile(boxfile, 'r')\n",
+    "zf.extractall()"
    ]
   },
   {
@@ -386,7 +400,7 @@
     "\n",
     "In this pipeline processing stage, the [world coordinate system (WCS)](https://jwst-pipeline.readthedocs.io/en/latest/jwst/assign_wcs/index.html#assign-wcs-step) is assigned, the data are [flat fielded](https://jwst-pipeline.readthedocs.io/en/latest/jwst/flatfield/index.html#flatfield-step), and a [photometric calibration](https://jwst-pipeline.readthedocs.io/en/latest/jwst/photom/index.html#photom-step) is applied to convert from units of countrate (ADU/s) to surface brightness (MJy/sr). \n",
     "\n",
-    "By default, the [background subtraction step](https://jwst-pipeline.readthedocs.io/en/latest/jwst/background_step/index.html#background-step) and the [resampling step](https://jwst-pipeline.readthedocs.io/en/latest/jwst/resample/index.html#resample-step) are turned off for NIRISS at this stage of the pipeline."
+    "By default, the [background subtraction step](https://jwst-pipeline.readthedocs.io/en/latest/jwst/background_step/index.html#background-step) and the [resampling step](https://jwst-pipeline.readthedocs.io/en/latest/jwst/resample/index.html#resample-step) are turned off for NIRISS at this stage of the pipeline. The background subtraction is turned off since there is no background template for the imaging mode and the local background is removed during the background correction for photometric measurements around individual sources. The resampling step occurs during the `Image3` stage by default. While the resampling step can be turned on during the `Image2` stage to, e.g.,  generate a source catalog for each image, the data quality from the `Image3` stage will be better since the bad pixels, which adversely affect both the centroids and photometry in individual images, will be mostly removed."
    ]
   },
   {
@@ -523,14 +537,14 @@
     "\n",
     "In the [Image3 stage of the pipeline](https://jwst-pipeline.readthedocs.io/en/latest/jwst/pipeline/calwebb_image3.html), the individual `*_cal.fits` files for each of the dither positions are combined to one single distortion corrected image. First, an [Association](https://jwst-pipeline.readthedocs.io/en/latest/jwst/associations/overview.html) needs to be created to inform the pipeline that these individual exposures are linked together. \n",
     "\n",
-    "By default, the `IMAGE3` stage of the pipeline performs the following steps on NIRISS data: \n",
+    "By default, the `Image3` stage of the pipeline performs the following steps on NIRISS data: \n",
     "- [tweakreg](https://jwst-pipeline.readthedocs.io/en/latest/jwst/tweakreg/index.html#tweakreg-step) - creates source catalogs of pointlike sources for each input image. The source catalog for each input image is compared to each other to derive coordinate transforms to align the images relative to each other.\n",
     "   - As of CRDS context `jwst_1156.pmap` and later, the `pars-tweakreg` parameter reference file for NIRISS performs an absolute astrometric correction to GAIA data release 3 by default (i.e., the `abs_refcat` parameter is set to `GAIADR3`). Though this default correction generally improves results compared with not doing this alignment, it can sometimes result in poor performance in crowded or sparse fields, so users are encouraged to check astrometric accuracy and revisit this step if necessary.\n",
     "   - As of pipeline version 1.12.5, the default source finding algorithm is `DAOStarFind` which can result in up to 0.5 pix uncertainties in the centroids for undersampled PSFs, like the NIRISS PSFs at short wavelengths [(Goudfrooij 2022)](https://www.stsci.edu/files/live/sites/www/files/home/jwst/documentation/technical-documents/_documents/JWST-STScI-008116.pdf). There are plans to update the default algorithm to `IRAFStarFind` in future pipeline versions.\n",
     "- [skymatch](https://jwst-pipeline.readthedocs.io/en/latest/jwst/skymatch/index.html#skymatch-step) - measures the background level from the sky to use as input into the subsequent `outlier detection` and `resample` steps.\n",
     "- [outlier detection](https://jwst-pipeline.readthedocs.io/en/latest/jwst/outlier_detection/index.html#outlier-detection-step) - flags any remaining cosmic rays, bad pixels, or other artifacts not already flagged during the `DETECTOR1` stage of the pipeline, using all input images to create a median image so that outliers in individual images can be identified.\n",
     "- [resample](https://jwst-pipeline.readthedocs.io/en/latest/jwst/resample/index.html#resample-step) - resamples each input image based on its WCS and distortion information and creates a single undistorted image.\n",
-    "- [source catalog](https://jwst-pipeline.readthedocs.io/en/latest/jwst/source_catalog/index.html#source-catalog-step) - creates a catalog of detected sources along with measured photometries and morphologies (i.e., point-like vs extended). Useful for quicklooks, but optimization is likely needed for specific science cases.\n"
+    "- [source catalog](https://jwst-pipeline.readthedocs.io/en/latest/jwst/source_catalog/index.html#source-catalog-step) - creates a catalog of detected sources along with measured photometries and morphologies (i.e., point-like vs extended). Useful for quicklooks, but optimization is likely needed for specific science cases, which is an on-going investigation for the NIRISS team. Users may wish to experiment with changing the `snr_threshold` and `deblend` options. Modifications to the following parameters will not significantly improve data quality and it is advised to keep them at their default values: `aperture_ee1`, `aperture_ee2`, `aperture_ee3`, `ci1_star_threshold`, `ci2_star_threshold`.\n"
    ]
   },
   {
@@ -749,7 +763,6 @@
     "viewer_cat.set_colormap('Viridis')\n",
     "viewer_cat.cuts = '95%'\n",
     "\n",
-    "\n",
     "imviz_cat.show()"
    ]
   },