pyExtinction 2.0

======================================================================
                     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/