{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "
\n", "REQUIREMENT:\n", " Before proceeding, install or update your\n", " \n", " stenv\n", " \n", " distribution. stenv is the replacement for AstroConda, which is unsupported as of February 2023.\n", "
" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "# Obtaining Pixel Area Maps for ACS Data\n", "\n", "## Introduction\n", "\n", "***\n", "\n", "The optical design of ACS introduces larger geometric distortion than in other *HST* instruments. In the event a user wishes to perform photometry on data that have not been processed by AstroDrizzle, a correction must be applied to account for the different sizes of the pixels on the sky across the field of view. \n", "\n", "A pixel area map (PAM), which is an image where each pixel value describes that pixel's area on the sky relative to the native plate scale, is used for this correction. The distortion corrections applied by both AstroDrizzle and the PAMs include observation-specific corrections (e.g., velocity distortion). For the best results, users are advised to create a PAM for each observation individually.\n", "\n", "To transform a distorted FLT/FLC image so that it is suitable for photometry, users must multiply the image by the PAM and divide the result by the exposure time so that the image has units of electrons/second. After this transformation, the information on the [ACS Zeropoints](http://www.stsci.edu/hst/instrumentation/acs/data-analysis/zeropoints) page can be used to convert flux measurements into physical units.\n", "\n", "### This tutorial will show you how to...\n", "\n", "#### 1. [Construct the Pixel Area Map](#_obtain)\n", "\n", "* Use `AstroDrizzle` with ASN files to combine images.\n", "\n", "#### 2. [Apply the Pixel Area Map](#_drkdrizzle)\n", "\n", "* Identify which dark images to use for your data.\n", "* Use `AstroDrizzle` to combine dark images." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Imports\n", "***\n", "\n", "Here we list the Python packages used in this notebook. Links to the documentation for each module is provided for convenience.\n", "\n", "| Package Name | module | docs | used for |\n", "|------------------|:-----------------|:-------------:|:------------|\n", "| `os` | `system` | link|command line input|\n", "| `os` | `environ` | link| setting environments |\n", "|`shutil` | `rmtree` | link| remove directory tree |\n", "|`matplotlib` |`pyplot` | link| plotting functions\n", "|`astroquery.mast` |`Observations` | link| download data from MAST |\n", "|`astropy.io` | `fits` | link| access and update fits files |\n", "|`stsci.skypac` |`pamutils`| link| construct pixel area map |" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "import os\n", "import shutil\n", "\n", "import matplotlib.pyplot as plt\n", "\n", "from astroquery.mast import Observations\n", "from astropy.io import fits\n", "from stsci.skypac import pamutils" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Download the Data\n", "***\n", "\n", "Here we download all of the data required for this notebook. This is an important step! Some of the image processing steps require all relevant files to be in the working directory. We recommend working with a brand new directory for every new set of data.\n", "\n", "#### [GO Proposal 9438](https://stdatu.stsci.edu/proposal_search.php?mission=hst&id=9438): \"The Origin of the Intergalactic Globular Cluster Population in Abell 1185\"\n", "\n", "For this example, we will only retreive data associated with the Observation ID **J6ME13QHQ**. Using the python package `astroquery`, we can retreive files from the [MAST](http://archive.stsci.edu) archive.\n", "\n", "
\n", "MAY CHANGE: The argument \"mrp_only\" stands for \"minimum recommended products only\". It currently needs to be set to False, although in the future, False is intended to be set as the default and can be left out.\n", "
" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "obs_table = Observations.query_criteria(proposal_id=9438, obs_id ='J6ME13QHQ')\n", "\n", "dl_table = Observations.download_products(obs_table['obsid'], \n", " mrp_only=False, \n", " productSubGroupDescription=['FLT'])" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "We'll use the packages `os` and `shutil` to put all of these files in our working directory for convenience and do a little housekeeping." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "for row in dl_table:\n", " oldfname = row['Local Path']\n", " newfname = os.path.basename(oldfname)\n", " os.rename(oldfname, newfname)\n", " \n", "shutil.rmtree('mastDownload')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## File Information\n", "***\n", "The structure of the fits files from ACS may be different depending on what kind of observation was made. For more information, refer to Section 2.2 of the [ACS Data Handbook](http://www.stsci.edu/files/live/sites/www/files/home/hst/instrumentation/acs/documentation/other-documents/_documents/acs_dhb.pdf).\n", "\n", "#### FLT Files (WFC-Specific)\n", "\n", "| Ext | Name | Type | Contains |\n", "|:----------:|------------------|--------------|:---------------------------------------------------------|\n", "|0 | PRIMARY | (PrimaryHDU) | Meta-data related to the entire file. |\n", "|1 | SCI (Image) | (ImageHDU) | WFC2 raw image data. |\n", "|2 | ERR (Error) | (ImageHDU) | WFC2 error array. |\n", "|3 | DQ (Data Quality)| (ImageHDU) | WFC2 data quality array. |\n", "|4 | SCI (Image) | (ImageHDU) | WFC1 raw image data. |\n", "|5 | ERR (Error) | (ImageHDU) | WFC1 error array. |\n", "|6 | DQ (Data Quality)| (ImageHDU) | WFC1 data quality array. |\n", "|7-10 | D2IMARR | (ImageHDU) | Filter-independent CCD pixel-grid distortion corrections.|\n", "|11-14| WCSDVARR | (ImageHDU) | Filter-dependent non-polynomial distortion corrections. |\n", "|15 | WCSCORR | (ImageHDU) | History of changes to the WCS solution. |" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Here, we set our files to variable names below for convenience." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "flt_file = 'j6me13qhq_flt.fits'" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "You can always use `.info()` on an HDUlist for an overview of the structure" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "with fits.open(flt_file) as hdulist:\n", " hdulist.info()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Construct Pixel Area Map\n", "***\n", "\n", "Function input for `pamutils.pam_from_file` is (input_file, extension, output_file). To create a PAM for the first science extension (WFC2) of this observation, we need to specify HDU Extension 1." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "pamutils.pam_from_file(flt_file, ext=1, output_pam='j6me13qhq_wfc2_pam.fits')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "For full-frame WFC observations, a second PAM for the WFC1 science array (extension 4) can be created as follows:" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "pamutils.pam_from_file(flt_file, ext=4, output_pam='j6me13qhq_wfc1_pam.fits')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Apply the Pixel Area Map\n", "***\n", "\n", "Because the pixel area map is an array of flux corrections based on 2d image distortion, you can multiply it by your data element-by-element to produce the corrected image. Here, we present the results." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "from p_module import plot" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "plot.triple_pam_plot(flt_file, 'j6me13qhq_wfc2_pam.fits', 'WFC2 PAM Correction Results')" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "plot.triple_pam_plot(flt_file, 'j6me13qhq_wfc1_pam.fits', 'WFC1 PAM Correction Results')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### For more help:\n", "\n", "More details may be found on the [ACS website](http://www.stsci.edu/hst/instrumentation/acs) and in the [ACS Instrument](https://hst-docs.stsci.edu/display/ACSIHB) and [Data Handbooks](http://www.stsci.edu/files/live/sites/www/files/home/hst/instrumentation/acs/documentation/other-documents/_documents/acs_dhb.pdf). Geometric Distortion information can be found in [Section 5.6.4](https://hst-docs.stsci.edu/display/ACSIHB/5.6+ACS+Point+Spread+Functions) and [Section 10.4](https://hst-docs.stsci.edu/display/ACSIHB/10.4+Geometrical+Distortion+in+the+ACS) of the ACS Instrument Handbook.\n", "\n", "Please visit the [HST Help Desk](http://hsthelp.stsci.edu). Through the help desk portal, you can explore the *HST* Knowledge Base and request additional help from experts." ] } ], "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.9.13" } }, "nbformat": 4, "nbformat_minor": 2 }