Mercurial > public > atmospheric_lidar / file comparison

comparison: docs/introduction.rst

docs/introduction.rst

changeset 95
efa2d8e1a2e5
equal deleted inserted replaced
94:7e2ab78dffd9 95:efa2d8e1a2e5
1 Overview
2 ========
3
4 This package provides utilities to handle raw (atmospheric) lidar input data.
5 The main format supported are Licel binary files (including the Raymetrics modified format).
6
7 The package provides a single command line tool, called licel2scc that can convert Licel binary files to the
8 EARLINET's Single Calculus Chain NetCDF format.
9
10 Installation
11 ------------
12
13 The easiest way to install this module is from the python package index using ``pip``::
14
15 pip install atmospheric-lidar
16
17 Using it as a Licel to SCC converter
18 ------------------------------------
19
20 Parameter file
21 ~~~~~~~~~~~~~~
22 Before converting Licel binary to SCC format, you need to create a file linking Licel channels to SCC channels.
23
24 As an example, you can start by changing the file “cf_netcdf_parameters.py” that describe such
25 parameters for the Clermont Ferrand lidar.
26
27 Command line interface
28 ~~~~~~~~~~~~~~~~~~~~~~
29 The usage of the ``licel2scc`` program is described below::
30
31 A program to convert Licel binary files to the SCC NetCDF format.
32
33 positional arguments:
34 parameter_file The path to a parameter file linking licel and SCC
35 channels.
36 files Location of licel files. Use relative path and
37 filename wildcards. (default './*.*')
38
39 optional arguments:
40 -h, --help show this help message and exit
41 -i, --id_as_name Use transient digitizer ids as channel names, instead
42 of descriptive names
43 -m MEASUREMENT_ID, --measurement_id MEASUREMENT_ID
44 The new measurement id
45 -n MEASUREMENT_NUMBER, --measurement_number MEASUREMENT_NUMBER
46 The measurement number for the date from 00 to 99.
47 Used if no id is provided
48 -t TEMPERATURE, --temperature TEMPERATURE
49 The temperature (in C) at lidar level, required if
50 using US Standard atmosphere
51 -p PRESSURE, --pressure PRESSURE
52 The pressure (in hPa) at lidar level, required if
53 using US Standard atmosphere
54 -D DARK_FILES, --dark_files DARK_FILES
55 Location of files containing dark measurements.
56 Use relative path and filename wildcars, see 'files'
57 parameter for example.
58 -d, --debug Print dubuging information.
59 -s, --silent Show only warning and error messages.
60 --version Show current version.
61
62 Similarly, the ``licel2scc-depol`` program can be used to convert
63 Licel files from Delta45 depolarization calibration measurements::
64
65 A program to convert Licel binary files from depolarization calibration
66 measurements to the SCC NetCDF format.
67
68 positional arguments:
69 parameter_file The path to a parameter file linking licel and SCC
70 channels.
71 plus45_string Search string for plus 45 degree files (default '*.*')
72 minus45_string Search string for minus 45 degree files (default
73 '*.*')
74
75 optional arguments:
76 -h, --help show this help message and exit
77 -i, --id_as_name Use transient digitizer ids as channel names, instead
78 of descriptive names
79 -m MEASUREMENT_ID, --measurement_id MEASUREMENT_ID
80 The new measurement id
81 -n MEASUREMENT_NUMBER, --measurement_number MEASUREMENT_NUMBER
82 The measurement number for the date from 00 to 99.
83 Used if no id is provided
84 -t TEMPERATURE, --temperature TEMPERATURE
85 The temperature (in C) at lidar level, required if
86 using US Standard atmosphere
87 -p PRESSURE, --pressure PRESSURE
88 The pressure (in hPa) at lidar level, required if
89 using US Standard atmosphere
90 -d, --debug Print dubuging information.
91 -s, --silent Show only warning and error messages.
92 --version Show current version.
93
94 Usage in python code
95 --------------------
96 System class
97 ~~~~~~~~~~~~
98 To read data from a system, you need create a class that describes you system.
99 This is very simple if your lidar data are in the Licel format, as you only need to specify
100 the external file with the extra SCC parameters. You can use as an example the file ``cf_netcdf_parameters.py``:
101
102 .. code-block:: python
103
104 from licel import LicelLidarMeasurement
105 import cf_netcdf_parameters
106
107 class CfLidarMeasurement(LicelLidarMeasurement):
108 extra_netcdf_parameters = cf_netcdf_parameters
109
110 This code assumes that the ``cf_netcdf_parameters.py`` is in your python path.
111
112 Using the class
113 ~~~~~~~~~~~~~~~
114
115 Once you have made the above setup you can start using it. The best way to understand how
116 it works is through an interactive shell (I suggest [ipython](http://ipython.org/)).
117 In the following example I use the cf_raymetrics setup:
118
119 .. code-block:: python
120
121 import glob # This is needed to read a list of filenames
122 import cf_lidar
123
124 # Go to the folder where you files are stored
125 cd /path/to/lidar/files
126
127 # Read the filenames
128 files = glob.glob("*") # The * reads all the files in the folder.
129
130 # Read the files
131 my_measurement = cf_lidar.CfLidarMeasurement(files)
132
133 # Now the data have been read, and you have a measurement object to work with:
134 # See what channels are present
135 print(my_measurement.channels)
136
137 # Quicklooks of all the channels
138 my_measurements.plot()
139
140 Converting to SCC format
141 ~~~~~~~~~~~~~~~~~~~~~~~~
142
143 There are some extra info you need to put in before converting to SCC format, "Measurement_ID", "Temperature", "Pressure":
144
145 .. code-block:: python
146
147 my_measurement.info["Measurement_ID"] = "20101229op00"
148 my_measurement.info["Temperature"] = "14"
149 my_measurement.info["Pressure"] = "1010"
150
151 You can use standard values of temperature and pressure by just calling:
152
153 .. code-block:: python
154
155 my_measurement.get_PT()
156
157 You can specify the standard values by overriding your system's ``get_PT`` method:
158
159 .. code-block:: python
160
161 from licel import LicelLidarMeasurement
162 import cf_netcdf_parameters
163
164 class CfLidarMeasurement(LicelLidarMeasurement):
165 extra_netcdf_parameters = cf_netcdf_parameters
166
167 def get_PT():
168 self.info['Temperature'] = 25.0
169 self.info['Pressure'] = 1020.0
170
171 If you have an external source of temperature and pressure information (a meteorological station) you can automate
172 this by reading the appropriate code in the ``get_PT`` method .
173
174
175 After you have used this extra input, you save the file using this command:
176
177 .. code-block:: python
178
179 my_measurement.save_as_SCC_netcdf("filename")
180
181 where you change the output filename to the filename you want to use.

EARLINET Repository: Atmospheric Lidar Package

mercurial