WOLFRAM

Wolfram Language & System Documentation Center

MAT (.mat)

  • Import fully supports MAT Version 7.3 and lower.
  • Export by default generates Version 5.0 or 7.3 MAT-files, depending on the file size.

Background & Context

    • MATLAB MAT-files.
    • Matrix data format.
    • Native data format of the MATLAB numerical computation software.
    • Stores numerical matrices, Boolean values, or strings.
    • Also stores sparse arrays, nested structures and more.
    • Binary format.
    • Version 7.3 of MAT-files uses HDF5.

Import & Export

  • Import["file.mat"] imports a MAT-file, returning a multidimensional array containing numbers, strings or Boolean values.
  • Import["file.mat",elem] imports the specified element from a MAT-file.
  • The import format can be specified with Import["file", "MAT"] or Import["file",{"MAT",elem,…}].
  • Export["file.mat",expr] creates a MAT-file from an array of integers, doubles and complex values.
  • Export["file.mat",{elem1->expr1,elem2->expr2,…},"Rules"] uses rules to specify the elements to be exported.
  • See the following reference pages for full general information:
  • Import, Exportimport from or export to a file
    CloudImport, CloudExportimport from or export to a cloud object
    ImportString, ExportStringimport from or export to a string
    ImportByteArray, ExportByteArrayimport from or export to a byte array

Import Elements

  • General Import elements:
  • "Elements" list of elements and options available in this file
    "Summary"summary of the file
    "Rules"list of rules for all available elements
  • Data representation element:
  • "Data"numerical or textual data given as a multidimensional array
    "LabeledData"data given as a list of rules
  • Import and Export use the "Data" element by default.
  • Data descriptor elements:
  • "DataFormat"variable data type
    "Dimensions"dimensions of the array
  • When appropriate, numerical data is imported as SparseArray objects.
  • Meta-information element:
  • "Comments"user comments stored in the file
    "Labels"variable names given as a list of strings
    "Version"version of the MAT specification for the file

Options

  • Import options:
  • "IndeterminateValues"Automaticreplacement values for infinity, NaN, etc.
  • Use "IndeterminateValues" to provide replacement rules for different values. The following settings are supported:
  • vala fixed value val for any indeterminate value
    <|"NaN"…,"Inf"…,"-Inf"…|>specific replacements depending on the type indeterminate
  • Export options:
  • CompressionLevelAutomaticcompression level to use
    OverwriteTargetTruewhether to overwrite an existing file
    "Version"Automaticversion of the file format to use
  • Using OverwriteTarget->"Append", new objects may be added to an existing file.
  • Supported versions in export are "4", "5", "7.3".
  • By default, export generates version "5" MAT-files. For variables larger than bytes, a version "7.3" file is generated.

Examples

open all close all

Basic Examples  (3)

This imports a simple MAT-file:

Wolfram Language code: Import["ExampleData/numbers.mat"]

Summary of a MAT-file:

Wolfram Language code: Import["ExampleData/numbers.mat", "Summary"]

Export a numerical matrix:

Wolfram Language code: Export["data.mat", {{{1, 2, 3}}}]

Scope  (9)

Import  (2)

List available Import elements

Wolfram Language code: Import["ExampleData/numbers.mat", "Elements"]

Import a variable with label "y":

Wolfram Language code: Import["ExampleData/numbers.mat", "y"]

Export  (7)

Export an array of numbers to a MAT-file:

Wolfram Language code: Export["file.mat", Range[5]]

If no variable name is given, the default variable name "Expression1" is used:

Wolfram Language code: Import["file.mat", "LabeledData"]

Export data with custom variable name:

Wolfram Language code: Export["file.mat", "v" -> Range[10]]
Wolfram Language code: Import[%, "LabeledData"]

Export multiple variables to a file. Variable names must be explicitly given:

Wolfram Language code: Export["file.mat", {"v1" -> Range[10], "v2" -> Reverse@Range[5]}]
Wolfram Language code: Import[%, "LabeledData"]

Export a SparseArray:

Wolfram Language code: Export["file.mat", SparseArray[{{1, 1} -> 1., {2, 2} -> 2., {3, 3} -> 3., {1, 4} -> 4.}]]
Wolfram Language code: Import[%, "Data"]

Export an array of strings:

Wolfram Language code: Export["file.mat", {{"a", "bb"}, {"ccc", "dddd"}}]
Wolfram Language code: Import[%, "Data"]

Export an array of expressions of possibly different types:

Wolfram Language code: Export["file.mat", {{"a", 5}, {{Pi, E}, "text"}}]
Wolfram Language code: Import[%, "Data"]

Export an array of associations with consistent keys into a "structure" array:

Wolfram Language code: data = Table[<|"a" -> 10 * i + j, "b" -> IntegerName[j * j + i]|>, {i, 1, 3}, {j, 1, 2}];data//Grid
Wolfram Language code: Export["file.mat", data]
Wolfram Language code: Import[%, "Data"]//First//Grid

Import Elements  (10)

"Comments"  (1)

Import comments from a MAT file, which often contains the version and additional comments:

Wolfram Language code: Import["ExampleData/numbers.mat", "Comments"]

"Data"  (2)

Import data from all variables in the file:

Wolfram Language code: Import["ExampleData/numbers.mat", "Data"]

Import a variable by its label:

Wolfram Language code: Import["ExampleData/numbers.mat", "y"]

"DataFormat"  (1)

Import the data type of each variable in the file:

Wolfram Language code: Import["ExampleData/numbers.mat", "DataFormat"]

"Dimensions"  (1)

Import the dimensions of each variable in the file:

Wolfram Language code: Import["ExampleData/numbers.mat", "Dimensions"]

"LabeledData"  (2)

Import data as a list or namedata rules, for all variables in the file:

Wolfram Language code: Import["ExampleData/numbers.mat", "LabeledData"]

Create a file with two variables:

Wolfram Language code: Export["file.mat", {"v1" -> Range[10], "v2" -> Reverse@Range[5]}];

Import one of the variables:

Wolfram Language code: Import["file.mat", {"LabeledData", "v1"}]

Import variables whose name matches a string pattern:

Wolfram Language code: Import["file.mat", {"LabeledData", "v*"}]

"Labels"  (1)

Import variable names in the same order as they are stored in the file:

Wolfram Language code: Import["ExampleData/numbers.mat", "Labels"]

"Summary"  (1)

Import the summary of the file, which includes file name, MAT format version, variable count and file size:

Wolfram Language code: Import["ExampleData/numbers.mat", "Summary"]

"Version"  (1)

Import the version of the MAT file specification in which the file has been saved:

Wolfram Language code: Import["ExampleData/numbers.mat", "Version"]

Export Options  (14)

CompressionLevel  (3)

Export a large numeric array. By default, the data will be compressed (equivalent to level 1):

Wolfram Language code: Export["file.mat", RandomInteger[1000, {1000, 1000}]]
Wolfram Language code: FileSize["file.mat"]

Export data with no compression:

Wolfram Language code: Export["file.mat", RandomInteger[1000, {1000, 1000}], CompressionLevel -> 0]
Wolfram Language code: FileSize["file.mat"]

Compression is not supported in MAT version 4:

Wolfram Language code: Export["file.mat", RandomInteger[1000, {1000, 1000}], "Version" -> 4, CompressionLevel -> 1]
Wolfram Language code: FileSize["file.mat"]

"Header"  (3)

By default, an automatic header is created:

Wolfram Language code: Export["file.mat", {1, 2, 3}, "Header" -> Automatic]
Wolfram Language code: Import["file.mat", "Comments"]

Specify a header, which is stored after the MAT version number:

Wolfram Language code: Export["file.mat", {1, 2, 3}, "Header" -> "I created this file"]

The header can be imported using the "Comments" element:

Wolfram Language code: Import["file.mat", "Comments"]

The header cannot be too long:

Wolfram Language code: Export["file.mat", {1, 2, 3}, "Header" -> StringJoin@@Table[Alphabet[], 5]];

OverwriteTarget  (3)

By default, a new file is created for each call to Export:

Wolfram Language code: Export["file.mat", {1, 2, 3}]

With OverwriteTargetFalse, existing files will not be overwritten:

Wolfram Language code: Export["file.mat", {4, 5, 6}, OverwriteTarget -> False]

To append variables at the end of an existing file, use OverwriteTarget"Append":

Wolfram Language code: Export["file.mat", {"v" -> {4, 5, 6}}, OverwriteTarget -> "Append"]
Wolfram Language code: Import["file.mat", "LabeledData"]

A variable being appended to an existing file should have a new name:

Wolfram Language code: Export["file.mat", {"v" -> {Pi, Pi}}, OverwriteTarget -> "Append"]

"Version"  (5)

By default, Export creates MAT-files Version 5:

Wolfram Language code: Export["file.mat", {1, 2, 3}]
Wolfram Language code: Import[%, "Version"]

Export data to MAT Version 4:

Wolfram Language code: Export["file.mat", {1, 2, 3}, "Version" -> 4]
Wolfram Language code: Import[%, "Version"]

Export data to MAT Version 7.3:

Wolfram Language code: Export["file.mat", {1, 2, 3}, "Version" -> 7.3]
Wolfram Language code: Import[%, "Version"]

Version can be specified either as a number or a string:

Wolfram Language code: Export["file.mat", {1, 2, 3}, "Version" -> "7.3"]
Wolfram Language code: Import[%, "Version"]

Some data types (e.g. arrays of mixed types) cannot be exported to MAT Version 4:

Wolfram Language code: Export["file.mat", {1, "text", Pi}, "Version" -> "4"]