MLLoadWave
MLLoadWave [/Q/O/B/I/A[=baseName]/N[=name]/P=pathName /R/C/M[=m]/Y=y/T/E/V/S[=s]/G/Z] fileNameStr
The MLLoadWave operation loads data from the named Matlab MAT file into single 1D waves (vectors), multidimensional waves (matrices), numeric variables or string variables.
For background information, including configuration instructions, see Loading Matlab MAT Files.
Parameters
The file to be loaded is specified by fileNameStr and /P=pathName where pathName is the name of an Igor symbolic path. fileNameStr can be a full path to the file, in which case /P is not needed, a partial path relative to the folder associated with pathName, or the name of a file in the folder associated with pathName. If LoadWave cannot determine the location of the file from fileNameStr and pathName, it displays a dialog allowing you to specify the file.
If you use a full or partial path for fileNameStr, see Path Separators for details on forming the path.
If fileNameStr is omitted or is "" or the /I flag is used, MLLoadWave displays an Open File dialog in which you locate the file to be loaded.
Flags
| /A[=name] | Assign wave names using "wave" or name , if present, as the name or base name. Skips names already in use. | ||||||||||||||||
| /B | This flag is obsolete and is ignored. Previously it was required to tell MLLoadWave the byte order of the data in the file. MLLoadWave now determines the byte order automatically. | ||||||||||||||||
| /C | Loads columns from a Matlab matrix into an Igor 1D wave. Use /R to load rows. | ||||||||||||||||
| /E | Skips empty Matlab matrices. | ||||||||||||||||
| /G | Tells Igor to make numeric and string variables global when called from a macro. When called from a user-defined function or from the command line, variables are always created as globals. | ||||||||||||||||
| /I | Interactive. Displays the Open File dialog to get the path to the file. | ||||||||||||||||
| /M=m |
| ||||||||||||||||
| /M by itself is equivalent to /M=1. | |||||||||||||||||
| Starting with Igor Pro 8.00, after loading a matrix that results in an Mx1 2D wave, MLLoadWave automatically redimensions the wave as an M-row 1D wave. | |||||||||||||||||
| /N[=name ] | Assign wave names using "wave" or name , if present, as the name or base name. Overwrites existing waves if the name is already in use. | ||||||||||||||||
| /O | Overwrites existing waves and variables in case of a name conflict. If /O is omitted, MLLoadWave chooses names that don’t conflict with existing objects. | ||||||||||||||||
| /P=pathName | Specifies the folder to look in for the specified file or folder. pathName is the name of an existing Igor symbolic path. | ||||||||||||||||
| /Q | Be quiet. Suppresses normal diagnostic messages. | ||||||||||||||||
| /R | Loads rows from a Matlab matrix into an Igor 1D wave. Use /C to load columns. | ||||||||||||||||
| /S=s |
| ||||||||||||||||
| /S by itself is equivalent to /S=1. | |||||||||||||||||
| /T | Displays the loaded waves in a new table. | ||||||||||||||||
| /V | Skips Matlab numeric variables (numeric matrices with one element). | ||||||||||||||||
| /Y=y | Specifies the number type of the numeric waves to be created. The allowed codes for y are: | ||||||||||||||||
| |||||||||||||||||
| /Z | Interactive load. Displays a dialog presenting options for each Matlab matrix in the file. | ||||||||||||||||
MLLoadWave Wave Naming
If neither /A, /A[=name ], /N, or N[=name ] is used then the waves names are taken from the matrix name, as stored in the Matlab file.
When loading 1D waves, the /N flag instructs MLLoadWave to automatically name new waves "wave" (or name if /N=name is used) plus a number. The number starts from zero and increments by one for each wave loaded from the file. When loading multidimensional waves, name is used without an appended number.
The /A flag is like /N except that MLLoadWave skips names already in use.
If you specify /M=2 (load matrix into matrix) or /M=3 (load matrix into transposed matrix), MLLoadWave uses the name without appending any digits. For example, if you have a 5x3 matrix in a file and you tell MLLoadWave to load it as a matrix using the name "mat", MLLoadWave will name the matrix "mat". However, if you tell MLLoadWave to load the matrix as 3 1D waves, it will use "mat0", "mat1" and "mat2".
If the name that MLLoadWave would use when creating a wave or variable is in use for an object of the same type and if you use the overwrite flag, then it will overwrite the existing object. If you do not tell MLLoadWave to overwrite, it will choose a non-conflicting name. If the conflict is with an object of a different type or with an operation or function, MLLoadWave will also choose a non-conflicting name.
Loading Strings from Matlab Files
When loading Matlab strings into Igor, you can tell MLLoadWave to create Igor string variables or Igor text waves. For example, if you have a 2x8 string matrix, MLLoadWave can create two string variables (/S=2) or one text wave (/S=3) containing two elements.
When loading Matlab string data into an Igor wave, the Igor wave will be of dimension one less than the Matlab data set. This is because each element in a Matlab string data set is a single byte whereas each element in an Igor string wave is a string (any number of bytes).
Loading Numeric Variables from Matlab Files
MLLoadWave loads numeric matrices with one element into Igor numeric variables. It loads all other numeric matrices into Igor waves.
When called from a macro, MLLoadWave creates local numeric and string variables unless you use the /G flag which tells it to create global variables. When called from the command line or from a user-defined function, MLLoadWave always creates global variables. Macros should be avoided in new programming.
Automatic Redimensioning from 2D to 1D
Starting with Igor Pro 8.00, after loading a matrix that results in an Mx1 2D wave, MLLoadWave automatically redimensions the wave as an M-row 1D wave.
This automatic redimensioning not affect the naming of the wave. It is still named using the 2D rules explained above under MLLoadWave Wave Naming.
Loading 3D and 4D Data from Matlab Files
For a discussion of how MLLoadWave handles 3D and 4D Matlab data, see Numeric Data Loading Modes.
Specifying Loading Options for Each Matlab Matrix
The /Z flag instructs MLLoadWave to load each Matlab object (matrix, vector, variable, string) step by step. MLLoadWave presents a dialog for each Matlab object in the file. You can choose to load or skip the object. If you omit the /Z flag, MLLoadWave will load all objects in the file without presenting any dialogs.
Output Variables
MLLoadWave sets the following output variables:
| S_path | File system path to the folder containing the file. | |
| This is a system file path (e.g., "hd:FolderA:FolderB:"), not an Igor symbolic path. The path uses Macintosh path syntax, even on Windows, and has a trailing colon. | ||
| S_fileName | Name of the loaded file. | |
| V_Flag | Number of waves created. | |
| V_Flag1 | Number of Matlab data sets (2D, 3D, or 4D) loaded. | |
| V_Flag2 | Number of waves created. | |
| V_Flag3 | Number of numeric variables created. | |
| V_Flag4 | Number of string variables created. | |
| S_waveNames | Semicolon-separated list of the loaded waves. | |
Prior to MLLoadWave 5.50, the variables V_Flag1, V_Flag2, V_Flag3 and V_Flag4 were named V1_Flag, V2_Flag, V3_Flag and V4_Flag.
See Also
See Loading Matlab MAT Files for background information, including configuration instructions.