Home > atmlab > geographical > ungridded2gridded.m

ungridded2gridded

PURPOSE ^

% ungridded2gridded

SYNOPSIS ^

function [data,lat,lon] = ungridded2gridded(in,opt)

DESCRIPTION ^

% ungridded2gridded

 PURPOSE
       Puts statistics of ungridded data onto a grid. e.g by default the nan-removed mean
       and numel are given for each user defined grid box


 IN
       in      struct      containing 
                                       in.lat 
                                       in.lon
                                       in.(field)
                                       e.g. if in.field = 'uth',
                                       then in.uth is the data
                                       field to grid

                                       data,lat,lon, must be the same size



 OPT   structure 

       field   string      'stringname of datafield'

       grid    cell        containing either
                           one (degree) scalar or vector to be applied in both
                           directions {[%f]} or {[%f %f]}
                                              or
                           two (degree) scalars or vectors to be appllied
                           to the lat and lon dimensions
                             {[latdim],[londim]} = {[%f],[%f]} or {[%f %f],[%f %f]}

                           Default grid is a 1x1 deg

       func    {@fhandle/s}    Any function handle for the statistic you want
                               to calculate within each grid box. default =
                               {@mean,@numel}

       valid   @fhandle    Throws away all invalid values before apply
                           statistics. This function handle 
                           toggles what you mean by "valid". To keep all values
                           valid = ''; By default only keep positive values
                           i.e., valid = @(x)(x(x>=0)). WARNING: but if you input a
                           matrix per cell be aware that the above example will
                           collapse your data to a vector
         

       noStatistics        If you only want to bin the data and return a 2D
                           grid cell that contains all the original values
                           as vectors in the grid boxes, set noStatistics=true;
                           this also implies that arguments "func" and "valid"
                           are not used

      region               [blcorner,trcorner] (lat1,lon1,lat2,lon2)
                           This limits the gridding to area of
                           interest. If this is not given the
                           gridding is global (slower if unnecessary)

      replace              value (e.g., NaN, or {NaN,0} 
                           replace empty cells with in.replace. Make it a cell
                           if you want difference replace values for the
                           function handles. NaN is default
                           
      dataClass           'class' (default='double'). Ensures that the data in
                          the cell matrix from binned_statistics is all your
                          class of choosing. This is necessary if you want to
                          use cell2mat on your data.
 OUT   
      
      data                Structure containing the gridded statistics, and the
                          corresponding lat lons.
                          OR
                          if noStatistic = true; data is a cell grid.
      lat
      lon                 lat and lon are also included in the data structure
                          (if it is a structure)


 USAGE  e.g., [data,lat,lon] = ungridded2gridded(in,struct('field','something','grid',1,'func',@sum,'valid',@(x)(x(x>0)));
              %creates rectangular grid with sum per grid of the values (>0) that were binned into that grid

 $Id: ungridded2gridded.m 8570 2013-08-10 18:36:48Z seliasson $
 Salomon Eliasson

CROSS-REFERENCE INFORMATION ^

This function calls: This function is called by:

DOWNLOAD ^

ungridded2gridded.m

SOURCE CODE ^

0001 function [data,lat,lon] = ungridded2gridded(in,opt)
0002 %% ungridded2gridded
0003 %
0004 % PURPOSE
0005 %       Puts statistics of ungridded data onto a grid. e.g by default the nan-removed mean
0006 %       and numel are given for each user defined grid box
0007 %
0008 %
0009 % IN
0010 %       in      struct      containing
0011 %                                       in.lat
0012 %                                       in.lon
0013 %                                       in.(field)
0014 %                                       e.g. if in.field = 'uth',
0015 %                                       then in.uth is the data
0016 %                                       field to grid
0017 %
0018 %                                       data,lat,lon, must be the same size
0019 %
0020 %
0021 %
0022 % OPT   structure
0023 %
0024 %       field   string      'stringname of datafield'
0025 %
0026 %       grid    cell        containing either
0027 %                           one (degree) scalar or vector to be applied in both
0028 %                           directions {[%f]} or {[%f %f]}
0029 %                                              or
0030 %                           two (degree) scalars or vectors to be appllied
0031 %                           to the lat and lon dimensions
0032 %                             {[latdim],[londim]} = {[%f],[%f]} or {[%f %f],[%f %f]}
0033 %
0034 %                           Default grid is a 1x1 deg
0035 %
0036 %       func    {@fhandle/s}    Any function handle for the statistic you want
0037 %                               to calculate within each grid box. default =
0038 %                               {@mean,@numel}
0039 %
0040 %       valid   @fhandle    Throws away all invalid values before apply
0041 %                           statistics. This function handle
0042 %                           toggles what you mean by "valid". To keep all values
0043 %                           valid = ''; By default only keep positive values
0044 %                           i.e., valid = @(x)(x(x>=0)). WARNING: but if you input a
0045 %                           matrix per cell be aware that the above example will
0046 %                           collapse your data to a vector
0047 %
0048 %
0049 %       noStatistics        If you only want to bin the data and return a 2D
0050 %                           grid cell that contains all the original values
0051 %                           as vectors in the grid boxes, set noStatistics=true;
0052 %                           this also implies that arguments "func" and "valid"
0053 %                           are not used
0054 %
0055 %      region               [blcorner,trcorner] (lat1,lon1,lat2,lon2)
0056 %                           This limits the gridding to area of
0057 %                           interest. If this is not given the
0058 %                           gridding is global (slower if unnecessary)
0059 %
0060 %      replace              value (e.g., NaN, or {NaN,0}
0061 %                           replace empty cells with in.replace. Make it a cell
0062 %                           if you want difference replace values for the
0063 %                           function handles. NaN is default
0064 %
0065 %      dataClass           'class' (default='double'). Ensures that the data in
0066 %                          the cell matrix from binned_statistics is all your
0067 %                          class of choosing. This is necessary if you want to
0068 %                          use cell2mat on your data.
0069 % OUT
0070 %
0071 %      data                Structure containing the gridded statistics, and the
0072 %                          corresponding lat lons.
0073 %                          OR
0074 %                          if noStatistic = true; data is a cell grid.
0075 %      lat
0076 %      lon                 lat and lon are also included in the data structure
0077 %                          (if it is a structure)
0078 %
0079 %
0080 % USAGE  e.g., [data,lat,lon] = ungridded2gridded(in,struct('field','something','grid',1,'func',@sum,'valid',@(x)(x(x>0)));
0081 %              %creates rectangular grid with sum per grid of the values (>0) that were binned into that grid
0082 %
0083 % $Id: ungridded2gridded.m 8570 2013-08-10 18:36:48Z seliasson $
0084 % Salomon Eliasson
0085 
0086 errId = ['atmlab:' mfilename,':badInput'];
0087 
0088 if nargin==1, opt = struct(); end
0089 
0090 assert(any([isfield(in,'data'),isfield(opt,'field')]),...
0091     errId,'need some way of knowing what "field" to do the gridding on.\nSee doc %s.m\n',mfilename)
0092 
0093 default.grid                = {1};
0094 default.func                = {@mean,@numel};
0095 default.valid               = '';
0096 default.noStatistics        = false;
0097 default.field               = 'data';
0098 default.replace             = NaN;
0099 default.dataClass           = 'double';
0100 opt = optargs_struct(opt,default);
0101 if ~iscell(opt.func), opt.func={opt.func}; end
0102 if ~iscell(opt.grid), opt.grid={opt.grid};end
0103 if ~iscell(opt.replace), opt.replace={opt.replace};end
0104 
0105 assert(isequal(size(in.(opt.field)(:)),size(in.lat(:)),size(in.lon(:)))|isequal(size(in.(opt.field),1),size(in.lat(:),1),size(in.lon(:),1)),...
0106         errId,'"%s" lat, lon must be the same size, or the first dimension of "%s" is the same size as lat lon',opt.field,opt.field)
0107 
0108 % ---------------
0109 % Grid
0110 assert(~isfield(in,'gridsize'),errId,'input in.gridsize will be ignored as this is set in this function using in.grid (see help section)')
0111 assert(~isfield(opt,'gridsize'),errId,'input opt.gridsize will be ignored as this is set in this function using in.grid (see help section)')
0112 assert(iscell(opt.grid),errId,'in.grid must be a one or two element cell')
0113 
0114 if length(opt.grid)==1 && isscalar(opt.grid{1})
0115     in.gridsize = opt.grid{1};
0116     logtext(1,'Binning the data to a %gx%g grid\n',in.gridsize,in.gridsize)
0117 elseif length(opt.grid)==1
0118     in.newlat = opt.grid{1};
0119     in.newlon = opt.grid{1};
0120     logtext(1,'Binning the data to a cutom square grid\n')
0121 elseif length(opt.grid)==2 && isscalar(opt.grid{1})
0122     in.gridsize = [opt.grid{1},opt.grid{2}];
0123 elseif length(opt.grid)==2
0124     in.newlat = opt.grid{1};
0125     in.newlon = opt.grid{2};
0126     logtext(1,'Binning the data to a cutom rectangular grid\n')
0127 else
0128     error(errId,'grid is incorrect. See doc %s',mfilename)
0129 end
0130 
0131 % ----------------
0132 % BIN THE DATA
0133 
0134 [tmpdata,lat,lon] = binning_fast(catstruct(in,struct('data',in.(opt.field))));
0135 
0136 if opt.noStatistics
0137     % Leave after this if you want
0138     data = tmpdata;
0139     return    
0140 end
0141 data.lat = lat;
0142 data.lon = lon;
0143 for F = opt.func
0144     logtext(1,'Getting the statistic called "%s" within each gridcell\n',func2str(F{1}))
0145 end
0146 
0147 % --------------------
0148 % APPLY STATISTICS
0149 
0150 out = binned_statistics(tmpdata, opt.func , opt.valid, opt.replace, opt); % The NaN is to be put in place of empty grids
0151 
0152 flds = fieldnames(out);
0153 for i = 1: length(flds)
0154     % check that the cells only contain scalars
0155     data.fhandle2fieldname{i} = sprintf('%s = %s',flds{i},func2str(opt.func{i}));
0156     if any(~cellfun(@isscalar,out.(flds{i})(:)))
0157         logtext(atmlab('OUT'),'Not doing cell2mat(x) since it only works on scalars. Statistic: "%s" that saved in data.%s will remain a cell\n',data.fhandle2fieldname{i} ,flds{i})
0158         data.(flds{i}) = out.(flds{i});
0159         continue
0160     end    
0161     data.(flds{i}) = cell2mat(out.(flds{i}));
0162 end
0163 
0164 end

Generated on Mon 15-Sep-2014 13:31:28 by m2html © 2005