--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/file_formats/hirelpp_product_format.rst Fri Mar 19 13:43:18 2021 +0100
@@ -0,0 +1,635 @@
+HiRELPP Products
+----------------
+
+This section describe the structure of HiRELPP products.
+
+
+HiRELPP Products: dimensions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following dimensions are defined in HiRELPP products:
+
+- time
+- level
+- channel
+- depolarization
+- angle
+- nv
+- nc
+
+The dimension *time* (mandatory) specifies the number of RCS (for each channel)
+composing all the pre-processed time-series reported in the products.
+
+The dimension *level* (mandatory) represents the number of rangebins characterizing
+the pre-processed RCS.
+
+The dimension *channel* (mandatory) indicates the number channels at which the RCS
+time-series included in the product refer to.
+
+The dimension *depolarization* (optional) indicates how many volume depolarization time-series are included in the products.
+
+The dimension *angle* (mandatory) takes into account how many zenith scan angles have been used to measure the RCS time-series reported into the products.
+
+The dimension *nv* (mandatory) is ancillary and it is always set to 2.
+
+The dimension *nc* (optional) is ancillary and provides the number of channels involved in the calculation of RCS or volume depolarization time-series.
+
+
+HiRELPP Products: variables
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+latitude
+ :Type: *double*
+ :Dimensions: --
+ :Variable\_Type: Mandatory
+ :Description: measurement site latitude
+ :Units: degrees_north
+ :Definition: *double latitude*
+
+longitude
+ :Type: *double*
+ :Dimensions: --
+ :Variable\_Type: Mandatory
+ :Description: measurement site longitude
+ :Units: degrees_east
+ :Definition: *double longitude*
+
+station\_altitude
+ :Type: *double*
+ :Dimensions: --
+ :Variable\_Type: Mandatory
+ :Description: station altitude above see level
+ :Units: m
+ :Definition: *double station\_altitude*
+
+altitude
+ :Type: *double*
+ :Dimensions: *time, level*
+ :Variable\_Type: Mandatory
+ :Description: altitude above see level
+ :Units: m
+ :Definition: *double altitude(time, level)*
+
+range
+ :Type: *double*
+ :Dimensions: *level*
+ :Variable\_Type: Mandatory
+ :Description: lidar range scale
+ :Units: m
+ :Definition: *double range(level)*
+
+laser\_pointing\_angle
+ :Type: *double*
+ :Dimensions: *angle*
+ :Variable\_Type: Mandatory
+ :Description: laser pointing angle with respect to the zenith
+ :Units: degrees
+ :Definition: *double laser\_pointing\_angle(angle)*
+
+laser\_pointing\_angle\_of\_profile
+ :Type: *int*
+ :Dimensions: *angle*
+ :Variable\_Type: Mandatory
+ :Description: index of scan angle at which each single raw profile has been detected
+ :Units: --
+ :Definition: *int laser\_pointing\_angle\_of\_profile(angle)*
+
+shots
+ :Type: *int*
+ :Dimensions: *time*
+ :Variable\_Type: Mandatory
+ :Description: accumulated laser shots
+ :Units: --
+ :Definition: *int shots(time)*
+
+time
+ :Type: *double*
+ :Dimensions: *time*
+ :Variable\_Type: Mandatory
+ :Description: seconds since 1970-01-01T00:00:00Z
+ :Units: --
+ :Definition: *double time(time)*
+
+time\_bounds
+ :Type: *double*
+ :Dimensions: *time, nv*
+ :Variable\_Type: Mandatory
+ :Description: seconds since 1970-01-01T00:00:00Z
+ :Units: --
+ :Definition: *double time\_bounds(time,nv)*
+
+scc\_product\_type
+ :Type: *byte*
+ :Dimensions: --
+ :Variable\_Type: Mandatory
+ :Description: Bitmask describing the SCC product type
+ :Units: --
+ :Definition: *byte scc\_product\_type*
+
+
+
+
+range\_corrected\_signal\_channel\_id
+ :Type: *int*
+ :Dimensions: *channel, nc*
+ :Variable\_Type: Optional
+ :Description: SCC channel ID list involved in the calculation of the range corrected signal total timeseries
+ :Units: --
+ :Definition: *int range\_corrected\_signal\_channel\_id(channel, nc)*
+
+
+range\_corrected\_signal\_channel\_name
+ :Type: *string*
+ :Dimensions: *channel*
+ :Variable\_Type: Mandatory
+ :Description: Channel name for the range corrected signal timeseries
+ :Units: --
+ :Definition: *string range\_corrected\_signal\_channel\_name(channel)*
+
+
+range\_corrected\_signal\_emission\_wavelength
+ :Type: *double*
+ :Dimensions: *channel*
+ :Variable\_Type: Mandatory
+ :Description: Emission wavelength used to measure the range corrected signal timeseries
+ :Units: *nm*
+ :Definition: *double range\_corrected\_signal\_emission\_wavelength(channel)*
+
+
+range\_corrected\_signal\_detection\_wavelength
+ :Type: *double*
+ :Dimensions: *channel*
+ :Variable\_Type: Mandatory
+ :Description: Detection wavelength used to measure the range corrected signal timeseries
+ :Units: *nm*
+ :Definition: *double range\_corrected\_signal\_detection\_wavelength(channel)*
+
+
+range\_corrected\_signal\_range
+ :Type: *byte*
+ :Dimensions: *channel*
+ :Variable\_Type: Mandatory
+ :Description: Bitmask to identify range corrected signal range type
+ :Units: --
+ :Definition: *byte range\_corrected\_signal\_range(channel)*
+
+
+
+
+range\_corrected\_signal\_scatterers
+ :Type: *byte*
+ :Dimensions: *channel*
+ :Variable\_Type: Mandatory
+ :Description: Bitmask to identify range corrected signal scatterer type
+ :Units: --
+ :Definition: *byte range\_corrected\_signal\_scatterers(channel)*
+
+
+
+
+
+range\_corrected\_signal\_detection\_mode
+ :Type: *byte*
+ :Dimensions: *channel*
+ :Variable\_Type: Mandatory
+ :Description: Bitmask to identify range corrected signal detection mode
+ :Units: --
+ :Definition: *byte range\_corrected\_signal\_detection\_mode(channel)*
+
+
+near\_range\_glueing\_region\_minimum
+ :Type: *double*
+ :Dimensions: *channel, time*
+ :Variable\_Type: Optional
+ :Description: Mininum altitude of glueing region for the near range and far range signals
+ :Units: *m*
+ :Definition: *double near\_range\_glueing\_region\_minimum(channel, time)*
+
+near\_range\_glueing\_region\_maximum
+ :Type: *double*
+ :Dimensions: *channel, time*
+ :Variable\_Type: Optional
+ :Description: Mininum altitude of glueing region for the near range and far range signals
+ :Units: *m*
+ :Definition: *double near_range_glueing_region_maximum(channel, time)*
+
+ultra\_near\_range\_glueing\_region\_minimum
+ :Type: *double*
+ :Dimensions: *channel, time*
+ :Variable\_Type: Optional
+ :Description: Mininum altitude of glueing region for the ultra near range and near range signals
+ :Units: *m*
+ :Definition: *double ultra\_near\_range\_glueing\_region\_minimum(channel, time)*
+
+ultra\_near\_range\_glueing\_region\_maximum
+ :Type: *double*
+ :Dimensions: *channel, time*
+ :Variable\_Type: Optional
+ :Description: Maximum altitude of glueing region for the ultra near range and near range signals
+ :Units: *m*
+ :Definition: *double ultra\_near_range_glueing_region_maximum(channel, time)*
+
+
+range\_corrected\_signal
+ :Type: *double*
+ :Dimensions: *channel, time, level*
+ :Variable\_Type: Mandatory
+ :Description: Range corrected signal timeseries
+ :Units: --
+ :Definition: *double range\_corrected\_signal(channel, time, level)*
+
+range\_corrected\_signal\_statistical\_error
+ :Type: *double*
+ :Dimensions: *channel, time, level*
+ :Variable\_Type: Mandatory
+ :Description: Statistical error (uncertainty) on range corrected signal timeseries
+ :Units: --
+ :Definition: *double range\_corrected\_signal\_statistical\_error(channel, time, level)*
+
+
+range\_corrected\_signal\_systematic\_error
+ :Type: *double*
+ :Dimensions: *channel, time, level*
+ :Variable\_Type: Optional
+ :Description: Systematic error (uncertainty) on range corrected signal timeseries
+ :Units: --
+ :Definition: *double range\_corrected\_signal\_statistical\_error(channel, time, level)*
+
+
+
+atmospheric\_background
+ :Type: *double*
+ :Dimensions: *channel, time*
+ :Variable\_Type: Mandatory
+ :Description: Mean uncalibrated atmospheric background calculated from lidar signal
+ :Units: --
+ :Definition: *double atmospheric\_background(channel, time)*
+
+atmospheric\_background\_stdev
+ :Type: *double*
+ :Dimensions: *channel, time*
+ :Variable\_Type: Mandatory
+ :Description: Standard deviation of uncalibrated atmospheric background calculated from lidar signal
+ :Units: --
+ :Definition: *double atmospheric\_background\_stdev(channel, time)*
+
+atmospheric\_background\_sterr
+ :Type: *double*
+ :Dimensions: *channel, time*
+ :Variable\_Type: Mandatory
+ :Description: Standard error of uncalibrated atmospheric background calculated from lidar signal
+ :Units: --
+ :Definition: *double atmospheric\_background\_sterr(channel, time)*
+
+atmospheric\_background\_min
+ :Type: *double*
+ :Dimensions: *channel, time*
+ :Variable\_Type: Mandatory
+ :Description: Minimum uncalibrated atmospheric background calculated from lidar signal
+ :Units: --
+ :Definition: *double atmospheric\_background\_min(channel, time)*
+
+atmospheric\_background\_max
+ :Type: *double*
+ :Dimensions: *channel, time*
+ :Variable\_Type: Mandatory
+ :Description: Maximum uncalibrated atmospheric background calculated from lidar signal
+ :Units: --
+ :Definition: *double atmospheric\_background\_max(channel, time)*
+
+polarization\_gain\_factor\_measurementid
+ :Type: *string*
+ :Dimensions: *depolarization*
+ :Variable\_Type: Optional
+ :Description: Measurement ID corresponding to the polarization measurements used to calibrate polarization channels
+ :Units: --
+ :Definition: *string polarization\_gain\_factor\_measurementid(depolarization)*
+
+polarization\_gain\_factor
+ :Type: *double*
+ :Dimensions: *depolarization*
+ :Variable\_Type: Optional
+ :Description: Reflected to transmitted polarization channel gain factor (eta*)
+ :Units: --
+ :Definition: *double polarization\_gain\_factor(depolarization)*
+
+polarization\_gain\_factor\_statistical\_error
+ :Type: *double*
+ :Dimensions: *depolarization*
+ :Variable\_Type: Optional
+ :Description: Statistical error (uncertainty) on reflected to transmitted polarization channel gain factor
+ :Units: --
+ :Definition: *double polarization\_gain\_factor\_statistical\_error(depolarization)*
+
+polarization\_gain\_factor\_systematic\_error
+ :Type: *double*
+ :Dimensions: *depolarization*
+ :Variable\_Type: Optional
+ :Description: Systamatic error (uncertainty) on reflected to transmitted polarization channel gain factor
+ :Units: --
+ :Definition: *double polarization\_gain\_factor\_systematic\_error(depolarization)*
+
+
+polarization\_gain\_factor\_start\_datetime
+ :Type: *double*
+ :Dimensions: *depolarization*
+ :Variable\_Type: Optional
+ :Description: Polarization gain factor measurement start datetime
+ :Units: seconds since 1970-01-01T00:00:00Z
+ :Definition: *double polarization\_gain\_factor\_start\_datetime(depolarization)*
+
+polarization\_gain\_factor\_stop\_datetime
+ :Type: *double*
+ :Dimensions: *depolarization*
+ :Variable\_Type: Optional
+ :Description: Polarization gain factor measurement stop datetime
+ :Units: seconds since 1970-01-01T00:00:00Z
+ :Definition: *double polarization\_gain\_factor\_stop\_datetime(depolarization)*
+
+
+polarization\_gain\_factor\_correction
+ :Type: *double*
+ :Dimensions: *depolarization*
+ :Variable\_Type: Optional
+ :Description: Reflected to transmitted polarization channel gain correction factor (K)
+ :Units: --
+ :Definition: *double polarization\_gain\_factor\_correction(depolarization)*
+
+polarization\_gain\_factor\_correction\_statistical\_error
+ :Type: *double*
+ :Dimensions: *depolarization*
+ :Variable\_Type: Optional
+ :Description: Statistical error (uncertainty) on reflected to transmitted polarization channel gain correction factor
+ :Units: --
+ :Definition: *double polarization\_gain\_factor\_correction\_statistical_error(depolarization)*
+
+polarization\_gain\_factor\_correction\_systematic\_error
+ :Type: *double*
+ :Dimensions: *depolarization*
+ :Variable\_Type: Optional
+ :Description: Systamatic error (uncertainty) on reflected to transmitted polarization channel gain correction factor
+ :Units: --
+ :Definition: *double polarization\_gain\_factor\_correction\_systematic\_error(depolarization)*
+
+
+polarization\_gain\_factor\_correction\_start\_datetime
+ :Type: *double*
+ :Dimensions: *depolarization*
+ :Variable\_Type: Optional
+ :Description: Polarization gain corrrection factor measurement start datetime
+ :Units: seconds since 1970-01-01T00:00:00Z
+ :Definition: *double polarization\_gain\_factor\_correction\_start\_datetime(depolarization)*
+
+polarization\_gain\_factor\_correction\_stop\_datetime
+ :Type: *double*
+ :Dimensions: *depolarization*
+ :Variable\_Type: Optional
+ :Description: Polarization gain correction factor measurement stop datetime
+ :Units: seconds since 1970-01-01T00:00:00Z
+ :Definition: *double polarization\_gain\_factor\_correction\_stop\_datetime(depolarization)*
+
+
+volume\_linear\_depolarization\_ratio\_channel\_id
+ :Type: *int*
+ :Dimensions: *depolarization, nc*
+ :Variable\_Type: Optional
+ :Description: SCC channel ID list involved in the calculation of the volume linear depolarization ratio timeseries
+ :Units: --
+ :Definition: *int volume\_linear\_depolarization\_ratio\_channel\_id(depolarization, nc)*
+
+
+volume\_linear\_depolarization\_ratio\_channel\_name
+ :Type: *string*
+ :Dimensions: *depolarization*
+ :Variable\_Type: Optional
+ :Description: Channel name for volume linear depolarization ration timeseries
+ :Units: --
+ :Definition: *string volume\_linear\_depolarization\_ratio\_channel\_name(depolarization)*
+
+
+volume\_linear\_depolarization\_ratio\_wavelength
+ :Type: *double*
+ :Dimensions: *depolarization*
+ :Variable\_Type: Optional
+ :Description: Wavelength at which the volume linear depolarization ratio is calculated
+ :Units: *nm*
+ :Definition: *double volume\_linear\_depolarization\_ratio\_wavelength(depolarization)*
+
+
+volume\_linear\_depolarization\_ratio\_range
+ :Type: *byte*
+ :Dimensions: *depolarization*
+ :Variable\_Type: Optional
+ :Description: Bitmask field indicating the volume linear depolarization range type
+ :Units: --
+ :Definition: *byte volume\_linear\_depolarization\_ratio\_range(depolarization)*
+
+
+
+volume\_linear\_depolarization\_ratio\_scatterers
+ :Type: *byte*
+ :Dimensions: *depolarization*
+ :Variable\_Type: Optional
+ :Description: Bitmask field indicating the volume linear depolarization scatteter type
+ :Units: --
+ :Definition: *byte volume\_linear\_depolarization\_ratio\_scatterers(depolarization)*
+
+
+volume\_linear\_depolarization\_ratio
+ :Type: *double*
+ :Dimensions: *depolarization, time, level*
+ :Variable\_Type: Optional
+ :Description: Volume linear depolarization ratio timeseries
+ :Units: --
+ :Definition: *double volume\_linear\_depolarization\_ratio(depolarization, time, level)*
+
+volume\_linear\_depolarization\_ratio\_statistical\_error
+ :Type: *double*
+ :Dimensions: *depolarization, time, level*
+ :Variable\_Type: Optional
+ :Description: Statistical error (uncertanity) on volume linear depolarization ratio timeseries
+ :Units: --
+ :Definition: *double volume\_linear\_depolarization\_ratio\_statistical\_error(depolarization, time, level)*
+
+volume\_linear\_depolarization\_ratio\_systematic\_error
+ :Type: *double*
+ :Dimensions: *depolarization, time, level*
+ :Variable\_Type: Optional
+ :Description: Systematic error (uncertanity) on volume linear depolarization ratio timeseries
+ :Units: --
+ :Definition: *double volume\_linear\_depolarization\_ratio\_systematic\_error(depolarization, time, level)*
+
+
+HiRELPP Products: global attributes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Conventions
+ :Type: *string*
+ :Global\_Attribute\_Type: Mandatory
+ :Description: List of the conventions the product is compliant to
+
+
+title
+ :Type: *string*
+ :Global\_Attribute\_Type: Mandatory
+ :Description: Product title
+
+source
+ :Type: *string*
+ :Global\_Attribute\_Type: Mandatory
+ :Description: String describing the source used to generate the product
+
+references
+ :Type: *string*
+ :Global\_Attribute\_Type: Mandatory
+ :Description: Reference(s) for data processing
+location
+ :Type: *string*
+ :Global\_Attribute\_Type: Mandatory
+ :Description: Measurement site location
+
+station_ID
+ :Type: *string*
+ :Global\_Attribute\_Type: Mandatory
+ :Description: Unique 3 digit code identifying SCC station
+
+PI
+ :Type: *string*
+ :Global\_Attribute\_Type: Mandatory
+ :Description: PI full name
+
+PI\_affiliation
+ :Type: *string*
+ :Global\_Attribute\_Type: Mandatory
+ :Description: PI complete affiliation
+
+PI\_affiliation_acronym
+ :Type: *string*
+ :Global\_Attribute\_Type: Mandatory
+ :Description: PI affiliation acronym
+
+PI\_address
+ :Type: *string*
+ :Global\_Attribute\_Type: Optional
+ :Description: PI address
+
+PI\_phone
+ :Type: *string*
+ :Global\_Attribute\_Type: Optional
+ :Description: PI phone number
+
+PI\_email
+ :Type: *string*
+ :Global\_Attribute\_Type: Mandatory
+ :Description: PI e-mail
+
+Data\_Originator
+ :Type: *string*
+ :Global\_Attribute\_Type: Mandatory
+ :Description: Data originator full name
+
+Data\_Originator\_affiliation
+ :Type: *string*
+ :Global\_Attribute\_Type: Mandatory
+ :Description: Data originator complete affiliation
+
+Data\_Originator\_affiliation\_acronym
+ :Type: *string*
+ :Global\_Attribute\_Type: Mandatory
+ :Description: Data originator affiliation acronym
+
+Data\_Originator\_address
+ :Type: *string*
+ :Global\_Attribute\_Type: Optional
+ :Description: Data originator complete address
+
+Data\_Originator\_phone
+ :Type: *string*
+ :Global\_Attribute\_Type: Optional
+ :Description: Data originator phone number
+
+Data\_Originator\_email
+ :Type: *string*
+ :Global\_Attribute\_Type: Mandatory
+ :Description: Data originator e-mail address
+
+institution
+ :Type: *string*
+ :Global\_Attribute\_Type: Mandatory
+ :Description: Istitution the product belong to
+
+system
+ :Type: *string*
+ :Global\_Attribute\_Type: Mandatory
+ :Description: Name of the measuring instrument (lidar)
+
+hoi\_system\_ID
+ :Type: *int*
+ :Global\_Attribute\_Type: Mandatory
+ :Description: Numeric ID identifying the measuring system in the ACTRIS/EARLINET Handbook Of Instrument (HOI)
+
+hoi\_configuration\_ID;
+ :Type: *int*
+ :Global\_Attribute\_Type: Mandatory
+ :Description: Numeric ID identifying the configuration of the measuring system in the ACTRIS/EARLINET Handbook Of Instrument (HOI)
+
+measurement\_ID;
+ :Type: *string*
+ :Global\_Attribute\_Type: Mandatory
+ :Description: Alphanumeric identifier for the raw data measurements use to generate the product
+
+measurement\_start\_datetime
+ :Type: *string*
+ :Global\_Attribute\_Type: Mandatory
+ :Description: Measurement start datetime YYYY-mm-ddTHH:MM:SSZ
+
+measurement\_stop\_datetime
+ :Type: *string*
+ :Global\_Attribute\_Type: Mandatory
+ :Description: Measruement stop datetime YYYY-mm-ddTHH:MM:SSZ
+
+comment
+ :Type: *string*
+ :Global\_Attribute\_Type: Optional
+ :Description: Any product comments
+
+scc\_version\_description
+ :Type: *string*
+ :Global\_Attribute\_Type: Mandatory
+ :Description: Extended SCC version description
+
+scc\_version
+ :Type: *string*
+ :Global\_Attribute\_Type: Mandatory
+ :Description: SCC version number
+
+processor\_name
+ :Type: *string*
+ :Global\_Attribute\_Type: Mandatory
+ :Description: Name of the processor used to generate the product
+
+processor\_version
+ :Type: *string*
+ :Global\_Attribute\_Type: Mandatory
+ :Description: Version of the processor used to generate the product
+
+history
+ :Type: *string*
+ :Global\_Attribute\_Type: Mandatory
+ :Description: Field describing the history of the product
+
+\_\_file\_format_version
+ :Type: *string*
+ :Global\_Attribute\_Type: Mandatory
+ :Description: Version of the product file format
+
+data\_processing\_institution
+ :Type: *string*
+ :Global\_Attribute\_Type: Mandatory
+ :Description: Instituion responsible for data processing
+
+input\_file
+ :Type: *string*
+ :Global\_Attribute\_Type: Mandatory
+ :Description: Filename of the input data product used to generate the current product
+
