rowg/daily_ais

Creates plots of AIS-generated antenna patterns from daily SeaSonde LOOP files.

daily_ais

Creates plots of AIS-generated antenna patterns from daily SeaSonde LOOP files.

Overview

daily_ais.py is a python script that automatically generates daily antenna patterns at AIS-equipped SeaSonde radial stations. This functionality is reportedly built into SeaSonde Release 8, but in SeaSonde Release 7, the generation of antenna patterns from AIS data requires extensive user intervention. The daily_ais.py script allows users to enjoy the convenience of automatic pattern generation without having to upgrade to Release 8.

daily_ais.py is called once per day by the cron daemon. It reads in data from the previous day's Loop file, generated by the SeaSonde software, filters it by target vessel range, bearing, speed, backscatter signal strength, etc., then uses it to generate an average antenna pattern for that day.

Output is in the form of three .png image files. One illustrates the effects of the filtering algorithm on the AIS data; the second contains a plot of the automatically-calculated antenna patterns for the day. The third .png image is also a plot of the antenna patterns, but represents an average of the daily patterns going back some user-specified number of days; this is referred to as a "history" pattern, and tends to be smoother than a single-day automatic pattern.

A python "shelf" database file containing multiple daily antenna patterns (for the creation of time-averaged "history" patterns) is also generated.

daily_ais.py is called by cron with the following syntax:

python daily_ais.py cfgFile

where cfgFile is the fully-qualified name of a .ini configuration file, specific to the radial station in question. For example, at the Ocean Networks Canada "VION" radial station, the script is called this way:

python /Users/codar/Documents/bin/daily_ais.py /Users/codar/Documents/configs/daily_ais_vion.ini

The daily_ais.py script reads in all the available Loop files that are not already represented in the shelf database file. The optional -f flag over-rides this behaviour, causing all available Loop files to be processed, whether or not they have been before.

The advantage of creating and plotting AIS-derived antenna patterns on the individual radial computers, rather than on the central Combiner computer, is that it removes the need to transfer large volumes of AIS data back to the Combiner. Python was chosen over Matlab as the language, as it avoids the expense of multiple Matlab licences.

CODAR operators may opt to use SeaSonde's FileExchange to fetch the .png files back to Combiner computer. Regardless, operators are advised to use SeaSonde's Archivalist program to manage the number of .png files that are retained; failing to do this may result in eventually running out of hard drive space.

The code

Apart from daily_ais.py itself, there are three python files in this toolbox:

1. CodarTableFormat.py is a general-purpose class for reading in the .ctf files produced by SeaSonde software.

2. Codar_loop.py is a subclass of CodarTableFormat.py that is specifically designed for reading in the "Loop" files produced by AIS-equipped SeaSonde radial stations.

3. pattern.py is a class that represents CODAR antenna patterns. It also represents antenna pattern "histories" (dictionary objects containing multiple daily antenna patterns, keyed by date).

The configuration file.

The daily_ais.py script is controlled by an ASCII .ini configuration file. This .ini file must be customized for each radial station. It is largely self-documenting.

One parameter of particular note is DOMAP, which must be set to False if the basemap toolbox is not installed.

Setting the headless parameter to False will cause plots to appear on the radial computer's desktop, stopping execution until the user closes the figure windows. For normal operation, headless is set to True, in which case the plots are written directly to .png image files without being displayed on the desktop.

Requirements

daily_ais.py was written for python 3, but has been made backwards-compatible with python 2.

The numpy and matplotlib packages are required. The basemap package, used for generating maps of the AIS data, is optional.

Installing python and python toolboxes on older versions of OSX can be difficult. It is suggested that users try either the "homebrew" or "anaconda" python distribution, though the details of this are beyond the scope of this README. The basemap package, in particular, is tricky to install, which is why it has been made optional.

Example figures

Several examples of the images generated by daily_ais.py are included here.

plot_filter_results_vion_2018-09-29.png is an example of the plots showing the effects of the filtering algorithm on the AIS data. Grey data lines and markers indicate discarded data points, while red denotes data points that have been kept. The axes in the first column depict the variables being filtered, plotted against compass bearing from the CODAR antenna. The axes in the second column depict the results of the filtering on a map of the region. The first row of axes is special: it depicts the overall effect of the filtering (i.e., the combined effects of the filtering depicted in the remaining axes).

plot_filter_results_vcol_2018-09-29.png is also a figure showing the effects of the filtering algorithm, but instead of maps in the second column of axes, there are polar plots. This is because the DOMAP parameter in VCOL's .ini file has been set to False.

The remaining two .png files included here are both examples of the antenna pattern plots generated by daily_ais.py. plot_AIS_pattern_VION_2018-10-10.png shows the antenna pattern generated at Ocean Network Canada's VION station for the single day of AIS data collected on October 10, 2018. plot_AIS_pattern_VION_history_10_2018-10-10.png is similar, but uses data averaged over the ten days up to and including October 10, 2018.

Known Issues:

• After a manual run (using the -f flag) to eliminate a backlog of unplotted Loop files, a subsequent cron-driven call to daily_ais.py was found to have resulted in the .shv "shelf" file being overwritten. It isn't clear how this happened; this problem may have been fixed with the addition of a file-existence test before saving, but this has not yet been tested.

• At one ONC site, a persistent operating system "Segmentation Fault 11" was occurring until the existing .shv "shelf" file was deleted. It is possible that the .shv file was corrupt in some way, but it is also possible that the MacIntosh computer in question (which is ONC's oldest) runs into problems with shelf files that are too large. If this problem recurs as the new shelf file grows over time, it may be necessary to reduce the shelf file size to keep only a month's worth of patterns, rather than a year's.

Acknowledgement

The daily_ais.py script is essentially a python implementation of a Matlab program called aispatt2.m, written by CODAR Ocean Sensor's Chad Whelan.