CS 211 Lesson 24

Text (formatted) File Input/Output

Quote:

"The man on top of the mountain didn't fall there."  Unknown

Lesson Objectives:

• Be able to read (input) and write (output) data using the load and save MATLAB functions

• Understand the syntax differences between issuing commands and calling functions

• Understand how to read data from a text file when the data is organized as a table.

• Understand how to read data from a text file when the data is not organized as a table.

Lesson:

I. MATLAB Concepts

A. Saving/Loading Workspace Variables

• save writes (outputs) the contents of one or more workspace variables to a specified file in binary format.
  For example:
  
      save('mydata.mat', 'Alpha', 'Beta')

stores the contents of the variables Alpha and Beta to a file called mydata.mat

• load reads (inputs) variable data values from a specified file.
  For example:
  
      load('mydata.mat', 'Beta')
  
  creates a variable called Beta in the current workspace and initializes its value from the data in the file mydata.mat .

B. Commands vs. Functions (unrelated to file I/O)

• Many MATLAB "commands" have a command line format and a function format.
   
• Commands use the format:
  
      commandName  arg1  arg2  arg3 ...
   
• Functions use the format:
  
      functionName(arg1, arg2, arg3, ...)
   
• For example - the help system defines the "load" command as shown below. The first 7 lines describe the function format, while the last line describes the command format.

load load('filename') load('filename', 'X', 'Y', 'Z') load('filename', '-regexp', exprlist) load('-mat', 'filename') load('-ascii', 'filename') S = load(...)	function format
load filename -regexp expr1 expr2 ...	command format

• The arguments to commands and functions sometimes require different formats. For example, both of the lines below will load the contents of a MATLAB binary data file into a variable called Alpha. Note that the function call format requires quotes around the variable name while the command format does not.
  
           load('MyData.mat', 'Alpha');  % function call
  
      load 'MyData.mat'  Alpha      % command
  
  It is recommended that you always use the function call format of MATLAB built-in functions to avoid confusion. In addition, in many cases, the function call format also allows for greater control over how a particular MATLAB procedure performs its work.

C. Overview of Text I/O

• A "text file" contains data that is encoded using ASCII or UNICODE values.

• A "text file" can be easily viewed and edited using a wide variety of text editors such as Notepad, WordPad, MS Word, vi, EMACS,  etc.
   

• MATLAB has two general types of text file input functions

  • If the data is organized as a table (i.e., a series of rows, where each row has the same number of values separated by white space), then use the textread() or the textscan() function.

  • For all other data (i.e., non-table data) use fscanf(), fgetl(), and/or fgets().
     

• All text file output in MATLAB is done using fprintf().
   

• This is summarized in the table below.

  Text File I/O	Table Data	Non-table Data
  MATLAB input functions	textread() textscan()	fscanf() fgetl() fgets()
  MATLAB output functions	fprintf()	fprintf()

D. Text Input of Tables

• The following chart compares the textread() and textscan() functions that will read (input) text data that is stored in a table format.

  	textread()	textscan()
  Results	Creates one or more parallel arrays. Each array contains the data from one column of the table. The data type of each array is determined by its format specifier in the format string.	Creates a single cell array. Each cell is a pointer to an array of data from one column of the table. The data type of each array is determined by its format specifier in the format string.
  General Format	[A,B,C,...] = textread('filename','format') [A,B,C,...] = textread('filename','format',N) If N (the 3rd argument) is specified, then the command only reads N lines from the file. Otherwise it reads the entire file.	C = textscan(fid, 'format') C = textscan(fid, 'format', N) If N (the 3rd argument) is specified, then the command only reads N lines from the file. Otherwise it reads the entire remainder of the file.
  Usage	textread() opens a file for reading, reads one or more lines of the table data, and then closes the file. For example: [A B C] = textread(File_name, ...                    '%d%f%s');	To use  textscan(), the file must be opened with a separate fopen() command. For example: FID = fopen(File_name, 'r'); C = textscan(FID , '%d%f%s'); fclose(FID);
  Limitations	Only lines at the beginning of the text file can be read using textread() .	No limitations. Since the user opens the file with a separate fopen() command, other input commands such as fscanf(), fgetl(), and/or fgets() can read non-table lines from the file before textscan() is used.
  Performance	textread() works well for small text files but can be slow when reading large text files.	textscan() is the most efficient method for reading large text files.

   

• The format string for textread() and textscan()is a string of  format specifiers identical to those used for the fprintf() function. The order of the  format specifiers must match the data types of the table data. For this reason, all columns of a table must contain the same type of data. For example, both of the code segments below can read the table of text data from the file 'FarmPrices.txt'.
   

  textread()	[Crop_name Price Amount] = textread('FarmPrices.txt', '%s%f%d');
  textscan()	FID = fopen('FarmPrices.txt', 'r'); Data = textscan(FID , '%s%f%d'); fclose(FID);

  
  Example text file in a table format named 'FarmPrices.txt':
   

  Cotton    0.34    3245
  Soybeans  0.45    5432
  Hay       0.28   65345

• Sometimes one or more columns in a table contain data that is not needed by your program. You can skip columns of a table by placing an asterisk (*) between the percent sign and format specifier in the format string. For example, the following format string would read a 5-column table and skip the integer data in column 3 and the string data in column 5:
  
          '%s %f %*d %d %*s'
   

E. Text Input of Non-tables

• There are three options for reading text files that are not formatted into a table:

  • Use the Line = fgetl(FID) (file get line) function to read a single line of text from a text file. The returned string does not contain the new line character that was at the end of the input line.
     

  • Use the Line = fgets(FID) (file get string) function to read a single line of text from a text file. The returned string contains the new line character that was at the end of the input line.
     

  • Use the Data = fscanf(FID, 'format', Size) (file scan file) function to read one or more elements from a text file. The Size argument determines the number of elements and the dimensions of the returned array Data. The values are always read input the return array in column-major order.
     

• An example use of fgets() is shown below. The code copies the entire contents of one text file into another text file, one line at a time.

  Input_file_id  = fopen(Input_file_name,  'r');
  Output_file_id = fopen(Output_file_name, 'w');
  while ~ feof(Input_file_id)
      Line = fgets(Input_file_id );
      fprintf(Output_file_id , '%s', Line );
  end
  fclose(Input_file_id );
  fclose(Output_file_id);

• An example use of fgets() and fscanf() to read the example text file shown below.

  Input_file_id = fopen('test.txt',  'r');
  
  Line = fgets(Input_file_id);                   % read the label line
  Vector = fscanf(Input_file_id, '%f', [1 5] );
  Line = fgets(Input_file_id);                   % get to the next line of the file
  Line = fgets(Input_file_id);                   % read the label line
  Matrix = fscanf(Input_file_id, '%f', [2 3] );  % reads in column major order
  
  fclose(Input_file_id );
  

Example text data file:

My test scores
78  89  93  85  94
My golf rounds
94 87
95 74
83 84

II. Good Programming Practices

• Use save() to write the entire contents of one or more variables from a program (actually workspace) to a file.

• Use load() to read the entire contents of one or more variables from a file into a program. 

• Storing data in a text format and in tabular form can simplify I/O for MATLAB programs.
   

III. Algorithms

• None for this lesson

Lab Work: Lab 24

References:  Chapman Textbook: sections 8.1, 8.6