.. highlight:: rest

.. _receptor:

Receptor File
=============

The receptor file is a file containing the file names of the stilt footprints, one line per file name.  This file is used
in a number of scripts.  Each file should include the entire directory path and name to the file.

   Example::

      /nfs/footprints/stilt/ctl-na-v1.1/flask/2012/06/stilt2012x06x01x09x16x40.0500Nx105.0040Wx00300.nc
      /nfs/footprints/stilt/ctl-na-v1.1/flask/2012/06/stilt2012x06x01x10x01x37.7553Nx122.4517Wx00232.nc
      /nfs/footprints/stilt/ctl-na-v1.1/flask/2012/06/stilt2012x06x01x12x02x43.9775Nx121.6861Wx00011.nc
      /nfs/footprints/stilt/ctl-na-v1.1/flask/2012/06/stilt2012x06x01x17x33x39.9902Nx105.2627Wx00002.nc
      /nfs/footprints/stilt/ctl-na-v1.1/flask/2012/06/stilt2012x06x01x18x26x40.1581Nx105.0551Wx00002.nc
      /nfs/footprints/stilt/ctl-na-v1.1/flask/2012/06/stilt2012x06x01x18x30x39.7830Nx086.1650Wx00031.nc
      /nfs/footprints/stilt/ctl-na-v1.1/flask/2012/06/stilt2012x06x01x18x30x39.7980Nx086.0180Wx00156.nc
      /nfs/footprints/stilt/ctl-na-v1.1/flask/2012/06/stilt2012x06x01x18x30x39.8947Nx086.2000Wx00139.nc
      /nfs/footprints/stilt/ctl-na-v1.1/flask/2012/06/stilt2012x06x01x18x46x39.6011Nx086.0379Wx00375.nc
      /nfs/footprints/stilt/ctl-na-v1.1/flask/2012/06/stilt2012x06x01x18x49x39.7018Nx085.9860Wx00348.nc
      /nfs/footprints/stilt/ctl-na-v1.1/flask/2012/06/stilt2012x06x01x18x54x39.6672Nx085.9959Wx00402.nc
      /nfs/footprints/stilt/ctl-na-v1.1/flask/2012/06/stilt2012x06x01x19x07x40.1454Nx104.8710Wx00007.nc
      /nfs/footprints/stilt/ctl-na-v1.1/flask/2012/06/stilt2012x06x01x19x12x39.7092Nx086.1428Wx00352.nc
      /nfs/footprints/stilt/ctl-na-v1.1/flask/2012/06/stilt2012x06x01x19x13x40.1453Nx104.8694Wx00006.nc

Receptor File Creation
----------------------

Because of the amount of footprint files available (1,264,306 for version 1.1) and the naming of the footprint files,
it is rather difficult to come up with a receptor file list solely based on the footprint file names.  There are a couple ways
to get around this:

1. Use the corresponding *receptor info* files to get more information about each footprint, and use this information to 
   narrow down the footprint files to use.

2. NOAA has created a :ref:`MySQL database <database>` with additional information for each footprint.  Then mysql queries can be used
   to extract a list of footprint file names to use for the inversion.  

Receptor Info Files
--------------------

These are text files containing information about the receptors.  Each text file covers one month of receptors of a certain type, 
e.g. flask, in-situ continuous, GOSAT, TCCON ...  Each file contains 17 columns of data, delimited by white space.  The columns are:

        * File - filename of the receptor footprint
        * Type - type of measurement corresponding to the footprint. One of 'flask', 'continuous', 'TCCON', 'GOSAT' or 'hatsflask'.
        * SubType - additional type information, describing categories of the location site.  For non TCCON types, the subtypes are

                * 'surface'
                * 'aircraft'
                * 'short-tower'
                * 'building'
                * 'tall-tower'
                * 'hats-flask'

                For TCCON type, the subtypes are 

                * ' tccon_pa_solarnoon '
                * ' tccon_pa_solar2pm  '
                * ' tccon_pa_fixedasza '
                * ' tccon_jc_solarnoon '
                * ' tccon_jc_solar2pm  '
                * ' tccon_jc_fixedasza '
                * ' tccon_oc_solarnoon '
                * ' tccon_oc_solar2pm  '
                * ' tccon_oc_fixedasza '
                * ' tccon_fc_solarnoon '
                * ' tccon_fc_fixedasza '
                * ' tccon_fc_solar2pm  '
                * ' tccon_jf_solarnoon '
                * ' tccon_jf_fixedasza '
                * ' tccon_jf_solar2pm  '
                * ' tccon_if_solarnoon '
                * ' tccon_if_fixedasza '
                * ' tccon_if_solar2pm  '

        * Model - model used to create footprint
        * Date - receptor date
        * Time - receptor time
        * Latitude - receptor latitude
        * Longitude - receptor longitude
        * Alt - altitude used in calculation of footprint
        * Alt_type - type of altitude, either above ground level (agl) or above sea level (asl)
        * Alt_index - Always set to 0 for receptors available via NOAA ftp.
        * Site - NOAA site code assigned to the location.  See :ref:`site codes description <site_codes>`.
        * Surface_Elev - Surface elevation of the site
        * Model_agl - receptor height above model ground level
        * Data_agl -  measurement height above ground level (e.g., tower intake height or aircraft height) If alt_type is 'asl' then data_agl is altitude minus surface elevation. If alt_type is 'agl', the data_agl is same as altitude.
        - Event - id number assigned by NOAA to NOAA flask measurements
        - Operator - Laboratory or agency that is responsible for the measurements at the site