{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Effective Area Analysis for X-Ray Telescope (XRT)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In this example, we will explore the effective areas for different XRT filter channels, considering their respective thicknesses of the CCD contamination layer at a specific date and time. Understanding the effective areas is essential for accurately interpreting and quantifying X-ray signals. Let's dive into the details and calculations below."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Import the xrtpy module for X-ray Telescope (XRT) calculations\n",
    "import xrtpy"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Contents\n",
    "\n",
    "1. [Define Filter](#Define-a-Filter-Channel)\n",
    "2. [Define Date & Time](#Define-a-date-and-time) \n",
    "3. [Effective-Area-Fundamental](#EffectiveAreaFundamental)\n",
    "4. [Effective Area Function](#Effective-Area-function)\n",
    "5. [Plotting the Effective Area versus Wavelength](#Plotting-the-Effective-Area-versus-Wavelength)\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Define a Filter Channel"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "[xrtpy- X-Ray Filter Channel]: https://xrtpy.readthedocs.io/en/latest/getting_started.html\n",
    "In XRT analysis, the filter channels play a crucial role in determining the effective areas. A filter channel refers to a specific configuration of filter materials. By defining the filter channel appropriately, we can accurately calculate the effective area for a given XRT configuration.\n",
    "\n",
    "Let's begin by defining a filter channel using its abbreviation. For example, if we want to explore the effective area for an aluminum-on-polyimide filter channel, we need to specify the relevant abbreviation. This step ensures that we consider the correct filter configuration in our calculations. Refer to the [xrtpy- X-Ray Filter Channel] section for more information.  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Define the filter channel abbreviation\n",
    "Filter = \"Al-poly\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Define a date and time"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "[sunpy-time]: https://docs.sunpy.org/en/stable/guide/time.html\n",
    "\n",
    "Let's consider exploring the data captured approximately a year after the launch date. We need to define a specific date and time. We will use the format \"YYYY-MM-DD HH:MM:SS\" to represent the desired date and time. The date and time can be specified using various formats depending on your preference and data availability. Please refer to the [sunpy-time] documentation for detailed examples and further information on different date and time string formats. \n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Define the date and time for analysis\n",
    "date_time = \"2007-09-22T22:59:59\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## EffectiveAreaFundamental"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `EffectiveAreaFundamental` object plays a central role in calculating the effective area. It provides a range of functions and properties that are essential for this computation. By utilizing the `EffectiveAreaFundamental` object, we can accurately determine the effective area based on the specified filter channel, date, and time.\n",
    "\n",
    "To access the functionality of the EffectiveAreaFundamental object, we need to reference it by inserting the defined `Filter` and `date_time`. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Create an instance of the EffectiveAreaFundamental object\n",
    "Effective_Area_Fundamental = xrtpy.response.EffectiveAreaFundamental(Filter, date_time)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Effective Area function"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To actually calculate the effective area function we call the `effective_area()` method of the `Effective_Area_Fundamental` object. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Calculate the effective area\n",
    "effective_area = Effective_Area_Fundamental.effective_area()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "[astropy-quantity]: https://docs.astropy.org/en/stable/api/astropy.units.quantity.Quantity.html\n",
    "\n",
    "[astropy.units]: https://docs.astropy.org/en/stable/units/index.html\n",
    "\n",
    "\n",
    "The `effective_area` function returns the effective area for a selected filter, date, and time as an [astropy-quantity] with [astropy.units].  \n",
    "  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(\"Effective Area:\\n\", effective_area)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Plotting the Effective Area versus Wavelength"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To gain insights into the X-ray Telescope (XRT) observations, we will plot the effective area against the corresponding wavelengths. This visualization allows us to understand how the effective area varies across different wavelengths and provides valuable information for interpreting XRT data."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We will utilize the `channel_wavelength` property within the Effective_Area_Fundamental object to get the wavelengths. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Wavelength unit in Angstroms A˚\n",
    "wavelength = Effective_Area_Fundamental.channel_wavelength"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "To further analyze the effective area data, we will focus on the observations relative to the spacecraft launch date. This will allow us to identify any differences or trends in the effective area during the early stages of the mission. We will define the effective area data for the launch date in the same manner as previously shown."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Create an instance of the EffectiveAreaFundamental object for the launch date and time of the same filter channel\n",
    "relative_launch_date_time = \"2006-09-22T22:59:59\"\n",
    "\n",
    "EAF_launch_date_time = xrtpy.response.EffectiveAreaFundamental(\n",
    "    Filter, relative_launch_date_time\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# launch date effective area\n",
    "launch_date_effective_area = EAF_launch_date_time.effective_area()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Create a plotting function that plots the effective area versus wavelegth."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def plot_effective_area():\n",
    "    import matplotlib.pyplot as plt\n",
    "\n",
    "    plt.figure(figsize=(30, 13))\n",
    "\n",
    "    plt.plot(\n",
    "        wavelength,\n",
    "        effective_area,\n",
    "        linewidth=8,\n",
    "        label=\"{:} {:}\".format(Filter, date_time),\n",
    "    )\n",
    "\n",
    "    plt.plot(\n",
    "        wavelength,\n",
    "        launch_date_effective_area,\n",
    "        linewidth=8,\n",
    "        label=\"{:} {:}\".format(Filter, relative_launch_date_time),\n",
    "    )\n",
    "\n",
    "    plt.title(\"XRT Effective Area\\nAl-Poly\", fontsize=30)\n",
    "    plt.xlabel(\"Wavelength (Å)\", fontsize=30)\n",
    "    plt.ylabel(\"Effective Area ($cm^{2}$)\", fontsize=30)\n",
    "    plt.legend(fontsize=30)\n",
    "\n",
    "    plt.xticks(fontsize=27)\n",
    "    plt.yticks(fontsize=27)\n",
    "    plt.xlim(0, 60)\n",
    "\n",
    "    plt.grid(color=\"lightgrey\")\n",
    "    plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Run `plot_effective_area` function to create the plot."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "plot_effective_area()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "[Montana State University Solar Physics site]: http://solar.physics.montana.edu/HINODE/XRT/xrt_contam_db.html \n",
    "[Narukage et. al. (2011)]: https://doi.org/10.1007/s11207-010-9685-2 \n",
    "\n",
    "\n",
    "By plotting the effective area at the spacecraft launch date and comparing it to the effective area a year after, we can observe and analyze any differences. These differences arise from variations in the contamination layer thickness on the CCD which blocks some of the X-rays thus reducing the effective area. For detailed information about the calculation of the XRT CCD contaminant layer thickness, you can refer to the [Montana State University Solar Physics site].\n",
    "\n",
    "To further understand the factors contributing to the observed differences, additional information can be found in the research paper by [Narukage et. al. (2011)]. This paper provides valuable insights into the characteristics and behavior of the XRT instrument, which can aid in interpreting the effective area data."
   ]
  }
 ],
 "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.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}
