
.. Label between '.. _' and ':' ; use :ref:`text <label>` for reference
.. _viirs-aod-processing:

*************************
VIIRS AOD data processing
*************************

This chapter describes the tasks performed for processing VIIRS AOD data.


.. _viirs-aod-product:

Product description
===================

The *Visible Infrared Imaging Radiometer Suite* (VIIRS) data products are developed by NASA.
See the `VIIRS Overview <https://lpdaac.usgs.gov/data/get-started-data/collection-overview/missions/s-npp-nasa-viirs-overview/>`_
for an extensive description of the instrument.

The VIIRS instrument has been mounted on two satellites, described in the following table:

    +---------------+--------------+----------------------+-----------------------------------------------+
    | **platform**  | **launch**   | **crossing equator** |                   **ESDT**                    |
    |               |              +-----------+----------+-----------------------+-----------------------+
    |               |              | **night** | **day**  | **Deep Blue**         | **Dark Target**       |
    +---------------+--------------+-----------+----------+-----------------------+-----------------------+
    | **Suomi NPP** |  2011-10-28  |   01:30   | 13:30    | AERDB_L2_VIIRS_SNPP   | AERDT_L2_VIIRS_SNPP   |
    +---------------+--------------+-----------+----------+-----------------------+-----------------------+
    | **NOAA-20**   |  2017-11-18  |   02:20   | 14:20    | AERDB_L2_VIIRS_NOAA20 | AERDT_L2_VIIRS_NOAA20 |
    +---------------+--------------+-----------+----------+-----------------------+-----------------------+

Selected instrument characteristics:

* Swath            :    3.000 km
* Spectral bands   :    22, range 412 nm - 12 um
* Resolutions      :  375 m and 750 m

AOD products are available from two retrieval algoriths 
(see also '`What Is The Difference Between Dark Target And Deep Blue? <https://darktarget.gsfc.nasa.gov/content/what-difference-between-dark-target-and-deep-blue>`_):

* Deep Blue (DB); example file: `AERDB_L2_VIIRS_SNPP.A2022001.0342.002.2023076013614.txt <../../samples/AERDB_L2_VIIRS_SNPP.A2022001.0342.002.2023076013614.txt>`_
* Dark Target (DT); example file: `AERDT_L2_VIIRS_SNPP.A2022001.0518.002.2023214051603.txt <../../samples/AERDT_L2_VIIRS_SNPP.A2022001.0518.002.2023214051603.txt>`_

Data access is described on the `LAADS/DAAC Aerosol page on VIIRS <https://ladsweb.modaps.eosdis.nasa.gov/missions-and-measurements/science-domain/aerosol/#viirs>`_.
For Level-2 AOD products, the *Earth Science Data Type* (ESDT) or *shortname* of the product is listed in the table above.

The CSO modules use the `EarthAccess <https://earthaccess.readthedocs.io/en/latest/>`_ package to inquire and download the data.


AOD Deep Blue product
---------------------

Overview of variables in the data files::

    dimensions:
	    Idx_Atrack        = 404 ;
	    Idx_Xtrack        = 400 ;
	    Land_Bands        = 3 ;
	    Ocean_Bands       = 7 ;
	    Reflectance_Bands = 8 ;

    variables:
	    float Idx_Atrack                                                                        (Idx_Atrack) ;
	    float Idx_Xtrack                                                                                    (Idx_Xtrack) ;
	    float Latitude                                                                          (Idx_Atrack, Idx_Xtrack) ;
	    float Longitude                                                                         (Idx_Atrack, Idx_Xtrack) ;
	    float Cell_Average_Elevation_Land                                                       (Idx_Atrack, Idx_Xtrack) ;
	    float Cell_Average_Elevation_Ocean                                                      (Idx_Atrack, Idx_Xtrack) ;

	    double Scan_Start_Time                                                                  (Idx_Atrack, Idx_Xtrack) ;

	    float Aerosol_Optical_Thickness_550_Land                                                (Idx_Atrack, Idx_Xtrack) ;
	    float Aerosol_Optical_Thickness_550_Land_Best_Estimate                                  (Idx_Atrack, Idx_Xtrack) ;
	    float Aerosol_Optical_Thickness_550_STDV_Land                                           (Idx_Atrack, Idx_Xtrack) ;
	    float Aerosol_Optical_Thickness_550_Expected_Uncertainty_Land                           (Idx_Atrack, Idx_Xtrack) ;
	    int   Aerosol_Optical_Thickness_QA_Flag_Land                                            (Idx_Atrack, Idx_Xtrack) ;
	    int   Aerosol_Type_Land                                                                 (Idx_Atrack, Idx_Xtrack) ;
	    int   Algorithm_Flag_Land                                                               (Idx_Atrack, Idx_Xtrack) ;

	    float Aerosol_Optical_Thickness_550_Ocean                                               (Idx_Atrack, Idx_Xtrack) ;
	    float Aerosol_Optical_Thickness_550_Ocean_Best_Estimate                                 (Idx_Atrack, Idx_Xtrack) ;
	    float Aerosol_Optical_Thickness_550_STDV_Ocean                                          (Idx_Atrack, Idx_Xtrack) ;
	    float Aerosol_Optical_Thickness_550_Expected_Uncertainty_Ocean                          (Idx_Atrack, Idx_Xtrack) ;
	    int   Aerosol_Optical_Thickness_QA_Flag_Ocean                                           (Idx_Atrack, Idx_Xtrack) ;
	    int   Aerosol_Type_Ocean                                                                (Idx_Atrack, Idx_Xtrack) ;
	    int   Algorithm_Flag_Ocean                                                              (Idx_Atrack, Idx_Xtrack) ;

	    float Aerosol_Optical_Thickness_550_Land_Ocean                                          (Idx_Atrack, Idx_Xtrack) ;
	    float Aerosol_Optical_Thickness_550_Land_Ocean_Best_Estimate                            (Idx_Atrack, Idx_Xtrack) ;
	    int   Aerosol_Type_Land_Ocean                                                           (Idx_Atrack, Idx_Xtrack) ;

	    float Angstrom_Exponent_Land                                                            (Idx_Atrack, Idx_Xtrack) ;
	    float Angstrom_Exponent_Land_Best_Estimate                                              (Idx_Atrack, Idx_Xtrack) ;
	    float Angstrom_Exponent_Ocean                                                           (Idx_Atrack, Idx_Xtrack) ;
	    float Angstrom_Exponent_Ocean_Best_Estimate                                             (Idx_Atrack, Idx_Xtrack) ;
	    float Angstrom_Exponent_Land_Ocean                                                      (Idx_Atrack, Idx_Xtrack) ;
	    float Angstrom_Exponent_Land_Ocean_Best_Estimate                                        (Idx_Atrack, Idx_Xtrack) ;

	    float Fine_Mode_Fraction_550_Ocean                                                      (Idx_Atrack, Idx_Xtrack) ;
	    float Fine_Mode_Fraction_550_Ocean_Best_Estimate                                        (Idx_Atrack, Idx_Xtrack) ;

	    float Land_Bands                                                (Land_Bands) ;
	    float Spectral_Aerosol_Optical_Thickness_Land                   (Land_Bands            , Idx_Atrack, Idx_Xtrack) ;
	    float Spectral_Single_Scattering_Albedo_Land                    (Land_Bands            , Idx_Atrack, Idx_Xtrack) ;
	    float Spectral_Surface_Reflectance                              (Land_Bands            , Idx_Atrack, Idx_Xtrack) ;
	    float Ocean_Bands                                               (Ocean_Bands) ;
	    float Spectral_Aerosol_Optical_Thickness_Ocean                  (Ocean_Bands           , Idx_Atrack, Idx_Xtrack) ;
	    float Reflectance_Bands                                                                                         (Reflectance_Bands) ;
	    float Spectral_TOA_Reflectance_Land                                                     (Idx_Atrack, Idx_Xtrack, Reflectance_Bands) ;
	    float Spectral_TOA_Reflectance_Ocean                                                    (Idx_Atrack, Idx_Xtrack, Reflectance_Bands) ;

	    int Number_Of_Pixels_Used_Land                                                          (Idx_Atrack, Idx_Xtrack) ;
	    int Number_Of_Pixels_Used_Ocean                                                         (Idx_Atrack, Idx_Xtrack) ;
	    int Number_Valid_Pixels                                                                 (Idx_Atrack, Idx_Xtrack) ;

	    float Ocean_Sum_Squares                                                                 (Idx_Atrack, Idx_Xtrack) ;
	    float Precipitable_Water                                                                (Idx_Atrack, Idx_Xtrack) ;
	    float Relative_Azimuth_Angle                                                            (Idx_Atrack, Idx_Xtrack) ;
	    float Scattering_Angle                                                                  (Idx_Atrack, Idx_Xtrack) ;
	    float Solar_Zenith_Angle                                                                (Idx_Atrack, Idx_Xtrack) ;
	    float TOA_NDVI                                                                          (Idx_Atrack, Idx_Xtrack) ;
	    float Total_Column_Ozone                                                                (Idx_Atrack, Idx_Xtrack) ;
	    float Unsuitable_Pixel_Fraction_Land_Ocean                                              (Idx_Atrack, Idx_Xtrack) ;
	    float Viewing_Zenith_Angle                                                              (Idx_Atrack, Idx_Xtrack) ;
	    float Wind_Direction                                                                    (Idx_Atrack, Idx_Xtrack) ;
	    float Wind_Speed                                                                        (Idx_Atrack, Idx_Xtrack) ;

The wavelenths are::

   Land_Bands  = 412, 488,      670
   Ocean_Bands =      488, 550, 670, 865, 1240, 1640, 2250



CSO processing
==============

*(See* :ref:`tutorial` *chapter for introduction to CSO scripts and configuration)*

An example configuration of the CSO processing of the VIIRS/AOD data is available via
the following settings:

* `config/VIIRS/viirs-aod.rc <../../../config/VIIRS/viirs-aod.rc>`_

Start the job-tree using::

  ./bin/cso  /config/VIIRS/viirs-aod.rc
  
Selected sub-steps in the processing are described below.



.. Label between '.. _' and ':' ; use :ref:`text <label>` for reference
.. _viirs-aod-inquire:

Inquire VIIRS archives
======================



.. Label between '.. _' and ':' ; use :ref:`text <label>` for reference
.. _viirs-aod-download:

Download VIIRS AOD data
=======================

To be able to download data, an account has to be created on `EarthData Login <https://urs.earthdata.nasa.gov/>`_.
Store the login name and password in the ``~/.netrc`` file in your home directory
(or in a file defined by the ``NETRC`` environment variable) as::

    machine  urs.earthdata.nasa.gov   login your.name@inst.nx  password ********

