check_field_structure

'check_field_structure': check the representation of fields by a Matlab structure 
----------------------------------------------------------------------
 function [DataOut,errormsg]=check_field_structure(Data)

 OUTPUT:
  Data: structure reproducing the input structure Data, with the additional elements:
           with fields:

            .ListDimName: cell listing the names of the array dimensions
               .DimValue: array dimension values (Matlab vector with the same length as .ListDimName
            .VarDimIndex: cell containing the set of dimension indices (in list .ListDimName) for each variable of .ListVarName
            .VarDimName: cell containing a cell of dimension names (in list .ListDimName) for each variable of .ListVarName
 errormsg: error message which is not empty when the input structure does not have the right form

INPUT:
 Data:   structure containing 
         (optional) .ListGlobalAttribute: cell listing the names of the global attributes
                    .Att_1,Att_2... : values of the global attributes
         (requested)  .ListVarName: list of variable names to select (cell array of  char strings {'VarName1', 'VarName2',...} ) 
         (requested)  .VarDimName: list of dimension names for each element of .ListVarName (cell array of string cells)                         
         (requested) .Var1, .Var2....: variables (Matlab arrays) with names listed in .ListVarName

0001 %'check_field_structure': check the representation of fields by a Matlab structure
0002 %----------------------------------------------------------------------
0003 % function [DataOut,errormsg]=check_field_structure(Data)
0004 %
0005 % OUTPUT:
0006 %  Data: structure reproducing the input structure Data, with the additional elements:
0007 %           with fields:
0008 %
0009 %            .ListDimName: cell listing the names of the array dimensions
0010 %               .DimValue: array dimension values (Matlab vector with the same length as .ListDimName
0011 %            .VarDimIndex: cell containing the set of dimension indices (in list .ListDimName) for each variable of .ListVarName
0012 %            .VarDimName: cell containing a cell of dimension names (in list .ListDimName) for each variable of .ListVarName
0013 % errormsg: error message which is not empty when the input structure does not have the right form
0014 %
0015 %INPUT:
0016 % Data:   structure containing
0017 %         (optional) .ListGlobalAttribute: cell listing the names of the global attributes
0018 %                    .Att_1,Att_2... : values of the global attributes
0019 %         (requested)  .ListVarName: list of variable names to select (cell array of  char strings {'VarName1', 'VarName2',...} )
0020 %         (requested)  .VarDimName: list of dimension names for each element of .ListVarName (cell array of string cells)
0021 %         (requested) .Var1, .Var2....: variables (Matlab arrays) with names listed in .ListVarName
0022 
0023 
0024 function [DataOut,errormsg]=check_field_structure(Data)
0025 DataOut=[]; %default
0026 errormsg=[];
0027 if ~isstruct(Data)
0028     errormsg='input field is not a structure';
0029     return
0030 end
0031 if isfield(Data,'ListVarName') && iscell(Data.ListVarName)
0032     nbfield=numel(Data.ListVarName); 
0033 else
0034     errormsg='input field does not contain the list of variables .ListVarNames';
0035     return
0036 end
0037 %check dimension names
0038 % definition by VarDimIndex (obsolete)
0039 if ~isfield(Data,'VarDimName') && isfield(Data,'VarDimIndex') && isfield(Data,'ListDimName')%old convention
0040     for ivar=1:nbfield
0041         DimCell=Data.VarDimIndex{ivar};
0042         if isnumeric(DimCell)
0043             if DimCell <= numel(Data.ListDimName)
0044                 Data.VarDimName{ivar}=Data.ListDimName(DimCell);
0045             else                      
0046                 errormsg='dimension names not defined';
0047                 return 
0048             end
0049         else 
0050             errormsg='unrecognized format for .VarDimIndex';
0051         end
0052     end
0053 end
0054 if ~(isfield(Data,'VarDimName') && iscell(Data.VarDimName))
0055     errormsg='input field does not contain the list of dimensions .VarDimName';
0056     return
0057 end
0058 if isfield(Data,'DimValue')
0059     Data=rmfield(Data,'DimValue');
0060 end
0061 if isfield(Data,'VarDimName') && iscell(Data.VarDimName)
0062     nbdim=0;
0063     if numel(Data.VarDimName)==nbfield
0064         for ivar=1:nbfield
0065             VarName=Data.ListVarName{ivar};
0066             if ~isfield(Data,VarName)
0067                 errormsg=['the listed variable ' VarName ' is not found'];
0068                 return
0069             else             
0070                 eval(['sizvar=size(Data.' VarName ');'])% sizvar = dimension of variable
0071                 DimCell=Data.VarDimName{ivar};
0072                 if ischar(DimCell)
0073                     DimCell={DimCell};
0074                 elseif ~iscell(DimCell)
0075                     errormsg=['wrong format for .VarDimName{' num2str(ivar) ' (must be the cell of dimension names of the variable ' VarName];
0076                     return
0077                 end
0078                 nbcoord=numel(sizvar);
0079 %                 Data.VarType{ivar}=[num2str(nbcoord) 'D'];%default
0080                 if numel(DimCell)==0
0081                     errormsg=['empty declared dimension .VarDimName{' num2str(ivar) '} for ' VarName];
0082                     return
0083                 elseif numel(DimCell)==1% one dimension declared
0084                     if nbcoord==2 
0085                         if sizvar(1)==1 
0086 %                             Data.VarType{ivar}='row';
0087                             nbcoord=1;
0088                             sizvar(1)=sizvar(2);
0089                         elseif sizvar(2)==1
0090 %                             Data.VarType{ivar}='column';
0091                             nbcoord=1;
0092                         else
0093                             errormsg=['1 dimension declared in .VarDimName{' num2str(ivar) '} inconsistent with the nbre of dimensions =2 of the variable ' VarName];
0094                             return
0095                         end
0096                     else
0097                           errormsg=['1 dimension declared in .VarDimName{' num2str(ivar) '} inconsistent with the nbre of dimensions =' num2str(nbcoord) ' of the variable ' VarName];
0098                           return      
0099                     end  
0100                 else
0101                     if nbcoord~=numel(DimCell)
0102                         errormsg=['nbre of declared dimensions in .VarDimName{' num2str(ivar) '} inconsistent with the nbre of dimensions =' num2str(nbcoord) ' of the variable ' VarName];
0103                         return
0104                     end
0105                 end
0106                 DimIndex=[];
0107                 for idim=1:nbcoord %loop on the coordinates of variable #ivar
0108                     DimName=DimCell{idim};
0109                     testprev=0;
0110                     for iprev=1:nbdim %check previously listed dimension names
0111                         if strcmp(Data.ListDimName{iprev},DimName)
0112                            if ~isequal(Data.DimValue(iprev),sizvar(idim))
0113                                if isequal(Data.DimValue(idim),0)  % the dimension has been already detected as range
0114                                    Data.DimValue(idim)=sizvar(idim); %update with actual value
0115                                elseif sizvar(idim)==2 && strcmp(DimName,VarName)
0116 %                                    Data.VarType{ivar}='range';  %case of a regularly spaced coordinate defined by the first and last values
0117                                else
0118                                    errormsg=['dimension declaration inconsistent with the size =[' num2str(sizvar) '] for ' VarName];
0119                                    return 
0120                                end
0121                            end
0122                            DimIndex=[DimIndex iprev];
0123                            testprev=1;
0124                            break
0125                         end
0126                     end
0127                     if ~testprev % a new dimension is appended to the list
0128                         nbdim=nbdim+1;
0129                         if sizvar(idim)==2 && strcmp(DimName,VarName)
0130                             Data.DimValue(nbdim)=0; %to be updated for a later variable
0131 %                             Data.VarType{ivar}='range';
0132                         else
0133                             Data.DimValue(nbdim)=sizvar(idim);
0134                         end
0135                         Data.ListDimName{nbdim}=DimName;
0136                         DimIndex=[DimIndex nbdim];
0137                     end
0138                 end
0139                 Data.VarDimIndex{ivar}=DimIndex;
0140             end
0141         end                               
0142     else
0143         errormsg=' .ListVarNames and .VarDimName have different lengths';
0144         return
0145     end
0146 else
0147     errormsg='input field does not contain the cell of dimension names .VarDimName for variables';
0148     return
0149 end
0150 DataOut=Data;
0151     
0152