You can contact me at 303-497-1708 or by emailing thoar 'at' ucar 'dot' edu
If you are at NCAR, my extension is simply 1708.
Matlab is an interpreted language that handles matrices with a natural syntax. This generally means a very short spin-up period for people unfamiliar with Matlab. One of Matlab's founding fathers (who is still president of the MathWorks) is Cleve Moler of Linpack fame.
As with any interpreted language, it is possible to write some incredibly slow F77 code. We recommend against that ... Take advantage of the vector- or matrix- based syntax and avoid loops whenever possible.
Matlab is gradually getting more JAVA-dependent, and the GUI interface is getting to be horribly slow to launch. It has some nice features that make it worthwhile if you are going to be using Matlab for 'a while', but for short sessions I find the launch time unacceptably long. Furthermore, I 'grew up' on the command line, so I'd just as soon use it for most purposes. For me, the motivation to use the GUI is the debugger. Another cool thing is the XML help ... put an "info.xml" file in a directory in the MATLABPATH and the directory is added to the help widget -- now called the "launchpad" ...
Nothing is really required, but there are some things that make life nicer, naturally.
mkdir ~/matlab mkdir ~/matlab/data/
Matlab automatically searches for a ~/matlab directory upon startup, this is a nice place to have general purpose scripts/functions. If there exists a ~/matlab/startup.m file, it is automatically executed upon startup. The file may contain any sequence of valid Matlab commands. If there are directories that contain certain third-party toolboxes, the obvious way to add them is with your startup.m file, which could be as simple as this:
% Startup.m is executed by the matlabrc script automatically at startup. % path(path,'~/data'); % append this directory to your MATLABPATHI frequently insert the following to add support for netCDF (this assumes they have been installed into '/contrib/matlab', which is by no means 'standard'):
disp('Adding the netCDF toolbox and the CSIRO netCDF support.')
addpath /contrib/matlab/mexnc
addpath /contrib/matlab/snctools
addpath /contrib/matlab/netcdf_toolbox/netcdf
addpath /contrib/matlab/netcdf_toolbox/netcdf/nctype
addpath /contrib/matlab/netcdf_toolbox/netcdf/ncutility
addpath /contrib/matlab/matlab_netCDF_OPeNDAP
Simply type matlab -nojvm at the UNIX prompt. If your (unix) PATH is correct, this will work. Windows and Mac users may have a little Matlab icon on the desktop/dock ... that works too, naturally. You can fire up Matlab from any directory and your MATLABPATH will be set to search the normal Matlab installation, anything specified in your ~/matlab/startup.m file, and the current working directory (which, for the icon startups, is a bit obfuscated).
The matlab prompt is:
>>if you didn't get the little splash screen, it means your DISPLAY is not set properly, which will make graphics a challenge. Let me know ASAP.
>> quit
There are lots of ways to get help in Matlab. Simply typing help
at the command line gets you started. If you know the command you want,
(for example "fft") simply type help fft.
If you do not know the name of the command, you can look for functions
by keywords -- lookfor fft, for example. This works for ALL functions
in the MATLABPATH, including the ones you create. More on this when we get
into the function section, ditto for "help".
If you are running with the JAVA interface, Matlab also has an interactive
WWW-based help system, called HelpDesk. This is the 800# gorilla of help.
Search all the manuals, connect to the MathWorks FAQ site, list by topics,
alphabetically, etc. It will commandeer your browser, simply by typing
helpdesk. "If you don't have one; GET ONE!"
Matlab is short for Matrix Laboratory. If you can think of the algebra in 2D, it will probably work exactly as you expect. The thing to get used to is that any command without a ";" at the end will print the result of the command to the screen. Not particularly desirable for large results. I am in the habit of terminating every command with a ";", whether it needs one or not.
General help for all the relational operators can be had with help relops. The only tricky part is that the square brackets are used for defining arrays, parentheses are for indexing, and the variables MUST be conformable.
a = [0:127]; % "a" is a row vector
b = cos(2*pi*a/length(a)); % so is "b"
plot(b(1:64)); % only plot the first 64 elements
title('My mental retention prowess.');
xlabel('(minutes)');
ylabel('fraction of capacity');
Multiplying a 10x3 matrix by a 10x3 matrix will generate an error message, unless you want the operator to work on an element-by-element basis. Here is another example of trying to multiply a 1xN matrix by another 1xN matrix ... simply not possible ...
size(a) size(b) a*bFor example, if you want to multiply each element of an array by the corresponding element of another array:
c = a.*b; % should be reminiscent of the "dot product" d = sum(c); % wow
It is best to simply ignore the existence of vectors and just admit they are really N x 1 or 1 x N matrices. All the rules of matrix algebra apply. Some functions are tailored for 1D matrices and can be used on higher-dimensional matrices, like sum.
c = b'*b; % premultiplying b by its transpose -> 128 x 128 d = sum(c) % what is "d"? (semicolon intentionally left off) imagesc(c); % color-code the result and plot colorbar; % plot a legend
The classic one is fft. Taking the fft of a 1D variable is pretty clear. What happens if you feed fft a M x N matrix? Matlab grew from Fortran beginnings, so it takes ffts of each column, since these are stored sequentially in memory (and it can take unit strides). If you want a real 2D fft, use fft2. This is a common theme in Matlab. Operations that have a different connotation for 2D as opposed to 1D have an additional "2" in the function name.
load topo;
wow = topo - mean(topo(:));
C = fft(wow); % take the fft of each column of "c"
whos % "who and size" (semicolon intentionally left off)
D = fft2(wow);
subplot(2,2,1)
imagesc(real(C))
title('Real part of FFT of each column')
colorbar
subplot(2,2,2)
imagesc(fftshift(real(D)))
title('Real part of 2DFFT')
colorbar
subplot(2,2,3)
imagesc(imag(C))
title('Imaginary part of FFT of each column')
colorbar
subplot(2,2,4)
imagesc(fftshift(imag(D)))
title('Imaginary part of 2DFFT')
colorbar
There are simply hundreds of third-party books and toolboxes. Check
out the MathWorks home page
and poke around.
first, we copy the ascii file to
~/data/soi.ascii and get on with it. The matlab variable will be
the filename without the extension, so we should wind up with
a variable called soi.
The only thing tricky about contour plots in matlab is the resulting
orientation. (1,1) is at the bottom left.
Changing the number of contour lines is easy.
Specifying which contour levels is also easy.
Personally, I like the imageplots a lot better, they give clues as
to the original resolution. However, the plot has (1,1) in the upper left.
The solution to A*X = B is simply X = A\B;
Pretty boring, but true.
Just for grins, put
worldmap.m in
your ~/matlab directory.
Just for grins, put
sinusoid.m in
your ~/matlab directory.
Also try the
free mapping routines
in the SEA-MAT distribution.
By now, you should be sick of cutting and pasting. Enter the script,
generically called a ".m" file. By inserting your matlab commands
into a file called (for example) foo.m, you can simply type
"foo" at the Matlab prompt and the entire file is checked for syntax
and executed. Put the following lines in a file called
~/matlab/foo.m:
Then, (one at a time) from Matlab's command line:
A Matlab Function is a special .m file. The first line of
the file is the function declaration.
You can peruse most functions with type.
The FIRST line of the help file should contain some keywords.
This is the only line searched by the lookfor function.
profile your favorite script/function --- VERY impressive.
follow the example from "help profile"
Perhaps the best part of Matlab. Infinitely customizable graphics.
You will definitely want
wysiwyg.m in
your ~/matlab directory.
Easy, as long as you know how the data is written.
For this exercise, save
some binary data as
~/matlab/data/chi_jan96.ieee
With a clever combination of fread, I feel supremely confident in
the ability to read any valid file. Read the help file for fread and
fopen
The binary file below was written in the following manner:
Basically exactly the same as the unformatted binary without the little
4 byte record headers/enders. Every record is constrained to be the same,
however. The logical format is:
The most flexible yet. "Let the buyer beware". C binary generally
comes with no header bytes, everything is simply data pasted together.
If you get off by a byte, you get garbage. There is no error-checking.
You can mix reads of different lengths and data types in any fashion.
The following is snytactically correct, but may not match the data at all.
Lots of postscript files are simply ascii files of postscript commands.
You can view and change the source with your favorite editor. This shifts
the burden of rendering the figure from the computer to the printer. There
can be some relatively small postscript files that take an extremely long
time to print because of this. By making the computer render the figures
to some finite raster density, the computational burden stays on the computer
at the expense of making potentially large (but simple and relatively
fast to print) postscript files for the printer.
This is particularly true for maps.
If you have figures that are taking too long to print, you may consider
having Matlab do the rendering. There is a huge tradeoff between size of
the file and the raster level (dots per inch).
ncexample.m demonstrates this. By way of explanation, the Matlab
type function allows you to view the contents of almost any matlab
script or function.
I will use the mapping toolbox as a demonstation of how to explore a topic
and write your own matlab function. We can also use some of the matlab GUI
tools, so let's log out of matlab and start it up WITH java enable ... i.e.
the default way. Also, get the MyMap.m function.
I used to use the matlab getframe, movie commands ... but then
I moved to a Mac and realized that for really nice animations, i just needed
to dump each frame to a .png file and make the animation in QuickTime.
Import an ascii file (of a matrix):
The ascii file in question contains ONLY numeric characters, no alphabetic.
This is important if you want to use the (simple) load command.
If you have mixed characters, you want to see the help file for fread.
load ~/data/soi.ascii
whos; % the command you will use most
years = soi(:,1); % save years as Nx1 matrix
a = soi(:,2:13); % strip out years, other columns are monthly values.
inds = find(a < -90); % locate the "missing" values
a(inds) = NaN; % replace with Matlab's "missing" flag.
[nrows,ncols] = size(a);
b = reshape(a',nrows*ncols,1); % reformat into Nx1 matrix.
plot(b) % plot, but pretty ugly
%
% Lets zoom in on just the first 10 years (120 months)
%
axis([0 10*12 -Inf Inf]) % [xmin xmax ymin ymax] (Inf == unknown)
grid
%
% It would be convenient to have a better time axis.
% I will make a matrix the same size as the input with each entry
% corresponding to the month midpoint == year.fraction
%
t = ones(nrows,1) * [0.5/12 : 1/12 : 11.5/12]; % matrix of fractions
tmat = years * ones(1,ncols) + t; % matrix of times
T = reshape(tmat',nrows*ncols,1); % array of times
plot(T,b)
Contour Plots:
clear % clears all variables in your workspace!!!!!
load topo % a default dataset
whos
contour(topo)
colorbar
contour(topo,5)
colorbar
contour(topo,[0:500:4500])
colorbar
imagesc(topo)
colorbar
This is the introduction to "Handle Graphics". It is generally trivial
to tweak almost any aspect of a figure.
imagesc(topo)
set(gca,'YDir','normal') % GetCurrentAxis attribute "YDir"; set to ...
colorbar
To see _what_ you can tweak, do a:
get(gca)
There are other neat plots, like mesh, pcolor, spy and a bunch more.
Meridional/Zonal means:
We need a field of data. The peaks functions creates some. In Matlab,
output variables are on the left of the equal sign. If there are more than
one, they must be enclosed in square brackets []. If you only put a single
variable on the left, the FIRST output variable is returned, the rest
are ignored.
[x,y,z] = peaks(360); % CREATE SOME FAKE DATA (z is 360x360)
imagesc(z); % TAKE A QUICK LOOK AT THE DATA
imagesc scales a matrix so the min corresponds to the lowest color
and the max corresponds the highest. Any of the "image" commands plots
element 1,1 in the upper left hand corner. This can be changed by setting
the appropriate axis attribute. This is "advanced", but simple.
newz = z(1:2:360,:); % GRAB EVERY OTHER ROW OF DATA
imagesc(newz); % IMAGE THE SUBSETTED MATRIX
set(gca,'YDir','normal'); % PLOT 1,1 IN THE LOWER LEFT
Taking the mean is simple. In general, Matlab applies operators to each
column, there is no need to "loop" over them. Since we conceptualize our
matrix z as 180 latitudes X 360 longitudes, we get the meridional or
zonal means in the following fashion:
clf; % CLEAR OUT THE FIGURE WINDOW (GOOD STYLE)
subplot(2,2,1); % CHOP PLOT WINDOW INTO A 2X2 MATRIX
imagesc(newz); % CHEAP PLOT OF DATA
set(gca,'YDir','normal'); % PLOT 1,1 IN THE LOWER LEFT
title('Peak data');
subplot(2,2,4); % use the 4th window of the 2x2
contour(newz); % duhhhhhhhh
title('Contoured peak data');
subplot(2,2,3); % USE THE THIRD WINDOW OF THE 2x2 set
mmeans = mean(newz); % CREATE MEANS OF EACH COLUMN (ALL LATITUDES)
plot(mmeans); % PLOT THEM (versus their index [1,360])
title('Meridional means');
subplot(2,2,2);
zmeans = mean(newz'); % TRANSPOSE THE MATRIX AND FIND THE MEANS
plot(zmeans); % PLOT THEM (versus their index [1,180]
title('Zonal means');
Labelled contour plots
[cs,h] = contour(peaks); % this is kinda sneaky
clabel(cs,h,'fontsize',15,'color','r','rotation',0)
Weighted Averages
This is simply multiplying two arrays together. Since Matlab does
"matrix" multiplication by default, it is necessary to have a
separate "operator" for this -- enter the dot "." -- which means to do a
the operation "pairwise". Since arrays are actually either Mx1 or 1xM
matrices, you must make sure the two matrices in question have the
same dimension.
clf; % CLEAR OUT THE FIGURE WINDOW (GOOD STYLE)
a = hamming(length(zmeans)); % CREATE WEIGHTING FUNCTION (column vector)
b = zmeans'; % CHANGE ROW VECTOR TO COLUMN VECTOR
c = a.*b; % CREATE THE WEIGHTED AVERAGE
lats = [-89:1:90]; % CREATE A "REALISTIC" LATITUDE AXIS
plot(lats,zmeans,'-.',lats,c,'-');
grid; % PUTS A GRID ON THE AXIS
legend('unweighted zonal mean','weighted zonal mean')
Here's where you click/drag the legend (multiple times if you wish). Instead
of plot, try semilogy, semilogx, or loglog.
Linear Least Squares:
help \
or
help relop
Masking (a bunch of color-coded matrix elements):
Masking can be achieved by setting the desired matrix elements equal to some
predefined color (like the background color).
clear; clf; % clear workspace, clear figure
load topo; % get some elevation data [180x360]
lon = [0.5:359.5];
lat = [-89.5:89.5];
a = peaks(360); % make some bogus data (too big)
cph = a(1:2:360,:); % cph is same size as elevation data
mask = topo < 0; % make a land/sea mask (sea is 1.0)
clear a topolegend topomap1 topomap2; % for illustrative purposes
figure(1); clf;
subplot(3,1,1);
imagesc(lon,lat,topo);
set(gca,'YDir','normal');
colorbar;
subplot(3,1,2);
imagesc(lon,lat,mask);
set(gca,'YDir','normal');
colorbar;
colormap(jet);
subplot(3,1,3);
imagesc(lon,lat,cph);
set(gca,'YDir','normal');
colorbar;
figure; % GET ANOTHER GRAPHICS WINDOW
newdat = cph.*mask; % Use only "cph" data over land
imagesc(lon,lat,newdat,[-7 7]); % quick look
set(gca,'YDir','normal'); % correct orientation
title('"Peaks" Masked by the Earth''s topography.');
colorbar; % because I said so
tim = jet; % snag a colormap
tim(32:33,:) = 0.9; % make colors around 0 == gray
colormap(tim); % apply new colormap
worldmap
Masked Contour Plots:
figure(1); clf
a = sinusoid(360,1,1,90); % make some phony data
b = a*a';
c = b(1:2:360,:)*10;
lon = [0.5:359.5];
lat = [-89.5:89.5];
subplot(2,1,1)
imagesc(lon,lat,c); % look at the phony data
set(gca,'YDir','normal'); % correct orientation
% MASK OUT THE "LAND"
i = find(mask > 0); % Find locations of land
c(i) = NaN; % set land elements to NAN
subplot(2,1,2)
contour(lon,lat,c,[-10:2:10]); % "gapped" contours
hold on; % add to current plot
[d,h] = contour(lon,lat,topo,[0 0]); % continents
Cheap Projections:
For this, we can "texture map" (drape?) a matrix over a matched set of 3
matrices specifying a "solid".
clf;
load topo
[x,y,z] = sphere(35); % MAKE A 3D SURFACE
h = surface(x,y,z,'FaceColor','texture','Cdata',topo) % DO TEXTURE MAP,
% KEEP GRAPHICS HANDLE
set(h,'EdgeColor','none') % USE HANDLE TO CHANGE
% AN ATTRIBUTE
axis square; % MAKE AXES EQUAL
axis off; % TURN OFF LABELLING
colormap(jet); % A DIFFERENT PALETTE
Scripts:
% This is a generic matlab script.
%
load topo; % GET [180x360] ELEVATION DATASET
lats = [-89.5:89.5]; % CREATE LAT ARRAY FOR TOPO MATRIX
lons = [0.5:359.5]; % CREATE LON ARRAY FOR TOPO MATRIX
imagesc(lons,lats,topo); % CREATE SOME PLOT w/ true x,y limits
set(gca,'YDir','normal'); % CORRECT ORIENTATION
worldmap;
which foo
help foo
type foo
foo
Notice that the initial block of comment lines forms the "help"
entry for the script! Pretty cool. A nice way to keep documentation
up-to-date with the program.
Functions:
Profiling:
Handle Graphics:
% A pretty ugly figure
h1 = subplot('position',[0.2 0.4 0.4 0.2]); % l, b, w, h
plot(1:10)
xlabel('wow')
ylabel('unbelievable!')
h2 = subplot('position',[0.1 0.1 0.8 0.2]);
plot(11:20)
xlabel('m/s^2')
ylabel('t_i')
h3 = subplot('position',[0.2 0.6 0.6 0.3]);
imagesc(peaks)
title('trumpets blare, twice')
h = colorbar;
orient tall % fill a page -- portrait style
wysiwyg % What You See Is What You Get ... wysiwyg
% Clean it up.
get(h)
set(h,'Position',[0.743 0.6 0.025 0.3]); % thinner colorbar
child = get(h,'Ylabel'); % get handle to the Ylabel.
set(child,'String','meters/furlong')
get(h3)
set(h3,'YTick',[1 13 22 38]); % change tick positions
set(h3,'YTickLabel',[' 1';' 13';'kahuna';' 38']); % change labels
child = get(h3,'Title')
set(child,'String',{'Trumpets Blare','Two times'},'FontSize',18)
get(h1)
set(h1,'Position',[0.2 0.4 0.6 0.1], ...
'YAxisLocation','right'); % line continuation, multiple
% attributes in one "set"
Importing binary:
Fortran unformatted binary
Every Fortran unformatted write makes a "record" that has a 4 byte
header and a 4 byte tailer(?) as well as the data you want to write.
C does not do this, this is the biggest difference in the binaries.
To be able to read both is a trivial thing IF you
remember the little 4 byte extras.
real datmat(129,64)
integer nt
do i = 1,nt
...
write(iunit)datmat
enddo
so each record is (1+129*64+1)*4 bytes, the file is this_same_number x nt.
Logically the format is:
[4bytes][129*64*4 bytes of data][4bytes]
[4bytes][129*64*4 bytes of data][4bytes]
...
[4bytes][129*64*4 bytes of data][4bytes]
[4bytes][129*64*4 bytes of data][4bytes]
The following segment just reads the data and makes a crude contour plot.
For more information on contour plots -- try help contour or
help clabel. Since each plot is being made in a loop, Matlab
must be told to `pause' so we can look at each plot being made. Otherwise,
Matlab's graphics is intelligent enough to realize it shouldn't bother to
draw each frame (on the screen) since you couldn't possibly just want to
see it flicker by.
nlon = 129;
nlat = 64;
nt = 5;
fid = fopen('~/matlab/data/chi_jan96.ieee','r')
frewind(fid);
for islice = 1:nt,
expr = sprintf('slice %.0f',islice);
dum1 = fread(fid, 1,'float32');
udat = fread(fid,[nlon nlat],'float32');
dum1 = fread(fid, 1,'float32');
contour(udat);
title(expr);
disp('Hit a key to continue ...'); pause;
end
Fortran direct access
[xxx bytes of data]
[xxx bytes of data]
...
[xxx bytes of data]
[xxx bytes of data]
Your Matlab script to read it could be:
fid = fopen('~/data/DirectAccess.ieee','r')
frewind(fid);
for islice = 1:nt,
udat = fread(fid,[xxx],'float32');
end
C binary
fid = fopen('~/data/wildcard.ieee','r')
udat = fread(fid,[10],'float32');
a = fread(fid,[10 30],'int32');
b = fread(fid,[1],'float64');
Printing:
You can print from the plot GUI directly,
which I have never done. I got into the game before that was
possible and never saw the need ... I do all my printing from
the command line.
To a particular printer:
If you leave off the -P[printer] argument, the default printer is
used.
print -dpsc -P[printer]
print -dps -P[printer]
To a file:
print -dpsc [filename]
print -dps [filename]
Making Matlab do the rasterization
print -dpsc2 -zbuffer -r200 [filename]
NetCDF
[overview]
[history]
[documentation]
[reading]
[creating]
[low-level examples]
Matlab and netCDF:
One public-domain package worth a separate entry is
MEXCDF, the
Matlab/NetCDF interface.
There is a function (ncstartup) which modifies your
MATLABPATH such that the netcdf operators are avialable.
The function lives in the /contrib/matlab directory.
From the Matlab prompt, type:
path(path,'/contrib/matlab');
ncstartup
Or you can beat the rush by simply putting those two lines in your
~/matlab/startup.m file and the netcdf functions/operators
will be avialable to every matlab session you invoke.
History of MexCDF
Chuck Denham of the
USGS
wrote the first netCDF/Matlab interface using m-files
that called stand-alone C-programs to implement the interface. For each
netCDF operation, netCDF files were opened and closed, and netCDF data
were written to matlab .mat files which were then "loaded" into Matlab.
The result was useful, but inefficient. To increase the efficiency,
Jim Mansbridge of
CSIRO combined many operations
into a single FORTRAN mex-file, called xnetcdf.f. Realizing the utility
of this method,
Julie Allen of
WHOI rewrote xnetcdf.f
in C, implemented additional operations (including operations relating to
creation of netCDF files from Matlab), and named the mexfile mexcdf.c.
The mexcdf.c code was rewritten by Chuck Denham to allow more flexibility
in the way the netCDF operations are invoked, and to streamline the code
to work on Macintosh and IBM PCs.
MexCDF Documentation
is available in several forms.
Reading a (known) variable from an existing netCDF file
First, get example.nc,
STN_050258.nc, and
Daily_b06_45.nc.
In example.nc, the variable is Elevation and is a
2-dimensional array. It could just as easily be a scalar or an
"N"-dimensional variable.
fname = 'example.nc';
EW = getnc(fname,'EW');
SN = getnc(fname,'SN');
x = getnc(fname,'Elevation');
size(x)
imagesc(EW,SN,x);
set(gca,'Ydir','normal')
title('Dr. Evil''s Volcano Lair','FontSize',18)
Creating a netCDF file.
type ncexample
Low Level Examples
You can roll around in broken glass and use the "low-level" netCDF
library routines via mexcdf.m:
cdf = '~/data/CAM_3d_data.nc';
[cdfid,rcode ]=mexcdf('open',cdf,'NOWRITE');
[varid]=mexcdf('varid',cdfid,var)
[var_name,var_type,nvdims,var_dim,natts]=mexcdf('varinq',cdfid,varid)
mexcdf('close',cdfid);
Mapping/Projections
[overview]
[documentation]
[reading]
[creating]
[examples]
Mapping / Projections
help map
help mapdemos
Movies/Animations
[overview]
[documentation]
[reading]
[creating]
[examples]
Movies / Animations
Movie Documentation
some user
Ingesting animations
Creating a movie.
There are two functions called MPGWRITE and MPGREAD for creating MPEG files
on the UNIX and PC platforms. MPGWRITE translates a MATLAB movie into an
MPEG file. MPGREAD translates a movie file in MPEG format into a MATLAB
movie matrix. You can download them from the anonymous FTP server:
ftp://ftp.mathworks.com/pub/contrib/v5/graphics/mpgwrite
ftp://ftp.mathworks.com/pub/contrib/v5/graphics/mpgread
Low Level Examples
Tim Hoar thoar 'at' ucar 'dot' edu