A quick guide on how to use Matlab netCDF functions

Prepared by HP Huang ([email protected]), Sept 2009. Revised. March

Please email
2015 HPH for
any questions/comments.
A netCDF file contains two parts: A "header" that describes the names, dimensions,
etc., of thestored in the file, and the main body that contains the real data. To
variables
need
to first
extractfile,
thewe
information in the header and determine what
process
a netCDF
portion/segment
data done
we by using a set of stand-alone tools. This is, in fact,
want
to use. Thisof
is the
usually
the more
tedious
task
which
we will discuss in Part (A). Once the content of a netCDF file is
known, it is rather
straightforward
to read the data as will be discussed in Part (B).

(A) Inspect the content of a netCDF file

We will use the netCDF data file, precip.mon.ltm.nc
, as an example to explain how the Matlab
functions work. This file, extracted and downloaded from the the NOAA ESRL(www.esrl.noaa.gov/psd),
contains the CMAP gridded data for the long-term mean
PSD web portal
of monthly for the global domain. It contains the values of precipitation rate on a
precipitation
regular grid
longitudelatitude
for the climatological means for January, February, ..., December.
Step 0: Display/check the header of the netCDF file
ncdisp('precip.mon.ltm.nc')
The output is listed in Appendix A.
Remark: The ncdisp command "dumps" out the whole header, which contains the
essential
about theinformation
variables and their dimensions in the netCDF file. Running ncdisp is
equivalent-c"
to (see
running
"ncdump
Appendix B) on Linux-based platfor ms. It is strongly
recommended
the be examined before one uses the data in a netCDF file. In
information in that
the header
fact,efully
just by
car
inspecting the header, one can skip many steps discussed in Step 2-4 in
this section.
Step 1: Open the file
ncid1 = netcdf.open('precip.mon.ltm.nc','NC_NOWRITE')
Remark: This command "opens" a netCDF file named precip.mon.ltm.nc and
assigns
a file
number
it.
This file
number
is to
the sole output of the function and is put into our variable,
ncid1,
for later
uses.
The
option
'NC_NOWRITE'
designates that the file is read-only (that is what we
need for now).
Steps 2-4 are often not necessary if one has already obtained the needed
specific
running
ncdisp in
Step
0. of
information
about
Step 2:
[ndim,
ndim
= Inspect
nvar,
3variables
natt,
the by
number
unlim]
=ofnetcdf.inq(ncid1)
variables
and
number
1 dimensions, etc., in the file

nvar = 4
natt = 6
unlim = 2
Remark: After opening a file and obtaining its "file number", we next
inquireof
what's
in the file.
The
output
the function,
netcdf.inq,
is a four-element array that contains
the number
of dimension,
number
of variable,
number of attribute, etc. (Let's focus on the first two
elementswe
forlearned
now.) From
those
outputs,
that the
file, "precip.mon.ltm.nc", contains 4
3variables
dimensions
= 3).maximum of
(nvar(ndim
= 4) and
Step 3: Extract further information for each "dimension"
[dimnam e, dimlength] = netcdf .inqDim(ncid1, 0)
dimname = lon
dimlength = 144
[dimnam e, dimlength] = netcdf .inqDim(ncid1, 1)
dimname = lat
dimlength = 72
[dimnam e, dimlength] = netcdf .inqDim(ncid1, 2)
dimname = time
dimlength = 12

Remark: From Step 2, we learned that there can be maximum of three

dimensions
for any variable We then call the function, netcdf.inqDim(ncid,
stored
in 'precip.mon.ltm.nc'.
, to ask about
dimid)the
detail of each dimension, one at a time . Note that the parameter,
, runs from
dimid
0 to 2 instead of 1
to 3 (dimension number zero, ,dimid
corresponds
= 0 to the 1st dimension; dimension number one,
dimid = 1, corresponds to the 2nd dimension, and
). This
so onis because Matlab netCDF utilities
adopt the convention of C language, in which the counting of numbers
often Here,
starts we
from
zero
of number 2 (or, the 3rd dimension)
one.
stop
at instead
dimension
because from
Step
we alreadynumber of dimension is 3. From this step,
determined
that
the2maximum
for
the
first
dimension
is stored in an array called "lon" with 144
we know that the coordinate
elements,
with
Step
[varname,
varname
72
4: Extract
elements,
=the
xtype,
lat2nd
further
dimension
and
dimid,
the
information
natt]
3rdisdimension
"lat"
= netcdf
for each
.inqVar(ncid1,
is "time"
variable
with
2 120)elements.

xtype = 5
dimid = 1
natt = 3
Remark: In this example, we first extract the name, dimension, etc.,
variable.
of
Again,
first for this
the
function,
netcdf.inqVar(ncid1, varid), the parameter "varid" starts from
0 instead ofadopted
1. This from
is a C language; See remarks for Step 3. The
convention
outcomeistells
us that
theIt1st
variable
named
"lat".
is of type "5" which translates to "float" or
documentation
provided by mathworks.com does not have the detail on
"real". (The Matlab
this point,
but thefrom
definition
of
xtypeis
available
the documentation
for the C interface for netCDF; See
p. 41 of thatSome commonly encountered types are 2 = character, 3
documentation.
shortand
integer,
4 = Note
integer,
= real,
6 = double.)
that5 if one simply reads the header obtained by running ncdisp in
Step see
0, that the "lat" variable is of "real" or "float"
one would immediately
type.
The "dimid = 1 " in the output tells us that the variable
is a"lat"
one-dimensional array (because
dimid is a single num ber, not an array) and the coordinate in that
dimension isnumber
defined 1"
by . Recall that in Step 3 the comamnd, [dim name, dim length] =
"dimension
netcdf.inqDim(ncid1, 1) , returned dimname = lat, dimlength
. Therefore,
= 72the variable "lat" is an
array with 72 elements, and the coordinate for these 72 elements are
defineditself
by the
"lat",(Here, "lat" is both a variable and a
which
hasdimension,
72 elements.
dimension
or coordinate.
If this and it will clear later.) Let's not worr y
sounds confusing,
keep reading
about the 4th parameter
("attribution")
for now.
[varname, xtype, dimid, natt] = netcdf .inqVar(ncid1, 1)
varname = lon
xtype = 5
dimid = 0
natt = 3
Remark: We find that the second variable is called "lon". It is of "real"
type. with
It is aitsone-dimensional
array
coordinate defined by "dimension number zero", i.e., the
1st dimension
or "lon",
elements.
Again,
"lon" iswith
both144
a "variable" and a "dimension" (or
coordinate).
[varname, xtype, dimid, natt] = netcdf .inqVar(ncid1, 2)
varname
xtype
dimid
=
= 62= time
3

natt = 6
Remark: The third variable is called "time". It is of "double" type). ( It xtype
is a one-dimensional
=6
array with its coordinate defined by "dimension number 2", i.e., the 3rd
dimensionAgain,
or "time",
with
elements.
"time"
is 12
both a "variable" and a "dimension" (or
coordinate).
(This is very common
of
a netCDF file.)
[varname, xtype, dimid, natt] = netcdf .inqVar(ncid1, 3)
varname = precip
xtype = 5
dimid = 0, 1, 2
natt = 14

Remark: We now obtain the information of the 4th and final variable.
(We knowinthere
are only
4 nvar = 4in Step 2.) It is named "precip". It is of "real"threevariables
this file
because
Ittype.
is a
dimensional variable , because dimid = [0, 1, 2], an array with three Moreover,
elements. the 1st
dimension corresponds to "dimension number zero" given by Step 3, the
"dimension
number
1", and the
2nd dimension
corresponds
to third dimension corresponds to
"dimension
number
variable
"precip"
has2".
theTherefore,
dimensionthe
of (144, 72, 12), with total of
144x72x12
elements
of 1st,
real 2nd,
numbers.
The coordinates
for the
and 3rd dimensions are defined by
lon(144), lat(72), and time(12).
Summary
From the above, we learned that there are four variables in the netCDF
file,
"lon",The
"lat",
andthere only to provide the coordinate (or
"precip".
first"time",
three are
"metadata")
for the
the real
4th variable,
which
contains
data that we want to use. Symbolically, the 4th
variable is
precip :
P
i , j ,t k ,
i= 1-144, j = 1-72, and k= 1-12 ,
and the first three are
lat :

j,

j = 1-72

lon :

i,

i = 1-144

time: t k ,

The arrangement of the block of data for "precip" is illustrated in Fig. 1.

k= 1-12

January

FebruaryMarch

72

12

3
2
1

3
1 2 3 4

lon

144

12

Fig. 1
Here, we use the "normal" convention with each of the indices, i, j, and
k, starting
from 1,
whereasadopt
the C convention such that the counting
Matlab
netCDF
functions
starts
from
zero. Figure
2 isthat
a illustrates the actual numbers that we
slightly
modified
diagram
the
Matlab
functions.
should
use to
extract the data using

71

Fig. 2

210 0 1 2 3

143
5

01 2 11

(B) Read a variable from the netCDF file

From Part (A), we now know the content of the netCDF file. We will
illustrate
how to
read a selected
variable, or a "subsection" of a variable,
next use some
examples
to
file. This is generally
afrom
ver the
y straightforward
task and only involve calling the function, netcdf.getVar
, in a one-line
command. (Read the documentation for that function at mathworks.com. It is
useful.)
Example 1 : Read the content of the variable "lat" (this is the latitude for the
precipitation data)
ncid1 = netcdf.open('precip.mon.ltm.nc','NC_NOWRITE');
lat1 = netcdf.getVar(ncid1,0,0,72)
Result:
88.7500
86.2500
83.7500
81.2500
78.7500
76.2500
...
...
-81.2500
-83.7500
-86.2500
-88.7500
Remark: The first line of command opens the file and assigns it a file
number,
is returned
to = netcdf.getVar(ncid1, varid, start, count) , we choose
ncid1. Inwhich
the second
line, lat1
ncid1 as the outcome from first line of code, so we know that the file we will be using is
"precip.mon.ltm.nc"
varid = 0 , which means we read variable number zero, or the
, which
1st variable
is "lat", a real array
with 72 elements - see Step 4 in Part A. As always, remember that
Matlab
netCDF
the
convention
of C functions
language:adopt
The counting
starts from zero instead of one.
SeeStep
further
of
3 inremark
Part A. at bottom
start = 0 , which means we read the segment of the variable starting from its 1st
element.
(Again,
remember that
counting
starts from zero.)
own
of
"lat"
variable,
in).the
In ,other
netCDF
lat1,
which
in
words,
means
the
fileleft
are
we
we
hand
[88.75,
read
read
side.
the
total
86.25,
array,
AsofMatlab
83.75,
72
[lat(1),
elements,
...,
dumps
lat(2),
-86.25,
starting
the
lat(3),
-88.75].
content
...,
from
lat(71),
the 1st
count
start
of
These
88.75N
lat1,
=are
=0we
72
to
lat(72)],
the
see
88.75S)
element
latitude
thatand
the
for
(from
put
(as
contents
the
defined
it into
precipitation
our
by
data.
6

Example 2: Read the full 144 x 72 global precipitation field for time = 1 (i.e.,
then make a contour
of it
January plot
climatology),
ncid1 = netcdf.open('precip.mon.ltm.nc','NC_NOWRITE');
precJanuary = netcdf.getVar(ncid1,3,[0 0 0],[144 72 1]);
lon1 = netcdf.getVar(ncid1,1,0,144);
lat1 = netcdf.getVar(ncid1,0,0,72);
for p = 1:144
for q = 1:72
% -- the following 3 lines provides a quick way to remove missing
values
-if
abs(precJanuary(p,q))
> 99
precJanuary(p,q) = 0;
end
% ---------------------------------------------------------------map1(q,p) = precJanuary(p,q);
end
end
contour(lon1,lat1,map1)
Result:

Remarks: Only the first 4 lines of the code are related to reading the
commands
post-processing
and plotting the data. In the second line,
netCDF file.for
The
rest are
PrecJanuary = netcdf.getVar(ncid1, varid, start, count) ,

we choose ncid1 from the outcome of the first, line

so we
of know
code that the file we are using is
"precip.mon.ltm.nc". In addition, varid,=which
3
means we read the 4th variable,start
"precip";
= [0
0 0], which indicates that we read the 1st, 2nd, and 3rd dimension from i =
0, j = 0,inand
k = count
0 as , =
illustrated
Fig.2;
which
[144 indicates
72 1]
that we actually read i = 0-143 (the total count
of grid point is 144), j = 0-71 (total count is 72), and k = 0-0 (total count
is 1) in Fig. to
2 (which
correspond
i = 1-144, j = 1-72, k = 1-1 in Fig. 1). Essentially, we just
with
= 1.x 72 slice of the data
cut a k144
Example 3: Read the full 144 x 72 global precipitation field for time = 1 (i.e.,
January climatology),
then make a color+contour
plot of it
ncid1 = netcdf.open('precip.mon.ltm.nc','NC_NOWRITE');
precJanuary = netcdf.getVar(ncid1,3,[0 0 0],[144 72 1],'double');
lon1 = netcdf.getVar(ncid1,1,0,144);
lat1 = netcdf.getVar(ncid1,0,0,72);
for p = 1:144
for q = 1:72
if abs(precJanuary(p,q)) > 99
precJanuary(p,q) = 0;
end
map1(q,p) = precJanuary(p,q);
end
end
pcolor(lon1,lat1,map1)
shading interp
colorbar
hold on
contour(lon1,lat1,map1,'k-')
Result:

Remark: This example is almost identical to Example 2, but note that in

the second line,
PrecJanuary = netcdf.getVar(ncid1, varid, start, count,
,
output_type)
we have an extra parameter, output_type. =This
'double'
helps conver t the outcome (which is put
into our variable, PrecJanuary) from "real" to "double" type. This is
the
function,
(for because
making a color map) requires that its input be
needed
in thispcolor
example,
of
type. [Typically,
for"double"
a 32-bit machine,
variables of "real" and "double" types contain 4
bytes
(orrespectively.
32 bits) and 8This
bytes
(or is not critical.] Without the extr a
64
bits),
detail
parameter
for Example
the conversion,
as iswould return the values of the variable
the case with
2, Matlab
in its original
type,it which
is 4 in Part (A) that xtype = 5for this variable.)
"real".
(We know
from Step
Appendix A. The header of a netCDF file as the output from the
example in Step 0
Executing the command, ncdisp('precip.mon.ltm.nc'), would produce
which
is the header
of output
the netCDF file, precip.mon.ltm.nc.
the following
detailed
title
= 'CPC Merged Analysis of Precipitation (excludes NCEP
For mat:Attributes:
m:\small_project\precip.mon.ltm.nc
Source:
Global
classic
Conventions
Reanalysis)'
= 'COARDS'
9

history
= 'created 12/98 by CASData version v207
'
platform = 'Analyses'
source
= 'ftp ftp.cpc.ncep.noaa.gov precip/cmap/monthly'
documentation = 'http://www.cdc.noaa.gov/cdc/data.cmap.html'
Dimensions:
lon = 144
lat = 72
time = 12 (UNLIMITED)
Variables:
lat
Size:
72x1
Dimensions: lat
Datatype: single
Attributes:
units
= 'degrees_north'
actual_range = [8.88e+01 -8.88e+01]
long_name = 'Latitude'
lon
Size:
144x1
Dimensions: lon
Datatype: single
Attributes:
units
= 'degrees_east'
long_name = 'Longitude'
actual_range = [1.25e+00 3.59e+02]
time
Size:
12x1
Dimensions: time
Datatype: double
Attributes:
units
= 'hours since 1-1-1 00:00:0.0'
long_name = 'Time'
delta_t = '0000-01-00 00:00:00'
actual_range = [0.00e+00 8.02e+03]
avg_per iod = '0000-01-00 00:00:00'
ltm_range = [1.73e+07 1.75e+07]
precip
Size:
144x72x12
Dimensions: lon,lat,time
Datatype: single
long_name
Attributes:
valid_range
units
add_offset
scale_factor
actual_range
= 'mm/day'
====01[0.00e+00
[0.00e+00
'Average Monthly
5.00e+01]
3.41e+01]
Rate of Precipitation'
10

missing_value
= -9.97e+36
precision
= 3.28e+04
least_significant_digit = 2
var_desc
= 'Precipitation'
dataset
= 'CPC Merged Analysis of Precipitation Standard'
level_desc
= 'Surface'
statistic
= 'Mean'
parent_stat
= 'Mean'
Appendix B: Obtaining the header using Linux-based utilities
The header of a netCDF file can also be extracted by using Linux-based
utilities.
most commonly
used
toolThe
is "ncdump".
The Linux equivalent of running
"ncdisp('precip.mon.ltm.nc') is
ncdump -c precip.m on.ltm.nc
Note that the "-c" option is essential. With it, the command only dumps
the header.will
Without
command
dumpit,allthe
data in the netCDF file.
Result:
netcdf precip.mon.ltm {
dimensions:
lon = 144 ;
lat = 72 ;
time = UNLIMITED ; // (12 currently)
variables:
float lat(lat) ;
lat:units = "degrees_north" ;
lat:actual_range = 88.75f, -88.75f ;
lat:long_name = "Latitude" ;
float lon(lon) ;
lon:units = "degrees_east" ;
lon:long_name = "Longitude" ;
lon:actual_range = 1.25f, 358.75f ;
double time(time) ;
time:units = "hours since 1-1-1 00:00:0.0" ;
time:long_name = "Time" ;
time:delta_t = "0000-01-00 00:00:00" ;
time:actual_range = 0., 8016. ;
time:avg_period = "0000-01-00 00:00:00" ;
time:ltm_range = 17338824., 17530944. ;
float precip(time,
precip:long_name
precip:valid_range
precip:units
precip:add_offset
precip:scale_factor
precip:actual_range
lat,=lon)
"mm/day"
;====0.f
="Average
0.f,
1.f
0.f,
; ;;50.f
34.05118f
;Monthly
; 11
Rate of Precipitation" ;

precip:missing_value = -9.96921e+36f ;
precip:precision = 32767s ;
precip:least_significant_digit = 2s ;
precip:var_desc = "Precipitation" ;
precip:dataset = "CPC Merged Analysis of Precipitation Standard" ;
precip:level_desc = "Surface" ;
precip:statistic = "Mean" ;
precip:parent_stat = "Mean" ;
// global attributes:
:Conventions = "COARDS" ;
:title = "CPC Merged Analysis of Precipitation (excludes NCEP
Reanalysis)"
;
:history
= "created
12/98 by CASData version v207\n",
"" ;
:platform = "Analyses" ;
:source = "ftp ftp.cpc.ncep.noaa.gov precip/cmap/monthly" ;
:documentation = "http://www.cdc.noaa.gov/cdc/data.cmap.html" ;
data:
lat = 88.75, 86.25, 83.75, 81.25, 78.75, 76.25, 73.75, 71.25, 68.75, 66.25,
63.75, 61.25, 58.75, 56.25, 53.75, 51.25, 48.75, 46.25, 43.75, 41.25,
38.75, 36.25, 33.75, 31.25, 28.75, 26.25, 23.75, 21.25, 18.75, 16.25,
13.75, 11.25, 8.75, 6.25, 3.75, 1.25, -1.25, -3.75, -6.25, -8.75, -11.25,
-13.75, -16.25, -18.75, -21.25, -23.75, -26.25, -28.75, -31.25, -33.75,
-36.25, -38.75, -41.25, -43.75, -46.25, -48.75, -51.25, -53.75, -56.25,
-58.75, -61.25, -63.75, -66.25, -68.75, -71.25, -73.75, -76.25, -78.75,
-81.25, -83.75, -86.25, -88.75 ;
lon = 1.25, 3.75, 6.25, 8.75, 11.25, 13.75, 16.25, 18.75, 21.25, 23.75,
26.25, 28.75, 31.25, 33.75, 36.25, 38.75, 41.25, 43.75, 46.25, 48.75,
51.25, 53.75, 56.25, 58.75, 61.25, 63.75, 66.25, 68.75, 71.25, 73.75,
76.25, 78.75, 81.25, 83.75, 86.25, 88.75, 91.25, 93.75, 96.25, 98.75,
101.25, 103.75, 106.25, 108.75, 111.25, 113.75, 116.25, 118.75, 121.25,
123.75, 126.25, 128.75, 131.25, 133.75, 136.25, 138.75, 141.25, 143.75,
146.25, 148.75, 151.25, 153.75, 156.25, 158.75, 161.25, 163.75, 166.25,
168.75, 171.25, 173.75, 176.25, 178.75, 181.25, 183.75, 186.25, 188.75,
191.25, 193.75, 196.25, 198.75, 201.25, 203.75, 206.25, 208.75, 211.25,
213.75, 216.25, 218.75, 221.25, 223.75, 226.25, 228.75, 231.25, 233.75,
236.25, 238.75, 241.25, 243.75, 246.25, 248.75, 251.25, 253.75, 256.25,
258.75, 261.25, 263.75, 266.25, 268.75, 271.25, 273.75, 276.25, 278.75,
281.25, 283.75, 286.25, 288.75, 291.25, 293.75, 296.25, 298.75, 301.25,
303.75, 306.25, 308.75, 311.25, 313.75, 316.25, 318.75, 321.25, 323.75,
326.25, 328.75, 331.25, 333.75, 336.25, 338.75, 341.25, 343.75, 346.25,
348.75,
353.75,
358.75
rate for351.25,
January,
February,
Based356.25,
on the
..., December
CMAP; data
at set,
the what
grid point
are the
that
climatological
is closest
values of the

Quick
to
Seattle,
(1)= Phoenix,
WA?
Make
AZ,
precipitation
aand
plot
(2)
of the3624,
results.
126552, 7296, 8016 ;
}_time
_____________________________________
0,exercise:
744, 1416,
2160,
2880,
4344, 5088, 5832,