LOADNC Interface to low level functions to read data from a NetCDF source.
Syntax:
VAR_DATA = LOADNC(URL)
VAR_DATA = LOADNC(URL, VAR_NAMES)
VAR_DATA = LOADNC(URL, VAR_NAMES, FIELD_NAMES)
[VAR_DATA, VAR_META, GLOBAL_META] = LOADNC(...)
Description:
VAR_DATA = LOADNC(URL) reads data from all variables in the NetCDF source
defined by string URL to struct VAR_DATA. For every variable there is a
field with the variable name as field name and the variable data as value
(see note on variable renaming). The URL might be the name of a local file
or an OPeNDAP url.
VAR_DATA = LOADNC(URL, VAR_NAMES) retrieves only variables named in string
cell array VAR_NAMES.
VAR_DATA = LOADNC(URL, VAR_NAMES, FIELD_NAMES) also retrieves variables
named in string cell array VAR_NAMES but performs a renaming, storing them
in fields named by string cell array FIELD_NAMES, which must be the same
size as VAR_NAMES.
[VAR_DATA, VAR_META] = LOADNC(...) reads also variable metadata to struct
VAR_META. For every variable field in VAR_DATA there is a field in VAR_META
with the same name, containing the metadata in a struct with fields:
NAME: string with the original variable name in the NetCDF source.
DATATYPE: string with the original variable NetCDF data type.
DIMENSIONS: cell array with the name of the dimensions of the variable.
ATTRIBUTES: struct array with the attributes of the variable with fields:
NAME: string with the attribute name.
VALUE: arbitrary typed value with the value of the attribute.
[VAR_DATA, VAR_META, GLOBAL_META] = LOADNC(...) reads also global
attributes and dimensions present in the NetCDF source to struct
GLOBAL_META, which has the following fields:
NAME: string with the url of the NetCDF resource (same as URL).
DIMENSIONS: struct array describing the dimensions with fields:
NAME: string with the dimension name.
LENGTH: number with the length of the dimension.
UNLIMITED: 1 if this is a record dimension, 0 otherwise.
ATTRIBUTES: struct array with global attributes with fields:
NAME: string with the attribute name.
VALUE: arbitrary typed value with the value of the attribute.
Notes:
Some variable names might not be valid field names. If field names are
not given, they are generated with the function GENVARNAME.
The original variable names are included in the variable metadata.
It would be more convenient to specify attributes in a struct with
attribute names as field names and attribute values as field values.
But due to a MATLAB limitation, it will cause trouble with attributes like
'_FillValue' (because it is not a valid field name).
Fill value and scale conversions are always performed.
Examples:
url = 'http://test.opendap.org:80/opendap/netcdf/examples/tos_O1_2001-2002.nc'
% Read all information at once.
[var_data, var_meta, global_meta] = loadnc(url)
% Retrieve data of interest without metadata.
var_data = loadnc(url, {'time', 'lon', 'lat', 'tos'})
% Retrieve data of interest with metadata.
[var_data, var_meta] = loadnc(url, {'time', 'lon', 'lat', 'tos'})
% Retrieve data renaming variables.
var_names = {'time', 'lon', 'lat', 'tos'}
new_names = {'time', 'longitude', 'latitude', 'temperature'}
var_data = loadnc(url, var_names, new_names)
[var_data, var_meta] = loadnc(url, var_names, new_names)
See also:
SAVENC
GENVARNAME
Authors:
Joan Pau Beltran <joanpau.beltran@socib.cat>0001 function [var_data, var_meta, global_meta] = loadnc(url, var_names, field_names) 0002 %LOADNC Interface to low level functions to read data from a NetCDF source. 0003 % 0004 % Syntax: 0005 % VAR_DATA = LOADNC(URL) 0006 % VAR_DATA = LOADNC(URL, VAR_NAMES) 0007 % VAR_DATA = LOADNC(URL, VAR_NAMES, FIELD_NAMES) 0008 % [VAR_DATA, VAR_META, GLOBAL_META] = LOADNC(...) 0009 % 0010 % Description: 0011 % VAR_DATA = LOADNC(URL) reads data from all variables in the NetCDF source 0012 % defined by string URL to struct VAR_DATA. For every variable there is a 0013 % field with the variable name as field name and the variable data as value 0014 % (see note on variable renaming). The URL might be the name of a local file 0015 % or an OPeNDAP url. 0016 % 0017 % VAR_DATA = LOADNC(URL, VAR_NAMES) retrieves only variables named in string 0018 % cell array VAR_NAMES. 0019 % 0020 % VAR_DATA = LOADNC(URL, VAR_NAMES, FIELD_NAMES) also retrieves variables 0021 % named in string cell array VAR_NAMES but performs a renaming, storing them 0022 % in fields named by string cell array FIELD_NAMES, which must be the same 0023 % size as VAR_NAMES. 0024 % 0025 % [VAR_DATA, VAR_META] = LOADNC(...) reads also variable metadata to struct 0026 % VAR_META. For every variable field in VAR_DATA there is a field in VAR_META 0027 % with the same name, containing the metadata in a struct with fields: 0028 % NAME: string with the original variable name in the NetCDF source. 0029 % DATATYPE: string with the original variable NetCDF data type. 0030 % DIMENSIONS: cell array with the name of the dimensions of the variable. 0031 % ATTRIBUTES: struct array with the attributes of the variable with fields: 0032 % NAME: string with the attribute name. 0033 % VALUE: arbitrary typed value with the value of the attribute. 0034 % 0035 % [VAR_DATA, VAR_META, GLOBAL_META] = LOADNC(...) reads also global 0036 % attributes and dimensions present in the NetCDF source to struct 0037 % GLOBAL_META, which has the following fields: 0038 % NAME: string with the url of the NetCDF resource (same as URL). 0039 % DIMENSIONS: struct array describing the dimensions with fields: 0040 % NAME: string with the dimension name. 0041 % LENGTH: number with the length of the dimension. 0042 % UNLIMITED: 1 if this is a record dimension, 0 otherwise. 0043 % ATTRIBUTES: struct array with global attributes with fields: 0044 % NAME: string with the attribute name. 0045 % VALUE: arbitrary typed value with the value of the attribute. 0046 % 0047 % Notes: 0048 % Some variable names might not be valid field names. If field names are 0049 % not given, they are generated with the function GENVARNAME. 0050 % The original variable names are included in the variable metadata. 0051 % 0052 % It would be more convenient to specify attributes in a struct with 0053 % attribute names as field names and attribute values as field values. 0054 % But due to a MATLAB limitation, it will cause trouble with attributes like 0055 % '_FillValue' (because it is not a valid field name). 0056 % 0057 % Fill value and scale conversions are always performed. 0058 % 0059 % Examples: 0060 % url = 'http://test.opendap.org:80/opendap/netcdf/examples/tos_O1_2001-2002.nc' 0061 % % Read all information at once. 0062 % [var_data, var_meta, global_meta] = loadnc(url) 0063 % % Retrieve data of interest without metadata. 0064 % var_data = loadnc(url, {'time', 'lon', 'lat', 'tos'}) 0065 % % Retrieve data of interest with metadata. 0066 % [var_data, var_meta] = loadnc(url, {'time', 'lon', 'lat', 'tos'}) 0067 % % Retrieve data renaming variables. 0068 % var_names = {'time', 'lon', 'lat', 'tos'} 0069 % new_names = {'time', 'longitude', 'latitude', 'temperature'} 0070 % var_data = loadnc(url, var_names, new_names) 0071 % [var_data, var_meta] = loadnc(url, var_names, new_names) 0072 % 0073 % See also: 0074 % SAVENC 0075 % GENVARNAME 0076 % 0077 % Authors: 0078 % Joan Pau Beltran <joanpau.beltran@socib.cat> 0079 0080 % Copyright (C) 2013-2016 0081 % ICTS SOCIB - Servei d'observacio i prediccio costaner de les Illes Balears 0082 % <http://www.socib.es> 0083 % 0084 % This program is free software: you can redistribute it and/or modify 0085 % it under the terms of the GNU General Public License as published by 0086 % the Free Software Foundation, either version 3 of the License, or 0087 % (at your option) any later version. 0088 % 0089 % This program is distributed in the hope that it will be useful, 0090 % but WITHOUT ANY WARRANTY; without even the implied warranty of 0091 % MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 0092 % GNU General Public License for more details. 0093 % 0094 % You should have received a copy of the GNU General Public License 0095 % along with this program. If not, see <http://www.gnu.org/licenses/>. 0096 0097 % Consider make the variable persistent. 0098 ISOCTAVE = exist('OCTAVE_VERSION','builtin'); 0099 0100 error(nargchk(1, 3, nargin, 'struct')); 0101 0102 if ISOCTAVE 0103 % Open the resource. 0104 nc = netcdf(url, 'r'); 0105 if (nargout < 2) && (nargin > 1) 0106 % Only selected variable data required, so go ahead for it. 0107 var_data = struct(); 0108 % If no variable renaming is specified preserve names as much as possible. 0109 if nargin < 3 0110 field_names = genvarname(var_names); 0111 end 0112 % Retrieve selected variable data. 0113 for var_idx = 1:numel(var_names) 0114 var_data.(field_names{var_idx}) = nc{var_names{var_idx}}(:); 0115 end 0116 else 0117 % Metadata required or selected variables not specified. 0118 var_data = struct(); 0119 var_meta = struct(); 0120 global_meta = struct(); 0121 % If no selected variables are specified, retrieve all variables. 0122 if nargin < 2 0123 nc_var_list = ncvar(nc); 0124 var_names = cellfun(@ncname, nc_var_list, 'UniformOutput', false); 0125 else 0126 nc_var_list = cellfun(@(v)(nc{v}), var_names, 'UniformOutput', false); 0127 end 0128 % If no variable renaming is specified preserve names as much as possible. 0129 if nargin < 3 0130 field_names = genvarname(var_names); 0131 end 0132 % Get available or selected variables, 0133 % variable data type, dimensions and attributes if any, 0134 % and variable data. 0135 for var_idx = 1:numel(nc_var_list) 0136 % Go for variable metadata. 0137 var_meta.(field_names{var_idx}) = struct(); 0138 % Get variable original name. 0139 var_meta.(field_names{var_idx}).name = ncname(nc_var_list{var_idx}); 0140 % Get variable original data type. 0141 var_meta.(field_names{var_idx}).datatype = ... 0142 ncdatatype(nc_var_list{var_idx}); 0143 % Get variable dimensions. 0144 nc_var_dim_list = ncdim(nc_var_list{var_idx}); 0145 var_meta.(field_names{var_idx}).dimensions = ... 0146 cellfun(@ncname, nc_var_dim_list, 'UniformOutput', false); 0147 % Get variable attributes. 0148 nc_var_att_list = ncatt(nc_var_list{var_idx}); 0149 var_meta.(field_names{var_idx}).attributes = ... 0150 struct('name', cell(size(nc_var_att_list)), ... 0151 'value', cell(size(nc_var_att_list))); 0152 for nc_var_att_idx = 1:numel(nc_var_att_list) 0153 var_meta.(field_names{var_idx}).attributes(nc_var_att_idx).name = ... 0154 ncname(nc_var_att_list{nc_var_att_idx}); 0155 var_meta.(field_names{var_idx}).attributes(nc_var_att_idx).value = ... 0156 nc_var_att_list{nc_var_att_idx}(:); 0157 end 0158 % Get variable data with invalid value and scale conversions enabled. 0159 ncautonan(nc_var_list{var_idx}, 1); 0160 ncautoscale(nc_var_list{var_idx}, 1); 0161 var_data.(field_names{var_idx}) = nc_var_list{var_idx}(:); 0162 end 0163 % Get global metadata: list of dimensions with its length and attributes. 0164 % Set global name (the url). 0165 global_meta.name = url; 0166 % Get global list of dimensions. 0167 nc_dim_list = ncdim(nc); 0168 global_meta.dimensions = struct('name', cell(size(nc_dim_list)), ... 0169 'length', cell(size(nc_dim_list)), ... 0170 'unlimited', cell(size(nc_dim_list))); 0171 for nc_dim_idx = 1:numel(nc_dim_list) 0172 global_meta.dimensions(nc_dim_idx).name = ... 0173 ncname(nc_dim_list{nc_dim_idx}); 0174 global_meta.dimensions(nc_dim_idx).length = ... 0175 nc_dim_list{nc_dim_idx}(:); 0176 global_meta.dimensions(nc_dim_idx).unlimited = ... 0177 ncisrecord(nc_dim_list{nc_dim_idx}); 0178 end 0179 % Get global attributes. 0180 nc_att_list = ncatt(nc); 0181 global_meta.attributes = struct('name', cell(size(nc_att_list)), ... 0182 'value', cell(size(nc_att_list))); 0183 for nc_att_idx = 1:numel(nc_att_list) 0184 global_meta.attributes(nc_att_idx).name = ... 0185 ncname(nc_att_list{nc_att_idx}); 0186 global_meta.attributes(nc_att_idx).value = nc_att_list{nc_att_idx}(:); 0187 end 0188 end 0189 % Close the resource. 0190 close(nc); 0191 else 0192 if (nargout < 2) && (nargin > 1) 0193 % Only selected variable data required, so go ahead for it. 0194 var_data = struct(); 0195 % If no variable renaming is specified preserve names as much as possible. 0196 if nargin < 3 0197 field_names = genvarname(var_names); 0198 end 0199 % Retrieve selected variable data. 0200 for var_idx = 1:numel(var_names) 0201 var_data.(field_names{var_idx}) = nc_varget(url, var_names{var_idx}); 0202 end 0203 else 0204 % Metadata required or selected variables not specified, 0205 % so full NetCDF description needed. 0206 var_data = struct(); 0207 var_meta = struct(); 0208 global_meta = struct(); 0209 nc_full_info = nc_info(url); 0210 % If no selected variables are specified, retrieve all variables. 0211 if nargin < 2 0212 % Dataset has no fields when there are no variables 0213 % (instead of being an empty struct but with the proper fields). 0214 nc_var_list = nc_full_info.Dataset; 0215 if isempty(nc_var_list) 0216 var_names = {}; 0217 else 0218 var_names = {nc_var_list.Name}; 0219 end 0220 else 0221 [nc_var_present, nc_var_select] = ... 0222 ismember(var_names, {nc_full_info.Dataset.Name}); 0223 nc_var_list = nc_full_info.Dataset(nc_var_select); 0224 end 0225 % If no variable renaming is specified preserve names as much as possible. 0226 if nargin < 3 0227 field_names = genvarname(var_names); 0228 end 0229 % Get available or selected variables, 0230 % variable data type, dimensions and attributes if any, 0231 % and variable data. 0232 for var_idx = 1:numel(nc_var_list) 0233 % Go for variable metadata. 0234 var_meta.(field_names{var_idx}) = struct(); 0235 % Get variable original name. 0236 var_meta.(field_names{var_idx}).name = nc_var_list(var_idx).Name; 0237 % Get variable original data type. 0238 var_meta.(field_names{var_idx}).datatype = ... 0239 nc_var_list(var_idx).Datatype; 0240 % Get variable dimensions. 0241 % Perform renaming to follow coding style guidelines, 0242 % and handle empty case for coherence. 0243 nc_var_dim_list = nc_var_list(var_idx).Dimension; 0244 if isempty(nc_var_dim_list) 0245 var_meta.(field_names{var_idx}).dimensions = {}; 0246 else 0247 var_meta.(field_names{var_idx}).dimensions = ... 0248 nc_var_list(var_idx).Dimension; 0249 end 0250 % Get variable attributes. 0251 % Perform renaming to follow coding style guidelines, 0252 % and handle empty case for coherence. 0253 nc_var_att_list = nc_var_list(var_idx).Attribute; 0254 if isempty(nc_var_att_list) 0255 var_meta.(field_names{var_idx}).attributes = ... 0256 struct('name', {}, 'value', {}); 0257 else 0258 var_meta.(field_names{var_idx}).attributes = ... 0259 struct('name', {nc_var_att_list.Name}, ... 0260 'value', {nc_var_att_list.Value}); 0261 end 0262 % Get variable data with invalid value and scale conversions enabled. 0263 var_data.(field_names{var_idx}) = nc_varget(url, var_names{var_idx}); 0264 end 0265 % Get global metadata: list of dimensions with its length and attributes. 0266 % Set global name (the url). 0267 global_meta.name = url; 0268 % Get global list of dimensions if any. 0269 % Perform renaming to follow coding style guidelines, 0270 % and handle empty case for coherence. 0271 nc_dim_list = nc_full_info.Dimension; 0272 if isempty(nc_dim_list) 0273 global_meta.dimensions = ... 0274 struct('name', {}, 'length', {}, 'unlimited', {}); 0275 else 0276 global_meta.dimensions = struct('name', {nc_dim_list.Name}, ... 0277 'length', {nc_dim_list.Length}, ... 0278 'unlimited', {nc_dim_list.Unlimited}); 0279 end 0280 % Get global attributes if any. 0281 % Perform renaming to follow coding style guidelines, 0282 % and handle empty case for coherence. 0283 nc_att_list = nc_full_info.Attribute; 0284 if isempty(nc_att_list) 0285 global_meta.attributes = struct('name', {}, 'value', {}); 0286 else 0287 global_meta.attributes = struct('name', {nc_att_list.Name}, ... 0288 'value', {nc_att_list.Value}); 0289 end 0290 end 0291 end 0292 0293 end