cl2nc is an open source command line Python program for converting Vaisala CL51 and CL31 ceilometer dat files to NetCDF.
On the command-line:
cl2nc input.dat output.nc
input.dat is a Vaisala CL51 or CL31 dat file and
output.nc is the name
of a NetCDF output file.
See example.zip for an example input and output.
Supported operating systems:
- Python 2.7 or Python 3
On Windows and macOS Anaconda distribution of Python is recommended. On Linux, use Python which comes with your Linux distribution (either built-in, or installed through a package manager).
The following commands should be run in the Terminal (Linux and macOS)
or Anaconda Prompt (Windows – you can find Anaconda Prompt in the
Start menu). To install with Python 3 instead of Python 2, replace
python3 in the commands below.
To install from the Python Package Index (PyPI):
pip install cl2nc
or to install in the user's home directory
~/.local/bin is in the
PATH environment variable):
pip install cl2nc --user
Alternatively, to install from source, download and unpack the latest
cl2nc archive, or
clone the repository from GitHub
git clone https://github.com/peterkuma/cl2nc.git). In the package
directory, run the following commands:
pip install netCDF4 python setup.py install # or to install in the user's home directory # (make sure `~/.local/bin` is in the `PATH` environment variable): python setup.py install --user
You can also use the Python script
cl2nc directly without installation
(as long as netCDF4 is installed).
Once installed, you should be able to run
cl2nc in the Terminal
(Linux and macOS) or Anaconda Prompt (Windows).
cl2nc [-chq] [--debug] [--help] <input> <output>
<input> is an input
<output> is an output
If directories are supplied for
<input> are converted to
.nc files in
-c: Enable checksum verification (slow).
--debug: Enable debugging output.
--help: Show help message and exit.
-q: Run quietly (suppress output).
A manual page is also available if cl2nc is installed on unix-like operating systems:
Please see Vaisala CL51 User's Guide for a complete description of the variables.
The DAT files can alternatively contain values in feet (instead of meters), in which case all values are converted by cl2nc to meters.
Time in DAT files is assumed to be UTC.
Missing values are encoded as NaN (floating-point variables) or -2147483648
(integer variables). The
_FillValue attribute contains the missing value
used in the given variable.
|backscatter||Attenuated volume backscatter coefficient||km-1.sr-1||time, level|
|cbh_1||Lowest cloud base height||m||time|
|cbh_2||Second lowest cloud base height||m||time|
|cbh_3||Highest cloud base height||m||time|
|sky_detection_status||Sky detection status||time|
|highest_signal||Highest signal detected||time|
|layer_cloud_amount||Layer cloud amount||octas||time, layer|
|layer_height||Layer height||m||time, layer|
|software_level||Software level ID||time|
|time||Time||seconds since 1970-01-01 00:00:00 UTC||time|
|time_utc||Time (UTC)||ISO 8601||time|
|unit||Unit identification character||time|
|window_transmission||Window transmission estimate||%||time|
Background light (mV)
Millivolts at internal ADC input.
Attenuated volume backscatter coefficient (km-1.sr-1)
Backscatter sum (sr-1)
Sum of detected and normalized backscatter (0–0.0999 sr-1).
Lowest cloud base height (m)
Second lowest cloud base height (m)
Highest cloud base height (m)
0– no significant backscatter
1– one cloud base detected
2– two cloud bases detected
3– three cloud bases detected
4– full obscuration determined but no cloud base detected
5– some obscuration detected but determined to be transparent
/– raw data input to algorithm missing or suspect
Sky detection status
- 0-8 – cloud coverage of the first layer in octas
- 9 – vertical visibility
- -1 – data missing, sky condition option not active or ceilometer in standby mode
- 99 – not enough data (after start-up)
Highest signal detected
Laser temperature (°C)
Layer cloud amount (octas)
Sky condition algorithm.
Layer height (m)
Sky condition algorithm.
- 1 – message without sky condition data
- 2 – message with sky condition data
- 6 – 10 m ⨉ 1540 samples, range 15400 m (msg1_10x1540)
- 8 – without a backscatter profile (msg1_base)
Pulse energy (% of nominal factory setting)
L– long (100 ns)
High by default, may be low in fog or heavy snow.
0– self-check OK
W– at least one warning active, no alarms
A– at least one alarm active
Software level ID
- 0x8000 – transmitter shut-off
- 0x4000 – transmitter failure
- 0x2000 – receiver failure
- 0x1000 – voltage failure
- 0x0400 – memory error
- 0x0200 – light path obstruction
- 0x0100 – receiver saturation
- 0x8000 – blower is on
- 0x4000 – blower heater is on
- 0x2000 – internal heater is on
- 0x1000 – working from battery
- 0x0800 – standby mode is on
- 0x0400 – self test in progress
- 0x0200 – manual data acquisition settings are effective
- 0x0080 – units are meters if on, else feet (note that units are always converted to m by cl2nc)
- 0x0040 – manual blower control
- 0x0020 – polling mode is on
- 0x8000 – window contamination
- 0x4000 – battery voltage low
- 0x2000 – transmitter expires
- 0x1000 – high humidity
- 0x0800 – blower failure
- 0x0100 – humidity sensor failure
- 0x0080 – heater fault
- 0x0040 – high background radiance
- 0x0020 – ceilometer engine board failure
- 0x0010 – battery failure
- 0x0008 – laser monitor failure
- 0x0004 – receiver warning
- 0x0002 – tilt angle > 45 degrees warning
Tilt angle (degrees from vertical)
Time (seconds since 1970-01-01 00:00:00 UTC, excluding leap seconds)
Time (UTC) (ISO 8601)
Unit identification character
Vertical resolution (m)
Vertical visibility (m)
Window transmission estimate (%)
90% to 100% means the window is clean.
cl2nc version string. Follows semantic versioning.
Time when the NetCDF file was created (ISO 8601 UTC).
This software is open source and can be used, shared and modified freely under the terms of the MIT License (see LICENSE.md).
cl2nc fails with an exception.
Please make sure you that the Python package netCDF4 is installed. If it still does not work for you contact me: Peter Kuma <firstname.lastname@example.org>. There are small variations in the .DAT file format with instruments. cl2nc may need to be modified to be able to read a particular type of format.
Where is the height information?
Height can be determined from vertical_resolution. The instrument samples vertical bins on regular intervals.
MATLAB cannot read the time_utc variable.
MATLAB NetCDF implementation currently does not support reading NC_STRING
variables. You can use the
time variable instead or use the MATLAB HDF
functions to read the file (you may need to change the file extension to
cl2nc follows semantic versioning.
- Fixed an issue of the last record in DAT files skipped.
- Fixed handling of certain types of time encoding.
- Issue a warning instead of an error when a line cannot be parsed.
- Fixed installation on Windows.
- Added manual page.
- Support for an alternative DAT format with UNIX timestamps.
- Improved error logging.
- New option:
- Support for Python 3.
- Accept directory input and output arguments.
timevariable to contain time offset in seconds since 1970-01-01 00:00:00 UTC.
time_utccontains the original time values (UTC as ISO 8601 strings).
- Fixed parsing on Windows (line endings).
- Added support for a specific CL31 format (timestamp line instead of checksum).
- Fixed writing of NA integer values.
- Fixed scale factor of
- Important: Fixed units conversion for sky condition height data and vertical resolution. In previous versions vertical_resolution is off by a factor of 0.3048 if input file units is ft. layer_height is off by a factor of 100 or 10 if units are ft or m, respectively.
- Added NetCDF file attributes:
- Format time with
Tas delimiter to conform to ISO 8601.
- Improved error handling.