feat(UI): detailLevel and aliases for instruments

These changes permit the user to set
the level of detail shown on all UI elements related
to instrument metadata description.

Two new options are provided in the toolboxProperties,
`instrumentAliases` and `detailLevel`.

instrumentAliases modify the display name of instruments
in the UI to the entries presented within
the GUI/instrumentAliases.txt file.

detailLevel modify the data description in all UI elements
to match several named options.

See the updated toolboxProperties.txt file for details.

GUI/instrumentAliases.txt

@@ -0,0 +1,5 @@
+%
+% Aliases for instrument names
+%
+% Instrument Exact Name, Alias/Abbreviation
+Seabird SBE19plus, SBE19+

Preprocessing/depthPP.m

@@ -334,7 +334,7 @@
 iMethodSam        = zeros(nDatasets, 1); % index of selected method within methodsSamString per dataset
 
 for iCurSam = 1:nDatasets
-    descSam{iCurSam} = genSampleDataDesc(sample_data{iCurSam}, 'medium');
+    descSam{iCurSam} = genSampleDataDesc(sample_data{iCurSam});
 
     iMethodsSamString(iCurSam, 4) = true;
     if useItsOwnPresRel(iCurSam)
@@ -353,7 +353,7 @@
     descOtherSam{iCurSam}{1} = ' - ';
     nOtherSam = length(nearestInsts{iCurSam});
     for iOtherSam = 1:nOtherSam
-        descOtherSam{iCurSam}{iOtherSam+1} = genSampleDataDesc(sample_data{nearestInsts{iCurSam}(iOtherSam)}, 'short');
+        descOtherSam{iCurSam}{iOtherSam+1} = genSampleDataDesc(sample_data{nearestInsts{iCurSam}(iOtherSam)});
     end
 end
 
@@ -1015,4 +1015,4 @@ function confirmCallback(source,ev)
         reset = false;
         delete(f);
     end
-end
+end

Util/genSampleDataDesc.m

@@ -1,14 +1,16 @@
-function desc = genSampleDataDesc( sam, detailLevel )
-%GENSAMPLEDATADESC Generates a string description of the given sample_data
+function desc = genSampleDataDesc(sam, detailLevel)
+%function desc = genSampleDataDesc(sam, detailLevel)
+%
+% Generates a string description of the given sample_data
 % struct.
 %
-% This function exists so that a uniform sample data description format can
-% be used throughout the toolbox.
-% 
+% This function exists so that a uniform sample data description
+% format can be used throughout the toolbox.
+%
 % Inputs:
 %   sam          - struct containing a data set
-%   detailLevel  - string either 'full', 'medium' or 'short', dictates the level of
-%                details for output sample description
+%   detailLevel  - string either 'full', 'medium' or 'short', dictates
+%                  the level of details for output sample description
 %
 % Outputs:
 %   desc - a string describing the given data set.
@@ -17,7 +19,7 @@
 %
 
 %
-% Copyright (C) 2017, Australian Ocean Data Network (AODN) and Integrated 
+% Copyright (C) 2017, Australian Ocean Data Network (AODN) and Integrated
 % Marine Observing System (IMOS).
 %
 % This program is free software: you can redistribute it and/or modify
@@ -30,15 +32,40 @@
 % GNU General Public License for more details.
 
 % You should have received a copy of the GNU General Public License
-% along with this program.
+%along with this program.
 % If not, see <https://www.gnu.org/licenses/gpl-3.0.en.html>.
 %
 narginchk(1,2);
 
 if ~isstruct(sam), error('sam must be a struct'); end
 
-if nargin == 1
+user_detailLevel = '';
+try
+    user_detailLevel = readProperty('toolbox.detailLevel');
+catch
+end
+
+simple_call_no_user_config = isempty(user_detailLevel) && nargin < 2;
+simple_call_with_user_config = ~isempty(user_detailLevel) && nargin < 2;
+full_call_with_user_config = ~isempty(user_detailLevel) && nargin > 1;
+
+if simple_call_no_user_config
     detailLevel = 'full';
+elseif simple_call_with_user_config
+    detailLevel = user_detailLevel;
+elseif full_call_with_user_config
+    %disambiguation towards shorter detailed levels
+    scores = containers.Map({'name-only','short','medium','full','id'},{1,2,3,4,5});
+    try
+        user_score = scores(user_detailLevel);
+        call_score = scores(detailLevel);
+        [found,ind] = inCell(scores.values,max(user_score,call_score));
+        if found
+            names = scores.keys;
+            detailLevel = names{ind};
+        end
+    catch
+    end
 end
 
 timeFmt = readProperty('toolbox.timeFormat');
@@ -50,26 +77,47 @@
 
 fName = [fName fSuffix];
 
+
+alias_file = '';
+try
+    alias_file = readProperty('toolbox.instrumentAliases');
+catch
+end
+
+instrument_entry = [sam.meta.instrument_make ' ' sam.meta.instrument_model];
+if ~isempty(alias_file)
+    try
+        map = readMappings(alias_file);
+        instrument_entry = map(instrument_entry);
+    catch
+    end
+end
+
 switch detailLevel
+
+    case 'name-only'
+        desc = [ instrument_entry ];
+
     case 'short'
-        desc = [   sam.meta.instrument_make ...
-            ' '    sam.meta.instrument_model ...
-            ' @'   num2str(sam.meta.depth) 'm'];
-
+        desc = [ instrument_entry ' @' num2str(sam.meta.depth) 'm'];
+
     case 'medium'
-        desc = [   sam.meta.instrument_make ...
-            ' '    sam.meta.instrument_model ...
+        desc = [   instrument_entry ...
             ' SN=' sam.meta.instrument_serial_no ...
             ' @'   num2str(sam.meta.depth) 'm' ...
             ' ('   fName ')'];
-
+
+    case 'id'
+        desc = [ '(' fName ')' ' SN=' sam.meta.instrument_serial_no ' @' num2str(sam.meta.depth) 'm'];
+
     otherwise
         % full details
         desc = [   sam.meta.site_id ...
-            ' - '  sam.meta.instrument_make ...
-            ' '    sam.meta.instrument_model ...
+            ' - '  instrument_entry ...
             ' SN=' sam.meta.instrument_serial_no ...
             ' @'   num2str(sam.meta.depth) 'm' ...
             ' '    timeRange ...
             ' ('   fName ')'];
-end
+end
+
+end

Util/readMappings.m

@@ -0,0 +1,49 @@
+function [mappings] = readMappings(file, delimiter)
+% function [mappings] = readMappings(file, delimiter)
+%
+% This read a mapping file, with a predefined delimiter (',').
+%
+% Inputs:
+%
+% file - a file location string
+% delimiter - a field delimiter
+%             default: ','
+%
+% Outputs:
+%
+% mappings - a containers.Map mapping
+%
+% Example:
+%
+% file =
+% [mappings] = readMappings(file)
+% assert()
+%
+% author: hugo.oliveira@utas.edu.au
+%
+
+% Copyright (C) 2020, Australian Ocean Data Network (AODN) and Integrated
+% Marine Observing System (IMOS).
+%
+% This program is free software: you can redistribute it and/or modify
+% it under the terms of the GNU General Public License as published by
+% the Free Software Foundation version 3 of the License.
+%
+% This program is distributed in the hope that it will be useful,
+% but WITHOUT ANY WARRANTY; without even the implied warranty of
+% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+% GNU General Public License for more details.
+%
+% You should have received a copy of the GNU General Public License
+% along with this program.
+% If not, see <https://www.gnu.org/licenses/gpl-3.0.en.html>.
+%
+if nargin < 2
+    delimiter = ',';
+end
+
+nf = fopen(file, 'r');
+raw_read = textscan(nf, '%s', 'Delimiter', delimiter);
+raw_read = raw_read{1};
+mappings = containers.Map(raw_read(1:2:end), raw_read(2:2:end));
+end

toolboxProperties.txt

@@ -1,26 +1,26 @@
 % filename or ODBC DSN of MS-ACCESS deployment database
 % ex. : /home/ggalibert/OceanDB.mdb or imos-ddb
-toolbox.ddb = 
+toolbox.ddb =
 
 % or full connection details to other kind of deployment database :
 % class name of JDBC database driver
 % ex. : net.ucanaccess.jdbc.UcanaccessDriver
-toolbox.ddb.driver = 
+toolbox.ddb.driver =
 
 % database connection string, must include user and password if required by the database
 % ex. : "jdbc:ucanaccess:///home/ggalibert/OceanDB.mdb;jackcessOpener=org.imos.ddb.CryptCodecOpener"
-toolbox.ddb.connection = 
+toolbox.ddb.connection =
 
 % user's login and password to database
-toolbox.ddb.user = 
-toolbox.ddb.password = 
+toolbox.ddb.user =
+toolbox.ddb.password =
 
-% toolbox execution mode. Values can be 'timeSeries' or 'profile'. 
+% toolbox execution mode. Values can be 'timeSeries' or 'profile'.
 toolbox.mode = timeSeries
 
 % directory which contains netcdf templates
 % (defaults to ./NetCDF/template/)
-toolbox.templateDir = 
+toolbox.templateDir =
 
 % date and time formats used internally and for GUI display
 toolbox.dateFormat = dd mmm yyyy
@@ -29,6 +29,22 @@ toolbox.timeFormat = yyyy-mm-ddTHH:MM:SS
 % QC set in use - see section 6.2 of the IMOS NetCDF User's Manual
 toolbox.qc_set = 1
 
+%Instrument display options
+% An alias file to change instrument visual names based on matched
+% entries.
+% [matched instrument maker/model], [display_name]
+toolbox.instrumentAliases = GUI/instrumentAliases.txt
+
+%Instrument detail level display options. This set the instrument metadata
+details. If instrumentAliases entries are found, [maker model] is substitute
+to the respective entry in toolbox.instrumentAliases
+% name-only - [maker model]
+% short - [maker model depth]
+% medium - [maker model serial_number depth filename]
+% full - [maker model serial number depth time_range filename]
+% id - [file serial depth]
+toolbox.detailLevel = full
+
 % format in which all dates should be exported in NetCDF attributes
 exportNetCDF.dateFormat = yyyy-mm-ddTHH:MM:SSZ
 
@@ -43,7 +59,7 @@ autoQCManager.autoQCDefaultChain.profile = imosImpossibleDateQC imosImpossibleLo
 autoQCManager.autoQCChain.timeSeries = imosImpossibleDateQC imosImpossibleLocationSetQC imosInOutWaterQC imosGlobalRangeQC imosImpossibleDepthQC imosSalinityFromPTQC imosSideLobeVelocitySetQC imosTiltVelocitySetQC imosHorizontalVelocitySetQC imosVerticalVelocityQC imosCorrMagVelocitySetQC imosHistoricalManualSetQC
 autoQCManager.autoQCChain.profile = imosImpossibleDateQC imosImpossibleLocationSetQC imosInOutWaterQC imosGlobalRangeQC imosImpossibleDepthQC imosSalinityFromPTQC imosHistoricalManualSetQC
 
-% prompt for preprocessing (if false, 
+% prompt for preprocessing (if false,
 % preprocessing routines are not executed)
 preprocessManager.preprocessPrompt = true
 
@@ -56,35 +72,35 @@ preprocessManager.preprocessChain.timeSeries = depthPP salinityPP oxygenPP absiD
 preprocessManager.preprocessChain.profile = depthPP salinityPP oxygenPP
 
 % file status dialog formatting styles
-% can be one of 'bold', 'normal', 'italic', or an HTML colour (e.g. 'red', 
+% can be one of 'bold', 'normal', 'italic', or an HTML colour (e.g. 'red',
 % 'blue' etc)
 dataFileStatusDialog.invalidFileNameFormat = red
 dataFileStatusDialog.noFileFormat          = bold
 dataFileStatusDialog.multipleFileFormat    = italic
 
 % last selected values for start dialog
-startDialog.dataDir.timeSeries = 
-startDialog.dataDir.profile = 
-startDialog.fieldTrip.timeSeries = 
-startDialog.fieldTrip.profile = 
-startDialog.lowDate.timeSeries = 
-startDialog.lowDate.profile = 
-startDialog.highDate.timeSeries = 
-startDialog.highDate.profile = 
+startDialog.dataDir.timeSeries =
+startDialog.dataDir.profile =
+startDialog.fieldTrip.timeSeries =
+startDialog.fieldTrip.profile =
+startDialog.lowDate.timeSeries =
+startDialog.lowDate.profile =
+startDialog.highDate.timeSeries =
+startDialog.highDate.profile =
 
 % last selected directory for manual data import
-importManager.manualDir = 
+importManager.manualDir =
 
 % last selected directory for file export
-exportDialog.defaultDir = 
+exportDialog.defaultDir =
 
-% prompt user to select parser if an appropriate one 
+% prompt user to select parser if an appropriate one
 % cannot be found (if false, the data is not imported)
 importManager.noParserPrompt = true
 
 % last selected directory for saving graphs as images
 saveGraph.noPrompt  = false
-saveGraph.exportDir = 
+saveGraph.exportDir =
 saveGraph.imgType   = png
 
 % visual QC plots export properties
@@ -98,4 +114,4 @@ visualQC.ncolors = 64
 
 % simple zbuffering of markers if using fallback fastScatterMesh plot (fastScatter = false)
 % 'ascending', 'descending', 'triangle', 'vee', 'flat', 'parabolic', 'hamming', 'hann'
-visualQC.zbuffer = triangle
+visualQC.zbuffer = triangle