Add support for HIS L2 format

New release v3.5.0

LICENSE.md

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2017–2023 Peter Kuma
+Copyright (c) 2017–2024 Peter Kuma
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,7 +1,7 @@
 # cl2nc
 
 cl2nc is an open source command line Python program for converting Vaisala
-CL51 and CL31 ceilometer dat files to NetCDF.
+CL51 and CL31 ceilometer DAT and HIS L2 files to NetCDF.
 
 ## Example
 
@@ -11,7 +11,7 @@ On the command-line:
 cl2nc input.dat output.nc
 ```
 
-where `input.dat` is a Vaisala CL51 or CL31 dat file and `output.nc` is the name
+where `input.dat` is a Vaisala CL51 or CL31 DAT file and `output.nc` is the name
 of a NetCDF output file.
 
 See [example.zip](example.zip) for an example input and output.
@@ -110,13 +110,13 @@ Synopsis:
 `cl2nc` [`-chq`] [`--debug`] *input* *output* \
 `cl2nc` `-h`|`--help`
 
-*input* is an input `.dat` file. *output* is an output `.nc` file.  If
-directories are supplied for *input* and *output*, all `.dat` and `.DAT` files
-in *input* are converted to `.nc` files in *output*.
+*input* is an input `.dat` or `.his` (L2) file. *output* is an output `.nc` file.
+If directories are supplied for *input* and *output*, all `.dat`, `.DAT`, `.his`
+and `.HIS` files in *input* are converted to `.nc` files in *output*.
 
 Options:
 
-- `-c`: Enable checksum verification (slow).
+- `-c`: Enable DAT checksum verification (slow).
 - `--debug`: Enable debugging output.
 - `-h`, `--help`: Show help message and exit.
 - `-q`: Run quietly (suppress output).
@@ -135,12 +135,14 @@ 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.
+Time in DAT and HIS 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.
 
+DAT files produce the following NetCDF output:
+
 | Variable | Description | Units | Dimensions |
 | --- | --- | --- | --- |
 | [background_light](#background_light) | Background light | mV | time |
@@ -177,6 +179,17 @@ used in the given variable.
 | [vertical_visibility](#vertical_visibility) | Vertical visibility | m | time |
 | [window_transmission](#window_transmission) | Window transmission estimate | % | time |
 
+HIS L2 files produce the following NetCDF output:
+
+| Variable | Description | Units | Dimensions |
+| --- | --- | --- | --- |
+| [backscatter](#backscatter) | Attenuated volume backscatter coefficient | km<sup>-1</sup>.sr<sup>-1</sup> | time, level |
+| [ceilometer](#ceilometer) | Ceilometer name | | time |
+| [level](#level) | Level number | | level |
+| [period](#period) | Period | | time |
+| [time](#time) | Time | seconds since 1970-01-01 00:00:00 UTC | time |
+| [time_utc](#time_utc) | Time (UTC) | ISO 8601 | time |
+
 ### background_light
 
 Background light (mV)
@@ -205,6 +218,10 @@ Second lowest cloud base height (m)
 
 Highest cloud base height (m)
 
+### ceilometer
+
+Ceilometer name (HIS L2 variable `CEILOMETER`).
+
 ### detection_status
 
 Detection status
@@ -268,6 +285,10 @@ Message subclass
 - 6 – 10 m ⨉ 1540 samples, range 15400 m (msg1_10x1540)
 - 8 – without a backscatter profile (msg1_base)
 
+### period
+
+Period (HIS L2 variable `PERIOD`).
+
 ### pulse_energy
 
 Pulse energy (% of nominal factory setting)
@@ -449,6 +470,10 @@ functions to read the file (you may need to change the file extension to `.h5`).
 
 cl2nc follows [semantic versioning](http://semver.org/).
 
+### 3.5.0 (2024-04-18)
+
+- Added support for the HIS L2 format.
+
 ### 3.4.0 (2023-03-10)
 
 - Added support for a CL51 format as in R/V Polarstern data.

cl2nc.1

@@ -1,7 +1,7 @@
-.TH cl2nc "3.4.0" 08/21/2023
+.TH cl2nc "3.5.0" 04/18/2024
 
 .SH NAME
-cl2nc \- convert Vaisala CL51 and CL31 dat files to NetCDF
+cl2nc \- convert Vaisala CL51 and CL31 DAT and HIS L2 files to NetCDF
 
 .SH SYNOPSIS
 .B cl2nc
@@ -16,7 +16,9 @@ cl2nc \- convert Vaisala CL51 and CL31 dat files to NetCDF
 .IR input
 is an input
 .I .dat
-file.
+or
+.I .his
+(L2) file.
 .IR output
 is an output
 .I .nc
@@ -26,7 +28,11 @@ If directories are supplied for
 and
 .IR output ,
 all
-.IR ".dat " "and " .DAT
+.IR .dat ,
+.IR .DAT ,
+.I .his
+and
+.I .HIS
 files in
 .I input
 are converted to
@@ -38,7 +44,7 @@ files in
 
 .TP
 .B -c
-Enable checksum verification (slow).
+Enable DAT checksum verification (slow).
 .TP
 .B --debug
 Enable debugging output.
@@ -68,12 +74,15 @@ to NetCDF files in the directory
 
 .SH COPYRIGHT
 
-Copyright (C) 2018-2023 Peter Kuma.
+Copyright (C) 2018-2024 Peter Kuma.
 .PP
 This program is available under the terms of an MIT license (see LICENSE.md in the distribution).
 
 .SH SEE ALSO
 
-See <https://github.com/peterkuma/cl2nc>
+See
+.UR https://github.com/peterkuma/cl2nc
+cl2nc GitHub repository
+.UE
 for more information about
 .BR cl2nc .