pyExtinction 2.0__py3-none-any.whl

pyextinction/atmospheric_extinction.py

@@ -0,0 +1,438 @@
+# SPDX-FileCopyrightText: 2013-present Yannick Copin <y.copin@ip2i.in2p3.fr>
+# SPDX-License-Identifier: CECILL-C
+
+"""
+.. _module:
+
+atmopheric_extinction (module)
+==============================
+"""
+
+from importlib.resources import files    # Python 3.10+
+
+import numpy as np
+from scipy.interpolate import UnivariateSpline
+import matplotlib.pyplot as plt
+from astropy.io import fits
+
+# Data path
+PYEXT_PATH = files("pyextinction.data")  #: Path to pyExtinction data.
+O3Template = PYEXT_PATH.joinpath('ozoneTemplate.fits') #: Default ozone template
+
+EXT2OPT = .92103403719761834  # LOG10/2.5 = Extinction to opt. thickness
+
+# Classes ======================================================================
+
+class ExtinctionModel:
+    """
+    ExtinctionModel class, to build an extinction curve from individual components.
+    """
+
+    def __init__(self, lbda=None, ozoneTemplate=O3Template, lrefAero=1e4):
+        """
+        Extinction model, from:
+
+        :param lbda: wavelength vector [Å] (default to extended optical range)
+        :param ozoneTemplate: name of the ozone template table (see
+          :func:`readOzoneTemplate`). By default, use the provided
+          ozone template.
+        :param lrefAero: aerosol reference wavelength [Å]
+        """
+
+        if lbda is None:
+            self.lbda = np.arange(3200, 10001, 10, dtype=float)
+        else:
+            self.lbda = np.asanyarray(lbda)  # Wavelength [Å]
+
+        # Rayleigh extinction template [mag/airmass] for a pressure of 1 mbar
+        self.rayleigh = self.rayleigh_HT74(self.lbda, 1.)
+
+        # Ozone extinction [mag/airmass]
+        self.ozoneName = ozoneTemplate
+
+        # Read transmission ozone template, interpolate at input
+        # wavelengthes, and convert to extinction [mag/airmass] for an
+        # ozone column density of 1 DU
+        self.ozone, self.ozoneNorm = readOzoneTemplate(self.ozoneName, self.lbda)
+        self.ozone /= self.ozoneNorm
+
+        # Aerosols
+        self.lrefAero = lrefAero        # Aerosol reference wavelength [Å]
+        self.lbdaN = self.lbda / self.lrefAero
+
+        # Parameters (to be set)
+        self.p = self.dp = None
+
+    def __str__(self):
+
+        lmin, lmax = self.lbda[[0, -1]]
+        dl = self.lbda[1] - self.lbda[0]
+        n = len(self.lbda)
+
+        s = f"""\
+Wavelength domain: {lmin:.0f}-{lmax:.0f} Å by step of {dl:.0f} Å ({n} px)
+Ozone template: {self.ozoneName} ({self.ozoneNorm} DU)
+Aerosol reference wavelength: {self.lrefAero:.0f} Å
+"""
+        if self.p is not None:
+            p, o3, tau, ang = self.p
+            dp, do3, dtau, dang = self.dp
+            s += f"""\
+Input extinction parameters:
+  Pressure: {p:.0f} ± {dp:.0f} mbar
+  Ozone:    {o3:.0f} ± {do3:.0f} DU
+  Aerosols: optical depth @ refLbda: {tau:.2g} ± {dtau:.2g}
+            angstrom exponent:       {ang:.2f} ± {dang:.2f}
+"""
+
+        else:
+            s += """\
+Input extinction parameters: not set yet
+"""
+
+        return s
+
+    def setParams(self, pars, dpars=None):
+        """
+        Set physical extinction parameters: pressure, ozone column
+        density [Dobson units], aerosol optical depth at reference
+        wavelength and aerosol angstrom exponent.
+
+        :param pars: extinction parameters (*pr*, *oi*, *ai*, *ap*)
+          where:
+
+          - *pr*: surface pressure [mbar]
+          - *oi*: ozone intensity [Dobson units]
+          - *ai*: aerosol optical depth at reference wavelength
+          - *ap*: aerosol angstrom exponent
+
+        :param dpars: associated standard errors
+
+        The total atmospheric extinction will then be the sum of
+        three components:
+
+        - Rayleigh extinction: `pr[mbar] * HT74(1 mbar)`
+        - Ozone extinction: `oi[DU] * OzoneTemplate(1 DU)`
+        - Aerosol extinction: `ai/EXT2OPT * (lbda/lRef)**(-ap)`
+
+        .. Note:: if `ndim(dpars)==2`, `dpars` is considered as the
+           *covariance* matrix of input extinction
+           parameters. Therefore, when `ndim(dpars)==1`,
+           `self.extinctionErrors(pars, dpars)` is equivalent to
+           `self.extinctionErrors(pars, np.diag(dpars)**2)` (note the
+           square power).
+        """
+
+        self.p = np.asanyarray(pars)
+        if dpars is None:
+            self.dp = np.zeros(4)
+        else:
+            self.dp = np.asanyarray(dpars)
+
+    def setDefaultParams(self, location='Mauna Kea'):
+        """
+        Set default physical extinction parameters from predefined location.
+
+        :param location: predefined location.
+
+        =================================  =================
+        Parameter                          Value ± Error
+        =================================  =================
+        *Mauna Kea*
+        ----------------------------------------------------
+        Pressure                           616 ± 2 mbar
+        Ozone column                       257 ± 23 DU
+        Aerosols optical depth @ 1 micron  0.0076 ± 0.0014
+        Aerosols angstrom exponent         1.26 ± 1.33
+        =================================  =================
+        """
+
+        if location == "Mauna Kea":
+            o3, do3 = 257., 23.         # Ozone column density [DU]
+            ang, dang = 1.26, 1.33      # Ångström exponent
+            tau, dtau = 7.6e-3, 1.4e-3  # Aerosol optical depth at 1 micron
+            p, dp = 616., 2.            # Surface pressure [mbar]
+        else:
+            raise ValueError(f"Unknown location {location!r}.")
+
+        self.setParams([p, o3, tau, ang],
+                       dpars=[dp, do3, dtau, dang])
+
+    def extinctionComponents(self):
+        """
+        Compute extinction individual components from extinction
+        parameters (see :meth:`setParams`)
+
+        :return: extinction components 2D-array [rayleigh,ozone,aerosols]
+        """
+
+        return np.array([
+            self.p[0] * self.rayleigh,                       # Rayleigh component
+            self.p[1] * self.ozone,                          # Ozone component
+            self.p[2] / EXT2OPT * self.lbdaN**(-self.p[3]),  # Aerosols component
+        ])
+
+    def extinctionErrors(self):
+        """
+        Compute total extinction (diagonal) standard error from extinction
+        parameters and associated standard errors (see :meth:`setParams`)
+
+        :return: total extinction standard error
+        """
+
+        jac = self.jac()
+        if np.ndim(self.dp) == 1:    # dp is a vector of std (independant) errors
+            vExt = np.dot(self.dp**2, jac**2)
+        elif np.ndim(self.dp) == 2:  # dp is actually a covariance matrix
+            vExt = np.dot(np.dot(jac.T, self.dp), jac).diagonal()
+        else:
+            raise ValueError("Invalid extinction errors.")
+
+        return np.sqrt(vExt)
+
+    def extinction(self, pars=None, dpars=None, components=False):
+        """
+        Compute total extinction (and associated standard error)
+        from extinction parameters (and associated standard errors).
+
+        :param pars: extinction parameters (see :meth:`setParams`)
+        :param dpars: extinction parameter errors (see :meth:`setParams`)
+        :param components: return individual extinction components if True
+        :return: 2D-array [ext,dext,[components]]
+        """
+
+        if None not in (pars, dpars):
+            self.setParams(pars, dpars)
+
+        comp = self.extinctionComponents()    # (ncomp,nlbda)
+        ext = comp.sum(axis=0)                # (nlbda,)
+        dext = self.extinctionErrors()        # (nlbda,)
+
+        if not components:      # Return [lbda, ext, dext]
+            return np.vstack((ext, dext))
+        else:                   # Return individual components as well
+            return np.vstack((ext, dext, comp))
+
+    def jac(self):
+        """Jacobian of total extinction with respect to extinction
+        parameters.
+
+        :return: jacobian 2D-array (nparam=4,nlbda)
+        """
+
+        jac = np.empty((len(self.p), len(self.lbda)), 'd')
+        jac[0] = self.rayleigh                            # dext/dP
+        jac[1] = self.ozone                               # dext/do3
+        jac[2] = self.lbdaN**(-self.p[3]) / EXT2OPT       # dext/dtau
+        jac[3] = -self.p[2] * jac[2] * np.log(self.lbdaN)  # dext/dang
+
+        return jac
+
+    @staticmethod
+    def rayleigh_HT74(lbda, pressure):
+        """
+        Rayleigh extinction from `Hansen & Travis (1974)
+        <http://cdsads.u-strasbg.fr/abs/1974SSRv...16..527H>`_.
+
+        :param lbda: wavelength vector [Å]
+        :param pressure: effective surface pressure [mbar]
+        :return: Rayleigh extinction [mag/airmass]
+        """
+
+        lm = lbda * 1e-4                # Wavelength from Å to microns
+
+        # Optical depth
+        tau = 0.008569 / lm**4 * (1 + 0.0113 / lm**2 + 0.00013 / lm**4)
+        tau *= pressure / 1013.25
+
+        return tau / EXT2OPT    # Convert to attenuation [mag/airmass]
+
+    def write(self, outname, ext=None, format='txt'):
+        """
+        Write extinction curve in output file.
+
+        :param outname: output filename
+        :param ext: explicit extinction curve(s) to be written out
+        :param format: output file format ('txt' or 'fits')
+        """
+
+        if ext is None:
+            ext = self.extinction(components=True)
+
+        if format == 'txt':             # ASCII table
+            ext = np.absolute(ext.round(6))  # Avoid rounding imprecisions
+
+            outFile = open(outname, 'w')
+            # Header
+            outFile.write('\n# '.join([''] + str(self).split('\n')) + '\n')
+            outFile.write('# Reference: Buton et al. (2013A&A...549A...8B)\n')
+            outFile.write('# Wavelength in Å\n')
+            outFile.write('# Extinctions in mag/airmass\n')
+            outFile.write('# lbda   Ext   dExt    Ray    O3     Aero \n')
+            # Values
+            for l, e, de, r, o, a in zip(self.lbda,
+                                         ext[0], ext[1], ext[2], ext[3], ext[4]):
+                outFile.write(' %5d  %.3f  %.3f  %.3f  %.3f  %.3f\n' % (l, e, de, r, o, a))
+            outFile.close()
+
+        elif format == 'fits':       # FITS table
+
+            p, o3, tau, ang = self.p
+            dp, do3, dtau, dang = self.dp
+
+            keywords = [
+                # Generic keywords
+                ('EXTMODEL', "Rayleigh+Ozone+Aerosols", "Extinction model"),
+                ('EXTREF',
+                 "Buton et al., 2013A&A...549A...8B", "Bibliographical ref."),
+                # Extinction parameters and errors
+                ('RA_P', p, "Surface pressure [mbar]"),
+                ('RA_DP', dp, "Pressure stddev [mbar]"),
+                ('OZ_INT', o3, "Ozone intensity [DU]"),
+                ('OZ_DINT', do3, "Ozone intensity stddev [DU]"),
+                ('AE_TAU', tau, "Aerosol optical depth"),
+                ('AE_DTAU', dtau, "Aerosol optical depth stddev"),
+                ('AE_ANG', ang, "Aerosol Angstrom exponent"),
+                ('AE_DANG', dang, "Aerosol Angstrom exponent stddev"),
+                ('AE_LREF', self.lrefAero, "Aerosol ref. wavelength [Angstrom]"),
+            ]
+
+            # Extinction table
+            arrays = [self.lbda, ext[0], ext[1], ext[2], ext[3], ext[4]]
+            names = ['LAMBDA', 'EXT', 'DEXT', 'RAYLEIGH', 'OZONE', 'AEROSOLS']
+            units = ['Angstrom'] + ['mag/airmass']*5
+
+            # Extinction BinTableHDU, with keywords
+            table = createTable(arrays, names, units=units, keywords=keywords,
+                                extname='EXTINCTION')
+            table.writeto(outname, overwrite=True)
+
+        else:
+            raise ValueError(f"Unknown output format {format!r}.")
+
+    def plot(self, ext=None, ax=None, components=True, transmission=False):
+        """
+        Plot the atmospheric extinction/transmission and its physical components.
+
+        :param ext: extinctions to be plotted (or None)
+        :param ax: matplotlib Axes instance (or None)
+        :param components: display individual components if True
+        :param transmission: display transmission rather than extinction
+        :return: matplotlib Axes instance
+        """
+
+        if ext is None:
+            ext = self.extinction(components=True)
+
+        p, o3, tau, ang = self.p
+
+        # Non-default colors
+        blue, red, green, orange = ('#0066CC', '#CC0033', '#009966', '#FF9900')
+
+        if transmission:  # Extinction [mag/airmass] -> Transmission
+            title = "Atmospheric transmission"
+            ylbl = "Transmission"
+            ext[0] = 10**(-0.4 * ext[0])    # Total transmission
+            ext[1] *= -EXT2OPT * ext[0]     # Error on total transmission
+            ext[2:] = 10**(-0.4 * ext[2:])  # Component transmissions
+        else:
+            title = "Atmospheric extinction"
+            ylbl = "Extinction [mag/airmass]"
+        title += " (Buton et al., 2013A&A...549A...8B)"
+
+        if ax is None:                      # Create a default axes
+            fig = plt.figure(figsize=(8, 5))
+            ax = fig.add_subplot(1, 1, 1,
+                                 title=title,
+                                 xlabel="Wavelength [Å]",
+                                 xlim=(self.lbda[0], self.lbda[-1]),
+                                 ylabel=ylbl)
+            ax.ticklabel_format(style='plain')
+
+        # Total extinction and errorband
+        ax.plot(self.lbda, ext[0], color=green, lw=2, label='Total')
+        ax.fill_between(self.lbda, ext[0] - ext[1], ext[0] + ext[1],
+                        alpha=0.3, fc=green, ec=green, label='_')
+
+        if components:                      # Physical components
+            ax.plot(self.lbda, ext[2], color=red, ls='--',
+                    label=f'Rayleigh [{p:.0f} mbar]')
+            ax.plot(self.lbda, ext[3], color=blue, ls=':',
+                    label=f'Ozone [{o3:.0f} DU]')
+            ax.plot(self.lbda, ext[4], color=orange, ls='-.',
+                    label=f'Aerosols [τ={tau:.4f}, å={ang:.2f}]')
+
+        ax.legend(loc='best', frameon=False)
+
+        return ax
+
+# Functions ==================================================================
+
+
+def readOzoneTemplate(ozoneName, lbda,
+                      colLbda='LAMBDA', colTrans='OZONE', ext=1):
+    """
+    Read ozone transmission template, interpolate over
+    wavelengthes, and convert to extinction [mag/airmass].
+
+    :param ozoneName: input FITS table, with columns *colLbda*
+      (wavelength in Å) and *colTrans* (fractional transmission), and
+      key 'REFO3COL' specifing the reference ozone column density [DU]
+    :param lbda: output wavelengthes [Å]
+    :param colLbda: name of the wavelength (in Å) column
+    :param colTrans: name of the ozone transmission column
+    :param ext: extension in which to look for wavelength and
+      transmission columns
+    :return: ozone extinction [mag/airmass], refO3col
+    """
+
+    # Read wavelength and transmission columns
+    ffile = fits.open(ozoneName)
+    x = ffile[ext].data.field(colLbda)   # Wavelength
+    y = ffile[ext].data.field(colTrans)  # Transmission
+    refO3col = ffile[ext].header["REFO3COL"]
+
+    # Interpolate transmissions over lbda
+    trans = UnivariateSpline(x, y, s=0)(lbda)
+
+    # Convert to extinction [mag/airmass]
+    return np.absolute(-2.5 * np.log10(trans)), refO3col
+
+
+def createTable(arrays, names,
+                units=None, formats=None, keywords=(), extname=None):
+    """
+    Create a FITS-table from a set of arrays.
+
+    :param arrays: list of input arrays (ncols,)
+    :param names: list of column names (ncols,)
+    :param units: list of column units (ncols,) ('none' by default)
+    :param formats: list of column formats (ncols,) ('1E' by default)
+    :param keywords: list of keys (key,val[,comment]) to add to table header
+    :param extname: name of the binary table extension
+    :return: table HDU
+    """
+
+    assert len(arrays) == len(names)
+    for arr in arrays[1:]:
+        assert len(arr) == len(arrays[0])
+    if units is None:
+        units = ['none'] * len(arrays)
+    else:
+        assert len(units) == len(arrays)
+    if formats is None:
+        formats = ['1E'] * len(arrays)
+    else:
+        assert len(formats) == len(arrays)
+
+    cols = [ fits.Column(array=arrays[i], name=names[i], unit=units[i], format=formats[i])
+             for i in range(len(arrays)) ]
+
+    thdu = fits.BinTableHDU.from_columns(cols)
+    if extname is not None:
+        thdu.header['EXTNAME'] = extname
+    thdu.header['FCLASS'] = (26, 'Table file class')
+    for key, val, cmt in keywords:        # Add some keywords if any
+        thdu.header[key] = (val, cmt)
+
+    return thdu

pyextinction-2.0.dist-info/METADATA

@@ -0,0 +1,128 @@
+Metadata-Version: 2.5
+Name: pyExtinction
+Version: 2.0
+Summary: Atmospheric extinction, from Buton et al. 2013A&A...549A...8B
+Project-URL: repository, https://gitlab.in2p3.fr/ycopin/pyExtinction
+Project-URL: documentation, https://pyextinction.readthedocs.io/en/latest/
+Author-email: Clément Buton <c.buton@araiko.ai>, Yannick Copin <y.copin@ip2i.in2p3.fr>
+Maintainer-email: Yannick Copin <y.copin@ipnl.in2p3.fr>
+License-Expression: CECILL-C
+License-File: LICENSE.txt
+Requires-Python: >=3.10
+Requires-Dist: astropy>=6
+Requires-Dist: matplotlib>=3
+Requires-Dist: numpy>=2
+Requires-Dist: scipy>=1
+Description-Content-Type: text/plain
+
+======================================================================
+                     pyExtinction's documentation
+======================================================================
+
+:Authors: Clément Buton, Yannick Copin
+:Contact: :email:`Yannick Copin <y.copin@ip2i.in2p3.fr>`
+:Copyright: 2012-present, Clément Buton, Yannick Copin
+
+.. only:: html
+
+   .. image:: https://img.shields.io/badge/ascl-1403.002-blue.svg?colorB=262255
+      :target: http://ascl.net/1403.002
+      :alt: ascl:1403.002
+
+   .. image:: https://img.shields.io/pypi/v/pyextinction
+      :target: https://pypi.org/project/pyextinction
+      :alt: pypi version
+
+   .. image:: https://img.shields.io/pypi/pyversions/pyextinction
+      :target: https://pypi.org/project/pyextinction
+      :alt: Supported Python Versions
+
+   .. figure:: https://readthedocs.org/projects/pyextinction/badge/?version=latest
+      :target: http://pyextinction.readthedocs.org/en/latest/?badge=latest
+      :alt: pyExtinction Documentation Status
+
+Introduction
+============
+
+This Python :ref:`script <script>` / :ref:`package <module>` computes total
+atmospheric extinction from decomposition into physical components (Rayleigh
+attenuation, ozone absorption, aerosol extinction), as described in `Buton et
+al. (2013) <http://adsabs.harvard.edu/abs/2013A%26A...549A...8B>`_,
+*Atmospheric extinction properties above Mauna Kea from the Nearby Supernova
+Factory spectro-photometric data set*.
+
+Installation
+------------
+
+The module is installable from `pypi <https://pypi.org/project/pyextinction/>`_
+(traditional dependencies: numpy_, scipy_, matplotlib_, astropy_)::
+
+   pip install pyextinction
+
+Extinction parameters
+---------------------
+
+:ref:`atmosphericExtinction.py <script>` default extinction parameters are
+adapted to mean `Mauna-Kea summit <http://www.ifa.hawaii.edu/mko/>`_
+conditions:
+
+.. table:: Atmospheric extinction parameters.
+
+   =================================  =================
+   Parameter                          Value ± Error
+   =================================  =================
+   *Mauna Kea*
+   ----------------------------------------------------
+   Pressure                           616 ± 2 mbar
+   Ozone column                       257 ± 23 DU
+   Aerosols optical depth @ 1 µm      0.0076 ± 0.0014
+   Aerosols angstrom exponent         1.26 ± 1.33
+   =================================  =================
+
+.. figure:: atmosphericExtinction.*
+   :width: 80%
+
+Please :email:`contact us <y.copin@ip2i.in2p3.fr>` if you have derived mean
+extinction parameters for other locations.
+
+Citations
+---------
+
+If you have found this extinction curve model useful for your research, we
+would appreciate a reference to `Buton et al. (2013)
+<http://adsabs.harvard.edu/abs/2013A%26A...549A...8B>`_.  The software itself
+can be cited with `Buton & Copin (2014)
+<http://adsabs.harvard.edu/abs/2014ascl.soft03002B>`_.
+
+Downloads
+---------
+
+* Mauna-Kea mean atmospheric extinction:
+  :download:`txt <atmosphericExtinction.txt>`,
+  :download:`fits <atmosphericExtinction.fits>`
+* Latest version of the software is available from `gitlab repository
+  <https://gitlab.in2p3.fr/ycopin/pyExtinction>`_
+* On-line documentation can be found on `gitlab pages
+  <https://ycopin.pages.in2p3.fr/pyExtinction>`_ (latest) and `rtfd
+  <http://pyextinction.readthedocs.org/en/latest/>`_ (legacy)
+
+Licence
+-------
+
+This code is placed under the `CeCILL-C free software license agreement
+<http://www.cecill.info/licences/Licence_CeCILL-C_V1-en.html>`_.
+
+Some external links cited in the paper (potentially deprecated)
+===============================================================
+
+* SkyProbe_
+* `Mauna Loa Observatory`_
+* `Total Ozone measurements`_
+
+.. _numpy: https://numpy.org/
+.. _scipy: https://www.scipy.org/
+.. _matplotlib: https://matplotlib.org/
+.. _astropy: https://www.astropy.org/
+.. _SkyProbe: http://www.cfht.hawaii.edu/Instruments/Elixir/skyprobe/home.html
+.. _Mauna Loa Observatory: http://www.esrl.noaa.gov/gmd/obop/mlo/
+.. _Total Ozone measurements: http://www.esrl.noaa.gov/gmd/ozwv/dobson/

pyextinction-2.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+pyextinction/__init__.py,sha256=ERIRIjXncRHDxppqB6UKlYnDy-ZDu6oWEgqzyTjVkPs,391
+pyextinction/__main__.py,sha256=q-zC7pGEx971fEeuCcQENBrgmlnRGajtXMIjWVwEo9A,5510
+pyextinction/__main__.py.bak,sha256=tJI-Kb3YI6NKzC4HSecE_SJt1vQyTTzQXEPynE5lTis,4750
+pyextinction/atmospheric_extinction.py,sha256=ZuVEnOsQqD2D-a2oUjEezbZyDwifBve_9hcS90x1SPU,16538
+pyextinction/data/ozoneTemplate.fits,sha256=dLMJdBS-AAvUqPZMCRREyIvkZ_ICDUUjixLhkYirlzE,11520
+pyextinction-2.0.dist-info/METADATA,sha256=yOZQ1FnVdEF40CTK-NoPFO291685doUoQniTCup-4zs,4712
+pyextinction-2.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+pyextinction-2.0.dist-info/entry_points.txt,sha256=pNSSqiIH3pDBhPLhbYju3DY2eo-J2mm6hRs5Fj8msao,60
+pyextinction-2.0.dist-info/licenses/LICENSE.txt,sha256=tI9dwW8UTNed2q3OPMjvGDd4oLT3WrQ2LhNLNHyiDz0,21863
+pyextinction-2.0.dist-info/RECORD,,

pyextinction-2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pyextinction-2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pyextinction = pyextinction.__main__:main