# HG changeset patch # User Iannis # Date 1512658481 -7200 # Node ID efa2d8e1a2e539d7c8eb6559001c20fe1860e322 # Parent 7e2ab78dffd900f52673fb04d0ec1705af38176e New documentation files. diff -r 7e2ab78dffd9 -r efa2d8e1a2e5 docs/Makefile --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/Makefile Thu Dec 07 16:54:41 2017 +0200 @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SPHINXPROJ = Atmosphericlidar +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file diff -r 7e2ab78dffd9 -r efa2d8e1a2e5 docs/apidocs.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/apidocs.rst Thu Dec 07 16:54:41 2017 +0200 @@ -0,0 +1,28 @@ +API documentation +================= + + +Generic classes +--------------- +.. automodule:: atmospheric_lidar.generic + :members: + + +Licel-specific classes +---------------------- +.. automodule:: atmospheric_lidar.licel + :members: + + +Scripts +------- + +licel2scc +~~~~~~~~~ +.. automodule:: atmospheric_lidar.scripts.licel2scc + :members: + +licel2scc_depol +~~~~~~~~~~~~~~~ +.. automodule:: atmospheric_lidar.scripts.licel2scc_depol + :members: diff -r 7e2ab78dffd9 -r efa2d8e1a2e5 docs/conf.py --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/conf.py Thu Dec 07 16:54:41 2017 +0200 @@ -0,0 +1,196 @@ +# -*- coding: utf-8 -*- +# +# Atmospheric lidar documentation build configuration file, created by +# sphinx-quickstart on Thu Dec 7 15:45:39 2017. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +import os +import sys +sys.path.insert(0, os.path.abspath('../')) + + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = ['sphinx.ext.autodoc', + 'sphinx.ext.intersphinx', + 'sphinx.ext.todo', + 'sphinx.ext.mathjax', + 'sphinx.ext.viewcode'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'Atmospheric lidar' +copyright = u'2017, Ioannis Binietoglou, Victor Nicolae' +author = u'Ioannis Binietoglou, Victor Nicolae' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = u'0.2.11' +# The full version, including alpha/beta/rc tags. +release = u'0.2.11' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This patterns also effect to html_static_path and html_extra_path +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = True + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'alabaster' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# This is required for the alabaster theme +# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars +html_sidebars = { + '**': [ + 'relations.html', # needs 'show_related': True theme option to display + 'searchbox.html', + ] +} + + +# -- Options for HTMLHelp output ------------------------------------------ + +# Output file base name for HTML help builder. +htmlhelp_basename = 'Atmosphericlidardoc' + + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'Atmosphericlidar.tex', u'Atmospheric lidar Documentation', + u'Ioannis Binietoglou, Victor Nicolae', 'manual'), +] + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'atmosphericlidar', u'Atmospheric lidar Documentation', + [author], 1) +] + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'Atmosphericlidar', u'Atmospheric lidar Documentation', + author, 'Atmosphericlidar', 'One line description of project.', + 'Miscellaneous'), +] + + + +# -- Options for Epub output ---------------------------------------------- + +# Bibliographic Dublin Core info. +epub_title = project +epub_author = author +epub_publisher = author +epub_copyright = copyright + +# The unique identifier of the text. This can be a ISBN number +# or the project homepage. +# +# epub_identifier = '' + +# A unique identification for the text. +# +# epub_uid = '' + +# A list of files that should not be packed into the epub file. +epub_exclude_files = ['search.html'] + + + +# Example configuration for intersphinx: refer to the Python standard library. +intersphinx_mapping = {'https://docs.python.org/': None} diff -r 7e2ab78dffd9 -r efa2d8e1a2e5 docs/index.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/index.rst Thu Dec 07 16:54:41 2017 +0200 @@ -0,0 +1,23 @@ +.. Atmospheric lidar documentation master file, created by + sphinx-quickstart on Thu Dec 7 15:45:39 2017. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to Atmospheric lidar's documentation! +============================================= + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + introduction + apidocs + + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` 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 diff -r 7e2ab78dffd9 -r efa2d8e1a2e5 docs/make.bat --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/make.bat Thu Dec 07 16:54:41 2017 +0200 @@ -0,0 +1,36 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build +set SPHINXPROJ=Atmosphericlidar + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% + +:end +popd