{ "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": [ "\n", "# Using ACS Polarization Tools\n", "\n", "## Introduction\n", "\n", "***\n", "\n", "In December 2020, the ACS Team made available a Python module called `polarization_tools` in the `acstools` package to facilitate data analysis of ACS polarization data. This package contains both tables of calibration terms and class methods for polarization calculations.\n", "\n", "Note that this example does not use imaging data (i.e., FITS files). Where necessary, we will indicate values that come from ACS FITS files.\n", "\n", "### This tutorial will show you how to...\n", "\n", "#### 1. [Retrieve Polarization Calibration Coefficients](#_coeffs) \n", "\n", "* Get the latest calibration coefficients that are used in `acstools`\n", "\n", "#### 2. [Calculate Polarization Properties](#_properties)\n", "\n", "* Use the `acstools.polarization_tools` module to compute:\n", " * Stokes parameters\n", " * Fractional polarization\n", " * Electric field vector position angle" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Imports\n", "\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", "|`acstools` |`polarization_tools`| link| polarization information and methods| " ] }, { "cell_type": "code", "execution_count": 1, "metadata": { "execution": { "iopub.execute_input": "2024-04-19T16:51:25.309571Z", "iopub.status.busy": "2024-04-19T16:51:25.309308Z", "iopub.status.idle": "2024-04-19T16:51:25.714804Z", "shell.execute_reply": "2024-04-19T16:51:25.714186Z" } }, "outputs": [ { "name": "stderr", "output_type": "stream", "text": [ "WARNING: matplotlib not found, plotting is disabled [acstools.satdet]\n", "WARNING:astropy:matplotlib not found, plotting is disabled\n" ] } ], "source": [ "from acstools import polarization_tools" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Retrieve Polarization Calibration Coefficients\n", "\n", "***\n", "\n", "The `polarization_tools` module contains all of the necessary calibration terms from the tables in section 5.3 of the ACS Data Handbook (see tables 5.6 and 5.7). These coefficients are stored in YAML files in `acstools` and may be retrieved as `astropy.Table` tables:" ] }, { "cell_type": "code", "execution_count": 2, "metadata": { "execution": { "iopub.execute_input": "2024-04-19T16:51:25.751941Z", "iopub.status.busy": "2024-04-19T16:51:25.751614Z", "iopub.status.idle": "2024-04-19T16:51:25.771813Z", "shell.execute_reply": "2024-04-19T16:51:25.771148Z" } }, "outputs": [ { "data": { "text/html": [ "
Table length=3\n", "\n", "\n", "\n", "\n", "\n", "\n", "
filterpol0pol60pol120
str5float64float64float64
F475W1.43031.47171.4269
F606W1.33141.36071.3094
F775W0.99651.02551.0071
" ], "text/plain": [ "\n", "filter pol0 pol60 pol120\n", " str5 float64 float64 float64\n", "------ ------- ------- -------\n", " F475W 1.4303 1.4717 1.4269\n", " F606W 1.3314 1.3607 1.3094\n", " F775W 0.9965 1.0255 1.0071" ] }, "execution_count": 2, "metadata": {}, "output_type": "execute_result" } ], "source": [ "polarizer_tables = polarization_tools.PolarizerTables.from_package_data()\n", "\n", "# print the ACS/WFC polarizer efficiencies\n", "polarizer_tables.wfc_efficiency" ] }, { "cell_type": "code", "execution_count": 3, "metadata": { "execution": { "iopub.execute_input": "2024-04-19T16:51:25.774364Z", "iopub.status.busy": "2024-04-19T16:51:25.773874Z", "iopub.status.idle": "2024-04-19T16:51:25.778565Z", "shell.execute_reply": "2024-04-19T16:51:25.778078Z" } }, "outputs": [ { "data": { "text/html": [ "
Table length=3\n", "
\n", "\n", "\n", "\n", "\n", "\n", "
filtert_parat_perpcorrection
str5float64float64float64
F475W0.42392767985130980.000152405838415519561.000719276691027
F606W0.51567345940494195.5908749369641956e-051.000216861312415
F775W0.60408912837465570.073673641177594121.2777959654493372
" ], "text/plain": [ "\n", "filter t_para t_perp correction \n", " str5 float64 float64 float64 \n", "------ ------------------ ---------------------- ------------------\n", " F475W 0.4239276798513098 0.00015240583841551956 1.000719276691027\n", " F606W 0.5156734594049419 5.5908749369641956e-05 1.000216861312415\n", " F775W 0.6040891283746557 0.07367364117759412 1.2777959654493372" ] }, "execution_count": 3, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# print the average ACS/WFC cross-polarization leak corrections\n", "polarizer_tables.wfc_transmission" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "In addition, the tables contain metadata that describe their derivation:" ] }, { "cell_type": "code", "execution_count": 4, "metadata": { "execution": { "iopub.execute_input": "2024-04-19T16:51:25.780975Z", "iopub.status.busy": "2024-04-19T16:51:25.780617Z", "iopub.status.idle": "2024-04-19T16:51:25.784473Z", "shell.execute_reply": "2024-04-19T16:51:25.783987Z" } }, "outputs": [ { "data": { "text/plain": [ "{'description': 'WFC filters use MJD corresponding to 2020-01-01. HRC filters use MJD corresponding to 2007-01-01.'}" ] }, "execution_count": 4, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# print the ACS/WFC cross-polarization leak correction metadata\n", "polarizer_tables.wfc_transmission.meta" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Calculate Polarization Properties\n", "\n", "***\n", "\n", "The `acstools.polarization_tools.Polarizer` class contains methods for calculating the polarization properties of a source given ACS photometry as input. The inputs may be either in electrons or electrons/second, as long as all three (for each POL0, POL60, and POL120) are consistently in the same units. In addition, the class can accept either a single float value for each photometric measurement or a `numpy` array. This has the advantage that the class can construct Stokes images from the ACS photometry.\n", "\n", "For this example, we will use photometry measurements of the polarizated calibration star Vela 1-81 (an OB supergiant). The observations were taken using the ACS/WFC detector and by crossing the polarization filters with the F606W filter. The average PA_V3 value from the primary headers of the FITS files is 294.41272 degrees." ] }, { "cell_type": "code", "execution_count": 5, "metadata": { "execution": { "iopub.execute_input": "2024-04-19T16:51:25.786801Z", "iopub.status.busy": "2024-04-19T16:51:25.786441Z", "iopub.status.idle": "2024-04-19T16:51:25.798581Z", "shell.execute_reply": "2024-04-19T16:51:25.798002Z" } }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Stokes I = 169652.47890399996, Stokes Q = -8276.254216000001, Stokes U = -4644.582265627395\n", "Fractional polarization = 5.60%, Position Angle = 180.8631543698736 deg\n" ] } ], "source": [ "# Measured photometry from ACS/WFC data\n", "pol0 = 60603.96\n", "pol60 = 62382.70\n", "pol120 = 67898.63\n", "\n", "# PA_V3 angle\n", "pa_v3 = 294.41272\n", "\n", "pol_data = polarization_tools.Polarization(pol0, pol60, pol120, 'F606W', 'WFC', pa_v3)\n", "pol_data.calc_stokes()\n", "pol_data.calc_polarization()\n", "print(f'Stokes I = {pol_data.stokes_i}, Stokes Q = {pol_data.stokes_q}, Stokes U = {pol_data.stokes_u}')\n", "print(f'Fractional polarization = {pol_data.polarization:0.2%}, Position Angle = {pol_data.angle}')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Notice that we did not provide any of the calibration coefficients from the Data Handbook or from the [Retrieve Polarization Calibration Coefficients](#_coeffs) section. This is because the `Polarization` class retrieves the values using the spectral filter and detector information. These calibration values may be overwritten manually by setting the appropriate attributes:" ] }, { "cell_type": "code", "execution_count": 6, "metadata": { "execution": { "iopub.execute_input": "2024-04-19T16:51:25.801009Z", "iopub.status.busy": "2024-04-19T16:51:25.800673Z", "iopub.status.idle": "2024-04-19T16:51:25.803990Z", "shell.execute_reply": "2024-04-19T16:51:25.803391Z" } }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "c0 = 1.3314, c60 = 1.3607, c120 = 1.3094, cross-leak = 1.000216861312415\n" ] } ], "source": [ "# print the efficiency coefficients cross-polarization leak term used\n", "print(f'c0 = {pol_data.c0}, c60 = {pol_data.c60}, c120 = {pol_data.c120}, cross-leak = {pol_data.transmission_correction}')" ] }, { "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).\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.\n", "\n", "---\n", "[Top of Page](#titlePolarization)\n", "\"Space \n", "

\n", "

" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [] } ], "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.11.9" } }, "nbformat": 4, "nbformat_minor": 4 }