--- a/docs/netcdf_file.rst Mon Feb 06 14:02:20 2017 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,1250 +0,0 @@
-.. _netcdf_file:
-
-The SCC input netCDF file format
-================================
-
-A more detailed version of this document can be found in this :download:`pdf file <files/NetCDF_input_file_v3.pdf>`.
-
-.. note::
-
- You can check the format of the files you create using the linked `script <https://bitbucket.org/iannis_b/scc-netcdf-checker>`_ .
-
-
-Rationale
----------
-
-The Single Calculus Chain (SCC) is composed by three different modules:
-
-- pre-processing module (*ELPP*)
-
-- optical processing module (*ELDA*)
-
-- depolarization calibrator module (*ELDEC*)
-
-To perfom aerosol optical retrievals the SCC needs not only the raw
-lidar data but also a certain number of parameters to use in both
-pre-processing and optical processing stages. The SCC gets these
-parameters looking at two different locations:
-
-- Single Calculus Chain relational database (SCC\_DB)
-
-- Input files
-
-There are some paramenters that can be found only in the input files
-(those ones changing from measurement to measurement), others that can
-be found only in the SCC\_DB and other ones that can be found in both
-these locations. In the last case, if a particular parameter is needed,
-the SCC will search first in the input files and then in SCC\_DB. If the
-parameter is found in the input files, the SCC will keep it without
-looking into SCC\_DB.
-
-The input files have to be submitted to the SCC in NetCDF format. At
-present the SCC can handle four different types of input files:
-
-1. Raw Lidar Data
-
-2. Sounding Data
-
-3. Overlap
-
-4. Lidar Ratio
-
-As already mentioned, the *Raw lidar data* file contains not only the
-raw lidar data but also other parameters to use to perform the
-pre-processing and optical processing. The *Sounding Data* file contains
-the data coming from a correlative radiosounding and it is used by the
-SCC for molecular density calculation. The *Overlap* file contains the
-measured overlap function. The *Lidar Ratio* file contains a lidar ratio
-profile to use in elastic backscatter retrievals. The *Raw Lidar Data*
-file is of course mandatory and the *Sounding Data*, *Overlap* and
-*Lidar Ratio* files are optional. If *Sounding Data* file is not
-submitted by the user, the molecular density will be calculated by the
-SCC using the "US Standard Atmosphere 1976". If the *Overlap* file is
-not submitted by the user, the SCC will get the full overlap height from
-SCC\_DB and it will produce optical results starting from this height.
-If *Lidar Ratio* file is not submitted by the user, the SCC will
-consider a fixed value for lidar ratio got from SCC\_DB.
-
-The user can decide to submit all these files or any number of them (of
-course the file *Raw Lidar Data* is mandatory). For example the user can
-submit together with the *Raw Lidar Data* file only the *Sounding Data*
-file or only the *Overlap* file.
-
-This document provides a detailed example about the structure of
-the NetCDF input files to use for SCC data submission. All Earlinet
-groups should read it carefully because they have to produce such kind
-of input files if they want to use the SCC for their standard lidar
-retrievals.
-
-Additionaly, the linked :download:`pdf file <files/NetCDF_input_file_v3.pdf>` contains
-tables with all mandatory and optional variables for the netcdf files
-accepted by the SCC. Table 1 contains a list of dimensions, variables and
-global attributes that can be used in the NetCDF *Raw Lidar Data*
-input file. For each of them it is indicated:
-
-- The name. For the multidimensional variables also the corresponding
- dimensions are reported
-
-- A description explaining the meaning
-
-- The type
-
-- If it is mandatory or optional
-
-As already mentioned, the SCC can get some parameters looking first in
-the *Raw Lidar Data* input file and then into SCC\_DB. This means that
-to use the parameters stored in SCC\_DB the optional variables or
-optional global attributes must not appear within *Raw Lidar Data* file.
-This is the suggested and recommended way to use the SCC. Please include
-optional parameters in the *Raw Lidar Data* only as an exception.
-
-Tables 2, 3, and 4 report all the
-information about the structure of *Sounding Data*, *Overlap* and *Lidar
-Ratio* input files respectively.
-
-
-Example
--------
-
-Let's now consider an example of *Raw Lidar Data* input file. Suppose
-we want to generate NetCDF input file corresponding to a measurement
-with the following properties:
-
-+----------------------+-------------------------------------------+
-| Start Date | 30\ :sup:`th` January 2009 |
-+----------------------+-------------------------------------------+
-| Start Time UT | 00:00:01 |
-+----------------------+-------------------------------------------+
-| Stop Time UT | 00:05:01 |
-+----------------------+-------------------------------------------+
-| Station Name | Dummy station |
-+----------------------+-------------------------------------------+
-| Earlinet call-sign | cc |
-+----------------------+-------------------------------------------+
-| Pointing angle | 5 degrees with respect to the zenith |
-+----------------------+-------------------------------------------+
-
-
-Moreover suppose that this measurement is composed by the following
-lidar channels:
-
-#. 1064 lidar channel
-
- +------------------------------+-------------------------------+
- | Emission wavelength=1064nm | Detection wavelength=1064nm |
- +------------------------------+-------------------------------+
- | Time resolution=30s | Number of laser shots=1500 |
- +------------------------------+-------------------------------+
- | Number of bins=3000 | Detection mode=analog |
- +------------------------------+-------------------------------+
- | Range resolution=7.5m | Polarization state=total |
- +------------------------------+-------------------------------+
-
-#. 532 cross lidar channel
-
- +-----------------------------+------------------------------------------+
- | Emission wavelength=532nm | Detection wavelength=532nm |
- +-----------------------------+------------------------------------------+
- | Time resolution=60s | Number of laser shots=3000 |
- +-----------------------------+------------------------------------------+
- | Number of bins=5000 | Detection mode=photoncounting |
- +-----------------------------+------------------------------------------+
- | Range resolution=15m | Polarization state=cross (transmitted) |
- +-----------------------------+------------------------------------------+
-
-#. 532 parallel lidar channel
-
- +-----------------------------+-------------------------------------------+
- | Emission wavelength=532nm | Detection wavelength=532nm |
- +-----------------------------+-------------------------------------------+
- | Time resolution=60s | Number of laser shots=3000 |
- +-----------------------------+-------------------------------------------+
- | Number of bins=5000 | Detection mode=photoncounting |
- +-----------------------------+-------------------------------------------+
- | Range resolution=15m | Polarization state=parallel (reflected) |
- +-----------------------------+-------------------------------------------+
-
-#. | 607 :math:`N_2` vibrational Raman channel
-
- +-----------------------------+---------------------------------+
- | Emission wavelength=532nm | Detection wavelength=607nm |
- +-----------------------------+---------------------------------+
- | Time resolution=60s | Number of laser shots=3000 |
- +-----------------------------+---------------------------------+
- | Number of bins=5000 | Detection mode=photoncounting |
- +-----------------------------+---------------------------------+
- | Range resolution=15m | |
- +-----------------------------+---------------------------------+
-
-Finally let's assume we have also performed dark measurements before the
-lidar measurements from the 23:50:01 UT up to 23:53:01 UT of
-29\ :sup:`th` January 2009.
-
-
-Dimensions
-~~~~~~~~~~
-
-Looking at table 1 of the pdf file we have to fix the following dimensions:
-
-::
-
- points
- channels
- time
- nb_of_time_scales
- scan_angles
- time_bck
-
-The dimension ``time`` is unlimited so we don’t have to fix it.
-We have 4 lidar channels so:
-
-::
-
- channels=4
-
-Regarding the dimension ``points`` we have only one channel with a
-number of vertical bins equal to 3000 (the 1064nm) and all other
-channels with 5000 vertical bins. In cases like this the dimension
-``points`` has to be fixed to the maximum number of vertical bins so:
-
-::
-
- points=5000
-
-Moreover only one channel (1064nm) is acquired with a time resolution of
-30 seconds, all the other channels have a time resolution of 60 seconds.
-This means that we have to define two different time scales. We have to
-set:
-
-::
-
- nb_of_time_scales=2
-
-The measurement is performed only at one scan angle (5 degrees with
-respect to the zenith) so:
-
-::
-
- scan_angles=1
-
-We have 3 minutes of dark measurements and two different time scales one
-with 60 seconds time resolution and the other one with 30 seconds time
-resolution. So we will have 3 different dark profiles for the channels
-acquired with the first time scale and 6 for the lidar channels acquired
-with the second time scale. We have to fix the dimension ``time_bck`` as
-the maximum between these values:
-
-::
-
- time_bck=6
-
-
-Variables
-~~~~~~~~~
-
-In this section it will be explained how to fill all the possible
-variables either mandatory or optional of *Raw Lidar Data* input file.
-
-- | ``Raw_Data_Start_Time(time, nb_of_time_scales)``
- | This 2 dimensional mandatory array has to contain the acquisition
- start time (in seconds from the time given by the global attribute
- ``RawData_Start_Time_UT``) of each lidar profile. In this example
- we have two different time scales: one is characterized by steps of
- 30 seconds (the 1064nm is acquired with this time scale) the other
- by steps of 60 seconds (532cross, 532parallel and 607nm). Moreover
- the measurement start time is 00:00:01 UT and the measurement stop
- time is 00:05:01 UT. In this case we have to define:
-
- ::
-
- Raw_Data_Start_Time =
- 0, 0,
- 60, 30,
- 120, 60,
- 180, 90,
- 240, 120,
- _, 150,
- _, 180,
- _, 210,
- _, 240,
- _, 270 ;
-
- The order used to fill this array defines the correspondence between
- the different time scales and the time scale index. In this example
- we have a time scale index of 0 for the time scale with steps of 60
- seconds and a time scale index of 1 for the other one.
-
-- | ``Raw_Data_Stop_Time(time, nb_of_time_scales)``
- | The same as previous item but for the data acquisition stop time.
- Following a similar procedure we have to define:
-
- ::
-
- Raw_Data_Stop_Time =
- 60, 30,
- 120, 60,
- 180, 90,
- 240, 120,
- 300, 150,
- _, 180,
- _, 210,
- _, 240,
- _, 270,
- _, 300 ;
-
-- | ``Raw_Lidar_Data(time, channels, points)``
- | This 3 dimensional mandatory array has to be filled with the
- time-series of raw lidar data. The photoncounting profiles have to
- submitted in counts (so as integers) while the analog ones in mV.
- The order the user chooses to fill this array defines the
- correspondence between channel index and lidar data.
- | For example if we fill this array in such way that:
-
- +-------------------------------------+---------------------------------------+
- | ``Raw_Lidar_Data(time,0,points)`` | is the time-series of 1064 nm |
- +-------------------------------------+---------------------------------------+
- | ``Raw_Lidar_Data(time,1,points)`` | is the time-series of 532 cross |
- +-------------------------------------+---------------------------------------+
- | ``Raw_Lidar_Data(time,2,points)`` | is the time-series of 532 parallel |
- +-------------------------------------+---------------------------------------+
- | ``Raw_Lidar_Data(time,3,points)`` | is the time-series of 607 nm |
- +-------------------------------------+---------------------------------------+
-
- |
- | from now on the channel index 0 is associated to the 1064 channel,
- 1 to the 532 cross, 2 to the 532 parallel and 3 to the 607nm.
-
-- | ``Raw_Bck_Start_Time(time_bck, nb_of_time_scales)``
- | This 2 dimensional optional array has to contain the acquisition
- start time (in seconds from the time given by the global attribute
- ``RawBck_Start_Time_UT``) of each dark measurements profile.
- Following the same procedure used for the variable
- ``Raw_Data_Start_Time`` we have to define:
-
- ::
-
- Raw_Bck_Start_Time =
- 0, 0,
- 60, 30,
- 120, 60,
- _, 90,
- _, 120,
- _, 150;
-
-- | ``Raw_Bck_Stop_Time(time_bck, nb_of_time_scales)``
- | The same as previous item but for the dark acquisition stop time.
- Following a similar procedure we have to define:
-
- ::
-
- Raw_Bck_Stop_Time =
- 60, 30,
- 120, 60,
- 180, 90,
- _, 120,
- _, 150,
- _, 180 ;
-
-- | ``Background_Profile(time_bck, channels, points)``
- | This 3 dimensional optional array has to be filled with the
- time-series of the dark measurements data. The photoncounting
- profiles have to submitted in counts (so as integers) while the
- analog ones in mV. The user has to fill this array following the
- same order used in filling the array ``Raw_Lidar_Data``:
-
- +---------------------------------------------+-------------------------------------+
- | ``Background_Profile(time_bck,0,points)`` | dark time-series at 1064 nm |
- +---------------------------------------------+-------------------------------------+
- | ``Background_Profile(time_bck,1,points)`` | dark time-series at 532 cross |
- +---------------------------------------------+-------------------------------------+
- | ``Background_Profile(time_bck,2,points)`` | dark time-series at 532 parallel |
- +---------------------------------------------+-------------------------------------+
- | ``Background_Profile(time_bck,3,points)`` | dark time-series at 607 nm |
- +---------------------------------------------+-------------------------------------+
-
- |
-
-- | ``channel_ID(channels)``
- | This mandatory array provides the link between the channel index
- within the *Raw Lidar Data* input file and the channel ID in
- SCC\_DB. To fill this variable the user has to know which channel
- IDs in SCC\_DB correspond to his lidar channels. For this purpose
- the SCC, in its final version will provide to the user a special
- tool to get these channel IDs through a Web interface. At the
- moment this interface is not yet available and these channel IDs
- will be communicated directly to the user by the NA5 people.
- | Anyway to continue the example let’s suppose that the four lidar
- channels taken into account are mapped into SCC\_DB with the
- following channel IDs:
-
- +----------------+-----------------+
- | 1064 nm | channel ID=7 |
- +----------------+-----------------+
- | 532 cross | channel ID=5 |
- +----------------+-----------------+
- | 532 parallel | channel ID=6 |
- +----------------+-----------------+
- | 607 nm | channel ID=8 |
- +----------------+-----------------+
-
- |
- | In this case we have to define:
-
- ::
-
- channel_ID = 7, 5, 6, 8 ;
-
-- | ``id_timescale(channels)``
- | This mandatory array is introduced to determine which time scale is
- used for the acquisition of each lidar channel. In particular this
- array defines the link between the channel index and the time scale
- index. In our example we have two different time scales. Filling
- the arrays ``Raw_Data_Start_Time`` and ``Raw_Data_Stop_Time`` we
- have defined a time scale index of 0 for the time scale with steps
- of 60 seconds and a time scale index of 1 for the other one with
- steps of 30 seconds. In this way this array has to be set as:
-
- ::
-
- id_timescale = 1, 0, 0, 0 ;
-
-- | ``Laser_Pointing_Angle(scan_angles)``
- | This mandatory array contains all the scan angles used in the
- measurement. In our example we have only one scan angle of 5
- degrees with respect to the zenith, so we have to define:
-
- ::
-
- Laser_Pointing_Angle = 5 ;
-
-- | ``Laser_Pointing_Angle_of_Profiles(time, nb_of_time_scales)``
- | This mandatory array is introduced to determine which scan angle is
- used for the acquisition of each lidar profile. In particular this
- array defines the link between the time and time scales indexes and
- the scan angle index. In our example we have a single scan angle
- that has to correspond to the scan angle index 0. So this array has
- to be defined as:
-
- ::
-
- Laser_Pointing_Angle_of_Profiles =
- 0, 0,
- 0, 0,
- 0, 0,
- 0, 0,
- 0, 0,
- _, 0,
- _, 0,
- _, 0,
- _, 0,
- _, 0 ;
-
-- | ``Laser_Shots(time, channels)``
- | This mandatory array stores the laser shots accumulated at each
- time for each channel. In our example the number of laser shots
- accumulated is 1500 for the 1064nm channels and 3000 for all the
- other channels. Moreover the laser shots do not change with the
- time. So we have to define this array as:
-
- ::
-
- Laser_Shots =
- 1500, 3000, 3000, 3000,
- 1500, 3000, 3000, 3000,
- 1500, 3000, 3000, 3000,
- 1500, 3000, 3000, 3000,
- 1500, 3000, 3000, 3000,
- 1500, _, _, _,
- 1500, _, _, _,
- 1500, _, _, _,
- 1500, _, _, _,
- 1500, _, _, _ ;
-
-- | ``Emitted_Wavelength(channels)``
- | This optional array defines the link between the channel index and
- the emission wavelength for each lidar channel. The wavelength has
- to be expressed in nm. This information can be also taken from
- SCC\_DB. In our example we have:
-
- ::
-
- Emitted_Wavelength = 1064, 532, 532, 532 ;
-
-- | ``Detected_Wavelength(channels)``
- | This optional array defines the link between the channel index and
- the detected wavelength for each lidar channel. Here detected
- wavelength means the value of center of interferential filter
- expressed in nm. This information can be also taken from SCC\_DB.
- In our example we have:
-
- ::
-
- Detected_Wavelength = 1064, 532, 532, 607 ;
-
-- | ``Raw_Data_Range_Resolution(channels)``
- | This optional array defines the link between the channel index and
- the raw range resolution for each channel. If the scan angle is
- different from zero this quantity is different from the vertical
- resolution. More precisely if :math:`\alpha` is the scan angle used
- and :math:`\Delta z` is the range resolution the vertical
- resolution is calculated as :math:`\Delta
- z'=\Delta z \cos\alpha`. This array has to be filled with
- :math:`\Delta z` and not with :math:`\Delta z'`. The unit is
- meters. This information can be also taken from SCC\_DB. In our
- example we have:
-
- ::
-
- Raw_Data_Range_Resolution = 7.5, 15.0, 15.0, 15.0 ;
-
-- | ``Scattering_Mechanism(channels)``
- | This optional array defines the scattering mechanism involved in
- each lidar channel. In particular the following values are adopted:
-
- +-----+---------------------------------------------------+
- | 0 | Total elastic backscatter |
- +-----+---------------------------------------------------+
- | 1 | N\ :math:`_2` vibrational Raman backscatter |
- +-----+---------------------------------------------------+
- | 2 | Cross polarization elastic backscatter |
- +-----+---------------------------------------------------+
- | 3 | Parallel polarization elastic backscatter |
- +-----+---------------------------------------------------+
- | 4 | H\ :math:`_2`\ O vibrational Raman backscatter |
- +-----+---------------------------------------------------+
- | 5 | Rotational Raman low quantum number |
- +-----+---------------------------------------------------+
- | 6 | Rotational Raman high quantum number |
- +-----+---------------------------------------------------+
-
- |
- | This information can be also taken from SCC\_DB. In our example we
- have:
-
- ::
-
- Scattering_Mechanism = 0, 2, 3, 1 ;
-
-- | ``Signal_Type(channels)``
- | This optional array defines the type of signal involved in each
- lidar channel. In particular the following values are adopted:
-
- +------+--------------------------------------------------------------+
- | 0 | Total elastic |
- +------+--------------------------------------------------------------+
- | 1 | Total elastic near range |
- +------+--------------------------------------------------------------+
- | 2 | Total elastic far range |
- +------+--------------------------------------------------------------+
- | 3 | N\ :math:`_2` vibrational Raman |
- +------+--------------------------------------------------------------+
- | 4 | N\ :math:`_2` vibrational Raman near range |
- +------+--------------------------------------------------------------+
- | 5 | N\ :math:`_2` vibrational Raman far range |
- +------+--------------------------------------------------------------+
- | 6 | Elastic polarization reflected |
- +------+--------------------------------------------------------------+
- | 7 | Elastic polarization transmitted |
- +------+--------------------------------------------------------------+
- | 8 | Rotational Raman line close to elastic line |
- +------+--------------------------------------------------------------+
- | 9 | Rotational Raman line far from elastic line |
- +------+--------------------------------------------------------------+
- | 10 | Elastic polarization reflected near range |
- +------+--------------------------------------------------------------+
- | 11 | Elastic polarization reflected far range |
- +------+--------------------------------------------------------------+
- | 12 | Elastic polarization transmitted near range |
- +------+--------------------------------------------------------------+
- | 13 | Elastic polarization transmitted far range |
- +------+--------------------------------------------------------------+
- | 14 | H\ :math:`_2`\ O vibrational Raman backscatter |
- +------+--------------------------------------------------------------+
- | 15 | Rotational Raman line far from elastic line near range |
- +------+--------------------------------------------------------------+
- | 16 | Rotational Raman line far from elastic line far range |
- +------+--------------------------------------------------------------+
- | 17 | Rotational Raman line close to elastic line near range |
- +------+--------------------------------------------------------------+
- | 18 | Rotational Raman line close to elastic line far range |
- +------+--------------------------------------------------------------+
- | 19 | H\ :math:`_2`\ O vibrational Raman backscatter near range |
- +------+--------------------------------------------------------------+
- | 20 | H\ :math:`_2`\ O vibrational Raman backscatter far range |
- +------+--------------------------------------------------------------+
- | 21 | Total elastic ultra near range |
- +------+--------------------------------------------------------------+
- | 22 | +45 rotated elastic polarization transmitted |
- +------+--------------------------------------------------------------+
- | 23 | +45 rotated elastic polarization reflected |
- +------+--------------------------------------------------------------+
- | 24 | -45 rotated elastic polarization transmitted |
- +------+--------------------------------------------------------------+
- | 25 | -45 rotated elastic polarization reflected |
- +------+--------------------------------------------------------------+
- | 26 | +45 rotated elastic polarization transmitted near range |
- +------+--------------------------------------------------------------+
- | 27 | +45 rotated elastic polarization transmitted far range |
- +------+--------------------------------------------------------------+
- | 28 | +45 rotated elastic polarization reflected near range |
- +------+--------------------------------------------------------------+
- | 29 | +45 rotated elastic polarization reflected far range |
- +------+--------------------------------------------------------------+
- | 30 | -45 rotated elastic polarization transmitted near range |
- +------+--------------------------------------------------------------+
- | 31 | -45 rotated elastic polarization transmitted far range |
- +------+--------------------------------------------------------------+
- | 32 | -45 rotated elastic polarization reflected near range |
- +------+--------------------------------------------------------------+
- | 33 | -45 rotated elastic polarization reflected far range |
- +------+--------------------------------------------------------------+
-
- |
- | This information can be also taken from SCC\_DB. In our example we
- have:
-
- ::
-
- Signal_Type = 0, 7, 6, 3 ;
-
-- | ``Acquisition_Mode(channels)``
- | This optional array defines the acquisition mode (analog or
- photoncounting) involved in each lidar channel. In particular a
- value of 0 means analog mode and 1 photoncounting mode. This
- information can be also taken from SCC\_DB. In our example we have:
-
- ::
-
- Acquisition_Mode = 0, 1, 1, 1 ;
-
-- | ``Laser_Repetition_Rate(channels)``
- | This optional array defines the repetition rate in Hz used to
- acquire each lidar channel. This information can be also taken from
- SCC\_DB. In our example we are supposing we have only one laser
- with a repetition rate of 50 Hz so we have to set:
-
- ::
-
- Laser_Repetition_Rate = 50, 50, 50, 50 ;
-
-- | ``Dead_Time(channels)``
- | This optional array defines the dead time in ns associated to each
- lidar channel. The SCC will use the values given by this array to
- correct the photoncounting signals for dead time. Of course for
- analog signals no dead time correction will be applied (for analog
- channels the corresponding dead time values have to be set to
- undefined value). This information can be also taken from SCC\_DB.
- In our example the 1064 nm channel is acquired in analog mode so
- the corresponding dead time value has to be undefined. If we
- suppose a dead time of 10 ns for all other channels we have to set:
-
- ::
-
- Dead_Time = _, 10, 10, 10 ;
-
-- | ``Dead_Time_Corr_Type(channels)``
- | This optional array defines which kind of dead time correction has
- to be applied on each photoncounting channel. The SCC will correct
- the data supposing a not-paralyzable channel if a value of 0 is
- found while a paralyzable channel is supposed if a value of 1 is
- found. Of course for analog signals no dead time correction will be
- applied and so the corresponding values have to be set to undefined
- value. This information can be also taken from SCC\_DB. In our
- example the 1064 nm channel is acquired in analog mode so the
- corresponding has to be undefined. If we want to consider all the
- photoncounting signals as not-paralyzable ones: we have to set:
-
- ::
-
- Dead_Time_Corr_Type = _, 0, 0, 0 ;
-
-- | ``Trigger_Delay(channels)``
- | This optional array defines the delay (in ns) of the middle of the
- first rangebin with respect to the output laser pulse for each
- lidar channel. The SCC will use the values given by this array to
- correct for trigger delay. This information can be also taken from
- SCC\_DB. Let’s suppose that in our example all the photoncounting
- channels are not affected by this delay and only the analog channel
- at 1064nm is acquired with a delay of 50ns. In this case we have to
- set:
-
- ::
-
- Trigger_Delay = 50, 0, 0, 0 ;
-
-- | ``Background_Mode(channels)``
- | This optional array defines how the atmospheric background has to
- be subtracted from the lidar channel. Two options are available for
- the calculation of atmospheric background:
-
- #. Average in the far field of lidar channel. In this case the value
- of this variable has to be 1
-
- #. Average within pre-trigger bins. In this case the value of this
- variable has to be 0
-
- This information can be also taken from SCC\_DB. Let’s suppose in our
- example we use the pre-trigger for the 1064nm channel and the far
- field for all other channels. In this case we have to set:
-
- ::
-
- Background_Mode = 0, 1, 1, 1 ;
-
-- | ``Background_Low(channels)``
- | This mandatory array defines the minimum altitude (in meters) to
- consider in calculating the atmospheric background for each
- channel. In case pre-trigger mode is used the corresponding value
- has to be set to the rangebin to be used as lower limit (within
- pre-trigger region) for background calculation. In our example, if
- we want to calculate the background between 30000 and 50000 meters
- for all photoncounting channels and we want to use the first 500
- pre-trigger bins for the background calculation for the 1064nm
- channel we have to set:
-
- ::
-
- Background_Low= 0, 30000, 30000, 30000 ;
-
-- | ``Background_High(channels)``
- | This mandatory array defines the maximum altitude (in meters) to
- consider in calculating the atmospheric background for each
- channel. In case pre-trigger mode is used the corresponding value
- has to be set to the rangebin to be used as upper limit (within
- pre-trigger region) for background calculation. In our example, if
- we want to calculate the background between 30000 and 50000 meters
- for all photoncounting channels and we want to use the first 500
- pre-trigger bins for the background calculation for the 1064nm
- channel we have to set:
-
- ::
-
- Background_High = 500, 50000, 50000, 50000 ;
-
-- | ``Molecular_Calc``
- | This mandatory variable defines the way used by SCC to calculate
- the molecular density profile. At the moment two options are
- available:
-
- #. US Standard Atmosphere 1976. In this case the value of this
- variable has to be 0
-
- #. Radiosounding. In this case the value of this variable has to be 1
-
- If we decide to use the option 1. we have to provide also the
- measured pressure and temperature at lidar station level. Indeed if
- we decide to use the option 2. a radiosounding file has to be
- submitted separately in NetCDF format (the structure of this file is
- summarized in table 2 of the pdf file). Let’s suppose we want to use the
- option 1. so:
-
- ::
-
- Molecular_Calc = 0 ;
-
-- | ``Pressure_at_Lidar_Station``
- | Because we have chosen the US Standard Atmosphere for calculation
- of the molecular density profile we have to give the pressure in
- hPa at lidar station level:
-
- ::
-
- Pressure_at_Lidar_Station = 1010 ;
-
-- | ``Temperature_at_Lidar_Station``
- | Because we have chosen the US Standard Atmosphere for calculation
- of the molecular density profile we have to give the temperature in
- C at lidar station level:
-
- ::
-
- Temperature_at_Lidar_Station = 19.8 ;
-
-- | ``LR_Input(channels)``
- | This array is required only for lidar channels for which elastic
- backscatter retrieval has to be performed. It defines the lidar
- ratio to be used within this retrieval. Two options are available:
-
- #. The user can submit a lidar ratio profile. In this case the value
- of this variable has to be 0.
-
- #. A fixed value of lidar ratio can be used. In this case the value
- of this variable has to be 1.
-
- If we decide to use the option 1. a lidar ratio file has to be
- submitted separately in NetCDF format (the structure of this file is
- summarized in table ). If we decide to use the option 2. the
- fixed value of lidar ratio will be taken from SCC\_DB. In our example
- we have to give a value of this array only for the 1064nm lidar
- channel because for the 532nm we will be able to retrieve a Raman
- backscatter coefficient. In case we want to use the fixed value
- stored in SCC\_DB we have to set:
-
- ::
-
- LR_Input = 1,_,_,_ ;
-
-- | ``DAQ_Range(channels)``
- | This array is required only if one or more lidar signals are
- acquired in analog mode. It gives the analog scale in mV used to
- acquire the analog signals. In our example we have only the 1064nm
- channel acquired in analog mode. If we have used a 100mV analog
- scale to acquire this channel we have to set:
-
- ::
-
- DAQ_Range = 100,_,_,_ ;
-
-
-Global attributes
-~~~~~~~~~~~~~~~~~
-
-- | ``Measurement_ID``
- | This mandatory global attribute defines the measurement ID
- corresponding to the actual lidar measurement. It is a string
- composed by 12 characters. The first 8 characters give the start
- date of measurement in the format YYYYMMDD. The next 2 characters
- give the Earlinet call-sign of the station. The last 2 characters
- are used to distinguish between different time-series within the
- same date. In our example we have to set:
-
- ::
-
- Measurement_ID= "20090130cc00" ;
-
-- | ``RawData_Start_Date``
- | This mandatory global attribute defines the start date of lidar
- measurements in the format YYYYMMDD. In our case we have:
-
- ::
-
- RawData_Start_Date = "20090130" ;
-
-- | ``RawData_Start_Time_UT``
- | This mandatory global attribute defines the UT start time of lidar
- measurements in the format HHMMSS. In our case we have:
-
- ::
-
- RawData_Start_Time_UT = "000001" ;
-
-- | ``RawData_Stop_Time_UT``
- | This mandatory global attribute defines the UT stop time of lidar
- measurements in the format HHMMSS. In our case we have:
-
- ::
-
- RawData_Stop_Time_UT = "000501" ;
-
-- | ``RawBck_Start_Date``
- | This optional global attribute defines the start date of dark
- measurements in the format YYYYMMDD. In our case we have:
-
- ::
-
- RawBck_Start_Date = "20090129" ;
-
-- | ``RawBck_Start_Time_UT``
- | This optional global attribute defines the UT start time of dark
- measurements in the format HHMMSS. In our case we have:
-
- ::
-
- RawBck_Start_Time_UT = "235001" ;
-
-- | ``RawBck_Stop_Time_UT``
- | This optional global attribute defines the UT stop time of dark
- measurements in the format HHMMSS. In our case we have:
-
- ::
-
- RawBck_Stop_Time_UT = "235301" ;
-
-
-Example of file (CDL format)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-To summarize we have the following NetCDF *Raw Lidar Data* file (in CDL
-format):
-
-::
-
- dimensions:
- points = 5000 ;
- channels = 4 ;
- time = UNLIMITED ; // (10 currently)
- nb_of_time_scales = 2 ;
- scan_angles = 1 ;
- time_bck = 6 ;
- variables:
- int channel_ID(channels) ;
- int Laser_Repetition_Rate(channels) ;
- double Laser_Pointing_Angle(scan_angles) ;
- int Signal_Type(channels);
- double Emitted_Wavelength(channels) ;
- double Detected_Wavelength(channels) ;
- double Raw_Data_Range_Resolution(channels) ;
- int Background_Mode(channels) ;
- double Background_Low(channels) ;
- double Background_High(channels) ;
- int Molecular_Calc ;
- double Pressure_at_Lidar_Station ;
- double Temperature_at_Lidar_Station ;
- int id_timescale(channels) ;
- double Dead_Time(channels) ;
- int Dead_Time_Corr_Type(channels) ;
- int Acquisition_Mode(channels) ;
- double Trigger_Delay(channels) ;
- int LR_Input(channels) ;
- int Laser_Pointing_Angle_of_Profiles(time, nb_of_time_scales) ;
- int Raw_Data_Start_Time(time, nb_of_time_scales) ;
- int Raw_Data_Stop_Time(time, nb_of_time_scales) ;
- int Raw_Bck_Start_Time(time_bck, nb_of_time_scales) ;
- int Raw_Bck_Stop_Time(time_bck, nb_of_time_scales) ;
- int Laser_Shots(time, channels) ;
- double Raw_Lidar_Data(time, channels, points) ;
- double Background_Profile(time_bck, channels, points) ;
- double DAQ_Range(channels) ;
-
- // global attributes:
- :Measurement_ID = "20090130cc00" ;
- :RawData_Start_Date = "20090130" ;
- :RawData_Start_Time_UT = "000001" ;
- :RawData_Stop_Time_UT = "000501" ;
- :RawBck_Start_Date = "20090129" ;
- :RawBck_Start_Time_UT = "235001" ;
- :RawBck_Stop_Time_UT = "235301" ;
-
- data:
-
- channel_ID = 7, 5, 6, 8 ;
-
- Laser_Repetition_Rate = 50, 50, 50, 50 ;
-
- Laser_Pointing_Angle = 5 ;
-
- Signal_Type = 0, 7, 6, 3 ;
-
- Emitted_Wavelength = 1064, 532, 532, 532 ;
-
- Detected_Wavelength = 1064, 532, 532, 607 ;
-
- Raw_Data_Range_Resolution = 7.5, 15, 15, 15 ;
-
- Background_Mode = 0, 1, 1, 1 ;
-
- Background_Low = 0, 30000, 30000, 30000 ;
-
- Background_High = 500, 50000, 50000, 50000 ;
-
- Molecular_Calc = 0 ;
-
- Pressure_at_Lidar_Station = 1010 ;
-
- Temperature_at_Lidar_Station = 19.8 ;
-
- id_timescale = 1, 0, 0, 0 ;
-
- Dead_Time = _, 10, 10, 10 ;
-
- Dead_Time_Corr_Type = _, 0, 0, 0 ;
-
- Acquisition_Mode = 0, 1, 1, 1 ;
-
- Trigger_Delay = 50, 0, 0, 0 ;
-
- LR_Input = 1,_,_,_ ;
-
- DAQ_Range = 100,_,_,_ ;
-
- Laser_Pointing_Angle_of_Profiles =
- 0, 0,
- 0, 0,
- 0, 0,
- 0, 0,
- 0, 0,
- _, 0,
- _, 0,
- _, 0,
- _, 0,
- _, 0 ;
-
-
- Raw_Data_Start_Time =
- 0, 0,
- 60, 30,
- 120, 60,
- 180, 90,
- 240, 120,
- _, 150,
- _, 180,
- _, 210,
- _, 240,
- _, 270 ;
-
- Raw_Data_Stop_Time =
- 60, 30,
- 120, 60,
- 180, 90,
- 240, 120,
- 300, 150,
- _, 180,
- _, 210,
- _, 240,
- _, 270,
- _, 300 ;
-
-
- Raw_Bck_Start_Time =
- 0, 0,
- 60, 30,
- 120, 60,
- _, 90,
- _, 120,
- _, 150;
-
-
- Raw_Bck_Stop_Time =
- 60, 30,
- 120, 60,
- 180, 90,
- _, 120,
- _, 150,
- _, 180 ;
-
-
- Laser_Shots =
- 1500, 3000, 3000, 3000,
- 1500, 3000, 3000, 3000,
- 1500, 3000, 3000, 3000,
- 1500, 3000, 3000, 3000,
- 1500, 3000, 3000, 3000,
- 1500, _, _, _,
- 1500, _, _, _,
- 1500, _, _, _,
- 1500, _, _, _,
- 1500, _, _, _ ;
-
-
- Raw_Lidar_Data = ...
-
- Background_Profile = ...
-
-The name of the input file should have the following format:
-
-::
-
- Measurement_ID.nc
-
-| so in the example the filename should be 20090130cc00.nc.
-
-Please keep in mind that in case you submit a file like the previous
-one all the parameters present in it will be used by the SCC even if
-you have different values for the same parameters within the SCC\_DB.
-If you want to use the values already stored in SCC\_DB (this should
-be the usual way to use SCC) the *Raw Lidar Data* input file has to be
-modified as follows:
-
-::
-
- dimensions:
- points = 5000 ;
- channels = 4 ;
- time = UNLIMITED ; // (10 currently)
- nb_of_time_scales = 2 ;
- scan_angles = 1 ;
- time_bck = 6 ;
- variables:
- int channel_ID(channels) ;
- double Laser_Pointing_Angle(scan_angles) ;
- double Background_Low(channels) ;
- double Background_High(channels) ;
- int Molecular_Calc ;
- double Pressure_at_Lidar_Station ;
- double Temperature_at_Lidar_Station ;
- int id_timescale(channels) ;
- int Laser_Pointing_Angle_of_Profiles(time, nb_of_time_scales) ;
- int Raw_Data_Start_Time(time, nb_of_time_scales) ;
- int Raw_Data_Stop_Time(time, nb_of_time_scales) ;
- int Raw_Bck_Start_Time(time_bck, nb_of_time_scales) ;
- int Raw_Bck_Stop_Time(time_bck, nb_of_time_scales) ;
- int LR_Input(channels) ;
- int Laser_Shots(time, channels) ;
- double Raw_Lidar_Data(time, channels, points) ;
- double Background_Profile(time_bck, channels, points) ;
- double DAQ_Range(channels) ;
-
- // global attributes:
- :Measurement_ID = "20090130cc00" ;
- :RawData_Start_Date = "20090130" ;
- :RawData_Start_Time_UT = "000001" ;
- :RawData_Stop_Time_UT = "000501" ;
- :RawBck_Start_Date = "20090129" ;
- :RawBck_Start_Time_UT = "235001" ;
- :RawBck_Stop_Time_UT = "235301" ;
-
- data:
-
- channel_ID = 7, 5, 6, 8 ;
-
- Laser_Pointing_Angle = 5 ;
-
- Background_Low = 0, 30000, 30000, 30000 ;
-
- Background_High = 500, 50000, 50000, 50000 ;
-
- Molecular_Calc = 0 ;
-
- Pressure_at_Lidar_Station = 1010 ;
-
- Temperature_at_Lidar_Station = 19.8 ;
-
- id_timescale = 1, 0, 0, 0 ;
-
- LR_Input = 1,_,_,_ ;
-
- DAQ_Range = 100,_,_,_ ;
-
- Laser_Pointing_Angle_of_Profiles =
- 0, 0,
- 0, 0,
- 0, 0,
- 0, 0,
- 0, 0,
- _, 0,
- _, 0,
- _, 0,
- _, 0,
- _, 0 ;
-
-
- Raw_Data_Start_Time =
- 0, 0,
- 60, 30,
- 120, 60,
- 180, 90,
- 240, 120,
- _, 150,
- _, 180,
- _, 210,
- _, 240,
- _, 270 ;
-
- Raw_Data_Stop_Time =
- 60, 30,
- 120, 60,
- 180, 90,
- 240, 120,
- 300, 150,
- _, 180,
- _, 210,
- _, 240,
- _, 270,
- _, 300 ;
-
-
- Raw_Bck_Start_Time =
- 0, 0,
- 60, 30,
- 120, 60,
- _, 90,
- _, 120,
- _, 150;
-
-
- Raw_Bck_Stop_Time =
- 60, 30,
- 120, 60,
- 180, 90,
- _, 120,
- _, 150,
- _, 180 ;
-
-
- Laser_Shots =
- 1500, 3000, 3000, 3000,
- 1500, 3000, 3000, 3000,
- 1500, 3000, 3000, 3000,
- 1500, 3000, 3000, 3000,
- 1500, 3000, 3000, 3000,
- 1500, _, _, _,
- 1500, _, _, _,
- 1500, _, _, _,
- 1500, _, _, _,
- 1500, _, _, _ ;
-
-
- Raw_Lidar_Data = ...
-
- Background_Profile = ...
-
-This example file contains the minimum collection of mandatory
-information that has to be found within the *Raw Lidar Data* input file.
-If it is really necessary, the user can decide to add to these mandatory
-parameters any number of additional parameters considered in the
-previous example.
-
-Finally, suppose we want to make the following changes with respect to
-the previous example:
-
-#. use a sounding file for molecular density calculation instead of “US
- Standar Atmosphere 1976”
-
-#. supply a lidar ratio profile to use in elastic backscatter retrieval
- instead of a fixed value
-
-#. provide a overlap function for overlap correction
-
-In this case we have to generate the following NetCDF additional files:
-
-- | ``rs_20090130cc00.nc``
- | The name of *Sounding Data* file has to be computed as follows:
- | ``"rs_"``\ +\ ``Measurement_ID``
- | The structure of this file is summarized in table 2 of the pdf.
-
-- | ``ov_20090130cc00.nc``
- | The name of *Overlap* file has to be computed as follows:
- | ``"ov_"``\ +\ ``Measurement_ID``
- | The structure of this file is summarized in table 3 of the pdf.
-
-- | ``lr_20090130cc00.nc``
- | The name of *Lidar Ratio* file has to be computed as follows:
- | ``"lr_"``\ +\ ``Measurement_ID``
- | The structure of this file is summarized in table 4 of the pdf.
-
-Moreover we need to apply the following changes to the *Raw Lidar Data*
-input file:
-
-#. Change the value of the variable ``Molecular_Calc`` as follows:
-
- ::
-
- Molecular_Calc = 1 ;
-
- Of course the variables ``Pressure_at_Lidar_Station`` and
- ``Temperature_at_Lidar_Station`` are not necessary anymore.
-
-#. Change the values of the array ``LR_Input`` as follows:
-
- ::
-
- LR_Input = 0,_,_,_ ;
-
-#. Add the global attribute ``Sounding_File_Name``
-
- ::
-
- Sounding_File_Name = "rs_20090130cc00.nc" ;
-
-#. Add the global attribute ``LR_File_Name``
-
- ::
-
- LR_File_Name = "lr_20090130cc00.nc" ;
-
-#. Add the global attribute ``Overlap_File_Name``
-
- ::
-
- Overlap_File_Name = "ov_20090130cc00.nc" ;
-
