RunMat
GitHub

View all functions

CategoryIo: Tabular

What does the csvread function do in MATLAB / RunMat?

csvread(filename) reads numeric data from a comma-separated text file and returns a dense double-precision matrix. It is a legacy convenience wrapper preserved for MATLAB compatibility, and RunMat intentionally mirrors the original zero-based semantics.

How does the csvread function behave in MATLAB / RunMat?

  • Accepts character vectors or string scalars for the file name. String arrays must contain exactly one element.
  • csvread(filename, row, col) starts reading at the zero-based row row and column col, skipping any data before that offset.
  • csvread(filename, row, col, range) reads only the rectangle described by range. Numeric ranges must contain four elements [r1 c1 r2 c2] (zero-based, inclusive). Excel-style ranges use the familiar "B2:D6" A1 notation, which RunMat converts to zero-based indices internally.
  • Empty fields (two consecutive commas or a trailing comma) are interpreted as 0. Tokens such as NaN, Inf, and -Inf are accepted (case-insensitive).
  • Any other nonnumeric token raises an error that identifies the offending row and column.
  • Results are dense double-precision tensors using column-major layout. An empty file produces a 0×0 tensor.
  • Paths can contain ~ to reference the home directory; RunMat expands the token before opening the file.

csvread Function GPU Execution Behaviour

csvread performs all work on the host CPU. Arguments are gathered from the GPU when necessary, and the resulting tensor is returned in host memory. To keep data on the GPU, call gpuArray on the output or switch to readmatrix with the 'Like' option. No provider hooks are required.

Examples of using the csvread function in MATLAB / RunMat

Import Entire CSV File

writematrix([1 2 3; 4 5 6], "scores.csv");
M = csvread("scores.csv");
delete("scores.csv");

Expected output:

M =
     1     2     3
     4     5     6

Skip Header Row And Column Using Zero-Based Offsets

fid = fopen("with_header.csv", "w");
fprintf(fid, "Name,Jan,Feb\nalpha,1,2\nbeta,3,4\n");
fclose(fid);

M = csvread("with_header.csv", 1, 1);
delete("with_header.csv");

Expected output:

M =
     1     2
     3     4

Read A Specific Range With Numeric Vector Syntax

fid = fopen("measurements.csv", "w");
fprintf(fid, "10,11,12,13\n14,15,16,17\n18,19,20,21\n22,23,24,25\n");
fclose(fid);

block = csvread("measurements.csv", 0, 0, [1 1 2 3]);
delete("measurements.csv");

Expected output:

block =
    15    16    17
    19    20    21

Read A Block Using Excel-Style Range Notation

fid = fopen("measurements2.csv", "w");
fprintf(fid, "10,11,12\n14,15,16\n18,19,20\n");
fclose(fid);

sub = csvread("measurements2.csv", 0, 0, "B2:C3");
delete("measurements2.csv");

Expected output:

sub =
    15    16
    19    20

Handle Empty Fields As Zeros

fid = fopen("with_blanks.csv", "w");
fprintf(fid, "1,,3\n,5,\n7,8,\n");
fclose(fid);

M = csvread("with_blanks.csv");
delete("with_blanks.csv");

Expected output:

M =
     1     0     3
     0     5     0
     7     8     0

Read Numeric Data From A File In The Home Directory

homePath = fullfile(getenv("HOME"), "runmat_csvread_home.csv");
fid = fopen(homePath, "w");
fprintf(fid, "9,10\n11,12\n");
fclose(fid);

M = csvread(fullfile("~", "runmat_csvread_home.csv"));
delete(homePath);

Expected output:

M =
     9    10
    11    12

Detect Errors When Text Appears In Numeric Columns

fid = fopen("bad.csv", "w");
fprintf(fid, "1,2,3\n4,error,6\n");
fclose(fid);

try
    csvread("bad.csv");
catch err
    disp(err.message);
end
delete("bad.csv");

Expected output:

csvread: nonnumeric token 'error' at row 2, column 2

GPU residency in RunMat (Do I need gpuArray?)

csvread always returns a host-resident tensor because it performs file I/O and parsing on the CPU. If you need the data on the GPU, wrap the call with gpuArray(csvread(...)) or switch to readmatrix with the 'Like' option so that RunMat can place the result directly on the desired device.

FAQ

Why does csvread complain about text data?

csvread is limited to numeric CSV content. If a field contains letters, quoted strings, or other tokens that cannot be parsed as numbers, the builtin raises an error. Switch to readmatrix or readtable when the file mixes text and numbers.

Are the row and column offsets zero-based?

Yes. csvread(filename, row, col) treats row and col as zero-based counts to skip from the start of the file before reading results.

How are Excel-style ranges interpreted?

Excel ranges such as "B2:D5" use the familiar 1-based row numbering and column letters. The builtin converts them internally to zero-based indices and includes both endpoints.

Can I read files with quoted numeric fields?

Quoted numeric fields are not supported. Remove quotes before calling csvread, or switch to readmatrix, which has full CSV parsing support.

What happens to empty cells?

Empty cells (two consecutive commas or a trailing delimiter) become zero, matching MATLAB's csvread behaviour.

Does csvread support custom delimiters?

No. csvread always uses comma separation. Use dlmread or readmatrix for other delimiters.

How do I keep the results on the GPU?

csvread returns a host tensor. Call gpuArray(csvread(...)) after reading, or prefer readmatrix with 'Like', gpuArray.zeros(1) to keep residency on the GPU automatically.

What if the file is empty?

An empty file results in a 0×0 double tensor. MATLAB behaves the same way.

Does csvread change the working directory?

No. Relative paths are resolved against the current working directory and do not modify it.

See Also

readmatrix, writematrix, gpuArray, gather

Source & Feedback