plotProfileStatistics

PLOTPROFILESTATISTICS  Plot vertical section of scatter data from a glider transect.

  Syntax:
    PLOTPROFILESTATISTICS(OPTIONS)
    PLOTPROFILESTATISTICS(OPT1, VAL1, ...)
    PLOTPROFILESTATISTICS(H, OPTIONS)
    PLOTPROFILESTATISTICS(H, OPT1, VAL1, ...)
    [HFIG, HAXS, HLGS, HLNS] = PLOTPROFILESTATISTICS(...)

  Description:
    PLOTPROFILESTATISTICS(OPTIONS) and 
    PLOTPROFILESTATISTICS(OPT1, VAL1, ...) generate a new figure with
    line plots of statistical profiles of gridded glider data according
    to options in  key-value pairs OPT1, VAL1... or in struct OPTIONS
    with field names as option keys and field values as option values.
    A profile statistic subplot is produced for each given variable,
    showing the mean value and the standard deviation of each given measured
    variable along the horizontal dimension over the given vertical coordinate
    for that subplot. The statistics are computed with the functions MEAN 
    and STD. The line plots are generated with the function PLOT.
    Recognized options are:
      MDATA: measurement data.
        Cell array of matrices with variable data from which the profile
        statistics will be computed. One subplot will be produced for each
        matrix. The subplot layout is given by the size of the cell array.
        The first dimension of each matrix should be the profile instance.
        The second dimension of each matrix should be the depth level.
        Default value: {[]}
      YDATA: vertical coordinate data.
        Cell array of vectors with the vertical coordinate data for each 
        subplot. The number of vectors in the cell array should match the 
        number of matrices in MDATA, and their lengths should match the second
        dimension of the corresponding matrix.
        Default value: {[]}
      XLABEL: horizontal axis label data.
        Struct array defining x label properties for each subplot.
        Label's text is in property 'String'.
        Default value: repmat(struct(), size(MDATA))
      YLABEL: vertical axis label data.
        Struct array defining y label properties for each subplot.
        Label's text is in property 'String'.
        Default value: repmat(struct(), size(MDATA))
      TITLE: axes title data.
        Struct array defining axes title properties for each subplot.
        Title's text is in property 'String'.
        Default value: repmat(struct(), size(MDATA))
      AXSPROPS: extra axis properties.
        Struct array of axis properties to be set for each subplot axes with 
        function SET.
        Default value: repmat(struct(), size(MDATA))
      FIGPROPS: extra figure properties.
        Struct of figure properties to be set for the figure with function SET.
        Default value: struct()

    PLOTPROFILESTATISTICS(H, ...) does not create a new figure,
    but plots to figure given by figure handle H.

    [HFIG, HAXS, HLGS, HLNS] = PLOTPROFILESTATISTICS(...) returns
    handles for the figure, subplot axes, subplot legends, and lineseries,
    in HFIG, HAXS, HLGS,  and HLNS, respectively. The dimesnions of HFIG, HAXS, 
    and HLGS match the number of suplots in the figure, MxN, and HLNS is 2xMxN,
    where M and N are the number of rows and columns in cell array MDATA.

  Examples:
    [hfig, haxs, hlgs, hlns] = ...
      plotProfileStatistics(gcf, ...
        'mdata', {rand(30,100) randn(30,100) 10.^rand(30,100)}, ...
        'ydata', {(1:30)' (1:30)' (1:30)'} , ...
        'xlabel', struct('String', {'x' 'x' 'x'}), ...
        'ylabel', struct('String', {'y' 'y' 'y'}), ...
        'title', struct('String', {'uniform profile' 'normal profile' 'exponential profile'}), ...
        'axsprops', struct('XGrid', {'on' 'on' 'on'}, ...
                           'YGrid', {'on' 'on' 'on'}, ...
                           'XScale',{'linear' 'linear' 'log'}), ...
        'figprops', struct('Name', 'Profile statistics example') )

  See also:
    MEAN
    STD
    PLOT
    SET

  Authors:
    Joan Pau Beltran  <joanpau.beltran@socib.cat>

0001 function [hfig, haxs, hlgs, hlns] = plotProfileStatistics(varargin)
0002 %PLOTPROFILESTATISTICS  Plot vertical section of scatter data from a glider transect.
0003 %
0004 %  Syntax:
0005 %    PLOTPROFILESTATISTICS(OPTIONS)
0006 %    PLOTPROFILESTATISTICS(OPT1, VAL1, ...)
0007 %    PLOTPROFILESTATISTICS(H, OPTIONS)
0008 %    PLOTPROFILESTATISTICS(H, OPT1, VAL1, ...)
0009 %    [HFIG, HAXS, HLGS, HLNS] = PLOTPROFILESTATISTICS(...)
0010 %
0011 %  Description:
0012 %    PLOTPROFILESTATISTICS(OPTIONS) and
0013 %    PLOTPROFILESTATISTICS(OPT1, VAL1, ...) generate a new figure with
0014 %    line plots of statistical profiles of gridded glider data according
0015 %    to options in  key-value pairs OPT1, VAL1... or in struct OPTIONS
0016 %    with field names as option keys and field values as option values.
0017 %    A profile statistic subplot is produced for each given variable,
0018 %    showing the mean value and the standard deviation of each given measured
0019 %    variable along the horizontal dimension over the given vertical coordinate
0020 %    for that subplot. The statistics are computed with the functions MEAN
0021 %    and STD. The line plots are generated with the function PLOT.
0022 %    Recognized options are:
0023 %      MDATA: measurement data.
0024 %        Cell array of matrices with variable data from which the profile
0025 %        statistics will be computed. One subplot will be produced for each
0026 %        matrix. The subplot layout is given by the size of the cell array.
0027 %        The first dimension of each matrix should be the profile instance.
0028 %        The second dimension of each matrix should be the depth level.
0029 %        Default value: {[]}
0030 %      YDATA: vertical coordinate data.
0031 %        Cell array of vectors with the vertical coordinate data for each
0032 %        subplot. The number of vectors in the cell array should match the
0033 %        number of matrices in MDATA, and their lengths should match the second
0034 %        dimension of the corresponding matrix.
0035 %        Default value: {[]}
0036 %      XLABEL: horizontal axis label data.
0037 %        Struct array defining x label properties for each subplot.
0038 %        Label's text is in property 'String'.
0039 %        Default value: repmat(struct(), size(MDATA))
0040 %      YLABEL: vertical axis label data.
0041 %        Struct array defining y label properties for each subplot.
0042 %        Label's text is in property 'String'.
0043 %        Default value: repmat(struct(), size(MDATA))
0044 %      TITLE: axes title data.
0045 %        Struct array defining axes title properties for each subplot.
0046 %        Title's text is in property 'String'.
0047 %        Default value: repmat(struct(), size(MDATA))
0048 %      AXSPROPS: extra axis properties.
0049 %        Struct array of axis properties to be set for each subplot axes with
0050 %        function SET.
0051 %        Default value: repmat(struct(), size(MDATA))
0052 %      FIGPROPS: extra figure properties.
0053 %        Struct of figure properties to be set for the figure with function SET.
0054 %        Default value: struct()
0055 %
0056 %    PLOTPROFILESTATISTICS(H, ...) does not create a new figure,
0057 %    but plots to figure given by figure handle H.
0058 %
0059 %    [HFIG, HAXS, HLGS, HLNS] = PLOTPROFILESTATISTICS(...) returns
0060 %    handles for the figure, subplot axes, subplot legends, and lineseries,
0061 %    in HFIG, HAXS, HLGS,  and HLNS, respectively. The dimesnions of HFIG, HAXS,
0062 %    and HLGS match the number of suplots in the figure, MxN, and HLNS is 2xMxN,
0063 %    where M and N are the number of rows and columns in cell array MDATA.
0064 %
0065 %  Examples:
0066 %    [hfig, haxs, hlgs, hlns] = ...
0067 %      plotProfileStatistics(gcf, ...
0068 %        'mdata', {rand(30,100) randn(30,100) 10.^rand(30,100)}, ...
0069 %        'ydata', {(1:30)' (1:30)' (1:30)'} , ...
0070 %        'xlabel', struct('String', {'x' 'x' 'x'}), ...
0071 %        'ylabel', struct('String', {'y' 'y' 'y'}), ...
0072 %        'title', struct('String', {'uniform profile' 'normal profile' 'exponential profile'}), ...
0073 %        'axsprops', struct('XGrid', {'on' 'on' 'on'}, ...
0074 %                           'YGrid', {'on' 'on' 'on'}, ...
0075 %                           'XScale',{'linear' 'linear' 'log'}), ...
0076 %        'figprops', struct('Name', 'Profile statistics example') )
0077 %
0078 %  See also:
0079 %    MEAN
0080 %    STD
0081 %    PLOT
0082 %    SET
0083 %
0084 %  Authors:
0085 %    Joan Pau Beltran  <joanpau.beltran@socib.cat>
0086 
0087 %  Copyright (C) 2013-2016
0088 %  ICTS SOCIB - Servei d'observacio i prediccio costaner de les Illes Balears
0089 %  <http://www.socib.es>
0090 %
0091 %  This program is free software: you can redistribute it and/or modify
0092 %  it under the terms of the GNU General Public License as published by
0093 %  the Free Software Foundation, either version 3 of the License, or
0094 %  (at your option) any later version.
0095 %
0096 %  This program is distributed in the hope that it will be useful,
0097 %  but WITHOUT ANY WARRANTY; without even the implied warranty of
0098 %  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
0099 %  GNU General Public License for more details.
0100 %
0101 %  You should have received a copy of the GNU General Public License
0102 %  along with this program.  If not, see <http://www.gnu.org/licenses/>.
0103 
0104   % No argument number checking since any number of arguments is allowed.
0105 
0106   %% Set plot options and default values.
0107   options = struct();
0108   options.mdata = {[]};
0109   options.ydata = {[]};
0110   options.xlabel = [];
0111   options.ylabel = [];
0112   options.title = [];
0113   options.axsprops = [];
0114   options.figprops = struct();
0115   
0116   
0117   %% Get optional figure handle and option arguments.
0118   if (nargin > 0) && isscalar(varargin{1}) && ishghandle(varargin{1})
0119     args = varargin(2:end);
0120     hfig = figure(varargin{1});
0121   else
0122     args = varargin;
0123     hfig = figure();
0124   end
0125   
0126   
0127   %% Get options from extra arguments.
0128   % Parse option key-value pairs in any accepted call signature.
0129   if isscalar(args) && isstruct(args{1})
0130     % Options passed as a single option struct argument:
0131     % field names are option keys and field values are option values.
0132     option_key_list = fieldnames(args{1});
0133     option_val_list = struct2cell(args{1});
0134   elseif mod(numel(args), 2) == 0
0135     % Options passed as key-value argument pairs.
0136     option_key_list = args(1:2:end);
0137     option_val_list = args(2:2:end);
0138   else
0139     error('glider_toolbox:plotProfileStatistics:InvalidOptions', ...
0140           'Invalid optional arguments (neither key-value pairs nor struct).');
0141   end
0142   % Overwrite default options with values given in extra arguments.
0143   for opt_idx = 1:numel(option_key_list)
0144     opt = lower(option_key_list{opt_idx});
0145     val = option_val_list{opt_idx};
0146     if isfield(options, opt)
0147       options.(opt) = val;
0148     else
0149       error('glider_toolbox:plotProfileStatistics:InvalidOption', ...
0150             'Invalid option: %s.', opt);
0151     end
0152   end
0153   
0154   
0155   %% Update subplot options not already set to match number or subplots.
0156   subplot_option_name_list = {'xlabel' 'ylabel' 'title' 'axsprops'};
0157   for subplot_option_name_idx = 1:numel(subplot_option_name_list)
0158     subplot_option_name = subplot_option_name_list{subplot_option_name_idx};
0159     if isempty(options.(subplot_option_name))
0160       options.(subplot_option_name) = repmat(struct(), size(options.mdata));
0161     end
0162   end
0163   
0164   
0165   %% Set figure properties.
0166   set(hfig, options.figprops);
0167   
0168   
0169   %% Initialize and set properties of all plot elements.
0170   haxs = nan(size(options.mdata));
0171   hlgs = nan(size(haxs));
0172   hlns = nan([2 size(haxs)]);
0173   [m, n] = size(options.mdata);
0174   for s = 1:(m*n)
0175     ydata = options.ydata{s};
0176     mdata = options.mdata{s};
0177     % mrange = quantile(options.mdata{s}, [0.01 0.99]);
0178     % mdata(mdata < mrange(1) | mdata > mrange(2)) = nan;
0179     mmean = nanmean(mdata, 1);
0180     mstd = nanstd(mdata, 1, 1); % 1 to compute the second moment biased estimator.
0181     haxs(s) = subplot(m, n, s);
0182     % Use 0 because plot does not return lineseries handles if empty inputs.
0183     hlns(:,s) = plot(haxs(s), 0, 0, '-', 0, 0, ':'); 
0184     hlgs(s) = legend(hlns(:,s));
0185     haxstit = title(haxs(s), []);
0186     haxsxlb = xlabel(haxs(s), []);
0187     haxsylb = ylabel(haxs(s), []);
0188     axis([min(mmean-mstd) max(mmean+mstd) min(ydata) max(ydata)] * ...
0189          [1.1 -0.1 0 0; -0.1 1.1 0 0; 0 0 1 0; 0 0 0 1]);
0190     set(haxs(s), options.axsprops(s));
0191     color_order = get(haxs(s), 'ColorOrder');
0192     set(hlns(1,s), ...
0193         'LineWidth', 2 * get(haxs(s), 'LineWidth'), ...
0194         'Color', color_order(1, :), ...
0195         'YData', ydata(:), 'XData', mmean(:));
0196     set(hlns(2,s), ...
0197         'LineWidth', 2 * get(haxs(s), 'LineWidth'), ...
0198         'Color', color_order( 1 + rem(1,size(color_order,1)) , : ), ...
0199         'YData', [ydata(:); nan; ydata(:)], ...
0200         'XData', [(mmean(:) - mstd(:)); nan; (mmean(:) + mstd(:))]);
0201     reverse_x = strcmp(get(haxs(s), 'XDir'), 'reverse');
0202     reverse_y = strcmp(get(haxs(s), 'YDir'), 'reverse');
0203     increasing = [1 0] * nancov(mmean(:), ydata(:), 1) * [0 1]' > 0;
0204     legend_location_list = {'NorthWest' 'NorthEast'; 'SouthWest' 'SouthEast'};
0205     legend_location = ...
0206       legend_location_list{1 + reverse_y, ...
0207                            2 - xor(increasing, reverse_x)};
0208     set(hlgs(s), 'String', {'mean', 'std'}, 'Location', legend_location);
0209     set(haxstit, options.title(s));
0210     set(haxsxlb, options.xlabel(s));
0211     set(haxsylb, options.ylabel(s));
0212     
0213   end
0214 
0215 end