readmtx

Read matrix stored in file

Syntax

mtx = readmtx(fname,nrows,ncols,precision) mtx = readmtx(fname,nrows,ncols,precision,readrows,readcols) mtx = readmtx(fname,nrows,ncols,precision,... readrows,readcols,mformat) mtx = readmtx(fname,nrows,ncols,precision,... readrows,readcols,mformat,nheadbytes) mtx = readmtx(fname,nrows,ncols,precision,... readrows,readcols,mformat,nheadbytes,nRowHeadBytes) mtx = readmtx(fname,nrows,ncols,precision,... readrows,readcols,mformat,nheadbytes,nRowHeadBytes,nRowTrailBytes) mtx = readmtx(fname,nrows,ncols,precision,... readrows,readcols,mformat,nheadbytes,nRowHeadBytes,... nRowTrailBytes,nFileTrailBytes) mtx = readmtx(fname,nrows,ncols,precision,... readrows,readcols,mformat,nheadbytes,nRowHeadBytes,... nRowTrailBytes,nFileTrailBytes,recordlen)

Description

mtx = readmtx(fname,nrows,ncols,precision) reads a matrix stored in a file. The file contains only a matrix of numbers with the dimensions nrows by ncols stored with the specified precision. Recognized precision values are described below.

mtx = readmtx(fname,nrows,ncols,precision,readrows,readcols) reads a subset of the matrix. readrows and readcols specify which rows and columns are to be read. They can be vectors containing the row or column numbers, or two-element vectors of the form [start end], which are expanded using the colon operator to start:end. To read just two rows or columns, without expansion by the colon operator, provide the indices as a column matrix.

mtx = readmtx(fname,nrows,ncols,precision,... readrows,readcols,mformat) specifies the machine format used to write the file. mformat can be any recognized by fopen. This option is used to automatically swap bytes for files written on platforms with a different byte ordering.

mtx = readmtx(fname,nrows,ncols,precision,... readrows,readcols,mformat,nheadbytes) skips the file header, whose length is specified in bytes.

mtx = readmtx(fname,nrows,ncols,precision,... readrows,readcols,mformat,nheadbytes,nRowHeadBytes) also skips a header that precedes every row of the matrix. The length of the header is specified in bytes.

mtx = readmtx(fname,nrows,ncols,precision,... readrows,readcols,mformat,nheadbytes,nRowHeadBytes,nRowTrailBytes) also skips a trailer that follows every row of the matrix. The length of the trailer is specified in bytes.

mtx = readmtx(fname,nrows,ncols,precision,... readrows,readcols,mformat,nheadbytes,nRowHeadBytes,... nRowTrailBytes,nFileTrailBytes) accounts for the length of data following the matrix. The sizes of the components of the matrix are used to compute an expected file size, which is compared to the actual file size.

mtx = readmtx(fname,nrows,ncols,precision,... readrows,readcols,mformat,nheadbytes,nRowHeadBytes,... nRowTrailBytes,nFileTrailBytes,recordlen) overrides the record length calculated from the precision and number of columns, and instead uses the record length given in bytes. This is used for formatted data with extra spaces or line breaks in the matrix.

Background

Map data is often provided as binary or ASCII files with a fixed format. Writing your own functions to read the data into the MATLAB^® workspace can be difficult and time-consuming, particularly for binary files. This function allows you to read the data by simply specifying the format of the file.

Examples

Write and read a binary matrix file:

fid = fopen('binmat','w');
fwrite(fid,1:100,'int16');
fclose(fid);
mtx = readmtx('binmat',10,10,'int16')

mtx =
     1     2     3     4     5     6     7     8     9    10
    11    12    13    14    15    16    17    18    19    20
    21    22    23    24    25    26    27    28    29    30
    31    32    33    34    35    36    37    38    39    40
    41    42    43    44    45    46    47    48    49    50
    51    52    53    54    55    56    57    58    59    60
    61    62    63    64    65    66    67    68    69    70
    71    72    73    74    75    76    77    78    79    80
    81    82    83    84    85    86    87    88    89    90
    91    92    93    94    95    96    97    98    99   100

mtx = readmtx('binmat',10,10,'int16',[2 5],3:2:9)

mtx =
    13    15    17    19
    23    25    27    29
    33    35    37    39
    43    45    47    49

Limitations

Every row of the matrix must have the same number of elements.

Tips

This function reads files that have a general format consisting of a header, a matrix, and a trailer. Each row of the matrix can have a certain number of bytes of extraneous information preceding or following the matrix data.

Both binary and formatted data files can be read. If the file is binary, the precision argument is a format recognized by fread. Repetition modifiers such as '40*char' are not supported. If the file is formatted, precision is a fscanf and sscanf-style format of the form '%nX', where n is the number of characters within which the formatted data is found, and X is the conversion character such as 'g' or 'd'. Fortran-style double-precision output such as '0.0D00' can be read using a precision such as '%nD', where n is the number of characters per element. This is an extension to the C-style format s accepted by sscanf. Users unfamiliar with C should note that '%d' is preferred over '%i' for formatted integers. MATLAB syntax follows C in interpreting '%i' integers with leading zeros as octal. Formatted files with line endings need to provide the number of trailing bytes per row, which can be 1 for platforms with carriage returns or linefeed (Macintosh, UNIX^®), or 2 for platforms with carriage returns and linefeeds (DOS).

Documentation