| MATLAB® | |
| On this page… |
|---|
Previewing Contents of the File or Clipboard [Text only] Specifying Delimiters and Header Format [Text only] |
The easiest way to import data into your MATLAB® application is to use the Import Wizard. You do not need to know the format of the data to use this tool. You simply specify the file that contains the data and the Import Wizard processes the file contents automatically. You can also use the Import Wizard to import HDF data. For more information, see Using the HDF Import Tool.
The sections on Previewing Contents of the File or Clipboard and Specifying Delimiters and Header Format apply only to text files and the clipboard.
To start the Import Wizard and select the source to import, see these sections:
If you use the uiimport function to start the Wizard, you can choose to have the imported data written to a MATLAB structure. See Importing to a Structure.
To start the Wizard and use a file browser to locate the file to import, use one of the menu options or MATLAB commands shown here:
Select Import Data from the File menu
Type uiimport -file
Type uiimport, and then click Browse
If you already know the name of the file to import, use one of the following means to initiate the operation:
In the Current Directory browser, right-click the filename and select Import Data
Type uiimport filename, where filename is an unquoted string containing the name of the file to import.
To import from the system clipboard, use one of the menu options or MATLAB commands shown here:
Select Paste to Workspace from the Edit menu
Type uiimport -pastespecial
Type uiimport, and then click Clipboard
Specifying an output argument with the uiimport command tells MATLAB to return the imported data in the fields of a single structure rather than as separate variables.
The command
S = uiimport('filename')imports the file filename to the fields of structure S. The filename argument is a single-quoted string containing the name of the file to import.
If you are importing from a binary file, skip ahead Determine Assignment to Variables. |
When the Import Wizard imports text data from a file or the clipboard, it opens the dialog box shown here and displays a portion of the raw data in the preview pane on the left. You can use this display to verify that the file contains the data you expect.
The pane on the right side of the dialog box shows how MATLAB has assigned the imported data to a default set of variables. The variable names appear in the tabs above the display pane. Click any of these tabs to see the values assigned to that variable. The variable names are derived from categories into which the Import Wizard has sorted the data. These are as follows:
rowheaders — Column vector containing the names of all row headers.
colheaders — Row vector containing the names of all column headers.
textdata — Matrix containing all imported text data. Empty elements are set to ''.
data — Matrix containing all imported numeric data. Empty elements are set to NaN.
If the imported file or clipboard contains only numeric or only text data, then the Import Wizard does not use the variable names shown above. Instead, it assigns all of the data to just one variable:
For data imported from a text file, the name of the variable is the same as the filename, minus the file extension.
For data imported from the clipboard, the name of the variable is A_pastespecial.
Using the options shown at the top of the Import Wizard dialog box, you can specify a delimiter character for separating data items, and also the number of lines you want to use for column headers.
Most text files use a unique character called a delimiter or column separator to mark the separation between items of data. For example, data in a comma-separated value (CSV) file is, of course, separated by commas. Data in some other file might be separated by tab or space characters.
When the Import Wizard imports from a text file or the clipboard, it makes its best guess as to which character was intended as the delimiter and displays the data accordingly. If this is not correct, you will need to set the correct delimiter from the choices shown under Select Column Separator(s) in the upper left of the dialog box. When you do this, the Import Wizard immediately reformats the data, displaying new values for the data shown in the preview pane.
When reading in data from a text file or the clipboard, the Wizard looks for any lines at the top that have no numeric characters, and assigns these lines to the variable textdata. MATLAB counts these lines and displays the count in the Number of text header lines value field in the upper right of the Import Wizard window. You can adjust this count if it does not accurately represent the header format within the file.
Note The Number of text header lines selector applies only to column headers. It has no effect on row headers. |
MATLAB creates a row vector from the bottommost of these lines and assigns it to the variable colheaders.
The Generate M-code checkbox at the bottom of the Import Wizard dialog box applies to both text and binary data, and thus is described in Automated M-Code Generation.
To continue, click Next at the bottom of the dialog box.
At this point, the Import Wizard displays the dialog box shown below. This dialog displays data for both text and binary files.
The left pane of the dialog box displays a list of the variables MATLAB created for your data. For text files, MATLAB derives the variable names as described in Preview Contents of the File. For binary files, the variable names are taken directly from the file.
Click any variable name and MATLAB displays the contents of that variable in the pane to the right. MATLAB highlights the name of the variable that is currently displayed in the right pane.
The top portion of this dialog box offers three options for organizing the file's data:
Create variables matching preview
Create vectors from each column using column names
Create vectors from each row using row names
Note For data imported from a binary file, only the top option is active. Variable names and assignment are taken directly from the imported file. For text data, you can use any of the three options; however, the bottom two are active only if the file or clipboard contains row or column headers. |
While importing from the example text file grades.txt, select the third option to create vectors from row names. Observe that the display replaces the default variable assignments with new variables derived from the row headers. Click any of these variable names, and the Wizard displays the contents of the corresponding row vector.
The checkboxes to the left of each variable name enable you to include or exclude individual variables from those that will be written to the workspace. By default, all variables are selected. Select the checkbox of any variable you do not want written to the workspace. The check mark is removed from any variables that you deselect.
Example of Selecting Variables to Load. Use the Import Wizard to import this sample binary MAT-file, my_data.mat,
C =
1 2 3 4 5
6 7 8 9 10
D =
a test string
The Import Wizard displays two variables, as listed in the preview pane. To select a variable to import, select the check box next to its name. All variables are preselected by default.
To perform additional imports from this or a similar type of file, you can automate this process by creating a MATLAB function that performs all of the steps you just went through. To have the Import Wizard write this function for you, select the Generate M-code checkbox in the lower right corner of the Wizard dialog.
Once you click Finish to complete the import, MATLAB opens an Editor window displaying the generated M-file function. The function is called importfile.m. If this name is already taken, then MATLAB names the file importfileN.m, where N is a number that is one greater than the highest existing importfile.m file.
The generated function has the following input and output arguments:
Input: fileToRead1 — Name of the file to import from. This argument exists only when importing from a file.
Output: newData1 — Structure to assign all imported data to. This argument exists only if you have specified an output argument with the call to uiimport when starting the Import Wizard. Otherwise, variables retain the same naming as assigned within the Wizard.
The newData1 output is a structure that has one field for each output of the import operation.
The workspace variables created by this generated M-code are the same as those created by running the Import Wizard. For example, if you elect to format the output in column vectors when running the Import Wizard, the generated M-file does the same. However, unlike the Import Wizard, you cannot mark any variables to be excluded from the output.
Make any necessary modifications to the generated M-file function in the Editor window. To save the M-file, select Save from the File menu at the top.
Caution You must save the file yourself; MATLAB does not automatically save it for you. |
The M-file shown below was generated by MATLAB during an import of the file grades.txt, shown earlier in this section. During the import that created this file, the option to Create vectors from each row using row names was selected, thus generating four row vectors for output: Ann, John, Martin, and Rob. Also, the row vector for John was deselected by clearing the checkbox next to that name in the Wizard.
If you run the function, you find that the workspace now holds the four row vectors Ann, John, Martin, and Rob, instead of the default variables created by the Import Wizard (data, textdata, and rowheaders). Also, note that the vector for John is written to the workspace along with the others, even though this one variable had been deselected from the Import Wizard interface.
importfile grades.txt whos Name Size Bytes Class Attributes Ann 1x3 24 double John 1x3 24 double Martin 1x3 24 double Rob 1x3 24 double
To complete the import operation, click Finish to bring the data into the MATLAB workspace. This button also dismisses the Import Wizard.
Variables written to the workspace are in one of the following formats. The first three apply only to data read from text files or the clipboard, the fourth applies only to binary files, and the last applies to both:
| Variable Name | Output |
|---|---|
| data, textdata, rowheaders, colheaders | Separate matrices for numeric, text, and header data. |
| Variables named after row or column headers | One vector for each row or column. |
| Single variable named after the file name, or A_pastespecial | One matrix for all data named after the file name |
| Variable names taken from binary file | Data assigned to each variable stored in a binary file. |
| Output variable assigned during call to uiimport | A single structure having fields that match one of the formats described above. |
Here are a few examples of how to use the Import Wizard.
Example 1—Text Data. Start by creating the text file grades.txt using the MATLAB editor. The file contains the following:
John 85 90 95 Ann 90 92 98 Martin 100 95 97 Rob 77 86 93
Import from text file grades.txt, using default variables to store the data:
uiimport grades.txt whos Name Size Bytes Class Attributes data 4x3 96 double rowheaders 4x1 272 cell textdata 4x1 272 cell
Example 2— Partial Text File with Row Vectors. Import from the same file as in the above example, but this time select Create vectors from each row using row names. Also, clear the checkbox next to variable John so that this one vector does not get written to the workspace:
whos Name Size Bytes Class Attributes Ann 1x3 24 double Martin 1x3 24 double Rob 1x3 24 double
Example 3 — Binary Data Assigned to a Structure. Save numeric and text data in binary format in file importtest.mat and use the Import Wizard to import the binary file into the workspace.
C = [1 2 3 4 5;6 7 8 9 10];
D = 'a test string';
save importtest C D
clear
s = uiimport('importtest.mat')
s =
C: [2x5 double]
D: 'a test string'
| Supported File Formats | Accessing Files with Memory-Mapping | |
| © 1984-2008- The MathWorks, Inc. - Site Help - Patents - Trademarks - Privacy Policy - Preventing Piracy - RSS |