write_matrix
Writes nicely-formatted integer, float, or double precision two-dimensional (2D) arrays to standard out or to a file.
Prototype
procedure write_matrix ( data [*][*] : numeric, ; integer, float, or double fmtf : string, option : logical )
Arguments
dataThe 2D array to be printed.
fmtfFormat to be used, specified via Fortran style. The format string used must agree with the variable type.
option
If False, the data are written to standard out according to the user specified format.
If True, then this variable may have associated with it one or more of the following attributes:
- fout
- String specifying the output file name. If not present, the data is sent to standard out. The maximum length of fout is 96 characters.
- title
- String specifying a title to be printed. If not present, no title is printed. (Default is title=" ".)
- tspace
- Integer specifying the number of spaces from left to skip prior to printing title. Only applicable if the title attribute is present. If the title attribute is present and tspace is not, then the title will be at the left edge. (Default is tspace = 0.)
- row
- If row=True, then row numbers are printed. The maximum number of lines is 99999. If row is not present or row=False, then no row numbers are printed.
Description
The write_matrix procedure provides the ability to "pretty-print" a 2D array to a user-specified destination: either standard out (the screen) or to a file. This procedure does not have the ability to print individual row and column text labels.
All standard Fortran edit descriptors are accepted. See any standard Fortran text for more complete descriptions.
In the following, w refers to the total width for each value. The edit descriptor width, w, must include room for any minus sign. All numbers are right-justified.
- Integers may use 'Iw/iw' or 'Iw.m/iw.m'.
- Commonly used float and double edit descriptors include:
'Fw.d/fw.d'
where d represents the number of digits allocated to the fractional part of value.
'Ew.d/ew.d'
'Dw.d'
'Gw.d/gw.d'
Value format output
35 I2 35
35 I5 bbb35
45 i5.3 bb045
-123 I5.1 b-123
-123 i5.4 -0123
1 I5.5 00001
12.345 f8.3 bb12.345
12.345 F8.1 bbbb12.3
-12.345 f8.3 b-12.345
12.355 F8.1 bbbb12.4 (note rounding of rightmost digit)
-12.355 F8.1 bbb-12.4 (note rounding of rightmost digit)
12.345 E11.5 0.12345E+02
12.345 e11.4 b0.1235E+02
-12.345 E11.5 -.12345E+02
-12.345 e11.3 b-0.123E+02
All edit descriptors may be preceded by an integer that specifies the
number of times the descriptor is to be repeated at any row. For
example, "9f12.5" means repeat the "f12.5" descriptor nine times.
Edit descriptors may also be combined so that different combinations
can be sent to the output destination.If the array to be output has a missing value [_FillValue] that can not be accommodated within the width of the edit descriptor specified by the user, then it is the user's responsibility to make a change prior to invoking this procedure. This can be accomplished by changing the _FillValue prior to the use of write_matrix.
Use write_table if you want to write multiple formatted variables to a file.
See Also
asciiwrite, asciiread, write_table, print_table
Examples
In examples 1-3, the x array is generated with:
N = 5 ; number of rows M = 7 ; number of columns ave = 0.0 std = 5.0 x = random_normal (ave, std, (/N,M/))Example 1
Examples 1a-b produce the following output to standard out:
4.35 4.36 9.73 4.91 1.77 -0.63 -4.29 4.39 4.66 -5.84 4.59 3.68 -14.12 0.07 0.27 3.77 0.89 -3.09 5.08 -2.51 5.85 -3.35 -1.66 8.46 7.55 0.14 1.76 0.87 -6.90 4.06 10.39 4.56 -5.63 -1.43 8.65Example 1a
write_matrix (x, "7f7.2", False)Example 1b
Dynamically specify the format string (fmtf): to account for the size M:
fmtf = M + "f7.2" ; same as "7f7.2" ; or fWidth = 7 ; specify the format width fDec = 2 ; specify the number to the right of decimal point fmtf = M + "f" + fWidth + "." + fDec ; same as "7f7.2" write_matrix (x, fmtf, False)Example 2
Examples 2a-b produce the following output:
Normal
4.35 4.36 9.73 4.91 1.77 -0.63 -4.29
4.39 4.66 -5.84 4.59 3.68 -14.12 0.07
0.27 3.77 0.89 -3.09 5.08 -2.51 5.85
-3.35 -1.66 8.46 7.55 0.14 1.76 0.87
-6.90 4.06 10.39 4.56 -5.63 -1.43 8.65
Example 2aWrite a user-specified title to standard out and specify the number of spaces to be skipped before title is printed:
opt = True opt@title = "Normal" opt@tspace = 22 write_matrix (x, "7f7.2" , opt)Example 2b
Dynamically calculate the value for tspace. This requires that the length of the title string be known:
opt = True opt@title = "Normal" opt@tspace = (M*fWidth - dimsizes(stringtochar(opt@title)))/2 + 1 write_matrix (x, "7f7.2" , opt)Example 3
Print out the row numbers for examples 2a-b. Here, 5 was added to tspace to account for the additional column space used to print the row. The following will be sent to standard out:
opt@row = True opt@tspace = ((M*fWidth - dimsizes(stringtochar(opt@title))))/2 + 6 write_matrix (x, "7f7.2" , opt)
Normal
0 4.35 4.36 9.73 4.91 1.77 -0.63 -4.29
1 4.39 4.66 -5.84 4.59 3.68 -14.12 0.07
2 0.27 3.77 0.89 -3.09 5.08 -2.51 5.85
3 -3.35 -1.66 8.46 7.55 0.14 1.76 0.87
4 -6.90 4.06 10.39 4.56 -5.63 -1.43 8.65
Example 4Combine several edit descriptors; this shows a repeat edit descriptor ("2e14.5") and an example of specifying a specific number of spaces to be skipped ("4x"):
fmtx = "f8.2,1x,f10.5,3x,2e14.5, 4x, e11.4,2f7.2"
write_matrix (x, fmtx, False)
This yields:
4.35 4.36462 0.97340E+01 0.49126E+01 0.1770E+01 -0.63 -4.29
4.39 4.65982 -0.58381E+01 0.45896E+01 0.3677E+01 -14.12 0.07
0.27 3.77360 0.88711E+00 -0.30932E+01 0.5078E+01 -2.51 5.85
-3.35 -1.66182 0.84589E+01 0.75549E+01 0.1364E+00 1.76 0.87
-6.90 4.06438 0.10386E+02 0.45631E+01 -0.5635E+01 -1.43 8.65
Example 5Let g be a 100 x 50 (N x M) array, and assume it is desired to send the output to a file called "GPRINT" with no title or row numbering:
N = 100 ; number of rows M = 50 ; number of columns ave = 0.0 std = 5.0 x = random_normal (ave, std, (/N,M/)) fWidth = 10 ; specify the format width fDec = 3 ; specify the number to the right of decimal point fmtx = M + "f" + fWidth + "." + fDec ; fmtx="50f10.3" opt = True opt@fout = "GPRINT" write_matrix (x, fmtx, opt)Example 6
Let's say a user calculated seven (K) 1D arrays of length 100 (I): a(I), b(I), c(I), d(I), e(I), f(I), g(I). Further, let's assume that the values in each array vary widely, so different edit descriptors are required for each variable. To use write_matrix, several steps are required:
- place the seven 1D arrays into a 2D array using NCL's new and typeof functions,
- create the format to be used
- specify a file
I = 100 ; number of elements per variable K = 7 ; number of variables (1D arrays) p = new ( (/I,K/), typeof(a) ) p(:,0) = a p(:,1) = b p(:,2) = c p(:,3) = d p(:,4) = e p(:,5) = f p(:,6) = g fmtx = "f8.2,1x,2e14.5,3x,2f7.1,2x,e11.4,f9.3" opt = True opt@title = "a,b,c,d,e,f,g" opt@tspace = 40 write_matrix (p, fmtx, opt)To send to a file, simply add the fout attribute:
opt@fout = "/some/place/special/ABCDEFG" write_matrix (p, fmtx, opt)Example 7
Let z be a 4D array of size ntim x nlev x nlat x mlon. Reshape z to be a 2D array via NCL's ndtooned and onedtond functions:
z2D = onedtond( ndtooned(z), (/ntim*nlev*nlat,mlon/) ) opt = True opt@fout = "Z2D" write_matrix (z2D, fmtx, opt)Example 8
Let the N x M array x have a _FillValue (missing value) of 1.e+20. Assume all valid numbers can be accommodated by the format string "f10.2". To avoid bogus characters being sent to fout, the user must change the _FillValue attribute (at least temporarily):
xmsg = x@_FillValue ; save _FillValue
x@_FillValue = -9999.0 ; change to some value
fmtx = M + "f10.2"
write_matrix (x, fmtx, False)
x@_FillValue = xmsg ; if desired, reset original _FillValue
Example 9Let z be a 2D gaussian grid of size 64 x 128, and with coordinate variables named lat and lon [z(lat,lon)]. To output a subset, either standard or coordinate subscripting can be used. To output data from say, 10S-to-10N and every other longitude from 90-to-270, either of the following approaches may be used:
write_matrix (z(28:35,32:96:2), fmt, opt) ; standard subscriptingor
write_matrix (z({-10:10},{0:360:10}), fmt, opt) ; coordinate sub