coffee v2 prerelease

CFF_coffee_version.m

@@ -0,0 +1,23 @@
+function ver = CFF_coffee_version()
+%CFF_COFFEE_VERSION  Get version of CoFFee
+%
+%   Get version of coffee. Using standard semantic versioning rules. 
+%   See info on:
+%   https://semver.org/
+%   https://interrupt.memfault.com/blog/release-versioning
+%
+%   IMPORTANT NOTE FOR DEVELOPERS: Whenever you develop CoFFee and intend
+%   to release a new tag on git, please update this function appropriately
+%   before. Keep the existing version as a comment and add the new one as a
+%   new line above. Add the date.
+%
+%   See also CFF_GET_CURRENT_FDATA_VERSION.
+
+%   Authors: Alex Schimel (NGU, alexandre.schimel@ngu.no) and Yoann Ladroit
+%   (NIWA, yoann.ladroit@niwa.co.nz) 
+%   2022-2022; Last revision: 11-08-2022
+
+ver = '2.0.0-alpha.1'; % 11/08/2022
+
+end
+

custom_validation_functions/CFF_mustBeTwoNonnegativeUnsignedIntegers.m

@@ -0,0 +1,8 @@
+function CFF_mustBeTwoNonnegativeUnsignedIntegers(a)
+condition = isvector(a) && numel(a)==2 && isreal(a) && isnumeric(a) && all(ge(a,0)) && all(a==floor(a));
+if ~condition
+    eidType = 'mustBeTwoPositiveUnsignedIntegers:notTwoPositiveUnsignedIntegers';
+    msgType = 'Input must be two positive unsigned integers.';
+    throwAsCaller(MException(eidType,msgType))
+end
+end

custom_validation_functions/CFF_mustBeVector.m

@@ -0,0 +1,8 @@
+function CFF_mustBeVector(a)
+condition = isreal(a) && isnumeric(a) && sum(size(a)==1)>=ndims(a)-1;
+if ~condition
+    eidType = 'mustBeVector:notVector';
+    msgType = 'Input must be vector.';
+    throwAsCaller(MException(eidType,msgType))
+end
+end

docstring_template.m

@@ -0,0 +1,40 @@
+function [output1,output2] = CFF_function_name(input1,input2,input3)
+%CFF_FUNCTION_NAME  One-line description
+%
+%   See also CFF_OTHER_FUNCTION_NAME.
+
+%   Authors: Alex Schimel (NGU, alexandre.schimel@ngu.no) and Yoann Ladroit
+%   (NIWA, yoann.ladroit@niwa.co.nz) 
+%   XXXX-XXXX; Last revision: XX-XX-XXXX
+
+
+
+%CFF_FUNCTION_NAME  One-line description of what the function performs
+%
+%   Optional multiple lines of information giving more details about the
+%   function. The first line above (so-called H1 line) has no space before
+%   the function name and two spaces after. CFF_FUNCTION_NAME is written in
+%   upper-case throughout this docstring. One or multiple examples syntaxes
+%   follow. The docstring is completed by a "See also" section that allows
+%   help functions such as "help" or "doc" to automatically create
+%   hyperlinks. Separated from the docstring by a single empty line are the
+%   author(s) and information on last versions.
+%
+%   [X,Y] = CFF_FUNCTION_NAME(A,B,C) returns the sum of A+B as X, and C as
+%   Y. Note the input and output variables are also written in upper case.
+%   This first syntax should show the basic use
+%
+%   X = CFF_FUNCTION_NAME(A,B) returns the sum of A+B as X, since the
+%   additional input and outputs in this example are unecessary. This other
+%   syntax shows alterative functioning.
+%
+%   CFF_FUNCTION_NAME(...,'parameter',VAL) is another syntax to introduce
+%   optional or paramter inputs. Since the basic inputs and outputs have
+%   already been discussed, they can be ommitted, so the text focuses
+%   exclusively on what the option does compared to the basic syntax.
+%
+%   See also CFF_FUNCTION_NAME_1, CFF_OTHER_FUNCTION_NAME_2.
+
+%   Authors: Alex Schimel (NGU, alexandre.schimel@ngu.no) and Yoann Ladroit
+%   (NIWA, yoann.ladroit@niwa.co.nz) 
+%   XXXX-XXXX; Last revision: XX-XX-XXXX

fData_tools/CFF_fix_fData_paths.m

@@ -0,0 +1,81 @@
+function [fData, flagPathsFixed] = CFF_fix_fData_paths(fData,rawFile)
+%CFF_FIX_FDATA_PATHS  Fix paths in converted data if files were moved
+%
+%   When a raw data file is converted to a fData.mat file, the path of the
+%   source file (field ALLfilename) is saved, as well as the paths to the
+%   binary files containing water-column data (if that data type was
+%   converted). If you then move the data to another folder (even if moving
+%   appropriately both the source data, and the converted data), the
+%   absolute paths in fData are no longer correct. This function fixes it.
+%
+%   FDATA = CFF_FIX_FDATA_PATHS(FDATA,RAWFILE) checks if
+%   the absolute paths in some fields of FDATA are correct, given the
+%   absolute path of the raw data file RAWFILE, and corrects them if
+%   necessary. The fixed FDATA is saved back on the drive. 
+%
+%   [FDATA, FLAGPATHSFIXED] = CFF_FIX_FDATA_PATHS(...) returns
+%   FLAGPATHSFIXED = 1 if a correction was performed, 0 otherwise.
+%
+%   See also CFF_LOAD_CONVERTED_FILES.
+
+%   Authors: Alex Schimel (NGU, alexandre.schimel@ngu.no) and Yoann Ladroit
+%   (NIWA, yoann.ladroit@niwa.co.nz) 
+%   2017-2022; Last revision: 25-07-2022
+
+
+% path to converted data on disk
+fDataFolder = CFF_converted_data_folder(rawFile);
+fDataFile = fullfile(fDataFolder,'fData.mat');
+
+% init flag indicating change
+flagPathsFixed = 0;
+
+% grab source file names in fData
+fDataSourceFile = fData.ALLfilename;
+if ischar(fDataSourceFile)
+    fDataSourceFile = {fDataSourceFile};
+end
+
+% let's only deal with cell arrays, wether single or paired files
+if ischar(rawFile)
+    rawFile = {rawFile};
+end
+
+% check that input raw file(s) match fData source file(s)
+if ~isequal(sort(CFF_file_name(rawFile,1)),sort(CFF_file_name(fDataSourceFile,1)))
+    error('Names of source file(s) do not match those saved in fData. Please reconvert file.');
+end
+
+% check paths of source file(s) and fix if necessary
+if ~isequal(sort(rawFile),sort(fDataSourceFile))
+    fData.ALLfilename = sort(rawFile);
+    flagPathsFixed = 1;
+end
+
+% WCD binary files fields
+fields = fieldnames(fData);
+fields = fields(startsWith(fields,{'WC_SBP' 'AP_SBP' 'X_SBP'}));
+
+% Check path of WCD binary file(s) and fix if necessary
+for ii = 1:numel(fields)
+    field = fields{ii};
+    for jj = 1:numel(fData.(field))
+        if ~isempty(fData.(field){jj})
+            [filepathSaved,name,ext] = fileparts(fData.(field){jj}.Filename); % path in fData
+            if ~strcmp(filepathSaved,fDataFolder) % compare with expected folder
+                fData.(field){jj}.Filename = fullfile(fDataFolder,[name ext]); % rename
+                flagPathsFixed = 1;
+            end
+        end
+    end
+end
+
+% If anything was fixed
+if flagPathsFixed
+    % update on disk
+    try
+        save(fDataFile,'-struct','fData','-v7.3');
+    catch
+        warning('Wrong paths in fData were found and modified, but it was not possible to save the corrected fData back on the disk.');
+    end
+end

fData_tools/CFF_get_datagramSource.m

@@ -0,0 +1,60 @@
+function datagramSource = CFF_get_datagramSource(fData,varargin)
+%CFF_GET_DATAGRAMSOURCE  Get or set a datagramSource for a fData
+%
+%   fData may have multiple datagram types that can be used for further
+%   processing (typically, seabed data and water-column data) but we can
+%   only process one at a time. datagramSource is the two-letter code
+%   defining which datagram type are being (or, to be) processed. This
+%   function allows deciding an appropriate datagramSource for unprocessed
+%   data, or returns the datagramSource for processed data.
+% 
+%   DS = CFF_GET_DATAGRAMSOURCE(FDATA) checks if FDATA is processed. If
+%   yes, it returns its datagramSource as DS. If not, it returns a
+%   suitable datagramSource DS for processing.
+%
+%   CFF_GET_DATAGRAMSOURCE(FDATA, DS) checks if DS is a suitable
+%   datagramSource for (presumably unprocessed) FDATA. If yes, it returns
+%   DS. If not, it returns another datagramSource that is suitable. 
+
+%   See also CFF_COMPUTE_PING_NAVIGATION_V2.
+
+%   Authors: Alex Schimel (NGU, alexandre.schimel@ngu.no) and Yoann Ladroit
+%   (NIWA, yoann.ladroit@niwa.co.nz) 
+%   2017-2022; Last revision: 22-07-2022
+
+% init output
+datagramSource = [];
+
+if ~isempty(varargin) && ~isempty(varargin{1})
+    % datagramSource requested in input
+    datagramSource = varargin{1};
+elseif isfield(fData,'MET_datagramSource')
+    % datagramSource not requested in input, but fData appears processed
+    % with a set datagramSource already
+    datagramSource = fData.MET_datagramSource;
+end
+
+if ~isempty(datagramSource)
+    % check that there are indeed fields for that datagramSource
+    if ~isfield(fData,sprintf('%s_1P_Date',datagramSource))
+        % if not, that datagramSource is unsuitable so reset it to empty
+        datagramSource = [];
+    end
+end
+
+if isempty(datagramSource)
+    % if datagramSource still empty at this point, it means we need to find
+    % a suitable one based on fields available in fData. Test all suitable
+    % fields, by order of priority
+    if isfield(fData, 'AP_1P_Date')
+        datagramSource = 'AP';
+    elseif isfield(fData, 'WC_1P_Date')
+        datagramSource = 'WC';
+    elseif isfield(fData, 'X8_1P_Date')
+        datagramSource = 'X8';
+    elseif isfield(fData, 'De_1P_Date')
+        datagramSource = 'De';
+    else
+        error('can''t find a suitable datagramSource')
+    end
+end

fData_tools/CFF_set_bottom_sample.m

@@ -0,0 +1,10 @@
+function fData = CFF_set_bottom_sample(fData,bot)
+%CFF_SET_BOTTOM_SAMPLE  One-line description
+%
+
+%   Authors: Alex Schimel (NGU, alexandre.schimel@ngu.no) and Yoann
+%   Ladroit (NIWA, yoann.ladroit@niwa.co.nz)
+%   2017-2021; Last revision: 27-07-2021
+
+datagramSource = CFF_get_datagramSource(fData);
+fData.(sprintf('X_BP_bottomSample_%s',datagramSource)) = bot; %in sample number

fData_tools/fData_version/CFF_get_current_fData_version.m

@@ -0,0 +1,28 @@
+function ver = CFF_get_current_fData_version()
+%CFF_GET_CURRENT_FDATA_VERSION  Current version of fData.
+%
+%   The fData format sometimes requires updating to implement novel
+%   features. Such changes imply that data that have been previously
+%   converted may not be compatible with newer versions of processing code.
+%   As a result, it is necessary to version the fData format. This function 
+%   returns the current version of the fData format in order for code to
+%   test whether a converted data is up-to-date or if re-converting is
+%   advised.
+%
+%   IMPORTANT NOTE FOR DEVELOPERS: Whenever you change the fData format,
+%   please update this function appropriately. Keep the existing version
+%   number as a comment and add the new one as a new line above. Add the
+%   date, and ideally a quick summary of changes.
+%
+%   See also CFF_GET_FDATA_VERSION, CFF_coffee_version.
+
+%   Authors: Alex Schimel (NGU, alexandre.schimel@ngu.no) and Yoann
+%   Ladroit (NIWA, yoann.ladroit@niwa.co.nz)
+%   2017-2022; Last revision: 11-08-2022
+
+ver = '0.3'; % DD-MM-YYYY. Changes?
+% ver = '0.2'; % DD-MM-YYYY. Changes?
+% ver = '0.1'; % DD-MM-YYYY. Changes?
+% ver = '0.0'; % DD-MM-YYYY. Changes?
+
+end

fData_tools/fData_version/CFF_get_fData_version.m

@@ -0,0 +1,83 @@
+function fDataVersionList = CFF_get_fData_version(fDataInputList)
+%CFF_GET_FDATA_VERSION  Get the fData version of input fData
+%
+%   fDataVersion = CFF_GET_FDATA_VERSION(fDataFilepath) returns the
+%   (string) version of the fData mat file whose (string) filepath is
+%   specified in input.
+%
+%   fDataVersion = CFF_GET_FDATA_VERSION(fData) returns the (string)
+%   version of the input fData structure or matfile object.
+%
+%   fDataVersionList = CFF_GET_FDATA_VERSION(fDataInputList) returns a cell
+%   array where each element is the (string) version of the corresponding
+%   element in the input cell array. Each element of the input cell array
+%   can be either a (string) filepath to a fData mat file, or a fData
+%   structure or matfile object.
+%
+%   Note that oldest versions of fData dit not have a version stored in it,
+%   so if the input (or an input element) is 1) a filepath to a mat file
+%   with no version field, or 2) a struct (or matfile object) with no
+%   version field, the function will assume this is an old fData struct and
+%   returns the corresponding old version, i.e. '0.0'. 
+%   If the input (or an input element) is not an existing mat file, struct,
+%   or matfile object, then the function returns empty. 
+%
+%   WARNING: do not confuse this function with
+%   CFF_GET_CURRENT_FDATA_VERSION, which returns the latest version of
+%   fData used by the converting code.
+%
+%   See also CFF_GET_CURRENT_FDATA_VERSION.
+
+%   Authors: Alex Schimel (NGU, alexandre.schimel@ngu.no) and Yoann Ladroit
+%   (NIWA, yoann.ladroit@niwa.co.nz) 
+%   2017-2022; Last revision: 19-07-2022
+
+% single input
+if ~iscell(fDataInputList)
+    fDataInputList = {fDataInputList};
+end
+
+% init output
+sz = size(fDataInputList);
+fDataVersionList = cell(sz);
+
+% process by input
+for iF = 1:numel(fDataInputList)
+
+    % get that item
+    fDataInput = fDataInputList{iF};
+
+    if ischar(fDataInput)
+        % input is filepath
+        if strcmp(CFF_file_extension(fDataInput), '.mat') && isfile(fDataInput)
+            % file exists
+            matObj = matfile(fDataInput);
+            if isprop(matObj,'MET_Fmt_version')
+                fDataVersionList{iF} = matObj.MET_Fmt_version;
+            else
+                fDataVersionList{iF} = '0.0';
+            end
+        end
+    elseif isstruct(fDataInput)
+        % input is fData structure
+        if isfield(fDataInput,'MET_Fmt_version')
+            fDataVersionList{iF} = fDataInput.MET_Fmt_version;
+        else
+            fDataVersionList{iF} = '0.0';
+        end
+    elseif isa(fDataInput,'matlab.io.MatFile')
+        % input is matfile to the fData file
+        if isprop(fDataInput,'MET_Fmt_version')
+            fDataVersionList{iF} = fDataInput.MET_Fmt_version;
+        else
+            fDataVersionList{iF} = '0.0';
+        end
+
+    end
+
+end
+
+% return in case of single input
+if numel(fDataVersionList) == 1
+    fDataVersionList = fDataVersionList{1};
+end

fData_tools/fData_version/CFF_is_fData_version_current.m

@@ -0,0 +1,19 @@
+function bool = CFF_is_fData_version_current(fdata_input)
+%CFF_IS_FDATA_VERSION_CURRENT  Check if fData version of input is current
+%
+%   Input can be either the filepath to a fData.mat file, OR a fData
+%   structure. 
+%
+
+%   Authors: Alex Schimel (NGU, alexandre.schimel@ngu.no) and Yoann
+%   Ladroit (NIWA, yoann.ladroit@niwa.co.nz)
+%   2017-2021; Last revision: 24-05-2021
+
+% version if the fData file
+fdata_ver = CFF_get_fData_version(fdata_input);
+
+% current version for the conversion code
+curr_ver = CFF_get_current_fData_version();
+
+% match?
+bool = strcmpi(fdata_ver,curr_ver);