Home > . > check_field_structure.m

# check_field_structure

## PURPOSE

'check_field_structure': check the representation of fields by a Matlab structure

## SYNOPSIS

function [DataOut,errormsg]=check_field_structure(Data)

## DESCRIPTION

    '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

## CROSS-REFERENCE INFORMATION

This function calls:

This function is called by:

- plot_field 'plot_field': plot any field with the structure defined in the uvmat package
- struct2nc 'struct2nc': create a netcdf file from a Matlab structure
- struct2nc_toolbox 'struct2nc_toolbox': create a netcdf file from a Matlab structure: use of netcdf toolbox
- uvmat 'uvmat': function associated with the GUI 'uvmat.fig' for images and data field visualization

## SOURCE CODE

    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