******************
Accessing PWV Data
******************

In order to model the PWV absorption for a given date and time, SuomiNet data
for that date must be available on your local machine. By default, each release
of **pwv_kpno** contains all necessary SuomiNet data from 2010 through the end
of the previous year. Access to the locally available PWV data is available
through the ``pwv_atm`` module.

Checking For Available Data
===========================

To check what years of SuomiNet data are locally available, use the
``available_data`` function.

.. autofunction:: pwv_kpno.pwv_atm.available_data

Examples:
---------

.. code-block:: python
    :linenos:

    >>> from pwv_kpno import pwv_atm
    >>> pwv_atm.available_data()

      [2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017]

Updating Data
=============

To download new SuomiNet data to your local machine, use the ``update_models``
function. This function will download new data from the SuomiNet web server,
and use that data to update the modeled precipitable water vapor for Kitt Peak
National Observatory.

.. autofunction:: pwv_kpno.pwv_atm.update_models

Examples:
---------

To ensure that the PWV data for **pwv_kpno** is up to date run:

.. code-block:: python
    :linenos:

    >>> from pwv_kpno import pwv_atm
    >>> pwv_atm.update_models()

      [2017, 2018]

If desired, **pwv_kpno** can be forced to (re)download SuomiNet data for a
specific year:

.. code-block:: python
    :linenos:

    >>> pwv_atm.update_models(2010)

      [2010]


Measured PWV Data
=================

Data that has been downloaded from SuomiNet can be accessed using the
``measured_pwv`` function.

.. autofunction:: pwv_kpno.pwv_atm.measured_pwv

Examples:
---------

To retrieve all SuomiNet data available on the local machine as an ``astropy``
table:

.. code-block:: python
    :linenos:

    >>> from pwv_kpno import pwv_atm
    >>> pwv_atm.measured_pwv()

               date       KITT KITT_err P014 P014_err SA46 SA46_err SA48 ...
               UTC         mm     mm     mm     mm     mm     mm     mm  ...
      ------------------- ---- -------- ---- -------- ---- -------- ---- ...
      2010-01-01 00:15:00   --       --  3.6    0.125  4.2    0.125  4.7 ...
      2010-01-01 00:45:00   --       --  3.7    0.125  4.0    0.125  4.7 ...
      2010-01-01 01:15:00   --       --  3.7    0.025  3.4    0.125  3.6 ...
                   ...     ...      ...  ...      ...  ...      ...  ... ...

To retrieve SuomiNet data taken on a specific date, specify the desired
datetime using keyword arguments. Note in the below example that there is no
data available from the SA48 receiver for this date:

.. code-block:: python
    :linenos:

    >>> pwv_atm.measured_pwv(year=2016, month=11, day=14)

               date       KITT KITT_err P014 P014_err SA46 SA46_err SA48 ...
               UTC         mm     mm     mm     mm     mm     mm     mm  ...
      ------------------- ---- -------- ---- -------- ---- -------- ---- ...
      2016-11-14 00:15:00  4.7    1.025  6.9    0.525  9.8    0.725   -- ...
      2016-11-14 00:45:00  4.3    1.025  6.7    0.425  9.9    0.525   -- ...
      2016-11-14 01:15:00  3.9    0.925  6.7    0.425  9.7    0.525   -- ...
                   ...     ...      ...  ...      ...  ...      ...  ... ...

**Note:** If no SuomiNet data is available at all during the specified datetime, then the
returned table will be empty.

Modeled PWV Data
================

To retrieve the modeled PWV level at Kitt Peak National Observatory, use the
``modeled_pwv`` function.

.. autofunction:: pwv_kpno.pwv_atm.modeled_pwv

Examples:
---------

To retrieve the entire PWV model from 2010 onward:

.. code-block:: python
    :linenos:

    >>> from pwv_kpno import pwv_atm
    >>> pwv_atm.modeled_pwv()

               date       pwv   pwv_err
               UTC         mm      mm
      ------------------- ----- -------
      2010-01-01 00:15:00 1.55    1.227
      2010-01-01 00:45:00 1.532   1.225
      2010-01-01 01:15:00 1.178   1.175
                      ...   ...     ...

To retrieve the modeled PWV level for November 14th, 2016:

.. code-block:: python
    :linenos:

    >>> pwv_atm.modeled_pwv(year=2016, month=11, day=14)

               date       pwv pwv_err
               UTC         mm    mm
      ------------------- --- -------
      2016-11-14 00:15:00 4.7   1.025
      2016-11-14 00:45:00 4.3   1.025
      2016-11-14 01:15:00 3.9   0.925
                      ... ...    ...

PWV For a Given Date
====================

For convenience, users can interpolate from the modeld PWV concentration at
Kitt Peak using the ``pwv_date`` function. Note that this function does not
return an uncertainty on the measured value.

.. autofunction:: pwv_kpno.pwv_atm.pwv_date

Examples:
---------

To retrieve the modeled PWV level for November 14, 2016 at 11:06 AM:

.. code-block:: python
    :linenos:

    >>> from datetime import datetime
    >>> from pwv_kpno import pwv_atm
    >>> import pytz
    >>>
    >>> date = datetime(2016, 11, 14, 11, 6, tzinfo=pytz.utc)
    >>> pwv = pwv_atm.pwv_date(date)