1

BMEN 398: MATLAB Module: Reading Data Files; plotting Fall 2005 Updated 8/16/2005 Hart Introduction:

In some cases it is convenient to input data to a program or to ‘hard-code’ it into the source code, (modifying the source when different data are used). However, in many cases with large alphanumeric data sets it is impractical to interactively type in data, or to modify source code to include it. MATLAB has a variety of commands for reading and writing data files, both as ASCII data (that can be read and manipulated by text editors) as well as binary data (more compact and intended only to be read by computers.) Most of the information in this handout about the syntax for opening files, reading data, and writing data is edited from the on-line help system. But instead of reading about these, we’ll jump into two examples.

Example 1:

This example shows how to read and display mri scan data. The example comes from the Mathworks web site at: http://www.mathworks.com/academia/student_center/homework/biomed/biomed_MRI_soln.html

The data (binary) consist of images from serial sections, read all-at-once, from a single file. The slices can be displayed all together or a specific slice can be isolated and shown. In addition, the code shows how the transverse slices can be stacked into a 3-D dataset, and a sagittal section produced and plotted. I’ve taken the snippets of code available from the web site, and combined into a single file, mri_example.m Simply seeing what can be accomplished may be helpful for various visualization projects, but we will not be spending additional time in class to dissect the code.

2

Example 2: As another example (relatively complex), we will consider in detail the case of reading of a portion of a finite element input file. These files are often quite long (many megabytes of data) and include text (e.g., keywords) as well as numerical data. We will consider an example with a portion of an ABAQUS* (ABAQUS.com) data file that includes the initial header lines of the file, all of the ‘node point data’ and the ‘element connectivity’ data, specialized for the 10-noded tetrahedral element, as shown below:

In order to define the geometry of the finite element model, all of the node points must be read (node number, x-coordinate, y-coordinate, and z-coordinate). The element connectivity is also read (element number, and the identity of the node number in the 1st position, as shown above, the 2nd position, etc. through the 10th position). The 10-noded tet may have curved sides, because each edge is defined by 3 points (that uniquely define a quadratic curve). First, let’s consider the format for ABAQUS files. The ABAQUS program expects to read an ASCII file that contains various ‘keywords’ followed by the data associated keyword. ABAQUS had a tremendous variety of analyses that can be performed, and so only a fraction of the available keywords are contained within any actual data file. In our simplified case, we will only consider two keywords: NODE and ELEMENT. We will be scanning the data file for these words – it’s made easier by ABAQUS’s convention of beginning each keyword with an asterisk: *. (Note that double asterisks indicates a comment.) Here is a portion of an ABAQUS file we will be reading:

*Heading data check ** Job name: output Model name: Model-1 *Preprint, echo=NO, model=NO, history=NO, contact=NO ** ** PARTS ** *Part, name=Part-1 *End Part ** ** ASSEMBLY ** *Assembly, name=Assembly **

3

*Instance, name=Part-1-1, part=Part-1 *NODE 1, -30., 30., 20. 2, -30., 10., 20. 3, -30., 10., 0. 4, -30., 30., 0. 5, -20., 0., 20. 6, -20., 0., 0. 7, -30., -20., 20. 8, -50., 0., 20.

many lines like this, then the end of the node numbers and the start of the element connectivity data:

9421, -34.5032, 3.399523, 8.366197 9422, -34.21561, 3.407859, 6.773405 9423, -33.771, 4.696672, 7.609779 9424, -34.9883, 5.188186, 6.400284 9425, -34.65103, 5.595265, 7.543461 9426, -48.88889, -1.111111, 0. ** *ELEMENT, type=C3D10 1, 404, 441, 135, 134, 1421, 1420, 1419, 1423, 1422, 1424 2, 475, 591, 146, 145, 1427, 1426, 1425, 1429, 1428, 1430 3, 158, 680, 600, 681, 1433, 1432, 1431, 1435, 1434, 1436 4, 158, 681, 600, 595, 1435, 1436, 1431, 1438, 1437, 1439 5, 158, 681, 595, 159, 1435, 1437, 1438, 1441, 1440, 1442 6, 158, 157, 600, 680, 1444, 1443, 1431, 1433, 1445, 1432 7, 105, 106, 448, 328, 1448, 1447, 1446, 1450, 1449, 1451

with many additional lines like this, then the end of the element connectivity, followed by other data:

5743, 1339, 1411, 1365, 1210, 9326, 9329, 8681, 8356, 9328, 8683 5744, 1339, 1365, 1411, 1279, 8681, 9329, 9326, 8756, 8678, 9325 5745, 1123, 1304, 1411, 1133, 7974, 9324, 9336, 6263, 7964, 9331 5746, 1123, 1411, 1122, 1133, 9336, 9332, 6164, 6263, 9331, 6264 5747, 1414, 1183, 1416, 872, 9412, 9399, 9393, 9372, 8992, 9400 5748, 1414, 872, 1417, 1183, 9372, 9414, 9413, 9412, 8992, 9405 *End Instance *End Assembly ** ** MATERIALS ** *Material, name=Material-1 *Elastic 0.3,100.

In our example, we need to scan the file until we hit upon *Node, then read the node number, the x-y-z-coordinates (1 set per line) until we hit the end of this data, indicated by an *. We then look for *Element, and read 1 line per element with the element number and the identities of the 10 nodes that compose that particular element. I have prepared three programs for us to consider:

read_abaqus_write.m: Read data file, write to output files read_abaqus_plot.m: Read data file, plot the geometry read_abaqus_results.m: Read data file, read results file (displacements at each node), plot results

The format for this displacement file is simply the node number, followed by the x-y- and z-displacements, e.g: 1 0.0000E+00 0.0000E+00 0.0000E+00 2 -1.1306E+00 -6.3375E-01 2.0627E+00 3 -1.1825E+00 -6.4317E-01 2.6757E+00 4 -9.6663E-01 -5.1917E-01 2.2108E+00 5 -9.5955E-01 -4.7667E-01 2.8115E+00 6 -8.9424E-01 -4.2989E-01 2.6062E+00 7 -8.8502E-01 -2.8903E-01 3.2265E+00 8 -8.8191E-01 -3.4321E-01 3.5674E+00 9 -1.0448E+00 -5.4472E-01 3.0750E+00 10 -1.1009E+00 -1.1743E-01 3.4097E+00

4

Attached:

MATLAB File and Data Manipulation Command Summary mri_example.m; mri.mat: MRI example (from web) read_abaqus_write.m: Read data file, write to output files read_abaqus_plot.m: Read data file, plot the geometry read_abaqus_results.m: Read data file, read results file (displacements at each node), plot results

*The ABAQUS data input is also used in the open source program CalculiX (http://calculix.de).

5

MATLAB File and Data Manipulation Commands Interactive input:

input Request user input Syntax: user_entry = input('prompt') user_entry = input('prompt', 's') Description: The response to the input prompt can be any MATLAB expression, which is evaluated using the variables in the current workspace. user_entry = input('prompt') displays prompt as a prompt on the screen, waits for input from the keyboard, and returns the value entered in user_entry. user_entry = input('prompt', 's') returns the entered string as a text variable rather than as a variable name or numerical value.

Open File: fopen Open file, or obtain information about open files Syntax:

fid = fopen(filename) fid = fopen(filename, mode) [fid,message] = fopen(filename, mode, machineformat) fids = fopen('all') [filename, mode, machineformat] = fopen(fid)

Description: fid = fopen(filename) opens the file filename for read access. (On PCs, fopen opens files for binary read access.) fid is a scalar MATLAB integer, called a file identifier. You use the fid as the first argument to other file input/output routines. If fopen cannot open the file, it returns -1. Two file identifiers are automatically available and need not be opened. They are fid=1 (standard output) and fid=2 (standard error). fid = fopen(filename, mode) opens the file filename in the specified mode. The mode argument can be any of the following:

'r' Open file for reading (default). 'w' Open file, or create new file, for writing; discard existing contents, if

any. 'a' Open file, or create new file, for writing; append data to the end of the file. 'r+' Open file for reading and writing. 'w+' Open file, or create new file, for reading and writing; discard existing

contents, if any. 'a+' Open file, or create new file, for reading and writing; append data to the

end of the file. 'A' Append without automatic flushing; used with tape drives. 'W' Write without automatic flushing; used with tape drives

Sample of Available Commands for Reading Files (with associated string conversion commands):

Functions Associated with Reading Data Function Name Description Fgetl Read one line of text from the device and discard the terminator Fgets Read one line of text from the device and include the terminator Fread Read binary data from the device Fscanf Read data from the device, and format as text Readasync Read data asynchronously from the device Stopasync Stop asynchronous read and write

6

fgetl Read line from file, discard newline character Syntax: tline = fgetl(fid) Description: tline = fgetl(fid) returns the next line of the file associated with the file identifier fid. If fgetl encounters the end-of-file indicator, it returns -1. (See fopen for a complete description of fid.) fgetl is intended for use with text files only. The returned string tline does not include the line terminator(s) with the text line. To obtain the line terminators, use fgets. findstr Find string within another, longer string Syntax: k = findstr(str1,str2) Description: k = findstr(str1,str2) searches the longer of the two input strings for any occurrences of the shorter string, returning the starting index of each such occurrence in the double array, k. If no occurrencs are found, then findstr returns the empty array, []. str2num String to number conversion Syntax: x = str2num('str') Description: x = str2num('str') converts the string str, which is an ASCII character representation of a numeric value, to numeric representation. The string can contain:

Digits A decimal point A leading + or - sign A letter e or d preceding a power of 10 scale factor A letter i or j indicating a complex or imaginary number.

The str2num function can also convert string matrices. strncmp Compare the first n characters of two strings Syntax: k = strncmp('str1','str2',n)

TF = strncmp(S,T,n) Description: k = strncmp('str1','str2',n) returns logical true (1) if the first n characters of the strings str1 and str2 are the same, and returns logical false (0) otherwise. Arguments str1 and str2 may also be cell arrays of strings. TF = strncmp(S,T,N) where either S or T is a cell array of strings, returns an array TF the same size as S and T containing 1 for those elements of S and T that match (up to n characters), and 0 otherwise. S and T must be the same size (or one can be a scalar cell). Either one can also be a character array with the right number of rows. strcat Concatenate strings horizontally Syntax: t = strcat(s1, s2, s3, ...) Description: t = strcat(s1, s2, s3, ...) horizontally concatenates corresponding rows of the character arrays s1, s2, s3, etc. All input arrays must have the same number of rows (or any can be a single string). When the inputs are all character arrays, the output is also a character array. When any of the inputs is a cell array of strings, strcat returns a cell array of strings formed by concatenating corresponding elements of s1, s2, etc. The inputs must all have the same size (or any can be a scalar). Any of the inputs can also be character arrays. Trailing spaces in character array inputs are ignored and do not appear in the output. This is not true for inputs that are cell arrays of strings. Use the concatenation syntax [s1 s2 s3 ...] to preserve trailing spaces.

7

break Terminate execution of a for loop or while loop Syntax: break Description: break terminates the execution of a for or while loop. Statements in the loop that appear after the break statement, are not executed. In nested loops, break exits only from the loop in which it occurs. Control passes to the statement that follows the end of that loop. Remarksbreak is not defined outside of a for or while loop. Use return for this context instead.

Writing output printf Write formatted data to file Syntax: [count, errmsg] = fprintf(fid, format, A, ...) Description: [count, errmsg] = fprintf(fid, format, A, ...) formats the data in the real part of matrix A (and in any additional matrix arguments) under control of the specified format string, and writes it to the file associated with file identifier fid. fprintf returns a count of the number of bytes written. errmsg is an optional output argument that returns an error message string if an error occurred, or an empty string if an error did not occur. Argument fid is an integer file identifier obtained from fopen. (It can also be 1 for standard output (the screen) or 2 for standard error. See fopen for more information.) Omitting fid causes output to appear on the screen. The format argument is a string containing C language conversion specifications. A conversion specification controls the notation, alignment, significant digits, field width, and other aspects of output format. The format string can contain escape characters to represent nonprinting characters such as newline characters and tabs. Conversion specifications begin with the % character and contain these optional and required elements:

Flags (optional) Width and precision fields (optional) A subtype specifier (optional) Conversion character (required)

Flags You can control the alignment of the output using any of these optional flags. Character Description Example Minus sign (-) Left-justifies the converted argument in its field %-5.2d Plus sign (+) Always prints a sign character (+ or -) %+5.2d Space character Inserts a space before the value % 5.2d Zero (0) Pads with zeros rather than spaces %05.2d Field Width and Precision Specifications You can control the width and precision of the output by including these options in the format string. Character Description Example Field width A digit string specifying the minimum number of

digits to be printed %6f Precision A digit string including a period (.) specifying the

number of digits to be printed to the right of the

8

decimal point %6.2f Conversion Characters

Conversion characters specify the notation of the output. Specifier Description %c Single character %d Decimal notation (signed) %e Exponential notation (using a lowercase e as in .1415e+00) %E Exponential notation (using an uppercase E as in 3.1415E+00) %f Fixed-point notation %g The more compact of %e or %f. Insignificant zeros do not print. %G Same as %g, but using an uppercase E%i Decimal notation (signed) %o Octal notation (unsigned) %s String of characters %u Decimal notation (unsigned) %x Hexadecimal notation (using lowercase letters a-f) %X Hexadecimal notation (using uppercase letters A-F)

Escape Characters

This list gives the escape character sequences you use to specify nonprinting characters in a format specification.

Character Description \b Backspace \f Form feed \n New line \r Carriage return \t Horizontal tab \\ Backslash \'' or '' Single quotation mark %% Percent character

Some Plotting Commands

plot Linear 2-D plot Syntax:

plot(Y) plot(X1,Y1,...) plot(X1,Y1,LineSpec,...) plot(...,'PropertyName',PropertyValue,...) plot(axes_handle,...) h = plot(...) hlines = plot('v6',...)

Description: plot(Y) plots the columns of Y versus their index if Y is a real number. If Y is complex, plot(Y) is equivalent to plot(real(Y),imag(Y)). In all other uses of plot, the imaginary component is ignored. plot(X1,Y1,...) plots all lines defined by Xn versus Yn pairs. If only Xn or Yn is a matrix, the vector is plotted versus the rows or columns of the matrix, depending on whether the vector's row or column dimension matches the matrix.

9

plot(X1,Y1,LineSpec,...) plots all lines defined by the Xn,Yn,LineSpec triples, where LineSpec is a line specification that determines line type, marker symbol, and color of the plotted lines. You can mix Xn,Yn,LineSpec triples with Xn,Yn pairs: plot(X1,Y1,X2,Y2,LineSpec,X3,Y3).

plot3 3-D line plot Syntax:

plot3(X1,Y1,Z1,...) plot3(X1,Y1,Z1,LineSpec,...) plot3(...,'PropertyName',PropertyValue,...) h = plot3(...)

Description: The plot3 function displays a three-dimensional plot of a set of data points. plot3(X1,Y1,Z1,...), where X1, Y1, Z1 are vectors or matrices, plots one or more lines in three-dimensional space through the points whose coordinates are the elements of X1, Y1, and Z1. plot3(X1,Y1,Z1,LineSpec,...) creates and displays all lines defined by the Xn,Yn,Zn,LineSpec quads, where LineSpec is a line specification that determines line style, marker symbol, and color of the plotted lines. plot3(...,'PropertyName',PropertyValue,...) sets properties to the specified property values for all line graphics objects created by plot3. h = plot3(...) returns a column vector of handles to lineseries graphics objects, with one handle. patch Create patch graphics object Syntax

patch(X,Y,C) patch(X,Y,Z,C) patch(FV) patch(...'PropertyName',PropertyValue...) patch('PropertyName',PropertyValue...) PN/PV pairs only handle = patch(...)

patch is the low-level graphics function for creating patch graphics objects. A patch object is one or more polygons defined by the coordinates of its vertices. You can specify the coloring and lighting of the patch. See Creating 3-D Models with Patches for more information on using patch objects. patch(X,Y,C) adds the filled two-dimensional patch to the current axes. The elements of X and Y specify the vertices of a polygon. If X and Y are matrices, MATLAB draws one polygon per column. C determines the color of the patch. It can be a single ColorSpec, one color per face, or one color per vertex (see "Remarks"). If C is a 1-by-3 vector, it is assumed to be an RGB triplet, specifying a color directly. patch(X,Y,Z,C) creates a patch in three-dimensional coordinates. patch(FV) creates a patch using structure FV, which contains the fields vertices, faces, and optionally facevertexdata. These fields correspond to the Vertices, Faces, and FaceVertexCData patch properties.

10

patch(...'PropertyName',PropertyValue...) follows the X, Y, (Z), and C arguments with property name/property value pairs to specify additional patch properties. patch('PropertyName',PropertyValue,...) specifies all properties using property name/property value pairs. This form enables you to omit the color specification because MATLAB uses the default face color and edge color unless you explicitly assign a value to the FaceColor and EdgeColor properties. This form also allows you to specify the patch using the Faces and Vertices properties instead of x-, y-, and z-coordinates. See the "Examples" section for more information. view Viewpoint specification Syntax:

view(az,el) view([az,el]) view([x,y,z]) view(2) view(3) view(T) [az,el] = view T = view

Description: The position of the viewer (the viewpoint) determines the orientation of the axes. You specify the viewpoint in terms of azimuth and elevation, or by a point in three-dimensional space. view(az,el) and view([az,el]) set the viewing angle for a three-dimensional plot. The azimuth, az, is the horizontal rotation about the z-axis as measured in degrees from the negative y-axis. Positive values indicate counterclockwise rotation of the viewpoint. el is the vertical elevation of the viewpoint in degrees. Positive values of elevation correspond to moving above the object; negative values correspond to moving below the object. view([x,y,z]) sets the viewpoint to the Cartesian coordinates x, y, and z. The magnitude of (x,y,z) is ignored. view(2) sets the default two-dimensional view, az = 0, el = 90. view(3) sets the default three-dimensional view, az = -37.5, el = 30. view(T) sets the view according to the transformation matrix T, which is a 4-by-4 matrix such as a perspective transformation generated by viewmtx. [az,el] = view returns the current azimuth and elevation. T = view returns the current 4-by-4 transformation matrix.

hold Hold current graph in the figure Syntax:

hold on hold off hold all hold hold(axes_handle,...)

Description:

11

The hold function determines whether new graphics objects are added to the graph or replace objects in the graph. hold on retains the current plot and certain axes properties so that subsequent graphing commands add to the existing graph. hold off resets axes properties to their defaults before drawing new plots. hold off is the default. hold all holds the plot and the current line color and line style so that subsequent plotting commands do not reset the ColorOrder and LineStyleOrder property values to the beginning of the list. Plotting commands continue cyclicing through the predefined colors and linestyles from where the last plot stopped in the list. hold toggles the hold state between adding to the graph and replacing the graph. hold(axes_handle,...) applies the hold to the axes identified by the handle axes_handle.

axis Axis scaling and appearance Syntax:

axis([xmin xmax ymin ymax]) axis([xmin xmax ymin ymax zmin zmax cmin cmax]) v = axis axis auto axis manual axis tight axis fill axis ij axis xy axis equal axis image axis square axis vis3d axis normal axis off axis on axis(axes_handles,...) [mode,visibility,direction] = axis('state')

Description: axis manipulates commonly used axes properties. (See Algorithm section.) axis([xmin xmax ymin ymax]) sets the limits for the x- and y-axis of the current axes. axis([xmin xmax ymin ymax zmin zmax cmin cmax]) sets the x-, y-, and z-axis limits and the color scaling limits (see caxis) of the current axes. v = axis returns a row vector containing scaling factors for the x-, y-, and z-axis. v has four or six components depending on whether the current axes is 2-D or 3-D, respectively. The returned values are the current axes XLim, Ylim, and ZLim properties.

12

axis auto sets MATLAB to its default behavior of computing the current axes limits automatically, based on the minimum and maximum values of x, y, and z data. You can restrict this automatic behavior to a specific axis. For example, axis 'auto x' computes only the x-axis limits automatically; axis 'auto yz' computes the y- and z-axis limits automatically. axis manual and axis(axis) freezes the scaling at the current limits, so that if hold is on, subsequent plots use the same limits. This sets the XLimMode, YLimMode, and ZLimMode properties to manual. axis tight sets the axis limits to the range of the data. axis fill sets the axis limits and PlotBoxAspectRatio so that the axes fill the position rectangle. This option has an effect only if PlotBoxAspectRatioMode or DataAspectRatioMode is manual. axis ij places the coordinate system origin in the upper left corner. The i-axis is vertical, with values increasing from top to bottom. The j-axis is horizontal with values increasing from left to right. axis xy draws the graph in the default Cartesian axes format with the coordinate system origin in the lower left corner. The x-axis is horizontal with values increasing from left to right. The y-axis is vertical with values increasing from bottom to top. axis equal sets the aspect ratio so that the data units are the same in every direction. The aspect ratio of the x-, y-, and z-axis is adjusted automatically according to the range of data units in the x, y, and z directions. axis image is the same as axis equal except that the plot box fits tightly around the data. axis square makes the current axes region square (or cubed when three-dimensional). MATLAB adjusts the x-axis, y-axis, and z-axis so that they have equal lengths and adjusts the increments between data units accordingly. axis vis3d freezes aspect ratio properties to enable rotation of 3-D objects and overrides stretch-to-fill. axis normal automatically adjusts the aspect ratio of the axes and the relative scaling of the data units so that the plot fits the figure's shape as well as possible. axis off turns off all axis lines, tick marks, and labels. axis on turns on all axis lines, tick marks, and labels. axis(axes_handles,...) applies the axis command to the specified axes. For example, the following statements

h1 = subplot(221); h2 = subplot(222); axis([h1 h2],'square')

set both axes to square. [mode,visibility,direction] = axis('state') returns three strings indicating the current setting of axes properties.