Piloting
Suggested workflows for using the piloting functions
This page is meant to demonstrate some suggested workflows and examples of how the piloting functions may be used in an active mission to help the pilot download basestation files, create monitoring plots, and monitor mission progress.
All code on this page combined in the workflow_downloadScript.m in the agate\example_workflows folder.
Details for each piloting function (inputs, outputs, etc) are available within the standard MATLAB-type documentation in the header of each function and include a detailed description, info on input and output arguments, and examples. These details can be pulled up by typing doc function or help function within the MATLAB Command Window.
Initialization
To run any of the agate functions, the toolbox must be initialized with a configuration file.
No configuration file yet? Go to the Configuration Guide. If agate will be used to download files from the basestation to the local computer, a basestation.cnf file is required and the OPTIONAL - working with the basestation section of the mission configuration file must be completed.
The examples on this page include some plotting, so the OPTIONAL - plotting section should be complete. Examples below will also include some outputs for both the PMAR (pm) and WISPR (ws) acoustic systems. Those are specified in the configuration file and the examples below will indicate which system is ‘active’ for each example. This is controlled with the CONFIG.pm.loggers and CONFIG.ws.loggers options in the OPTIONAL - acoustics section of the configuration file.
% !make sure agate is on the path!
% initialize with specified configuration file, 'agate_config.cnf'
CONFIG = agate(agate_config.cnf);
% OR
% initialize with prompt to select configuration file
CONFIG = agate;Downloading files from the basestation
agate can use SSH to automatically download any new files present on the basestation to a local computer for further processing. The below folder structure is the suggested approach for working with agate and will ensure later functions are looking in the right spots. It may be possible to customize the folder structure but may result in bugs; if that happens, please report them and we can try to fix it!
% specify the local piloting folder for this trip in CONFIG.path.mission
% set up nested folders for basestation files and piloting outputs
path_status = fullfile(CONFIG.path.mission, 'flightStatus'); % where to store output plots/tables
path_bsLocal = fullfile(CONFIG.path.mission, 'basestationFiles'); % local copy of basestation files
% make the dirs if they don't exist
mkdir(path_status);
mkdir(path_bsLocal);
% download basestation files
downloadBasetationFiles(CONFIG, path_bsLocal)Creating a piloting parameters (pp) variable
Many of the plotting and other piloting-related functions within agate rely on a pp (piloting parameters) variable - a large table with various outputs from the .nc and .log files compiled in one place. Use the extractPilotingParams to create this table.
The last argument, preload, is used to specify if the table should be made from scratch (does not load any previously created table), or if a previous table should be loaded and any new dives appended to that table. As more dives occur during a mission, creating a new table each time can get slow, so saving the previous table and setting preload to 1 can save processing time. If the piloting parameters table is saved in the default location shown in the save() step below, then it will be loaded automatically. If it is saved elsewhere, the function will prompt to select the correct .mat to load.
% create piloting parameters (pp) table from downloaded basestation files
pp = extractPilotingParams(CONFIG, fullfile(CONFIG.path.mission, 'basestationFiles'), ...
fullfile(CONFIG.path.mission, 'flightStatus'), 0);
% change last argument from 0 to 1 to load existing data and append new dives/rows
% save it to the default location
save(fullfile(CONFIG.path.mission, 'flightStatus', ['diveTracking_' CONFIG.glider '.mat']), 'pp');Mid-mission plots
For detail on all available plotting functions, see the Plots page. A highlight of those most useful for piloting are below.
These plots will be assigned figure numbers as specified in CONFIG.plots.figNumList in the mission configuration file; that is required for the below steps but is commented out by default in the example mission configuration file. By assigning specific figure numbers, when plots are regenerated after subsequent dives, it will overwrite the previous figure rather than create a new one, preventing an overcluttered desktop.
The below steps require a pp variable. If it was created already, this first step is not needed.
% load existing pp table
load(fullfile(CONFIG.path.mission, 'flightStatus', ['diveTracking_' CONFIG.glider '.mat']))Map
…with target waypoints, dives completed thus far, and vector arrows for the currents.
In this example, bathymetry is plotted, specified by CONFIG.map.bathyFile. That last argument can be left out to not plot bathymetry (which can be slow depending on the resolution of the selected bathymetry raster). If the last argument is set to 1, a prompt will appear to select the correct bathymetry file.
The below example code saves the map both as a .fig file and a .png. The .fig version will be a very large file, if bathymetry is included, but it is useful for reopening in MATLAB and being able to zoom and move around in the plot. The .png is good for a quick easy overview and ease of sharing, but doesn’t allow the interactive zooming that a pilot may need.
High resolution bathymetry TIFF files can be downloaded from NCEI. See Dependecies - Basemap rasters for more info on how to select and download bathymetry rasters.
% print map **SLOWISH**
% make sure CONFIG.plots.figNumList is set in the configuration .cnf file.
% this will plot in fig number specified by figNumList(1)
targetsFile = fullfile(CONFIG.path.mission, 'targets');
plotGliderPath_etopo(CONFIG, pp, targetsFile, CONFIG.map.bathyFile);
% save it as a .fig (for zooming)
savefig(fullfile(path_status, [CONFIG.glider '_map.fig']))
% and as a .png (for quick/easy view)
exportgraphics(gca, fullfile(path_status, [CONFIG.glider '_map.png']), ...
'Resolution', 300)Monitoring plots
…for humidity, internal pressure, battery consumption, power draw, and acoustic system status.
Individual pilots may find some or all or none of these plots useful, but here are just a few examples. The example code has the option to save the figures with the print() function, but that is optional. To automatically plot, save, and then close the figures, just add a close command after print (see example with third and fifth plots below).
% humidity and pressure - figNumList(2)
plotHumidityPressure(CONFIG, pp)
print(fullfile(path_status, [CONFIG.glider '_humidityPressure.png']), '-dpng')
% battery usage/free space - figNumList(3)
plotBattUseFreeSpace(CONFIG, pp, 310)
print(fullfile(path_status, [CONFIG.glider '_battUseFreeSpace.png']), '-dpng')
% voltage pack use (power draw by device) - figNumList(4)
plotVoltagePackUse(CONFIG, pp)
print(fullfile(path_status, [CONFIG.glider '_usageByDevice.png']), '-dpng')
close
% voltage pack use (power draw by device, normalized by dive duration) - figNumList(5)
plotVoltagePackUse_norm(CONFIG, pp)
print(fullfile(path_status, [CONFIG.glider '_usageByDevice_normalized_.png']), '-dpng')
% minimum reported voltages - figNumList(6)
plotMinVolt(CONFIG, pp)
print(fullfile(path_status, [CONFIG.glider '_minimumVoltage.png']), '-dpng')
% closeIf the glider is running a PMAR acoustic system (and CONFIG.pm.loggers = 1 is set in the configuration file), the free space remaining on each SD card will be plotted by plotBattUseFreeSpace. Additionally, storage space used per minute, by dive, and over time can be plotted with plotPmUsed:
% PMAR space used per minute and over time
plotPmUsed(CONFIG, pp)If the glider is running a WISPR acoustic system (and CONFIG.ws.loggers = 1 is set in the configuration file), and using the on-board ERMA sperm whale detector, detection events can be plotted for a single dive. The plots show ICI (inter-click-interval) over the event duration and as a histogram. This plot is interactive and allows the user to click backwards through previous dives; a specific dive can be specified in the function call or end can be used to plot the most recent dive. The plot also provides a ‘reference plot’ showing what a true detection event of both a group of sperm whales or an individual sperm whale would look like. This plot can be used by the pilot to compare and validate the incoming detections.
% plot detection events from the most recent dive
plotErmaDetections(CONFIG, path_bsLocal, pp.diveNum(end))Printing errors and mission speed and duration information
The Seaglider .log file provides a summary of any errors that occurred during each dive, but they are just a list of integers that then have to be compared to a manual (and differ by Rev B vs Rev E!) so there is a function to print out all non-zero errors and a short descriptor of the type. Any dive can be specified in the second argument, or just the most recent dive as shown below.
% print out errors with info on type, for the most recent dive
printErrors(CONFIG, size(pp,1), pp)The printTravelMetrics and printRecoveryMetrics functions calculate several summary values for the glider’s average speed, progress along the trackline, and estimated time of arrival at the recovery point (last waypoint in targets file). These outputs can be printed to the MATLAB Command Window if the last argument is set to 1, otherwise they will be stored in a structure tm.
% print avg speed and rough estimate of total mission duration
tm = printTravelMetrics(CONFIG, pp, fullfile(CONFIG.path.mission, 'targets'), 1);
% specify planned recovery date and time
recovery = '2023-06-05 19:00:00';
recTZ = 'Pacific/Honolulu';
tm = printRecoveryMetrics(CONFIG, pp, fullfile(CONFIG.path.mission, 'targets'), ...
recovery, recTZ, 1);