diff -r 7e2ab78dffd9 -r efa2d8e1a2e5 docs/introduction.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/introduction.rst Thu Dec 07 16:54:41 2017 +0200 @@ -0,0 +1,181 @@ +Overview +======== + +This package provides utilities to handle raw (atmospheric) lidar input data. +The main format supported are Licel binary files (including the Raymetrics modified format). + +The package provides a single command line tool, called licel2scc that can convert Licel binary files to the +EARLINET's Single Calculus Chain NetCDF format. + +Installation +------------ + +The easiest way to install this module is from the python package index using ``pip``:: + + pip install atmospheric-lidar + +Using it as a Licel to SCC converter +------------------------------------ + +Parameter file +~~~~~~~~~~~~~~ +Before converting Licel binary to SCC format, you need to create a file linking Licel channels to SCC channels. + +As an example, you can start by changing the file “cf_netcdf_parameters.py” that describe such +parameters for the Clermont Ferrand lidar. + +Command line interface +~~~~~~~~~~~~~~~~~~~~~~ +The usage of the ``licel2scc`` program is described below:: + + A program to convert Licel binary files to the SCC NetCDF format. + + positional arguments: + parameter_file The path to a parameter file linking licel and SCC + channels. + files Location of licel files. Use relative path and + filename wildcards. (default './*.*') + + optional arguments: + -h, --help show this help message and exit + -i, --id_as_name Use transient digitizer ids as channel names, instead + of descriptive names + -m MEASUREMENT_ID, --measurement_id MEASUREMENT_ID + The new measurement id + -n MEASUREMENT_NUMBER, --measurement_number MEASUREMENT_NUMBER + The measurement number for the date from 00 to 99. + Used if no id is provided + -t TEMPERATURE, --temperature TEMPERATURE + The temperature (in C) at lidar level, required if + using US Standard atmosphere + -p PRESSURE, --pressure PRESSURE + The pressure (in hPa) at lidar level, required if + using US Standard atmosphere + -D DARK_FILES, --dark_files DARK_FILES + Location of files containing dark measurements. + Use relative path and filename wildcars, see 'files' + parameter for example. + -d, --debug Print dubuging information. + -s, --silent Show only warning and error messages. + --version Show current version. + +Similarly, the ``licel2scc-depol`` program can be used to convert +Licel files from Delta45 depolarization calibration measurements:: + + A program to convert Licel binary files from depolarization calibration + measurements to the SCC NetCDF format. + + positional arguments: + parameter_file The path to a parameter file linking licel and SCC + channels. + plus45_string Search string for plus 45 degree files (default '*.*') + minus45_string Search string for minus 45 degree files (default + '*.*') + + optional arguments: + -h, --help show this help message and exit + -i, --id_as_name Use transient digitizer ids as channel names, instead + of descriptive names + -m MEASUREMENT_ID, --measurement_id MEASUREMENT_ID + The new measurement id + -n MEASUREMENT_NUMBER, --measurement_number MEASUREMENT_NUMBER + The measurement number for the date from 00 to 99. + Used if no id is provided + -t TEMPERATURE, --temperature TEMPERATURE + The temperature (in C) at lidar level, required if + using US Standard atmosphere + -p PRESSURE, --pressure PRESSURE + The pressure (in hPa) at lidar level, required if + using US Standard atmosphere + -d, --debug Print dubuging information. + -s, --silent Show only warning and error messages. + --version Show current version. + +Usage in python code +-------------------- +System class +~~~~~~~~~~~~ +To read data from a system, you need create a class that describes you system. +This is very simple if your lidar data are in the Licel format, as you only need to specify +the external file with the extra SCC parameters. You can use as an example the file ``cf_netcdf_parameters.py``: + +.. code-block:: python + + from licel import LicelLidarMeasurement + import cf_netcdf_parameters + + class CfLidarMeasurement(LicelLidarMeasurement): + extra_netcdf_parameters = cf_netcdf_parameters + +This code assumes that the ``cf_netcdf_parameters.py`` is in your python path. + +Using the class +~~~~~~~~~~~~~~~ + +Once you have made the above setup you can start using it. The best way to understand how +it works is through an interactive shell (I suggest [ipython](http://ipython.org/)). +In the following example I use the cf_raymetrics setup: + +.. code-block:: python + + import glob # This is needed to read a list of filenames + import cf_lidar + + # Go to the folder where you files are stored + cd /path/to/lidar/files + + # Read the filenames + files = glob.glob("*") # The * reads all the files in the folder. + + # Read the files + my_measurement = cf_lidar.CfLidarMeasurement(files) + + # Now the data have been read, and you have a measurement object to work with: + # See what channels are present + print(my_measurement.channels) + + # Quicklooks of all the channels + my_measurements.plot() + +Converting to SCC format +~~~~~~~~~~~~~~~~~~~~~~~~ + +There are some extra info you need to put in before converting to SCC format, "Measurement_ID", "Temperature", "Pressure": + +.. code-block:: python + + my_measurement.info["Measurement_ID"] = "20101229op00" + my_measurement.info["Temperature"] = "14" + my_measurement.info["Pressure"] = "1010" + +You can use standard values of temperature and pressure by just calling: + +.. code-block:: python + + my_measurement.get_PT() + +You can specify the standard values by overriding your system's ``get_PT`` method: + +.. code-block:: python + + from licel import LicelLidarMeasurement + import cf_netcdf_parameters + + class CfLidarMeasurement(LicelLidarMeasurement): + extra_netcdf_parameters = cf_netcdf_parameters + + def get_PT(): + self.info['Temperature'] = 25.0 + self.info['Pressure'] = 1020.0 + +If you have an external source of temperature and pressure information (a meteorological station) you can automate +this by reading the appropriate code in the ``get_PT`` method . + + +After you have used this extra input, you save the file using this command: + +.. code-block:: python + + my_measurement.save_as_SCC_netcdf("filename") + +where you change the output filename to the filename you want to use. \ No newline at end of file