source: trunk/src/nc2struct.m @ 1157

Last change on this file since 1157 was 1157, checked in by sommeria, 3 months ago

filter_time added

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