Merge pull request #689 from aodn/parser_oceanContour

IMOS utilities and OceanContour Parser, closes #691

Parser/oceanContourParse.m

@@ -0,0 +1,40 @@
+function [sample_data] = oceanContourParser(filename_in_cell, toolbox_mode)
+% function [data] = oceanContourParser(filename_in_cell, toolbox_mode)
+%
+% The OceanContour Parser for netcdf or mat files.
+%
+% Inputs:
+%
+% filename [cell[str]] - A cell containing one filename string.
+% toolbox_mode [str] - the processing mode string.
+%                    Default: 'timeSeries'
+%
+% Outputs:
+%
+% sample_data - toolbox struct containing the data.
+%
+% Example:
+%
+% [data] = OceanContourParser(file,mode)
+% assert()
+%
+% author: [email protected]
+%
+narginchk(1, 2)
+
+invalid_file_arg = ~iscellstr(filename_in_cell) && length(filename_in_cell) ~= 1;
+
+if invalid_file_arg
+    errormsg('First argument file isn''t a singleton cell of strings')
+end
+
+filename = filename_in_cell{1};
+inexistent_file = isempty(dir(filename));
+
+if inexistent_file
+    errormsg('file %s doesn''t exist', filename)
+end
+
+sample_data = OceanContour.readOceanContourFile(filename);
+
+end

Util/+IMOS/+random/get_random_param.m

@@ -0,0 +1,39 @@
+function [param] = get_random_param(param_name)
+% function [param] = get_random_param(param_name)
+%
+% Get a random IMOS parameter index.
+%
+% Inputs:
+%
+% param_name - the parameter name. See IMOS.param.
+%
+% Outputs:
+%
+% param - A random item.
+%
+% Example:
+%
+% valid_entry = @(x)(~isempty(x) && ischar(x));
+% assert(valid_entry(IMOS.random.get_random_param('name')))
+% assert(valid_entry(IMOS.random.get_random_param('long_name')))
+% assert(valid_entry(IMOS.random.get_random_param('netcdf_ctype')))
+%
+% author: [email protected]
+%
+narginchk(1, 1)
+
+if ~ischar(param_name)
+    error('First argument is not a char')
+end
+
+imosparams = IMOS.params();
+available_names = fieldnames(imosparams);
+
+if ~inCell(available_names, param_name)
+    errormsg('IMOS parameter %s does not exist', param_name)
+end
+
+all_values = unique(imosparams.(param_name));
+rind = random_between(1, numel(all_values), 1, 'int');
+param = all_values{rind};
+end

Util/+IMOS/+random/imos_data.m

@@ -0,0 +1,67 @@
+function [rdata] = imos_data(imos_type, data_size)
+% function [rdata] = imos_data(imos_type,data_size)
+%
+% Generate a random IMOS variable
+% given a type and a size.
+% A column vector is used if data_size provided
+% is singleton.
+%
+% If no arguments, a double random data of size [100x1]
+% is generated.
+%
+% Inputs:
+%
+% imos_type [function_handle] - the fh imos type.
+% data_size [array] - an size array to use
+%                     in the resolution of the data.
+%
+% Outputs:
+%
+% rdata [type] - the random data array of specific type
+%
+% Example:
+%
+% %random generation 100xN
+% [rdata] = IMOS.random.imos_data();
+% assert(iscolumn(rdata) && numel(rdata)==100)
+%
+% %random typed
+% [rdata] = IMOS.random.imos_data(@int32);
+% assert(isint32(rdata) && iscolumn(rdata) && numel(rdata)==100)
+%
+% %random typed with defined size
+% [rdata] = IMOS.random.imos_data(@int32,[6,1]);
+% assert(isint32(rdata) && iscolumn(rdata) && numel(rdata)==6)
+% [rdata] = IMOS.random.imos_data(@int32,[1,6]);
+% assert(isint32(rdata) && isrow(rdata) && numel(rdata)==6)
+% [rdata] = IMOS.random.imos_data(@int32,[6,6]);
+% assert(isint32(rdata) && isnumeric(rdata) && numel(rdata)==36)
+%
+% %invalid type argument
+% f=false;try; IMOS.random.imos_data('float');catch;f=true;end
+% assert(f)
+%
+% %invalid size argument
+% f=false;try; IMOS.random.imos_data(@double,1);catch;f=true;end
+% assert(f)
+%
+%
+% author: [email protected]
+%
+
+if nargin == 0
+    rdata = randn(100, 1);
+    return
+elseif nargin > 0 && ~isfunctionhandle(imos_type)
+    errormsg('First argument `imos_type` is not a function handle')
+elseif nargin > 1 && ~issize(data_size)
+    errormsg('Second argument `data_size` is not a valid size')
+end
+
+if nargin == 1
+    rdata = imos_type(randn(100, 1));
+else
+    rdata = imos_type(randn(data_size));
+end
+
+end

Util/+IMOS/+random/imos_name.m

@@ -0,0 +1,21 @@
+function [name] = imos_name
+% function [name] = imos_name
+%
+% Generate a random IMOS name
+%
+% Inputs:
+%
+% Outputs:
+%
+% name [string] - an IMOS name from imosParameters.txt
+%
+% Example:
+%
+% [name] = IMOS.random.imos_name();
+% assert(~isempty(name))
+% assert(all(isstrprop(name,'print')))
+%
+% author: [email protected]
+%
+name = IMOS.random.get_random_param('name');
+end

Util/+IMOS/+random/imos_type.m

@@ -0,0 +1,19 @@
+function [rtype] = imos_type
+% function [rtype] = imos_type
+%
+% Generate a random imos type function handle
+%
+% Inputs:
+%
+% Outputs:
+%
+% rtype [function_handle] - the function handle of the type.
+%
+% Example:
+%
+% assert(isa(IMOS.random.imos_type,'function_handle'))
+%
+% author: [email protected]
+%
+rtype = str2func(netcdf3ToMatlabType(IMOS.random.get_random_param('netcdf_ctype')));
+end

Util/+IMOS/+resolve/imos_type.m

@@ -0,0 +1,46 @@
+function [itype] = imos_type(imos_name)
+% function [itype] = imos_type(imos_name)
+%
+% Resolve an IMOS data type function handle
+% based on its name.
+%
+% If the name is not an IMOS dimension/variable name,
+% an error is raised.
+%
+% Inputs:
+%
+% imos_name [str] - an IMOS variable name to use
+%                 in the resolution of the type.
+%
+% Outputs:
+%
+% itype [function_handle] - the resolved function handle.
+%
+% Example:
+%
+% %basic
+% assert(isequal(IMOS.resolve.imos_type('TIME'),@double));
+%
+% %imos_name missing
+% f=false;try;IMOS.resolve.imos_type('ABC');catch;f=true;end;
+% assert(f)
+%
+%
+% author: [email protected]
+%
+narginchk(1, 1)
+
+if ~ischar(imos_name)
+    errormsg('First argument is not a valid string')
+end
+
+params = IMOS.params();
+[name_exist, name_ind] = inCell(params.name, imos_name);
+
+if ~name_exist
+    errormsg('Name %s is missing within the imosParameter table.', imos_name)
+else
+    itype = str2func(netcdf3ToMatlabType(params.netcdf_ctype{name_ind}));
+end
+
+end

Util/+IMOS/+resolve/name.m

@@ -0,0 +1,37 @@
+function [rname] = name(cnames, rindex)
+% function [rname] = name(cnames,rindex)
+%
+% Return cnames{rindex} if cnames is a cell
+% of strings and rindex<numel(cnames).
+% If out-of-bounds, returns an empty string.
+%
+% This function will type check the arguments.
+%
+% Inputs:
+%
+% cnames [cell[str]] - a cell of strings.
+% rindex [integer] -  an integer index.
+%
+% Outputs:
+%
+% rname [str] - cnames{index} or empty string.
+%
+% Example:
+%
+% [rname] = IMOS.resolve.name({'A'},1);
+% assert(rname=='A');
+% [rname] = IMOS.resolve.name({'A'},10);
+% assert(isempty(rname));
+%
+% author: [email protected]
+%
+narginchk(2, 2)
+
+if ~iscellstr(cnames)
+    errormsg('First argument `cnames` is not a cell of strings.')
+elseif (~isindex(rindex) || numel(rindex) > 1)
+    errormsg('Second argument `rindex` is not a singleton valid index.')
+end
+
+rname = IMOS.getitem(cnames, rindex);
+end

Util/+IMOS/+templates/dimensions.m

@@ -0,0 +1,40 @@
+classdef  dimensions
+	% A collection of minimal IMOS dimensions templates.
+	properties (Constant)
+		timeseries = timeseries_dims();
+		profile = profile_dims();
+		ad_profile = ad_profile_dims();
+		adcp_raw = adcp_raw_dims();
+		adcp_remapped = adcp_remapped_dims();
+	end
+end
+
+function [dimensions] = timeseries_dims()
+%create basic timeseries dimensions
+dimensions = {struct('name','TIME','typeCastFunc',getIMOSType('TIME'),'data',[],'comment','')};
+end
+
+function [dimensions] = profile_dims()
+%create basic profile dimensions
+dimensions = {struct('name','DEPTH','typeCastFunc',getIMOSType('DEPTH'),'data',[],'comment','','axis','Z')};
+end
+
+function [dimensions] = ad_profile_dims()
+%create basic ad profile dimensions
+dimensions = cell(1,2);
+dimensions{1} = struct('name','MAXZ','typeCastFunc',getIMOSType('MAXZ'),'data',[]);
+dimensions{2} = struct('name','PROFILE','typeCastFunc',getIMOSType('PROFILE'),'data',[]);
+dimensions{2}.data = dimensions{2}.typeCastFunc([1,2]);
+end
+
+function [dimensions] = adcp_raw_dims()
+dimensions = timeseries_dims();
+dimensions{2} = struct('name','DIST_ALONG_BEAMS','typeCastFunc',getIMOSType('DIST_ALONG_BEAMS'),'data',[]);
+end
+
+function [dimensions] = adcp_remapped_dims()
+dimensions = timeseries_dims();
+dimensions{2} = struct('name','HEIGHT_ABOVE_SENSOR','typeCastFunc',getIMOSType('HEIGHT_ABOVE_SENSOR'),'data',[]);
+end
+
+

Util/+IMOS/cellfun.m

@@ -0,0 +1,77 @@
+function [result, failed_items] = cellfun(func, icell)
+% function [result, failed_items] = cellfun(func,icell)
+%
+% A MATLAB cellfun function that wraps errors
+% in empty results.
+% The items that triggered the fails may be returned.
+%
+% Inputs:
+%
+% func [function_handle] - a FH to apply to each cell member
+% icell [cell[Any]] - a cell where func will be applied itemwise.
+%
+% Outputs:
+%
+% result [cell{any}] - the result of func(icell{k})
+% failed_items [cell{any}] - the icell{k} items that erroed.
+%
+% Example:
+%
+% %valid inputs
+% [result] = IMOS.cellfun(@iscell,{{},{}});
+% assert(all(cell2mat(result)));
+%
+% %empty results for invalid evaluations
+% [result,failed_items] = IMOS.cellfun(@zeros,{'a',1,'b'});
+% assert(isempty(result{1}))
+% assert(isequal(result{2},0))
+% assert(isempty(result{3}))
+% assert(isequal(failed_items{1},'a'))
+% assert(isequal(failed_items{2},'b'))
+%
+% author: [email protected]
+%
+narginchk(2, 2)
+
+if ~isfunctionhandle(func)
+    errormsg('First argument `func` is not a function handle')
+elseif ~iscell(icell)
+    errormsg('Second argument `icell` is not a cell')
+end
+
+nc = numel(icell);
+result = cell(1, nc);
+failed_items = {};
+fcount = 0;
+
+try
+    [result] = cellfun(func, icell, 'UniformOutput', false);
+catch
+
+    for k = 1:numel(icell)
+
+        try
+            result{k} = func(icell{k});
+        catch
+
+            if nargout > 1
+
+                if fcount == 0
+                    failed_items = cell(1, nc - k);
+                end
+
+                fcount = fcount + 1;
+                failed_items{fcount} = icell{k};
+            end
+
+        end
+
+    end
+
+end
+
+if nargout > 1 && fcount > 0
+    failed_items = failed_items(1:fcount);
+end
+
+end