Add a topic guide for response function vocabulary (#111)

Co-authored-by: Joy  <[email protected]>
Co-authored-by: Nick Murphy <[email protected]>
Co-authored-by: Nabil Freij <[email protected]>
Co-authored-by: Laura Hayes <[email protected]>
Co-authored-by: Stuart Mumford <[email protected]>
Co-authored-by: Joy <[email protected]>

changelog/111.doc.rst

@@ -0,0 +1 @@
+Add a topic guide on a vocabulary for instrument response functions.

docs/index.rst

@@ -42,6 +42,7 @@ Once you have that virtual environment, you will want to fork the repo and then
 
    code_ref/index
    generated/gallery/index
+   topic_guide/index
    whatsnew/index
 
 

docs/topic_guide/channel_response.rst

@@ -0,0 +1,162 @@
+.. _sunkit-instruments-topic-guide-channel-response:
+
+************************************
+A Vocabulary for Instrument Response
+************************************
+
+This topic guide provides a vocabulary for response functions for imaging instruments.
+The reason to provide a single vocabulary for instrument response calculations is to define a specification for a common interface that can be used by multiple instruments.
+This reduces the amount of effort needed to develop analysis software for new instruments and enables cross-instrument comparisons as upstream packages and users can program against a single interface for these response calculations.
+An abstract implementation of this vocabulary is provided in this package.
+
+Temperature Response
+--------------------
+
+The temperature response describes the instrument sensitivity as a function of temperature.
+It is a useful quantity when performing thermal analysis of imaging data, such as a differential emission measure or filter ratio analysis.
+The temperature response is defined as,
+
+.. math::
+
+    K(T) = \int\mathrm{d}\lambda\,R(\lambda)S(\lambda,T)\quad[\mathrm{DN}\,\mathrm{pixel}^{-1}\,\mathrm{s}^{-1} \,\mathrm{cm}^5]
+
+It has a physical type of data number (DN) per pixel per unit time per unit emission measure.
+Note that the temperature response is a function of *both* the instrument properties as well as the atomic physics of the emitting source.
+The temperature response is related to the observed intensity in a given pixel by,
+
+.. math::
+
+    I = \int\mathrm{d}T\,K(T)\mathrm{DEM}(T)\quad[\mathrm{DN}\,\mathrm{pixel}^{-1}\,\mathrm{s}^{-1}],
+
+where,
+
+.. math::
+
+    \mathrm{DEM}(T)=n^2\frac{dh}{dT}
+
+is the line-of-sight *differential* emission measure distribution in a given pixel.
+It is typically expressed in units of :math:`\mathrm{cm}^{-5}\,\mathrm{K}^{-1}`.
+
+Source Spectra
+--------------
+
+The source spectra describes how a source is emitting as a function of wavelength and temperature.
+It is denoted by :math:`S(\lambda, T)`.
+The source spectra has a physical type of photon per unit time per unit wavelength per solid angle per unit density.
+The units are commonly expressed as
+:math:`\mathrm{photon}\,\mathrm{s}^{-1}\,\mathring{\mathrm{A}}^{-1}\,\mathrm{sr}^{-1}\,\mathrm{cm}^3`.
+As such, it may also be referred to as the *spectral radiance per unit emission measure*.
+The source spectra is specified by the user and can be computed from atomic databases (e.g. CHIANTI).
+This quantity is independent of any instrument properties.
+
+
+Wavelength Response
+-------------------
+
+The wavelength response describes the instrument sensitivity as a function of wavelength and time.
+The wavelength response is defined as,
+
+.. math::
+
+    R(\lambda,t) = A_{\mathrm{eff}}(\lambda,t)f(\lambda)\frac{pg}{s}\quad[\mathrm{cm}^2\,\mathrm{DN}\,\mathrm{photon}^{-1}\,\mathrm{sr}\,\mathrm{pixel}^{-1}]
+
+It has a physical type of area DN per photon solid angle per pixel.
+
+Camera Gain
+-----------
+
+The camera gain, :math:`g`, describes the conversion between electrons and data number (DN).
+This is a property of the detector.
+The units of the camera gain are :math:`\mathrm{DN}\,\mathrm{electron}^{-1}`.
+
+Photon-to-Energy Conversion
+---------------------------
+
+The photon-to-energy conversion is given by the amount of energy carried by a photon of wavelength :math:`\lambda`,
+
+.. math::
+
+    f(\lambda) = \frac{hc}{\lambda}\quad[\mathrm{eV}\,\mathrm{photon}^{-1}]
+
+where :math:`h` is Planck's constant and :math:`c` is the speed of light.
+It has a physical type of energy per photon.
+
+.. note::
+
+    Use the `~astropy.units.spectral` unit equivalency to provide a list of appropriate `astropy.units` equivalencies for this conversion.
+
+Energy-to-Electron Conversion
+-----------------------------
+
+The energy-to-electron conversion, :math:`s`, describes the conversion between electrons released in the detector and the energy of an incoming photon.
+This is commonly referred to as the *electron-hole-pair-creation energy*.
+It has a physical type of energy per electron.
+For silicon detectors, a value of :math:`s=3.65\,\mathrm{eV}\,\mathrm{electron}^{-1}` is typically used as this is approximately the energy required to free an electron in silicon.
+
+Pixel Solid Angle
+-----------------
+
+The pixel area, :math:`p`, is the angular area in the plane of the sky subtended by a single detector pixel.
+It has a physical type of solid angle per pixel.
+The units of the pixel area are typically expressed as :math:`\mathrm{sr}\,\mathrm{pixel}^{-1}`.
+Typically, this quantity can be determined as the product of the spatial plate scale in each direction.
+In the FITS standard, these keys are denoted by "CDELTi", with "i" typically taking on values of 1 or 2.
+Note that the pixel area is sometimes confusingly referred to as the plate scale.
+However, here we explicitly define the plate scale to be the angular *distance* subtended by one side of a pixel.
+
+Effective Area
+--------------
+
+The effective area describes the instrument sensitivity as a function of wavelength and time.
+It is given by,
+
+.. math::
+
+    A_{\mathrm{eff}}(\lambda,t) = A_{\mathrm{geo}}M(\lambda)F(\lambda)Q(\lambda)D(\lambda,t)\quad[\mathrm{cm}^2]
+
+The effective area has a physical type of area.
+:math:`A_\mathrm{eff}(\lambda,t=0)` is defined as the effective area at the start of the mission.
+Each component of the effective area is described in detail below.
+
+Geometrical Area
+****************
+
+The geometrical collecting area, :math:`A_\mathrm{geo}`, is the cross-sectional area of the telescope aperture.
+It has a physical type of area.
+The units of the geometrical collecting area are commonly expressed as :math:`\mathrm{cm}^2`.
+For example, for a telescope with a circular aperture of diameter :math:`d`, the geometrical collecting area is :math:`A_\mathrm{geo}=\pi d^2/4`.
+
+Mirror Reflectance
+******************
+
+The mirror reflectance, :math:`M(\lambda)`, is a dimensionless quantity describing the efficiency of the mirror(s) in the instrument as a function of wavelength.
+If the instrument contains multiple mirrors (e.g. a primary and secondary mirror), this quantity is the product of the reflectance of each mirror.
+:math:`M(\lambda)` should always be between 0 and 1.
+
+Filter Transmittance
+********************
+
+The filter transmittance, :math:`F(\lambda)`, is a dimensionless quantity describing the efficiency of the filter(s) as a function of wavelength.
+This is typically calculated by computing the transmittance through a given compound of a specified thickness.
+In the case of a multilayer coating, the transmittance is the product of the transmittance of each layer of the coating.
+Similarly, if an instrument contains multiple filters (e.g. an entrance and focal-plane filter), this quantity is the product of the transmittance of each mirror.
+:math:`F(\lambda)` should always be between 0 and 1.
+
+Effective Quantum Efficiency
+****************************
+
+The effective quantum efficiency, :math:`Q(\lambda)`, is a dimensionless quantity describing the efficiency of the detector.
+:math:`Q(\lambda)` should always be between 0 and 1.
+This quantity may also be referred to as the `external quantum efficiency <https://en.wikipedia.org/wiki/Quantum_efficiency#Types>`__.
+Note that the *quantum efficiency* is usually defined as the number of electron-hole pairs measured per photon.
+
+Degradation
+***********
+
+The degradation, :math:`D(\lambda,t)`, is a dimensionless quantity describing how the effective area degrades as a function of time and also how that degradation varies with wavelength.
+The time dimension, :math:`t`, corresponds to the lifetime of the mission.
+:math:`D(\lambda,t)` should always be between 0 and 1.
+The degradation need not be equal to 1 at :math:`t=0`.
+For example, there could be some known degradation due to contamination in the telescope known at the time of launch.
+This quantity should include all sources of degradation in the instrument.
+For example, if there is a known degradation model for the filter and the CCD, :math:`D(\lambda,t)` will be the product of these two degradation factors.

docs/topic_guide/index.rst

@@ -0,0 +1,15 @@
+.. _sunkit-instruments-topic-guide-index:
+
+************
+Topic Guides
+************
+
+
+These topic guides provide a set of in-depth explanations for various parts of the ``sunkit-instruments`` package.
+They are designed to be read in a standalone manner, without running code at the same time.
+Although there are code snippets in various parts of each topic guide, these are present to help explanation, and are not structured in a way that they can be run as you are reading a topic guide.
+
+.. toctree::
+   :maxdepth: 1
+
+   channel_response