Home > . > find_field_indices.m

# find_field_indices

## PURPOSE

'find_file_indices': group the variables of a nc-formated Matlab structure into 'fields' with common dimensions

## SYNOPSIS

function [CellVarIndex,NbDim,VarType,errormsg]=find_field_indices(Data)

## DESCRIPTION

    'find_file_indices': group the variables of a nc-formated Matlab structure into 'fields' with common dimensions
    ----------------------------------------------------------------------
     function [DimVarIndex,CellVarIndex,NbDim,VarType]=find_field_indices(Data)

    OUTPUT:
     CellVaxIndex: cell whose elements are arrays of indices in the list data.ListVarName
                  CellvarIndex{i} represents a set of variables with the same dimensions
     NbDim: array with the length of CellVarIndex, giving its  space dimension
     VarType: cell array of structures with fields
          .coord_x, y, z: indices (in .ListVarname) of variables representing  unstructured coordinates x, y, z
          .vector_x,_y,_z: indices of variables giving the vector components x, y, z
          .warnflag: index of warnflag
          .errorflag: index of error flag
          .ancillary: indices of ancillary variables
          .image   : B/W image, (behaves like scalar)
          .color : color image, the last index, which is not a coordinate  variable, represent the color components
          .scalar: scalar field

## CROSS-REFERENCE INFORMATION

This function calls:

This function is called by:

- get_field 'get_field': display variables and attributes from a Netcdf file, and plot selected fields
- plot_field 'plot_field': plot any field with the structure defined in the uvmat package
- proj_field 'proj_field': projects the field on a projection object
- series 'series': master function associated to the GUI series.m for analysis field series
- uvmat 'uvmat': function associated with the GUI 'uvmat.fig' for images and data field visualization

## SOURCE CODE

    0001 %'find_file_indices': group the variables of a nc-formated Matlab structure into 'fields' with common dimensions
    0002 %----------------------------------------------------------------------
    0003 % function [DimVarIndex,CellVarIndex,NbDim,VarType]=find_field_indices(Data)
    0004 %
    0005 %OUTPUT:
    0006 % CellVaxIndex: cell whose elements are arrays of indices in the list data.ListVarName
    0007 %              CellvarIndex{i} represents a set of variables with the same dimensions
    0008 % NbDim: array with the length of CellVarIndex, giving its  space dimension
    0009 % VarType: cell array of structures with fields
    0010 %      .coord_x, y, z: indices (in .ListVarname) of variables representing  unstructured coordinates x, y, z
    0011 %      .vector_x,_y,_z: indices of variables giving the vector components x, y, z
    0012 %      .warnflag: index of warnflag
    0013 %      .errorflag: index of error flag
    0014 %      .ancillary: indices of ancillary variables
    0015 %      .image   : B/W image, (behaves like scalar)
    0016 %      .color : color image, the last index, which is not a coordinate  variable, represent the color components
    0017 %      .scalar: scalar field
    0018
    0019 %
    0020 %INPUT:
    0021 % Data: structure representing fields, output of check_field_structure
    0022 %            .ListDimName: cell listing the names of the array dimensions
    0023 %            .ListVarName: cell listing the names of the variables
    0024 %            .VarDimIndex: cell containing the set of dimension indices (in list .ListDimName) for each variable of .ListVarName
    0025 %
    0026 % HELP:
    0027 % to get the dimensions of arrays common to the field #icell
    0028 %         VarIndex=CellVarIndex{icell}; % list of variable indices
    0029 %         DimIndex=Data.VarDimIndex{VarIndex(1)} % list of dimensions for each variable in the cell #icell
    0030 %
    0031 %AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
    0032 %  Copyright Joel Sommeria, 2008, LEGI / CNRS-UJF-INPG, sommeria@coriolis-legi.org.
    0033 %AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
    0034 %     This file is part of the toolbox UVMAT.
    0035 %
    0036 %     UVMAT is free software; you can redistribute it and/or modify
    0037 %     it under the terms of the GNU General Public License as published by
    0038 %     the Free Software Foundation; either version 2 of the License, or
    0039 %     (at your option) any later version.
    0040 %
    0041 %     UVMAT is distributed in the hope that it will be useful,
    0042 %     but WITHOUT ANY WARRANTY; without even the implied warranty of
    0043 %     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    0044 %     GNU General Public License (file UVMAT/COPYING.txt) for more details.
    0045 %AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
    0046
    0047 function [CellVarIndex,NbDim,VarType,errormsg]=find_field_indices(Data)
    0048 CellVarIndex={};
    0049 NbDim=[];
    0050 VarType=[];
    0051 errormsg=[];
    0052 nbvar=numel(Data.ListVarName);%number of field variables
    0053 icell=0;
    0054 ivardim=0;
    0055 VarDimIndex=[];
    0056 VarDimName={};
    0057
    0058 if ~isfield(Data,'VarDimName')
    0059     errormsg='missing .VarDimName';
    0060     return
    0061 end
    0062
    0063 %loop on the list of variables
    0064 for ivar=1:nbvar
    0065     DimCell=Data.VarDimName{ivar}; %dimensions associated with the variable #ivar
    0066     if ischar(DimCell)
    0067         DimCell={DimCell};
    0068         Data.VarDimName{ivar}={Data.VarDimName{ivar}};%transform char chain into cell
    0069     end
    0070     testnewcell=1;
    0071     for icell_prev=1:numel(CellVarIndex)%detect whether the dimensions of ivar fit with an existing cell
    0072         PrevVarIndex=CellVarIndex{icell_prev};
    0073         PrevDimName=Data.VarDimName{PrevVarIndex(1)};
    0074         if isequal(PrevDimName,DimCell)
    0075             CellVarIndex{icell_prev}=[CellVarIndex{icell_prev} ivar];% add variable index #ivar to the cell #icell_prev
    0076             testnewcell=0; %existing cell detected
    0077             break
    0078         end
    0079     end
    0080     if testnewcell
    0081         icell=icell+1;
    0082         CellVarIndex{icell}=ivar;%put the current variabl index in the new cell
    0083     end
    0084
    0085     %look for dimension variables
    0086     if numel(DimCell)==1% if the variable has a single dimension
    0087         Role='';
    0088         if isfield(Data,'VarAttribute') && length(Data.VarAttribute)>=ivar && isfield(Data.VarAttribute{ivar},'Role')
    0089             Role=Data.VarAttribute{ivar}.Role;
    0090         end
    0091         if strcmp(DimCell{1},Data.ListVarName{ivar}) || strcmp(Role,'dimvar')
    0092             ivardim=ivardim+1;
    0093             VarDimIndex(ivardim)=ivar;%index of the variable
    0094             VarDimName{ivardim}=DimCell{1};%name of the dimension
    0095         end
    0096     end
    0097 end
    0098
    0099 % find the spatial dimensions and vector components
    0100 ListRole={'coord_x','coord_y','coord_z','vector_x','vector_y','vector_z','warnflag','errorflag',...
    0101     'ancillary','image','color','discrete','scalar'};
    0102 for icell=1:length(CellVarIndex)
    0103     for ilist=1:numel(ListRole)
    0104         eval(['ivar_' ListRole{ilist} '=[];'])
    0105     end
    0106     VarIndex=CellVarIndex{icell};%set of variable indices with the same dim
    0107     DimCell=Data.VarDimName{VarIndex(1)};% list of dimensions for each variable in the cell #icell
    0108     if isfield(Data,'VarAttribute');
    0109         VarAttribute=Data.VarAttribute;
    0110     else
    0111         VarAttribute={};
    0112     end
    0113     test_2D=0;
    0114     for ivar=VarIndex
    0115         if length(VarAttribute)>=ivar
    0116             if isfield(VarAttribute{ivar},'Role')
    0117                 role=VarAttribute{ivar}.Role;
    0118                 switch role
    0119                     case ListRole
    0120                         eval(['ivar_' role '=[ivar_' role ' ivar];'])
    0121                     otherwise
    0122                        ivar_scalar=[ivar_scalar ivar];
    0123                 end
    0124             else
    0125               ivar_scalar=[ivar_scalar ivar];% variable considered as scalar in the absence of Role attribute
    0126             end
    0127             if isfield(VarAttribute{ivar},'Coord_2')
    0128                 test_2D=1; %obsolete convention
    0129             end
    0130         else
    0131             ivar_scalar=[ivar_scalar ivar];% variable considered as scalar in the absence of variable a  attribute
    0132         end
    0133     end
    0134     for ilist=1:numel(ListRole)
    0135         eval(['VarType{icell}.' ListRole{ilist} '=ivar_' ListRole{ilist} ';'])
    0136     end
    0137     if numel(ivar_coord_x)>1 || numel(ivar_coord_y)>1 || numel(ivar_coord_z)>1
    0138         errormsg='multiply defined coordinates  in the same cell';
    0139         return
    0140     end
    0141     if numel(ivar_vector_x)>1 || numel(ivar_vector_y)>1 || numel(ivar_vector_z)>1
    0142         errormsg='more than one vector fields in the same cell';
    0143         return
    0144     end
    0145     NbDim(icell)=0;% nbre of space dimensions
    0146     if ~isempty(ivar_coord_z)
    0147         NbDim(icell)=3;
    0148     elseif ~isempty(ivar_coord_y)
    0149         NbDim(icell)=2;
    0150     elseif ~isempty(ivar_coord_x)
    0151         NbDim(icell)=1;
    0152     end
    0153
    0154     % look at coordinates variables
    0155     coord=zeros(1,numel(DimCell));%default
    0156     if NbDim(icell)==0 && ~isempty(VarDimName)% no unstructured coordinate found
    0157         for idim=1:numel(DimCell)   %loop on the dimensions of the variables in cell #icell
    0158             for ivardim=1:numel(VarDimName)
    0159                 if strcmp(VarDimName{ivardim},DimCell{idim})
    0160                     coord(idim)=VarDimIndex(ivardim);
    0161                     break
    0162                 end
    0163             end
    0164         end
    0165         NbDim(icell)=numel(find(coord));
    0166     end
    0167     VarType{icell}.coord=coord;
    0168     if NbDim(icell)==0 && test_2D %look at attributes Coord_1, coord_2 (obsolete convention)
    0169         NbDim(icell)=2;
    0170     end
    0171 end