Get started with agate

Installation and quick start guide

This page is meant to help you get started with agate by getting it properly ‘installed’ on your MATLAB path, setting up the necessary configuration files and folder structure, and a quick start guide for some basic commands.

It page is not a detailed list of all available functions and their specific documentation (that might be coming later!). Those details 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> in the MATLAB Command window, replacing <function> with the actual name of the function.

Installation

See the Dependencies section of the home page for more info on the required Mathworks File Exchange packages (copies of these come packaged with agate) and MATLAB Toolbox requirements.

• Download agate from GitHub
  • Option 1: Download the latest release
    • This option ensures a stable release and removes the requirement of working with GitHub but will need manual updating
    • Visit the Releases page and download the latest release source code as a zip or tar.gz file
    • Unzip the downloaded folder and place within the default MATLAB directory (e.g., C:\Users\User.Name\Documents\MATLAB\). You only need the agate folder (the docs folder contains the files for this website so they can be deleted).
  • Option 2: Clone the repository using GitHub or GitHub Desktop
    • This package is actively being developed and the easiest way stay up to date with the latest improvements is to regularly check for updates from GitHub, but this comes with risks as it may be buggy
    • Click on the green Code button and select Open with GitHub Desktop
    • Specify where to clone the cloned local copy. Suggest the default MATLAB directory (e.g., C:\Users\User.Name\Documents\MATLAB\)
    • For more help with GitHub see this Git Started Doc
  • Option 3: Fork the repository using GitHub, then clone your fork via the Option 2 steps above
    • This is the best option if you would like to modify the tools and contribute to agate but also stay up to date with the latest developer changes
    • Click on the grey Fork button in the upper right and follow the prompts to create a copy of the repository in your personal GitHub account
    • Follow the Option 2 steps to clone your fork to your local computer
    • In the future, use the Sync fork button on GitHub to update your fork with any changes in the main repository, while maintaining any of your own modification and use the Contribute button to create pull requests so contribute your modifications to the package
  • Option 4: Download the repository as a zip file
    • This provides the latest functionality before an official release and removes requirement of working with GitHub but will need manual updating
    • Click the green Code button at the landing page of the repository and choose Download ZIP
    • Unzip the downloaded folder and place within the default MATLAB directory (e.g., C:\Users\User.Name\Documents\MATLAB\)
• Add agate to the MATLAB path
  • Open MATLAB and click on Set Path in the Environment section of the Home tab (Figure 1)
  • In the Set Path dialog box, choose Add with Subfolders…, select the agate folder, and click Save, then Close (Figure 2)
  • This will now be saved for future MATLAB sessions, but would need to be repeated for any installation on a new computer

Figure 1: Screenshot of MATLAB Home Tab showing where to click to Set Path

Figure 2: Example screenshot of the Set Path dialog box showing the Add with Subfolders... and Save buttons.

_{Back to top}

Quick Start Guide

Create configuration files

Running agate requires a few configuration files. Both of these are plain text files that end with .cnf and can be edited in any text editor or in MATLAB’s Editor window

1. An overview mission configuration file for a specific glider/mission
2. A basestation configuration file with SSH login info

Mission configuration file

An example configuration file is located in the agate/settings folder: agate_config_example.cnf

The configuration file has settings for the glider and mission, paths to relevant input and output folders, map extent and plotting settings, and acoustic system settings. The top section is required to initialize agate and use the most basic functions. The remaining sections are optional depending on what agate functionality is desired. Make a copy and save this file with a unique name for each glider and mission. Descriptions of each configuration item are included in the example file as comments that start with %.

Additional info on setting up configuration files can be found in the Configuration file guide.

To suggest additional configuration items, please open an issue.

Basestation configuration file

The path and filename for a basestation configuration file is specified in the mission configuration file. An example is located in the agate/settings folder: basestation_example.cnf.

This is a separate configuration file that typically does not change between missions and gliders, and contains potentially sensitive information for the SSH connection to a research group’s basestation. This file should be stored somewhere central and safe, preferably outside of the GitHub repository for security reasons.

Additional info on setting up configuration files can be found in the Configuration file guide.

_{Back to top}

Set up folder structure

The suggested folder structure for working with agate is to specify a ‘mission’ folder, and then within that have a standardized set of nested folders for the various agate inputs and outputs. The path of the ‘mission’ folder is specified by CONFIG.path.mission in the mission configuration file and typically follows the Seaglider naming scheme (e.g., C:\Users\User.Name\Desktop\sg###_Location_MonYYYY).

Within that, should be a flightStatus and a basestationFiles folder; flightStatus will house output figures and tables, and basestationFiles is where downloaded basestation files will be saved.

These folders can be set up manually, or created in MATLAB:

% specify the local piloting folder for this trip
path_status = fullfile(CONFIG.path.mission, 'flightStatus'); % where to store status outputs 
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);

_{Back to top}

Initialize agate

• Open MATLAB
• Add the agate folder to the path (with subfolders), if not already done
• Type CONFIG = agate(<agate_config.cnf>); in the command window and hit enter
  • Replace <agate_config.cnf> with the name of your configuration file (e.g., 'agate_config_sg639_MHI_Apr2022.cnf')
  • If the configuration file is located within the agate/settings folder, just the name is sufficient. If it is located elsewhere, specify the fullfile path (e.g., 'C:/Users/User.Name/Desktop/agate_config_sgXXX.cnf')
• Alternatively, simply type CONFIG = agate; and you will be prompted to select a configuration file

% make sure the agate folder has been added to the path!

% initialize by specifying the configuration file
CONFIG = agate('agate_config.cnf');

% OR intialize and select the configuration file
CONFIG = agate;

_{Back to top}

Download all basestation files

Use downloadBasestationFiles to automatically download various basestation files to a local machine for further examination. This function requires both a mission configuration file and a basestation configuration file that contains the host url, username, and either a password or paths to an SSH key pair.

Below is example code to run this step. This can be saved as a script that makes it easy to re-run each time the glider surfaces, or it can be typed directly into the MATLAB Command Window.

% initialize agate as above

% specify the local basestation and status/output folder for this mission
path_status = fullfile(CONFIG.path.mission, 'flightStatus'); % where to store status outputs 
path_bsLocal = fullfile(CONFIG.path.mission, 'basestationFiles'); % local copy of basestation files - this can be defined in the configuation file as CONFIG.path.bsLocal

% make the dirs if they don't exist
mkdir(path_status);
mkdir(path_bsLocal); % OR mkdir(CONFIG.path.bsLocal);

% download basestation files
downloadBasetationFiles(CONFIG)

_{Back to top}

Extract select piloting parameters and flight metrics

%% extract various piloting parameters and values reported by .log file
pp = extractPilotingParams(CONFIG, path_bsLocal, path_status, 0);
% the last argument (0) indicates that you don't want to preload an existing pp 
% variable that has been saved as a .mat file. Preloading saves time, but should
% be set to 0 the first time through. Change to 1 after an existing `pp` 
% variable has been saved

% print errors for quick glance/check
pp.ERRORS(end)

% save as .xlsx and .mat 
writetable(pp, fullfile(path_status, ['diveTracking_' CONFIG.glider '.xlsx'])); % local copy
save(fullfile(path_status, ['diveTracking_' CONFIG.glider '.mat']), 'pp');

_{Back to top}