matopen(filename [, mode]; compress = false, table = MatlabTable, convert_opaque = true) -> handle
matopen(f::Function, filename [, mode]; compress = false, table = MatlabTable, convert_opaque = true) -> f(handle)

Mode defaults to "r" for read. It can also be "w" for write, or "r+" for read or write without creation or truncation.

Compression on reading is detected/handled automatically; the compress keyword argument only affects write operations.

Use with read, write, close, keys, and haskey.

Optional keyword argument is the table type, for automatic conversion of Matlab tables and timetables (a timetable's row times become its first column). Note that Matlab tables may contain non-vector columns which cannot always be converted to a Julia table, like DataFrame.

With convert_opaque = false, MATLAB string, datetime, duration, categorical, table and timetable objects are returned as MatlabOpaque rather than converted to Julia types.

Example

using MAT, DataFrames
filepath = abspath(pkgdir(MAT), "./test/v7.3/struct_table_datetime.mat")
fid = matopen(filepath; table = DataFrame)
keys(fid)

# outputs

1-element Vector{String}:
 "s"

Now you can read any of the keys

s = read(fid, "s")
close(fid)
s

# outputs

Dict{String, Any} with 2 entries:
  "testDatetime" => DateTime("2019-12-02T16:42:49.634")
  "testTable"    => 3×5 DataFrame…

matread(filename; table = MatlabTable, convert_opaque = true) -> Dict

Return a dictionary of all the variables and values in a Matlab file, opening and closing it automatically.

Optionally provide the table type to convert Matlab tables and timetables into. Default uses a simple MatlabTable type. With convert_opaque = false, MATLAB string, datetime, duration, categorical, table and timetable objects are returned as MatlabOpaque rather than converted to Julia types.

Example

using MAT, DataFrames
filepath = abspath(pkgdir(MAT), "./test/v7.3/struct_table_datetime.mat")
vars = matread(filepath; table = DataFrame)
vars["s"]["testTable"]

# outputs

3×5 DataFrame
 Row │ FlightNum  Customer  Date                 Rating  Comment
     │ Float64    String    DateTime             String  String
─────┼─────────────────────────────────────────────────────────────────────────────────────
   1 │    1261.0  Jones     2016-12-20T00:00:00  Good    Flight left on time, not crowded
   2 │     547.0  Brown     2016-12-21T00:00:00  Poor    Late departure, ran out of dinne…
   3 │    3489.0  Smith     2016-12-22T00:00:00  Fair    Late, but only by half an hour. …

matread(filename, varname, T; table = MatlabTable, convert_opaque = true) -> T

Read a single variable from a Matlab file and construct it as type T using StructUtils.jl. This enables round-tripping Julia structs through .mat files.

Supports StructUtils features including @tags for field renaming, @defaults for default values, and @choosetype for abstract type dispatch.

Values are converted to the requested field types where MATLAB's data model differs from Julia's:

• a 1x1 MATLAB array is read back as a scalar, and is widened again for an array-typed field, so Vector{Float64} accepts a one-element array;
• element types are converted, so a MATLAB single/int32/logical array or a cell array of numbers can be read as Matrix{Float64};
• trailing singleton dimensions are added or dropped to match the requested dimensionality, and a MATLAB array with a single non-singleton dimension (a row or column vector) can be read as a Vector. A shape that cannot be matched this way is reported rather than being silently flattened;
• an empty array reads as nothing/missing for a Union{Nothing,T} or Union{Missing,T} field, matching MATLAB's use of [] for a missing value.

A value that cannot be constructed as T raises a MATConstructionError, whose cause field holds the underlying error.

Example

using MAT

@defaults struct Person
    name::String = ""
    age::Int = 0
end

matwrite("people.mat", Dict("person" => Person("Alice", 30)))
person = matread("people.mat", "person", Person)
# Person("Alice", 30)

matwrite(filename, d::Dict; compress::Bool = false, version::String = "v7.3")

Write a dictionary containing variable names as keys and values as values to a Matlab file, opening and closing it automatically.

Internal Marker for Empty Structs with dimensions like 1x0 or 0x0

FunctionHandle(d::Dict{String, Any}) <: AbstractDict{String, Any}

Type to store function handles which are stored as structs in MATLAB.

MATConstructionError(T, cause)

Raised by the typed read methods when a value read from a MAT file cannot be constructed as the requested type T. The underlying cause is reported as part of the error message.

MATReadStyle <: MATStyle

The StructUtils style used by the typed reads, matread(filename, varname, T) and read(matfile_handle, varname, T). Extend a StructUtils function on this style to change how a type is built from MAT data without affecting how it is written, for example @choosetype MATReadStyle MyAbstractType x -> ... to limit a type choice to MAT reads. See MATStyle.

MATStyle <: StructUtils.StructStyle

The StructUtils.jl style MAT.jl uses to convert between Julia values and MAT data. It has two concrete subtypes, MATReadStyle and MATWriteStyle.

You only need the style types to customize how your own types are converted, by adding a method for a StructUtils function that dispatches on the style. A method on MATStyle applies to both reading and writing; one on a subtype applies to that direction only. Methods on a MAT style do not affect other packages built on StructUtils, such as JSON.jl.

Field tags are namespaced under mat, so they can sit alongside tags for other packages:

@tags struct Sample
    x::Float64 &(mat=(name="sample_x",), json=(name="x",))
end

Example

A type MATLAB has no representation for is stored as a plain number by extending StructUtils.lower for MATWriteStyle, and read back by extending StructUtils.lift. Declaring it not structlike tells StructUtils it is a single value rather than a struct to be rebuilt field by field. This two-argument lift takes no style, so unlike the other two methods it applies to every package built on StructUtils:

using MAT

struct Celsius
    degrees::Float64
end

StructUtils.lower(::MATWriteStyle, x::Celsius) = x.degrees
StructUtils.structlike(::MATStyle, ::Type{Celsius}) = false
StructUtils.lift(::Type{Celsius}, x::Float64) = Celsius(x)

MATWriteStyle <: MATStyle

The StructUtils style used by matwrite and write. Extend StructUtils.lower on this style to convert a value to something MATLAB can store before it is written; the overload applies wherever the value appears, whether as a variable, a struct field, a Dict value or a cell array element:

StructUtils.lower(::MATWriteStyle, x::Celsius) = x.degrees

See MATStyle.

MatlabClassObject(
    d::Dict{String, Any},
    class::String,
) <: AbstractDict{String, Any}

Type to store old class objects. Inside MATLAB a class named "TestClassOld" would be defined within @TestClassOld folders.

If you want to write these objects you have to make sure the keys in the Dict match the class defined properties/fields.

MatlabOpaque(
    d::Dict{String, Any},
    class::String,
) <: AbstractDict{String, Any}

Type to store opaque class objects. These are the 'modern' Matlab classes, different from the old MatlabClassObject types.

MatlabStructArray{N}(
    names::Vector{String},
    values::Vector{Array{Any,N}},
    class::String = "",
)

Data structure to store matlab struct arrays, which stores the field names separate from the field values. The field values are stored as columns of Array{Any,N} per Matlab field, which is how MAT files store these structures.

These are distinct from cell arrays of structs, which are handled as in MAT.jl as Array{Any,N} with Dict{String,Any} inside, for example Any[Dict("x"=>1), Dict("x"=>2)].

Old class object arrays can be handled by providing a non-empty class name.

Example

using MAT

s_arr = MatlabStructArray(["a", "b"], [[1, 2],["foo", 5]])

# write-read
matwrite("matfile.mat", Dict{String,Any}("struct_array" => s_arr))
read_s_arr = matread("matfile.mat")["struct_array"]

# convert to Dict Array
dict_array = Array{Dict{String,Any}}(s_arr)

# convert to Dict (with arrays as fields)
dict = Dict{String,Any}(s_arr)

MatlabTable(names, columns)

Representation of a MATLAB table, with column names in names and the corresponding column arrays in columns. Implements the Tables.jl column interface.

For vector columns, convert to a DataFrames.jl table with DataFrame(table); the destination controls whether columns are copied. To convert MATLAB tables while reading a file, pass table=DataFrame to matread.

MATLAB columns with several values per row are retained as matrices. Adapt those columns before converting to a destination that only accepts vectors.

construct_from_raw(raw, ::Type{T}) -> T

Convert a raw MAT value (Dict, MatlabStructArray, Array, ...) into type T via StructUtils. Shared by the MAT_HDF5, MAT_v5 and MAT_v4 typed-read methods. Failures are wrapped in a MATConstructionError.

This is internal to MAT.jl; use read(matfile_handle, varname, T) or matread(filename, varname, T) instead.

prepare_source(raw, ::Type{T})

Unwrap a source before it reaches StructUtils.make: a whole variable, or an element of an array being constructed.

A one-element struct array is a valid source for a single T, and the make method below implements that. It cannot be the only implementation, though: being general in the target type, it is ambiguous with the per-type make methods @choosetype defines, so a @choosetype target built from a struct array would fail on dispatch. Unwrapping here happens before dispatch, which keeps that case working.

to_zoned(utc::DateTime, tz::String)

A zoned datetime from its UTC instant and MATLAB's name for the zone (an IANA name such as "Europe/London", "UTC", or a fixed offset such as "+05:30"). Defined by the TimeZones extension (Julia 1.9 and later, when TimeZones.jl is loaded), which returns a ZonedDateTime; without it, zoned datetimes are read as their UTC instant.