readmatrix — Import numeric data from delimited text files with MATLAB-compatible readmatrix behavior.

readmatrix(filename) reads numeric data from text or delimited files and returns a dense matrix. It follows MATLAB defaults for delimiter detection, import ranges, header skipping, and missing-value handling.

Syntax

M = readmatrix(filename)
M = readmatrix(filename, options)
M = readmatrix(filename, name, optionValue)
M = readmatrix(filename, options, name, optionValue)
M = readmatrix(filename, nameValuePairs...)

Inputs

Returns

Errors

How readmatrix works

• Accepts character vectors or string scalars for the file name. String arrays must contain exactly one element.
• Supports option structs (from detectImportOptions) as well as name/value arguments such as 'Delimiter', 'NumHeaderLines', 'TreatAsMissing', 'DecimalSeparator', 'ThousandsSeparator', and 'EmptyValue'.
• Accepts 'Range' as either an Excel-style address ("B2:E10") or a numeric vector [rowStart colStart rowEnd colEnd] to slice the imported data.
• Automatically detects comma, tab, semicolon, pipe, or whitespace delimiters when none are specified. Detection is based on the first few non-empty data lines.
• Parses numeric values using MATLAB-compatible rules, recognising NaN, Inf, -Inf, and locale-specific decimal/thousands separators.
• Treats empty fields as NaN by default; specify 'EmptyValue', value to inject a replacement scalar, or 'TreatAsMissing', tokens to mark additional strings as missing.
• 'OutputType','logical' coalesces non-zero numeric values (including NaN) to logical true, mirroring MATLAB's casting behaviour.
• 'Like', prototype matches the output class and residency of an existing array. Supplying a GPU tensor keeps the parsed matrix on the device when an acceleration provider is active.
• Tolerates ragged rows by padding trailing elements with the configured empty value (default NaN).
• Raises descriptive errors when the file cannot be read or when a field cannot be parsed as a numeric value.

Does RunMat run readmatrix on the GPU?

readmatrix always executes on the host CPU. If the file name or option arguments are GPU-resident scalars, RunMat gathers them automatically before accessing the filesystem. The resulting matrix is created in host memory unless you pass 'Like', gpuPrototype, in which case the parsed tensor is uploaded to the same provider so subsequent operations remain on the device. Acceleration providers do not need bespoke hooks for this builtin.

Examples

Read Comma-Separated Values With Automatic Delimiter Detection

M = readmatrix("data/scores.csv")

Expected output:

% Returns a numeric matrix containing the CSV data.

Skip Header Lines Before Reading Numeric Data

M = readmatrix("data/sensor_log.txt", 'NumHeaderLines', 2)

Expected output:

% The first two lines are skipped; the remaining numeric rows are returned.

Import Tab-Delimited Text By Specifying The Delimiter

M = readmatrix("data/report.tsv", 'Delimiter', 'tab')

Expected output:

% Numeric matrix representing the tab-delimited values.

Treat Custom Tokens As Missing Values

M = readmatrix("data/results.csv", 'TreatAsMissing', ["NA", "missing"])

Expected output:

% Entries equal to "NA" or "missing" become NaN in the output matrix.

Use European Decimal And Thousands Separators

M = readmatrix("data/europe.csv", 'Delimiter', ';', 'DecimalSeparator', ',', 'ThousandsSeparator', '.')

Expected output:

% Values like "1.234,56" are interpreted as 1234.56.

Replace Empty Numeric Fields With A Custom Value

M = readmatrix("data/with_blanks.csv", 'EmptyValue', 0)

Expected output:

% Blank entries become 0 instead of NaN.

Import A Specific Range Of Cells

M = readmatrix("data/quarterly.csv", 'Range', 'B2:D5')

Expected output:

% Returns only the rows and columns covered by the specified range.

Convert The Result To A Logical Matrix

flags = readmatrix("data/thresholds.csv", 'OutputType', 'logical')

Expected output:

% Non-zero entries (including NaN) become logical true, zero stays false.

Keep The Result On The GPU By Matching A Prototype

proto = gpuArray.zeros(1);        % simple prototype to establish residency
G = readmatrix("data/heavy.csv", 'Like', proto)

Expected output:

% The parsed matrix is uploaded to the same GPU device as the prototype.

Provide Options Using A Struct From detectImportOptions

opts = struct('Delimiter', ',', 'NumHeaderLines', 1);
M = readmatrix("data/measurements.csv", opts)

Expected output:

% Reads the file using the supplied options struct.

Using readmatrix with coding agents

Open a RunMat example with live inputs, then ask the agent to explain how readmatrix changes the result.

FAQ

Related Io functions

Open-source implementation

Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how readmatrix is executed, line by line, in Rust.

• View the source for readmatrix in Rust on GitHub
• Learn how the RunMat runtime works
• Found a bug? Open an issue with a minimal reproduction.

About RunMat

RunMat is an open-source runtime that executes MATLAB-syntax code blazing on any GPU. It is licensed under the Apache 2.0 license.

• RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
• Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.

Getting started · Benchmarks · Pricing