Merge pull request #60 from sfregosi/dev

LOTS of updates from dev branch

.gitignore

@@ -6,9 +6,7 @@ agate/draft/*
 # personal settings files kept locally only
 agate/settings/secret/*
 !agate/settings/secret/README-secret.md
-# personal workflow files kept locally only
-agate/workflows/*
-!agate/workflows/README-workflow.md
+
 
 
 # CONFIG FILES #

README.md

@@ -4,19 +4,24 @@
 # Acoustic Glider Analysis Tools and Environment
 
 <img
-src="README_files/figure-gfm/fa-icon-ef3463a0984ba0e303f1b25b6e50a309.svg"
-style="width:0.88em;height:1em" /> *Last Update: 25 May 2023*
+src="README_files/figure-gfm/fa-icon-bcbd573b0c4bf742a1242819bebaac28.svg"
+style="width:0.88em;height:1em" /> *Last Update: 05 Aug 2024*
 
-A collection of MATLAB-based tools to be used for piloting acoustic
+A collection of MATLAB-based tools for piloting passive acoustic
 gliders, processing glider positional and environmental data, and
-analyzing glider-collected acoustic data for surveys of marine mammals.
+analyzing glider-collected passive acoustic data, particularly for
+surveys of marine mammals.
 
-This package is very much under development, but my hope is that I will
-maintain a [stable
+This package is very much under development and is hosted and version
+controlled on [GitHub](https://github.com/sfregosi/agate-public). My
+hope is that I will maintain a [stable
 release](https://github.com/sfregosi/agate-public/releases) and then for
-those interested in the latest functionality, the repository can be
-cloned. For those interested in contributing to the package, I suggest
-creating a fork and using pull requests to contribute.
+those interested in the latest functionality, the GitHub repository can
+be cloned. For those interested in to the package, I suggest creating a
+fork and using pull requests to contribute. See the [How to
+contribute](https://sfregosi.github.io/agate-public/contribute.html)
+page for more detail. Please contact me if you have any questions,
+feedback, or suggestions!
 
 This code was either developed or most recently updated and tested with
 MATLAB version 2022b, but has undergone some testing with 2020b.
@@ -26,27 +31,6 @@ MATLAB version 2022b, but has undergone some testing with 2020b.
 *(the documentation is also under construction and I welcome any and all
 feedback!)*
 
-## Background
-
-These tools were initially developed for use with passive acoustic
-glider surveys conducted by the OSU/NOAA CIMERS Bioacoustics Lab
-<a href="https://bioacoustics.us"
-data-index="_blank">bioacoustics.us</a> and as part of my PhD. Initial
-development was for surveys using Seaglider platforms and either the
-Wideband Intelligent Signal Processor and Recorder (WISPR) or PMAR-XL
-recording systems.
-
-Through NOAA’s Uncrewed Systems Initiative (UxS) we received funding to
-develop and improve these tools into a more broadly applicable and
-user-friendly tool box that could be used by all interested in
-conducting glider-based passive acoustic surveys for marine mammals.
-
-Please contact me if you have any questions, feedback, or suggestions!
-
-selene \[dot\] fregosi \[at\] noaa.gov or
-<a href="https://github.com/sfregosi/agate-public/issues/new"
-target="_blank">Report an issue on GitHub</a>
-
 ## Disclaimer
 
 <sub>The scientific results and conclusions, as well as any views or

README.rmd

@@ -19,25 +19,14 @@ library(fontawesome)
 
 A collection of MATLAB-based tools for piloting passive acoustic gliders, processing glider positional and environmental data, and analyzing glider-collected passive acoustic data, particularly for surveys of marine mammals.
 
-This package is very much under development, but my hope is that I will maintain a [stable release](https://github.com/sfregosi/agate-public/releases) and then for those interested in the latest functionality, the repository can be cloned. For those interested in contributing to the package, I suggest creating a fork and using pull requests to contribute. 
+This package is very much under development and is hosted and version controlled on [GitHub](https://github.com/sfregosi/agate-public). My hope is that I will maintain a [stable release](https://github.com/sfregosi/agate-public/releases) and then for those interested in the latest functionality, the GitHub repository can be cloned. For those interested in  to the package, I suggest creating a fork and using pull requests to contribute. See the [How to contribute](https://sfregosi.github.io/agate-public/contribute.html) page for more detail. Please contact me if you have any questions, feedback, or suggestions!
 
 This code was either developed or most recently updated and tested with MATLAB version 2022b, but has undergone some testing with 2020b.  
 
 **Detailed documentation and information on dependencies can be found at [sfregosi.github.io/agate-public](https://sfregosi.github.io/agate-public)**
 *(the documentation is also under construction and I welcome any and all feedback!)*
 
 
-## Background
-
-These tools were initially developed for use with passive acoustic glider surveys conducted by the OSU/NOAA CIMERS Bioacoustics Lab [bioacoustics.us](https://bioacoustics.us){index='_blank'} and as part of my PhD. Initial development was for surveys using Seaglider platforms and either the Wideband Intelligent Signal Processor and Recorder (WISPR) or PMAR-XL recording systems. 
-
-Through NOAA's Uncrewed Systems Initiative (UxS) we received funding to develop and improve these tools into a more broadly applicable and user-friendly tool box that could be used by all interested in conducting glider-based passive acoustic surveys for marine mammals. 
-
-Please contact me if you have any questions, feedback, or suggestions!
-
-selene [dot] fregosi [at] noaa.gov or [Report an issue on GitHub](https://github.com/sfregosi/agate-public/issues/new){target='_blank'}
-
-
 ## Disclaimer
 
 <sub>The scientific results and conclusions, as well as any views or opinions expressed herein, are those of the author(s) and do not necessarily reflect the views of NOAA or the Department of Commerce.</sub>

agate/agate.m

@@ -1,4 +1,4 @@
-function agate(missionCnf)
+function CONFIG = agate(missionCnf)
 %AGATE	Initialize a new session of agate
 %
 %   Syntax:
@@ -14,7 +14,8 @@ function agate(missionCnf)
 %                   particular mission e.g., 'sg639_MHI_Apr2023.cnf'
 %
 %   Outputs:
-%      No workspace outputs. Generates a global CONFIG variable
+%       CONFIG  [struct] containing all the user-set configurations such as
+%               paths, basestation login info, etc
 %
 %   Examples:
 %       agate agate_sgXXX_Location_MonYear_config.cnf
@@ -25,19 +26,18 @@ function agate(missionCnf)
 %       S. Fregosi <[email protected]> <https://github.com/sfregosi>
 %
 %   FirstVersion:   06 April 2023
-%   Updated:        09 March 2024
+%   Updated:        06 August 2024
 %
 %   Created with MATLAB ver.: 9.13.0.2166757 (R2022b) Update 4
 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
-clear global CONFIG;  % clear out old globals
+clear CONFIG;
 warning off % this is turned off for plotting messages
 
-global CONFIG
-% CONFIG = struct;
+CONFIG = struct;
 
-CONFIG.ver = '0.1.20240309   https://github.com/sfregosi/agate-public';
-fprintf('      agate   version %s\n\n', CONFIG.ver)
+CONFIG.ver = '0.1.20240806   https://github.com/sfregosi/agate-public';
+fprintf('      agate   version %s\n', CONFIG.ver)
 
 if nargin < 1
 	CONFIG.missionCnf = [];
@@ -48,32 +48,36 @@ function agate(missionCnf)
 % get matlab version for differences and backwards compatibility
 CONFIG.mver = version;
 
-checkPath;
+CONFIG = checkPath(CONFIG);
 
-setCONFIG(CONFIG.missionCnf);
+CONFIG = setCONFIG(CONFIG);
+
+fprintf('      loaded config file   %s\n\n', CONFIG.missionCnf)
 
 end
 
 
-function checkPath
+function CONFIG = checkPath(CONFIG)
 %CHECKPATH	Check the necessasry folders are there and on the path
 %
 %   Syntax:
-%       CHECKPATH
+%       CONFIG = CHECKPATH(CONFIG)
 %
 %   Description:
 %       Called from the agate initialization. Sets up the necessary paths
 %       in the CONFIG variable, while checking that all needed subfolders
 %       are present and on the path. If not, it makes them.
 %
 %   Inputs:
-%       none
+%       CONFIG  [struct] containing all the user-set configurations such as
+%               paths, basestation login info, etc
 %
 %	Outputs:
-%       none
+%       CONFIG  [struct] containing all the user-set configurations such as
+%               paths, basestation login info, etc
 %
 %   Examples:
-%       checkPath
+%       CONFIG = checkPath(CONFIG);
 %
 %	See also
 %       agate
@@ -86,13 +90,11 @@ function agate(missionCnf)
 %           https://github.com/MarineBioAcousticsRC/Triton/
 %
 %   FirstVersion:   06 April 2023
-%   Updated:        04 March 2024
+%   Updated:        06 August 2024
 %
 %   Created with MATLAB ver.: 9.13.0.2166757 (R2022b) Update 4
 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
-global CONFIG
-
 % root directory
 CONFIG.path.agate = fileparts(which('agate'));
 addpath(CONFIG.path.agate); % no subdirs

agate/archive/workflow_createTargetsFileFromKML.m

@@ -0,0 +1,113 @@
+% workflow to get a Google Earth created proposed trackline into a targets
+% file and then into a 5-km spacing schedule to share with the Navy
+
+% 1 - create track manually in Google Earth, using input from collaborators
+% and sponsor. Save as .kml when finalized. 
+
+% kmlFile = 'C:\Users\Selene.Fregosi\Documents\UxS_HI_Glider\piloting\UxS_PIFSC_twoDeployments.kml';
+% kmlFile = 'C:\Users\Selene.Fregosi\Desktop\sg680_HI_Apr2022\Leeward Glider_revised_20220503.kml';
+% kmlFile = 'C:\Users\Selene.Fregosi\Desktop\sg639_HI_Apr2022\Windward Glider_revised_20220509.kml';
+% kmlFile = 'C:\Users\Selene.Fregosi\Desktop\sg680_HI_Apr2022\Leeward Glider_revised_20220524.kml';
+% kmlFile = 'C:\Users\Selene.Fregosi\Desktop\sg639_HI_Apr2022\Windward Glider_revised_20220524.kml';
+[kmlFileName, kmlPath] = uigetfile('*.kml', 'Select .kml track');
+kmlFile = fullfile(kmlPath, kmlFileName);
+[~, kmlName, kmlExt] = fileparts(kmlFileName);
+
+% kml saves the vertices of lines as decimal degrees in a code snippet like
+% % this: 
+% 		<Placemark>
+% 			<name>Leeward Glider</name>
+% 			<styleUrl>#inline13</styleUrl>
+% 			<LineString>
+% 				<tessellate>1</tessellate>
+% 				<coordinates>
+% 					-159.3180977061045,21.93379120241162,0 -159.3915294840902,21.50741673680377,0 -158.8809373915385,21.73528994893612,0 -158.9763412128043,21.27910694076397,0 -158.4324636016379,21.47030430788609,0 -158.5300178504395,20.97351624005566,0 -158.0118868380484,21.04165660408255,0 -157.9015894020643,20.52832280966129,0 -157.3568488495222,20.82859768139042,0 -157.5622783640389,20.30084306318159,0 -157.0340176577208,20.63583528150905,0 -157.2485263069477,20.08415381579547,0 -156.5958158941286,20.38616727824648,0 -156.9019851472443,19.83461456110239,0 -156.1842310583716,20.20053668786948,0 -156.557056073062,19.59525648291685,0 -156.1124900576321,19.74835140750147,0 
+% 				</coordinates>
+% 			</LineString>
+% 		</Placemark>
+% FOR NOW
+% search for the name of the path you want and find the coordinates line.
+% then just copy and paste the coordinates into a text file alone. 
+% txtCoordFile = 'C:\Users\Selene.Fregosi\Documents\UxS_HI_Glider\piloting\kml_leeward_coords.txt';
+% txtCoordFile = 'C:\Users\Selene.Fregosi\Documents\UxS_HI_Glider\piloting\kml_windward_coords.txt';
+% txtCoordFile = 'C:\Users\Selene.Fregosi\Desktop\sg680_HI_Apr2022\kml_leeward_revised_20200503.txt';
+% txtCoordFile = 'C:\Users\Selene.Fregosi\Desktop\sg639_HI_Apr2022\kml_windward_revised_20200509.txt';
+% txtCoordFile = 'C:\Users\Selene.Fregosi\Desktop\sg680_HI_Apr2022\kml_leeward_revised_20200524.txt';
+% txtCoordFile = 'C:\Users\Selene.Fregosi\Desktop\sg639_HI_Apr2022\kml_windward_revised_20200524.txt';
+[txtCoordFileName, txtCoordPath] = uigetfile([kmlPath '\*.txt'], 'Select .txt coordinate file');
+txtCoordFile = fullfile(txtCoordPath, txtCoordFileName);
+
+% read in the coords and rearrange in a readable way
+fid = fopen(txtCoordFile, 'r');
+decDegCoords = textscan(fid, '%f%f%f', 'delimiter', ',', 'CollectOutput',1);
+fclose(fid);
+decDegCoords = decDegCoords{1,1}; % convert to array
+decDegCoords = decDegCoords(:,1:2); % get rid of the "z" coord which should be 0s
+% leeward glider has to be flipped because track order goes from N to S
+% decDegCoords = flip(decDegCoords);
+
+% convert to deg decmins
+degMinLons = decdeg2degmin(decDegCoords(:,1));
+degMinLats = decdeg2degmin(decDegCoords(:,2)); 
+% define waypoint names
+% wpNames = {'LW01', 'LW02', 'LW03', 'LW04', 'LW05', 'LW06', 'LWmA', 'LW07', ...
+%     'LWmB', 'LW08', 'LWmC', 'LW09', 'LWmD', 'LW10', 'LWmE', 'LW11', 'LWmF', ...
+%     'LW12', 'LWmG', 'LW13', 'LWmH', 'LW14', 'LW15', 'LWmI', 'LWmJ', 'RECV'}';
+% wpNames = {'LW01', 'LW02', 'LW03', 'LW04', 'LW05', 'LW06', 'LW07', 'LW08', ...
+%      'LW09', 'LW10', 'LW11', 'LW12', 'LW13', 'LW14', 'LW15', 'LW16', 'RECV'}';
+
+% wpNames = {'WW01', 'WW02', 'WW03', 'WW04', 'WW05', 'WW06', 'WW07', 'WW08', ...
+%      'WW09', 'WW10', 'WW11', 'WW12', 'WW13', 'WW14', 'WW15', 'WW16', 'RECV'}';
+% wpNames = {'WW01', 'WW02', 'WWaa', 'WWab', 'WW03', 'WWm4', 'WW04', 'WWmE', ...
+%     'WW05', 'WWmF', 'WW06', 'WWmG', 'WW07', 'WWmH', 'WW08', 'WWmI', 'WW09', ...
+%     'WWmJ', 'WW10', 'WWmK', 'WW11', 'WWmL', 'WW12', 'WWmM', 'WW13', 'WWmN', ...
+%     'WW14', 'WWmO', 'WW15', 'WWmP', 'WW16', 'WWmQ', 'WW17', 'WWmR', 'WWmS', ...
+%     'WWmT', 'RECV'}';
+wpNames = {'WW01', 'WW02', 'WW03', 'WW04', 'WW05', 'WW06', 'WW07', 'WW08', ...
+    'WW09', 'WW10', 'WW11', 'WW12', 'WW13', 'WW14', 'WW15', 'WW16', ...
+    'WW17', 'RECV'}';
+
+% now write it into a targets file
+% example header text
+% / Glider survey plan for UxS HI March 2022
+% / Deployment will take place at WPo1
+% / template WPo lat= lon= radius=2000 goto=WPo
+% / radius set to 2000 m
+
+% targetsOut =  'C:\Users\Selene.Fregosi\Documents\UxS_HI_Glider\piloting\targets_leeward_20220121_auto';
+% targetsOut =  'C:\Users\Selene.Fregosi\Documents\UxS_HI_Glider\piloting\targets_windward_20220121_auto';
+% targetsOut = 'C:\Users\Selene.Fregosi\Documents\UxS_HI_Glider\piloting\targets_leeward_revised_20220503_auto';
+% targetsOut = 'C:\Users\Selene.Fregosi\Documents\UxS_HI_Glider\piloting\targets_windward_revised_20220509_auto';
+% targetsOut = 'C:\Users\Selene.Fregosi\Documents\UxS_HI_Glider\piloting\targets_leeward_revised_20220524_auto';
+% targetsOut = 'C:\Users\Selene.Fregosi\Documents\UxS_HI_Glider\piloting\targets_windward_revised_20220524_auto';
+
+targetsOut = fullfile(kmlPath, ['targets_' kmlName]);
+fid = fopen(targetsOut, 'w');
+% write the header text 
+% fprintf(fid, '%s\n', '/ Glider survey plan for UxS HI April 2022 - Leeward Glider');
+% fprintf(fid, '%s\n', '/ Deployment will take place at LW01, recovery at RECV');
+fprintf(fid, '%s\n', '/ Glider survey plan for UxS MHI April 2023 - SG639 - Windward Glider');
+fprintf(fid, '%s\n', '/ Deployment will take place at WW01, recovery at RECV');
+
+fprintf(fid, '%s\n', '/ template WPxx lat=DDMM.MMMM lon=DDDMM.MMMM radius=2000 goto=WPo');
+fprintf(fid, '%s\n', '/ radius set to 2000 m');
+
+for f = 1:length(wpNames)-1
+fprintf(fid, '%s lat=%d%07.4f lon=%d%07.4f radius=2000 goto=%s\n', ...
+    wpNames{f}, degMinLats(f,1), degMinLats(f,2), degMinLons(f,1), degMinLons(f,2), wpNames{f+1});
+end
+f = length(wpNames);
+fprintf(fid, '%s lat=%d%07.4f lon=%d%07.4f radius=2000 goto=%s', ...
+    wpNames{f}, degMinLats(f,1), degMinLats(f,2), degMinLons(f,1), degMinLons(f,2), wpNames{f});
+fclose(fid);
+
+%% plot
+glider = ['sg639']; % leeward
+% glider = 'sg680'; % windward
+latLim = [17 22];
+lonLim = [-157 -152];
+path_shp = 'C:\Users\Selene.Fregosi\Documents\GIS\';
+
+plotGliderPath_etopo(glider, latLim, lonLim, pp, path_out, path_shp, figNum)
+
+

agate/convertAcoustics/convertPmar/convertPmarFun.m

@@ -13,11 +13,11 @@ function convertPmarFun(CONFIG)
 % convertPMARFun.m is a functionized version of the convertPmar.m script.
 % it allows for a CONFIG input argument that is created from the
 % pmarConvertConfig_template.m, which is meant to keep configuration for
-% each survey organized in its own file
+% each mission organized in its own file
 
 % Dave Mellinger
 % Oregon State Univ.
-% last modified 2024 02 28 S. Fregosi [email protected]
+% last modified 2024 08 07 S. Fregosi [email protected]
 
 
 %% %%%%%%%%%%%%%%%%%%%%%%%%%%%% Configuration %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

agate/convertAcoustics/convertWispr/convertWispr.m

@@ -19,7 +19,7 @@ function convertWispr(CONFIG)
 % % % convertPmarFun.m is a functionized version of the convertPmar.m script.
 % % % it allows for a CONFIG input argument that is created from the
 % % % pmarConvertConfig_template.m, which is meant to keep configuration for
-% % % each survey organized in its own file
+% % % each mission organized in its own file
 %
 %   Inputs:
 %       CONFIG   [struct] optional agate global mission configuration
@@ -40,7 +40,7 @@ function convertWispr(CONFIG)
 %       S. Fregosi <[email protected]> <https://github.com/sfregosi>
 %
 %   FirstVersion:   30 June 2023
-%   Updated:        
+%   Updated:        07 August 2024
 %
 %   Created with MATLAB ver.: 9.13.0.2166757 (R2022b) Update 4
 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

agate/example_workflows/README_example_workflows.md

@@ -0,0 +1,3 @@
+README example_workflows
+
+Large files/folders that cannot be hosted on GitHub but are useful for testing can be found on Google Drive at [agate_test_data](https://drive.google.com/drive/u/0/folders/1GnItHEbR1tEG1HANGU7hliI625q2OORB)

agate/example_workflows/workflow_convertPMAR.m

@@ -31,8 +31,7 @@
 % - specify path to PMAR convert configuration file with CONFIG.pm.cnfFile
 
 % initialize agate - either specify the mission .cnf or leave blank to browse/select
-agate agate_mission_config.cnf
-global CONFIG
+CONFIG = agate('agate_mission_config.cnf');
 
 % convert!
 convertPmarFun(CONFIG)

agate/example_workflows/workflow_downloadScript.m

@@ -33,8 +33,7 @@
 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 % initialize agate
-agate agate_mission_config.cnf
-global CONFIG
+CONFIG = agate('agate_mission_config.cnf');
 
 % specify the local piloting folder for this trip in CONFIG.path.mission
 % set up nested folders for basestation files and piloting outputs
@@ -46,7 +45,7 @@
 mkdir(path_bsLocal);
 
 %% (1) download files from the basestation
-downloadBasestationFiles(CONFIG639, path_bsLocal)
+downloadBasestationFiles(CONFIG, path_bsLocal)
 
 % To plot Seaglider Piloting Tools plots at this point, run DiveData below
 % DiveData