ImportMatrix - Maple Programming Help

ImportMatrix

import a Matrix from a file or URL

ExportMatrix

export a Matrix to a file

 Calling Sequence ImportMatrix(f, options) ImportMatrix(url, options) ExportMatrix(f, M, options)

Parameters

 f - string or symbol; name of file where Matrix is stored url - string or symbol; URL from which to retrieve a Matrix M - Matrix or list of Matrices options - (optional) zero or more of the options described below

Options

ImportMatrix Options

 • datatype=d
 Set data type of resulting Matrix, where d is a Maple type compatible with the imported data. The default is anything.
 • direct=true or false
 When direct=true, specifies that the parameter f is not a file path but a string containing the actual data to be parsed. The default is false.
 • fill=fval
 Set the default value for entries not filled by the imported data. This can occur with delimited or csv files when one line contains fewer entries than another line elsewhere in the file. The value fval must be compatible with datatype d.
 • output=t
 Return names and Matrices, if t is all, or just Matrices, if t is matrices. This option applies to MATLAB® binary files only. The default is all.
 • skiplines=n
 Ignore n lines at the beginning of the file, where n is a non-negative integer. This option applies to text files only. The default value for n is 0.
 • source=s
 Specify data source format, where s is one of the names auto, csv, delimited, dif, Excel, MATLAB, MatrixMarket, ods, sxc, or tsv.  The default is auto, meaning ImportMatrix will attempt to infer the source format. Matlab is also accepted as a synonym for MATLAB.
 • sourceid=s
 Use a specific table from a data source supporting multiple tables. This option applies only when the source format is Excel, ods, or sxc.

ExportMatrix Options

 • target=t
 Specify data target format, where t is one of the names auto, csv, delimited, dif, Excel, MATLAB, MatrixMarket, ods, sxc, or tsv.   The default is auto, meaning ExportMatrix will attempt to infer the target format from the filename extension. Matlab is also accepted as a synonym for MATLAB.
 • arraynames=m
 Specify MATLAB® array names, where m is a string or list of strings. The default for m is "mat". This option applies to MATLAB® binary files only.

Options That Can Be Used with Both ImportMatrix and ExportMatrix

 • delimiter=s
 Specify character that separates entries in the file, where s is a string containing a single character. This option applies to text files only. The default is "\t" (Tab) except for MATLAB® ASCII files, for which it is " " (space).
 • format=f
 Specify data storage method, where f is one of the names rectangular, entries, or vectors. The default is rectangular. See details in the Overview section below.
 • transpose=t
 Indicate whether to transpose the data being imported or exported. The value of t can be true or false. The option transpose on its own is equivalent to transpose=true. The default value is false.
 • mode=m
 Specify the type of MATLAB® file. ASCII, Version 6 binary files and Version 7 binary files are supported and correspond to the following values of m respectively: ascii, v6, v7. The value binary is also accepted and is equivalent to v7.

Description

 • The ImportMatrix command imports a matrix from an external file, URL, string or ByteArray.
 • The ExportMatrix command exports a matrix or list of matrices to an external file, string, or ByteArray.
 • The type of file to be imported by ImportMatrix is specified with the source option. In some cases, the ImportMatrix command is able to detect the file type automatically and the source option may be omitted. The ImportMatrix command returns a single Matrix, or in the case of MATLAB® binary files, a sequence of lists with names and Matrices.
 • The type of file to be exported by ExportMatrix is specified with the target option. The ExportMatrix command writes the Matrix or list of Matrices to the given filename and returns the number of bytes written.
 • The parameter M to ExportMatrix must be a single Matrix unless the export format is the MATLAB® binary format, in which case a list of Matrices is also accepted.
 • The format option is available for ASCII files. This option is not applicable to MATLAB® binary files and is ignored. Three values for the format option are allowed, with rectangular being the default.
 The rectangular format means data is provided in row-major order and each line in the file represents a row in the Matrix.
 The entries format means each stored value is provided as a row-column-value triple, and the entries can appear in any order. There must be exactly three entries per line for real data and four entries per line for complex data.
 The vectors format means that a vector of row indices is provided, followed by a vector of column indices, followed by a vector of values.  If these vectors are r, c, and v, then the entries in Matrix M, which can be provided in any order, are given by ${M}_{{r}_{i},{c}_{i}}≔{v}_{i}$.
 • See the sections below for information specific to one of the supported file formats.

Details on Formats

 • The data format can be specified for ImportMatrix with the source option and for ExportMatrix with the target option.
 • The default value for both source and target is auto, in which case Maple will attempt to infer the data format from the filename or content data.

MATLAB® Binary Format

 • MATLAB® binary files are imported using the source=MATLAB option. In most cases, ImportMatrix can automatically detect binary files created in MATLAB® versions 5, 6, or 7 and the source option may be omitted. Binary files from earlier versions are not supported.
 ImportMatrix returns a sequence of lists, each containing the name of the MATLAB® array as a string and the imported Matrix. To get a sequence of Matrices only, use the output=matrices option.
 Both sparse and dense arrays can be imported. MATLAB® sparse and dense arrays are imported as Maple sparse and rectangular Matrices, respectively.  The format option is not applicable in this case.
 MATLAB® objects, cell arrays, structures and arrays with dimension greater than two cannot be imported. If any of these are detected, they are skipped over and a warning is issued.
 • A single Matrix or list of Matrices can be exported to a MATLAB® binary file using the target=MATLAB option. By default, this option generates the latest MATLAB® version supported by Maple. Currently, this is Version 7, which includes compression of the data as described on the StringTools[Compress] help page. To generate a binary file without compression that is compatible with MATLAB® Version 6, include the mode=v6 option in the calling sequence.
 ExportMatrix assigns automatically generated names to the exported Matrices and writes them as double-precision MATLAB® arrays. Only numeric data can be exported.
 Maple sparse and rectangular Matrices are exported as MATLAB® sparse and dense arrays respectively.
 The names written to the file may be specified with the arraynames=m option. If m is a list, it must have exactly n names where n is the number of Matrices in M. If m is a string and n>1, then unique names generated from m will be created.
 • The datatype and transpose options are available (the former for ImportMatrix only), but the delimiter and skiplines options are ignored. The format option is ignored.

MATLAB® ASCII Format

 • MATLAB® ASCII files are imported using the source=MATLAB and mode=ascii options. It is assumed that the MATLAB® "save ... -ascii" command was used to export the Matrix from MATLAB®. If the MATLAB® "dlmwrite" (delimited write) command was used, use the source=delimited option and see the instructions for Generic Delimited Format below.
 • A Matrix can be exported to MATLAB® ASCII format using the target=MATLAB and mode=ascii options. Only numeric data can be written. Because the MATLAB® rectangular format does not support complex numbers, use the format=entries option with complex data.
 • The default delimiter is " " (space), but an alternate delimiter can be specified. Files imported from and exported to MATLAB® look very similar to generic delimited files but there are a few differences. First, if the last entry in the Matrix is zero, then the entries format adds this entry explicitly, so that the row and column dimension can be deduced. Second, complex values are written out in "z g" format (i.e., a space between real and complex part) instead of "Zg" format (i.e., +I);
 • All options are accepted except the ones for MATLAB® binary files only. The format option does not accept the value vectors.

Matrix Market Format

 • Matrix Market files are imported using the source=MatrixMarket option. Files in Matrix Market format include a standard comment line indicating that the file contains Matrix Market data; if Maple detects such a comment line when importing a Matrix from a file, it assumes that the file is in Matrix Market format. Otherwise, a generic delimited file is assumed.
 If the imported file is in Matrix Market "coordinate" format, a sparse Matrix is returned. If the file is in "array" format, a dense (rectangular) Matrix is created. The "pattern" format is not supported. The format or delimited options are ignored by ImportMatrix.
 • With the ExportMatrix command, sparse Matrices are written in the "coordinate" format and dense Matrices are written in the "array" format. The default behavior can be changed with the format option: entries results in "coordinate" format, rectangular results in "array" format, and vectors is not accepted.
 If the Matrix contains symbolic entries, it will not fit into the predefined data types "integer", "real", or "complex"; "Maple[symbolic]" is used instead.
 • The delimiter option and the options specific to MATLAB® binary files are ignored.

Excel Format

 • The source=Excel or target=Excel causes f to be interpreted as a Microsoft Excel file. Both ImportMatrix and ExportMatrix support this format, which is autodetected when the format is unspecified and the filename ends in ".xlsx" or ".xls". Both XLSX (Office Open XML) and XLS (Excel 97-2003) file formats are supported.

DIF Format

 • The option source=dif or target=dif causes f to be interpreted as a Data Interchange Format file. Both ImportMatrix and ExportMatrix support this format, which is autodetected when the format is unspecified and the filename ends in ".dif".

ODS Format

 • The option source=ods or target=ods causes f to be interpreted as an OpenDocument Spreadsheet file. Both ImportMatrix and ExportMatrix support this format, which is autodetected when the format is unspecified and the filename ends in ".ods".

SXC Format

 • The option source=sxc or target=sxc causes f to be interpreted as a Sun XML Calc Spreadsheet file, Both ImportMatrix and ExportMatrix support this format, which is autodetected when the format is unspecified and the filename ends in ".sxc".

CSV (Comma-Separated Values) Format

 • The option source=csv or target=csv causes f to be interpreted as a Comma-Separated Values file.
 • If the source option value csv or csv[Microsoft], then ImportMatrix reads fields from a Microsoft CSV file format. Otherwise, if csv[standard] is specified, it reads fields from a standard CSV file. The result is a Matrix of objects of type string.

TSV (Tab-Separated Values) Format

 • The option source=tsv or target=tsv causes f to be interpreted as a Tab-Separated Values file.  This is equivalent to the delimited format with the delimiter set to a Tab character.  In this case the delimited option has no effect.

Generic Delimited Format

 • With ImportMatrix, if the source file format cannot be determined and the file contains numeric data, then it is assumed to be a generic delimited file. The source=delimited option can also be used to specify this information.
 Since the type of imported data is not known, the Matrix is read by using %s and then parsed. The exception to this rule is complex Matrices that have been stored by using %Zf format; they are read with %Zf format instead. For more information, see help on the scanf statement.
 • ExportMatrix assumes delimited format if the target option is not provided.
 Complex numbers are written in Zg format (i.e., + I) to make it obvious that they represent complex numbers.
 When the format=rectangular option is given, all entries are written out. When format is vectors or entries, only stored values are written out, resulting in more efficient storage for non-dense structures such as band and sparse Matrices. With symmetric Matrices having sparse[upper] or sparse[lower] storage, only half the entries are written. The program importing the data needs to be made aware of the symmetry properties of the Matrix.
 • All options except the ones specific to MATLAB® binary files are accepted and have the default values as described in the Options sections above.

Examples

 > $\mathrm{matlabFile}≔\mathrm{FileTools}:-\mathrm{JoinPath}\left(\left[\mathrm{ifelse}\left(\mathrm{kernelopts}\left(\mathrm{byteorder}\right)="little endian","example/dataLE.mat","example/dataBE.mat"\right)\right],\mathrm{base}=\mathrm{datadir}\right):$

Import a MATLAB® binary data file.

 > $A≔\mathrm{ImportMatrix}\left(\mathrm{matlabFile},\mathrm{source}=\mathrm{MATLAB}\right)$
  (1)

Import the same file but return the Matrices only.

 > $A≔\mathrm{ImportMatrix}\left(\mathrm{matlabFile},\mathrm{source}=\mathrm{MATLAB},\mathrm{output}=\mathrm{matrices}\right)$
  (2)
 > $\mathrm{matlabFile}≔\mathrm{FileTools}:-\mathrm{JoinPath}\left(\left["example/MatlabData.txt"\right],\mathrm{base}=\mathrm{datadir}\right):$

Import a MATLAB® ASCII data file with entries format.

 > $A≔\mathrm{ImportMatrix}\left(\mathrm{matlabFile},\mathrm{source}=\mathrm{MATLAB},\mathrm{format}=\mathrm{entries},\mathrm{transpose}=\mathrm{true}\right)$
  (3)

Export the previous data as MATLAB® target with rectangular format.

 > $\mathrm{ExportMatrix}\left(\mathrm{matlabData},A,\mathrm{target}=\mathrm{MATLAB},\mathrm{format}=\mathrm{rectangular},\mathrm{mode}=\mathrm{ascii}\right)$
 ${625180}$ (4)

Use the skiplines option to skip lines at the beginning of the source data.

 > $\mathrm{ImportMatrix}\left(\mathrm{matlabData},\mathrm{source}=\mathrm{MATLAB},\mathrm{skiplines}=30\right)$
  (5)
 > $\mathrm{delimitedFile}≔\mathrm{FileTools}:-\mathrm{JoinPath}\left(\left["example/example.del"\right],\mathrm{base}=\mathrm{datadir}\right):$

Use the delimiter option to specify the data delimiter.

 > $\mathrm{ImportMatrix}\left(\mathrm{delimitedFile},\mathrm{delimiter}="",\mathrm{datatype}=\mathrm{string}\right)$
  (6)
 > $\mathrm{csvFile}≔\mathrm{FileTools}:-\mathrm{JoinPath}\left(\left["example/timedata.csv"\right],\mathrm{base}=\mathrm{datadir}\right)$
 ${\mathrm{csvFile}}{≔}{"/maple/cbat/active/147321/data/example/timedata.csv"}$ (7)

This illustrates the use of the CSV file formats.

 > $\mathrm{ImportMatrix}\left(\mathrm{csvFile}\right)$
  (8)

Compatibility

 • The ExportMatrix command was updated in Maple 18.
 • The url parameter was introduced in Maple 18.
 • The sourceid option was introduced in Maple 18.
 • The source and target options were updated in Maple 18.