Merge pull request #923 from mperrin/update_ifu_docs

update ifu docs to describe about coord_system and pixel scale

docs/jwst_ifu_datacubes.ipynb

@@ -43,11 +43,48 @@
     "   *  Specifically, it assumes that the wavefront optical path difference in the IFU exit pupil is independent of wavelength. This assumption is reasonably true for both MIRI and NIRSpec IFU modes within the current level of fidelity."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "ef5ecc18-2412-4ca3-bb1f-7f1c8ee8f9e6",
+   "metadata": {
+    "editable": true,
+    "slideshow": {
+     "slide_type": ""
+    },
+    "tags": []
+   },
+   "source": [
+    "## Datacube Coordinate Frames for IFU PSFs: SkyAlign vs IFUAlign\n",
+    "\n",
+    "<div class=\"alert alert-warning\">\n",
+    "WebbPSF is intended to simulate IFU PSFs in <I>IFUAlign</I> orientation only.\n",
+    "</div>\n",
+    "\n",
+    "For IFU observations, the JWST pipeline ``cube_build`` step (see [pipeline docs](https://jwst-pipeline.readthedocs.io/en/latest/jwst/cube_build/main.html)) can produce output datacubes in two different reference frames or orientations: \n",
+    "\n",
+    " - ``coord_system='skyalign'``. In these cubes, north is up and east is left. This is the default orientation.\n",
+    " - ``coord_system='ifualign'``. These cubes are build on the local IFU slicer plane's native coordinate system. The X and Y coordinates corresponds to the along-slice and across-slice directions, respectively (which are often labeled as the $\\alpha$ and $\\beta$ axes for MIRI MRS; see [JDox](https://jwst-docs.stsci.edu/jwst-mid-infrared-instrument/miri-instrumentation/miri-mrs-field-and-coordinates#MIRIMRSFieldandCoordinates-CoordinatesMRScoordinateframes).)\n",
+    "\n",
+    "<B>PSF simulations are always produced in the ifualign orientation only.</b> For PSF modeling work, we recommend reducing your science data using the ifualign frame. This allows PSF models and orientations to be consistent between multiple datasets, independent of position angles on the sky. \n",
+    "\n",
+    "If your science data has been reduced in skyalign frame, you can rotate the PSF based on the aperture position angle to match your data. However this will introduce numerical interpolation noise, particularly for spatially undersampled IFU data. That can be avoided by working in IFUalign frame, as we recommend here. \n",
+    "\n",
+    "\n",
+    "**Pixelscales:** By default, IFU PSFs are made using the same default pixel scales as the pipeline defaults (0.1 arcsec/pixel for NIRSpec, and variously 0.13 - 0.35 arcsec/pixel for MIRI depending on which MRS channel). If you have reduced your science data using a different pixelscale in the JWST pipeline, e.g. 0.123 arcsec/pix, simply set e.g. `miri.pixelscale = 0.123` to the same value for creating the PSF model. "
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 1,
    "id": "7ce1366f-dcc8-47b7-9e73-f0ebbee3f1ba",
-   "metadata": {},
+   "metadata": {
+    "editable": true,
+    "nbsphinx": "hidden",
+    "slideshow": {
+     "slide_type": ""
+    },
+    "tags": []
+   },
    "outputs": [
     {
      "name": "stderr",