MATLAB Function Reference

dlmread - Read ASCII-delimited file of numeric data into matrix

Graphical Interface

As an alternative to dlmread, use the Import Wizard. To activate the Import Wizard, select Import data from the File menu.

Syntax

M = dlmread(filename) M = dlmread(filename, delimiter) M = dlmread(filename, delimiter, R, C) M = dlmread(filename, delimiter, range)

Description

M = dlmread(filename) reads from the ASCII-delimited numeric data file filename to output matrix M. The filename input is a string enclosed in single quotes. The delimiter separating data elements is inferred from the formatting of the file. Comma (,) is the default delimiter.

M = dlmread(filename, delimiter) reads numeric data from the ASCII-delimited file filename, using the specified delimiter. Use \t to specify a tab delimiter.

Note When a delimiter is inferred from the formatting of the file, consecutive whitespaces are treated as a single delimiter. By contrast, if a delimiter is specified by the delimiter input, any repeated delimiter character is treated as a separate delimiter.

M = dlmread(filename, delimiter, R, C) reads numeric data from the ASCII-delimited file filename, using the specified delimiter. The values R and C specify the row and column where the upper left corner of the data lies in the file. R and C are zero based, so that R=0, C=0 specifies the first value in the file, which is the upper left corner.

Note dlmread reads numeric data only. The file being read may contain nonnumeric data, but this nonnumeric data cannot be within the range being imported.

M = dlmread(filename, delimiter, range) reads the range specified by range = [R1 C1 R2 C2] where (R1,C1) is the upper left corner of the data to be read and (R2,C2) is the lower right corner. You can also specify the range using spreadsheet notation, as in range = 'A1..B7'.

Remarks

If you want to specify an R, C, or range input, but not a delimiter, set the delimiter argument to the empty string, (two consecutive single quotes with no spaces in between, ''). For example,

M = dlmread('myfile.dat', '', 5, 2)

Using this syntax enables you to specify the starting row and column or range to read while having dlmread treat repeated whitespaces as a single delimiter.

dlmread fills empty delimited fields with zero. Data files having lines that end with a nonspace delimiter, such as a semicolon, produce a result that has an additional last column of zeros.

dlmread imports any complex number as a whole into a complex numeric field, converting the real and imaginary parts to the specified numeric type. Valid forms for a complex number are

Form	Example
`±<real>±<imag>i\|j`	`5.7-3.1i`
`±<imag>i\|j`	`-7j`

Embedded white-space in a complex number is invalid and is regarded as a field delimiter.

Examples

Example 1

Export the 5-by-8 matrix M to a file, and read it with dlmread, first with no arguments other than the filename:

rand('state', 0);   M = rand(5,8);   M = floor(M * 100);
dlmwrite('myfile.txt', M, 'delimiter', '\t')

dlmread('myfile.txt')
ans =
    95    76    61    40     5    20     1    41
    23    45    79    93    35    19    74    84
    60     1    92    91    81    60    44    52
    48    82    73    41     0    27    93    20
    89    44    17    89    13    19    46    67

Now read a portion of the matrix by specifying the row and column of the upper left corner:

dlmread('myfile.txt', '\t', 2, 3)
ans =
    91    81    60    44    52
    41     0    27    93    20
    89    13    19    46    67

This time, read a different part of the matrix using a range specifier:

dlmread('myfile.txt', '\t', 'C1..G4')
ans =
    61    40     5    20     1
    79    93    35    19    74
    92    91    81    60    44
    73    41     0    27    93

Example 2

Export matrix M to a file, and then append an additional matrix to the file that is offset one row below the first:

M = magic(3);
dlmwrite('myfile.txt', [M*5 M/5], ' ')

dlmwrite('myfile.txt', rand(3), '-append', ...
   'roffset', 1, 'delimiter', ' ')

type myfile.txt

80 10 15 65 3.2 0.4 0.6 2.6
25 55 50 40 1 2.2 2 1.6
45 35 30 60 1.8 1.4 1.2 2.4
20 70 75 5 0.8 2.8 3 0.2

0.99008 0.49831 0.32004
0.78886 0.21396 0.9601
0.43866 0.64349 0.72663

When dlmread imports these two matrices from the file, it pads the smaller matrix with zeros:

dlmread('myfile.txt')
   40.0000    5.0000   30.0000   1.6000   0.2000   1.2000
   15.0000   25.0000   35.0000   0.6000   1.0000   1.4000
   20.0000   45.0000   10.0000   0.8000   1.8000   0.4000
    0.6038    0.0153    0.9318        0        0        0
    0.2722    0.7468    0.4660        0        0        0
    0.1988    0.4451    0.4187        0        0        0