(13Nov2002) PCWIN DLL Placement Revisited -- To help PCWIN Matlab find the Mex-file "mexcdf53.dll" and its associated "netcdf.dll", execute "rehash toolboxcache" at the prompt, after adjusting the Matlab path to include the location of the two DLLs.
(18Sep2002) PCWIN DLL Placement -- (See above.) See the "Troubleshooting" page on the issue of where to put the two DLLs in PCWIN installations of the NetCDF Toolbox. Some combination of the Matlab "bin", "bin\Win32", and "toolbox\local" directories generally works, but there seems to be no universal solution. (See above.)
(07Aug2001) NetCDF Toolbox Installer -- The "netcdf_install.m" installer has been corrected to better deal with new-lines, especially on PCWIN machines. Also, the NUMEL additions (see next item) seem to be working fine with Matlab 6.1. Please do not hesitate to contact me if the NetCDF Toolbox is misbehaving in any way on your machine.
(01Aug2001) NUMEL -- Very Important Notice For Matlab-6.1 -- Unlike earlier Matlabs, version 6.1 calls NUMEL, which we have now overloaded in each of the relevant NetCDF classes, where SUBSREF and SUBSASGN have also been overloaded. We believe the correct answer for NUMEL is always 1, because of the way we have traditionally programmed the NetCDF Toolbox. Our overloaded NUMEL calls a new function NUMEL_DEFAULT, which we have placed in the "ncutility" area. It returns 1 for all arguments. Since NUMEL is ignored in earlier Matlabs, our new NUMEL methods will have no effect on them. Download and install the NetCDF Toolbox as usual, using the M-file installer "netcdf_install.m" (see Step #2 below). Matlab 6.1 users -- please download and use the latest installer, then let us know what happens when you run "tnetcdf".
(01Mar2001) Character Data Inconvenience -- Unlike Matlab-5, Matlab-6 interprets negatively-valued characters as zero (0), thereby eliminating any opportunity to "cast" the data into the proper range. In "mexcdf53.c" and derivatives (such as "mexcdf60.c"), a callback is made to the Matlab built-in function called "setstr". If you are able, change the "setstr" callback string to "ncsetstr", then rebuild the mex-file. We have now added "ncsetstr.m" to the "nctype" subdirectory in the latest "netcdf_install" installer, and have also changed "mexcdf53.c" at this site accordingly. Henceforth, we will cast NetCDF character-data to the non-negative range (0:255) when importing it to Matlab. On export, the Matlab "abs" function will continue to be called. Only the "mexcdf53.mex" mex-file for PowerMacintosh has been upgraded at the present site. We would appreciate hearing from users who have re-built the mex-file for other machines, and would like to include them here as well.
(13Feb2001) Linux Users -- Get the file "mexcdf60.tar.gz" below. It contains the mex-file you need, called "mexcdf60.mexglx", plus modified versions of "ncmex.m" and "mexcdf.m" that recognize the name "mexcdf60". Courtesy of Nelson Hogg, Woods Hole Oceanographic Institution.
In order to maintain compatibility with all versions of Matlab-5, the NetCDF Toolbox does not use the following newer features introduced after Matlab 5.0: "persistent", "switch/case/otherwise", or "try/catch".
We refer to each NetCDF entity by its case-sensitive name, not by its internal NetCDF identification number: ('name') refers to a dimension object, {'name'} refers to a variable object, and .name refers to an attribute object. (N.B. The conventional NetCDF "_FillValue" attribute must be accessed as "FillValue_", since Matlab does not allow names to begin with underscore. The proper "_FillValue" is used internally.)
When indexing into a variable, we use the conventional Matlab left-to-right base-one scheme. The (:) operator is used to refer to all the elements along a particular dimension. Indices can be defaulted in the following way: whenever (:) is the rightmost given index, all remaining indices farther the right are assumed to be (:) as well; otherwise, they are assumed to be 1. Also, the Matlab concept of one-dimensional indexing has been extended; indices that exceed their particular dimension are folded into succeeding dimensions.
The () indexing operator is an essential ingredient of the syntax for extracting and replacing the contents of a NetCDF object. The Matlab assignment operator itself is not overloaded except when subscripting appears to the left of the equal-sign. Thus, if d were a NetCDF dimension object, then d(1) or simply d(:) would return its value, whereas d alone would return the object, not the value.
Behind the scenes, each request is translated into the syntax required by the "mexcdf53" gateway and the C-language interface to NetCDF, including the automatic conversion of indices to base-zero, and the permutation of data-order so that it transcribes properly. Users of the NetCDF toolbox can ignore these issues altogether, whereas direct-callers to old or new versions of the "mexcdf" driver must take special heed in such matters. To improve portability, "mexcdf" is now a Matlab M-file that calls "mexcdf53". The NetCDF Toolbox itself bypasses "mexcdf" and relies instead on another M-file, "ncmex", for its own work.
Imagine a NetCDF variable called "depth", whose dimensions are "latitude" and "longitude". There are two "coordinate-variables" to store the grid positions along the "latitude" and "longitude" directions where the "depth" data were collected. The depths are scaled in "meters", and the geographic positions are stored in "degrees". All the data are written in the appropriate default precision, either "double" for numbers or "char" for strings.Here is "ncexample", a Matlab function that stores and recalls some data.It can be found in the "ncutility" folder of the "NetCDF Toolbox".
function ncexample
% ncexample.m -- "NetCDF Toolbox for Matlab-5" example.
% ncexample (no argument) is a short example that lists
% itself, builds a simple NetCDF file, then displays
% its variables.
% Copyright (C) 1997 Dr. Charles R. Denham, ZYDECO.
% All Rights Reserved.
% Disclosure without explicit written consent from the
% copyright owner does not constitute publication.
% Version of 12-Jun-1997 16:23:04.
type(mfilename)
help(mfilename)
% ---------------------------- DEFINE THE FILE --------------------------- %
ncquiet % No NetCDF warnings.
nc = netcdf('ncexample.nc', 'clobber'); % Create NetCDF file.
nc.description = 'NetCDF Example'; % Global attributes.
nc.author = 'Dr. Charles R. Denham';
nc.date = 'June 9, 1997';
nc('latitude') = 10; % Define dimensions.
nc('longitude') = 10;
nc{'latitude'} = 'latitude'; % Define variables.
nc{'longitude'} = 'longitude';
nc{'depth'} = {'latitude', 'longitude'};
nc{'latitude'}.units = 'degrees'; % Attributes.
nc{'longitude'}.units = 'degrees';
nc{'depth'}.units = 'meters';
% ---------------------------- STORE THE DATA ---------------------------- %
latitude = [0 10 20 30 40 50 60 70 80 90]; % Matlab data.
longitude = [0 20 40 60 80 100 120 140 160 180];
depth = rand(length(latitude), length(longitude));
nc{'latitude'}(:) = latitude; % Put all the data.
nc{'longitude'}(:) = longitude;
nc{'depth'}(:) = depth;
nc = close(nc); % Close the file.
% ---------------------------- RECALL THE DATA --------------------------- %
nc = netcdf('ncexample.nc', 'nowrite'); % Open NetCDF file.
description = nc.description(:) % Global attribute.
variables = var(nc); % Get variable data.
for i = 1:length(variables)
disp([name(variables{i}) ' =']), disp(' ')
disp(variables{i}(:))
end
nc = close(nc); % Close the file.
% --------------------------------- DONE --------------------------------- %
The NetCDF Toolbox greatly simplifies interactions with NetCDF files from within Matlab, most notably because the syntax is based on operators and Matlab indexing. There are other pleasant features as well. For example, we did not call the "endef" NetCDF operation before populating the variables in the example. Both "redef" and "endef" are automated within the NetCDF toolbox and are invoked whenever the situation requires. (Users may still employ them manually, of course, because they both are methods of the "netcdf" class.)
In the example, we remembered only one object, the "netcdf" object called "nc". Because all of the components of the file were available through "nc", we did not need to remember a separate object for each one. For example, the expression "nc('latitude')" actually created an object itself, from class "ncdim", but there was no compelling need to remember it explicitly, since we made so little use of it.
There are times, however, when it does make sense to remember an object, especially an "ncvar" object that represents a NetCDF variable. Whenever the data in a NetCDF variable are too large for memory, they will need to be processed in a sequence of subsets. In the example, we could have remembered the "latitude" variable with the expression "lat = nc{'latitude'}", and then populated it in subsets by iterating with "lat(...) = latitude(...)", where "..." represents conventional Matlab indexing.