source: trunk/src/nc2struct.m @ 773

Last change on this file since 773 was 771, checked in by sommeria, 11 years ago
File size: 14.6 KB
Line 
1%'nc2struct': transform a netcdf file in a corresponding matlab structure
2% it reads all the global attributes and all variables, or a selected list.
3% The corresponding dimensions and variable attributes are then extracted
4%----------------------------------------------------------------------
5% function [Data,var_detect,ichoice,errormsg]=nc2struct(nc,varargin)
6%
7% OUTPUT:
8%  Data: structure containing all the information of the netcdf file (or netcdf object)
9%           with (optional)fields:
10%                    .ListGlobalAttribute: cell listing the names of the global attributes
11%                    .Att_1,Att_2... : values of the global attributes
12%                    .ListVarName: list of variable names to select (cell array of  char strings {'VarName1', 'VarName2',...} )
13%                    .VarDimName: list of dimension names for each element of .ListVarName (cell array of string cells)                         
14%                    .Var1, .Var2....: variables (Matlab arrays) with names listed in .ListVarName
15%                  .ListDimName=list of dimension (added information, not requested for field description)
16%                  .DimValue= vlalues of dimensions (added information, not requested for field description)
17%                  .VarType= integers giving the type of variable as coded by netcdf= 2 for char, =4 for single,=( for double
18%  var_detect: vector with same length as the cell array ListVarName, = 1 for each detected variable and 0 else.
19%            var_detect=[] in the absence of input cell array
20%  ichoice: index of the selected line in the case of multiple choice
21%        (cell array of varible names with multiple lines) , =[] by default
22%INPUT:
23%  nc:  name of a netcdf file (char string) or netcdf object   
24%  additional arguments:
25%       -no additional arguments: all the variables of the netcdf file are read.
26%       -a cell array, ListVarName, made of  char strings {'VarName1', 'VarName2',...} )
27%         if ListVarName=[] or {}, no variable value is read (only global attributes and list of variables and dimensions)
28%         if ListVarName is absent, or = '*', ALL the variables of the netcdf file are read.
29%         if ListVarName is a cell array with n lines, the set of variables will be sought by order of priority in the list,
30%            while output names will be set by the first line
31%       - the string 'ListGlobalAttribute' followed by a list of attribute  names: reads only these attributes (fast reading)
32%       - the string 'TimeVarName', a string (the name of the variable considered as time), an integer or vector with integer values
33%            representing time indices to select for each variable, the cell of other input variable names.
34%       - the string 'TimeDimName', a string (the name of the dimension considered as time), an integer or vector with integer values
35%            representing time indices to select for each variable, the cell of other input variable names.
36
37%AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
38%  Copyright Joel Sommeria, 2008, LEGI / CNRS-UJF-INPG, sommeria@coriolis-legi.org.
39%AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
40%     This file is part of the toolbox UVMAT.
41%
42%     UVMAT is free software; you can redistribute it and/or modify
43%     it under the terms of the GNU General Public License as published by
44%     the Free Software Foundation; either version 2 of the License, or
45%     (at your option) any later version.
46%
47%     UVMAT is distributed in the hope that it will be useful,
48%     but WITHOUT ANY WARRANTY; without even the implied warranty of
49%     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
50%     GNU General Public License (file UVMAT/COPYING.txt) for more details.
51%AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
52   
53function [Data,var_detect,ichoice,errormsg]=nc2struct(nc,varargin)
54errormsg='';%default error message
55if isempty(varargin)
56    varargin{1}='*';
57end
58hhh=which('netcdf.open');% look for built-in matlab netcdf library
59
60if ~isequal(hhh,'')
61    %% default output
62    Data=[];%default
63    var_detect=[];%default
64    ichoice=[];%default
65   
66    %% open the netcdf file for reading
67    if ischar(nc)
68        if exist(nc,'file')
69            try
70                nc=netcdf.open(nc,'NC_NOWRITE');
71                testfile=1;
72            catch ME
73                errormsg=['ERROR opening ' nc ': ' ME.message];
74                return
75            end
76        else
77            errormsg=['ERROR:file ' nc ' does not exist'];
78            return
79        end
80    else
81        testfile=0;
82    end
83   
84    %% short reading option for global attributes only, if the first argument is 'ListGlobalAttribute'
85    if isequal(varargin{1},'ListGlobalAttribute')
86        for ilist=2:numel(varargin)
87            valuestr=[];%default
88            try
89                valuestr = netcdf.getAtt(nc,netcdf.getConstant('NC_GLOBAL'),varargin{ilist});
90            catch ME
91            end
92            eval(['Data.' varargin{ilist} '=valuestr;'])
93        end
94        netcdf.close(nc)
95        return
96    end
97   
98    %% time variable or dimension
99    input_index=1;
100    CheckTimeVar=0;
101    TimeVarName='';
102    if isequal(varargin{1},'TimeVarName')
103        TimeVarName=varargin{2};
104        CheckTimeVar=1;
105        TimeIndex=varargin{3};
106        input_index=4;% list of varibles to read is at fourth argument
107    elseif isequal(varargin{1},'TimeDimName')
108        TimeDimName=varargin{2};
109        TimeIndex=varargin{3};
110        input_index=4;
111    end
112   
113    %% full reading: get the nbre of dimensions, variables, global attributes
114    ListVarName=varargin{input_index};
115    [ndims,nvars,ngatts]=netcdf.inq(nc);%nbre of dimensions, variables, global attributes, in the netcdf file
116   
117    %%  -------- read all global attributes (constants)-----------
118    Data.ListGlobalAttribute={};%default
119    att_key=cell(1,ngatts);%default
120    for iatt=1:ngatts
121        keystr= netcdf.inqAttName(nc,netcdf.getConstant('NC_GLOBAL'),iatt-1);
122        valuestr = netcdf.getAtt(nc,netcdf.getConstant('NC_GLOBAL'),keystr);
123        keystr=regexprep(keystr,{'\','/','\.','-',' '},{'','','','',''});%remove  '\','.' or '-' if exists
124        if strcmp(keystr(1),'_')
125            keystr(1)=[];
126        end
127        try
128            if ischar(valuestr) %& length(valuestr)<200 & double(valuestr)<=122 & double(valuestr)>=48 %usual characters
129                eval(['Data.' keystr '=''' valuestr ''';'])
130            elseif isnumeric(valuestr)
131                eval(['Data.' keystr '=valuestr;'])
132            else
133                eval(['Data.' keystr '='';'])
134            end
135            att_key{iatt}=keystr;
136        catch ME
137            att_key{iatt}=['attr_' num2str(iatt)];
138            Data.(att_key{iatt})=[];
139        end
140    end
141    Data.ListGlobalAttribute=att_key;
142   
143    %%  -------- read dimension names-----------
144    ListDimNameNetcdf=cell(1,ndims);
145    dim_value=zeros(1,ndims);
146    for idim=1:ndims %loop on the dimensions of the netcdf file
147        [ListDimNameNetcdf{idim},dim_value(idim)] = netcdf.inqDim(nc,idim-1);%get name and value of each dimension
148    end
149    if ~isempty(ListDimNameNetcdf)
150        flag_used=zeros(1,ndims);%initialize the flag indicating the selected dimensions in the list (0=unused)
151    end
152    if isequal(varargin{1},'TimeDimName')% time dimension introduced
153        TimeDimIndex=find(strcmp(TimeDimName,ListDimNameNetcdf));
154        if isempty(TimeDimIndex)
155            errormsg=['requested time dimension ' varargin{2} ' not found'];
156            return
157        end
158        if dim_value(TimeDimIndex)<varargin{3}
159           errormsg=['requested time index ' num2str(varargin{3}) ' exceeds matrix dimension'];
160            return
161        end
162    end 
163   
164    %%  -------- read names of variables -----------
165    ListVarNameNetcdf=cell(1,nvars); %default
166    dimids=cell(1,nvars);
167    nbatt=zeros(1,nvars);
168    for ncvar=1:nvars %loop on the variables of the netcdf file
169        %get name, type, dimensions and attribute numbers of each variable
170        [ListVarNameNetcdf{ncvar},xtype(ncvar),dimids{ncvar},nbatt(ncvar)] = netcdf.inqVar(nc,ncvar-1);
171    end
172%     testmulti=0;
173    if isequal(ListVarName,'*')||isempty(ListVarName)
174        var_index=1:nvars; %all the variables are selected in the netcdf file
175        Data.ListVarName=ListVarNameNetcdf;
176    else   %select input variables, if requested by the input ListVarName
177        check_keep=ones(1,size(ListVarName,2));
178        for ivar=1:size(ListVarName,2) % check redondancy of variable names
179            if ~isempty(find(strcmp(ListVarName{1,ivar},ListVarName(1:ivar-1)), 1))
180                check_keep(ivar)=0;% the variable #ivar is already in the list
181            end
182        end
183        ListVarName=ListVarName(:,logical(check_keep));
184        if size(ListVarName,1)>1 %multiple choice of variable ranked by order of priority
185            for iline=1:size(ListVarName,1)
186                search_index=find(strcmp(ListVarName{iline,1},ListVarNameNetcdf),1);%look for the first variable name in the list of netcdf variables
187                if ~isempty(search_index)
188                    break % go to the next line
189                end
190            end
191            ichoice=iline-1;%selected line number in the list of input names of variables
192        else
193            iline=1;
194        end
195        %ListVarName=ListVarName(iline,:);% select the appropriate option for input variable (lin ein the input name matrix)
196        if CheckTimeVar
197            TimeVarIndex=find(strcmp(TimeVarName,ListVarNameNetcdf),1); %look for the index of the time variable in the netcdf list
198            if isempty(TimeVarIndex)
199                errormsg='requested variable for time is missing';
200                return
201            end
202            TimeDimIndex=dimids{TimeVarIndex}(1)+1;
203            ListVarName=[ListVarName {TimeVarName}];
204        end
205        var_index=zeros(1,size(ListVarName,2));%default list of variable indices
206        for ivar=1:size(ListVarName,2)
207            search_index=find(strcmp(ListVarName{iline,ivar},ListVarNameNetcdf),1);%look for the variable name in the list of netcdf file
208            if ~isempty(search_index)
209                var_index(ivar)=search_index;%index of the netcdf list corresponding to the input list index ivar
210            end
211        end
212        var_detect=(var_index~=0);%=1 for detected variables
213        list_index=find(var_index);% indices in the input list corresponding to a detected variable
214        var_index=var_index(list_index);% netcdf variable indices corresponding to the output list of read variable
215        Data.ListVarName=ListVarName(1,list_index);%the first line of ListVarName sets the output names of the variables
216    end
217   
218    %% get the dimensions and attributes associated to  variables
219    var_dim=cell(size(var_index));% initiate list of dimensions for variables
220    for ivar=1:length(var_index)
221        var_dim{ivar}=dimids{var_index(ivar)}+1; %netcdf dimension indices used by the variable #ivar
222        Data.VarDimName{ivar}=ListDimNameNetcdf(var_dim{ivar});
223        flag_used(var_dim{ivar})=ones(size(var_dim{ivar}));%flag_used =1 for the indices of used dimensions
224        for iatt=1:nbatt(var_index(ivar))
225            attname = netcdf.inqAttName(nc,var_index(ivar)-1,iatt-1);
226            valuestr= netcdf.getAtt(nc,var_index(ivar)-1,attname);
227            attname=regexprep(attname,{'\','/','\.','-',' '},{'','','','',''});%remove  '\','.' or '-' if exists
228            if strcmp(attname(1),'_')
229                attname(1)=[];
230            end
231            try
232                if isempty(valuestr)
233                    Data.VarAttribute{ivar}.(attname)=valuestr;
234                end
235            catch ME
236                display(attname)
237                display(valuestr)
238                display(ME.message)
239                Data.VarAttribute{ivar}.(['atrr_' num2str(iatt)])='not read';
240            end
241        end
242    end
243   
244    %% select the dimensions used for the set of input variables
245    if ~isempty(var_index)
246        dim_index=find(flag_used);%list of netcdf dimensions indices corresponding to used dimensions
247        Data.ListDimName=ListDimNameNetcdf(dim_index);
248        Data.DimValue=dim_value(dim_index);
249        if input_index==4% if a dimension is selected as time
250            Data.DimValue(TimeDimIndex)=numel(TimeIndex);
251        end
252    end
253   
254    %% get the values of the input variables
255    if  ~isempty(ListVarName)
256        for ivar=1:length(var_index)
257            VarName=Data.ListVarName{ivar};
258            VarName=regexprep(VarName,'-','_'); %suppress '-' if it exists in the netcdf variable name (leads to errors in matlab)
259%             CheckSub=0;
260            if input_index==4% if a dimension is selected as time
261                ind_vec=zeros(1,numel(var_dim{ivar}));% vector with zeros corresponding to al the dimensions of the variable VarName
262                ind_size=dim_value(var_dim{ivar});% vector giving the size (for each dimension) of the variable VarName
263                index_time=find(var_dim{ivar}==TimeDimIndex);
264                if ~isempty(index_time)
265                    if ind_size(index_time)<max(TimeIndex)
266                        errormsg=['requested index ' num2str(TimeIndex) ' exceeds matrix dimension'];
267                        return
268                    end
269                    ind_vec(index_time)=TimeIndex-1;% selected index(or indices) to read
270                    ind_size(index_time)=numel(TimeIndex);%length of the selected set of time indices
271                    if numel(TimeIndex)==1 && ~strcmp(VarName,TimeVarName)
272                        Data.VarDimName{ivar}(index_time)=[];% for a single selected time remove the time in the list of dimensions (except for tTime itself)
273                    end
274                end                   
275                Data.(VarName)=double(netcdf.getVar(nc,var_index(ivar)-1,ind_vec,ind_size)); %read the variable data
276                Data.(VarName)=squeeze(Data.(VarName));%remove singeton dimension
277            else
278                Data.(VarName)=netcdf.getVar(nc,var_index(ivar)-1); %read the whole variable data
279            end
280            if xtype(var_index(ivar))==5
281                Data.(VarName)=double(Data.(VarName)); %transform to double for single pecision
282            end
283        end
284    end
285    Data.VarType=xtype(var_index);
286   
287    %%  -------- close fle-----------
288    if testfile==1
289        netcdf.close(nc)
290    end
291   
292    %% old netcdf library
293else
294    [Data,var_detect,ichoice]=nc2struct_toolbox(nc,varargin);
295end
Note: See TracBrowser for help on using the repository browser.