Python Module Reference
The igorpro Python module provides access to Igor objects and data structures such as waves, data folders, strings, and variables. Each Igor object type has an associated Python class:
Methods
The following are top-level methods in the igorpro Python module:
igorpro.execute (code, ignoreErrors = False)
Executes arbitrary Igor code as if it had been typed in Igor's command line. Equivalent to Execute.
Parameters
| code | Igor code to execute as a string. | |
| ignoreErrors | Optional. If True, errors are not fatal and error dialogs are suppressed. | |
igorpro.print (str)
Prints the input str to Igor's command history.
Parameters
| str | String to print. | |
igorpro.version ()
Prints the current build version of the Igor Pro application.
igorpro.wave
igorpro.wave is the Python representation of an Igor wave object, which is a data array in Igor (see Waves). This class provides access to various wave-related functions, and allows conversions between Igor waves and other analogous Python types, such as NumPy arrays.
In order to access a pre-existing wave in Igor, use the igorpro.wave constructor. If you wish to create a new Igor wave, use igorpro.wave.create or igorpro.wave.createfrom.
Every igorpro.wave has an underlying Igor wave as its source. A igorpro.wave doesn't hold a copy of the underlying wave data, only a reference to it, so any changes to the Igor wave will be automatically tracked by the igorpro.wave.
Killing an Igor wave out from under Python is permitted, which will result in an exception if Python attempts to use the dead wave. However, deleting the igorpro.wave itself has no effect on the underlying Igor wave.
igorpro.wave (path, folder = None)
Constructs a new igorpro.wave that refers to an existing Igor wave at path.
Parameters
| path | Full or relative Igor path to the wave. | |
| folder | Optional. Parent igorpro.folder to retrieve the Igor wave from. If path is a relative path, it is based off of this folder. If no data folder is provided, folder is interpreted as the current data folder. | |
Details
Free waves are currently not supported.
Examples
# Getting a reference to an existing Igor wave in the current data folder
foo = igorpro.wave('root:foo')
# Getting a reference to an existing Igor wave (root:data:bar) using folder argument
dataFolder = igorpro.folder('root:data')
bar = igorpro.wave('bar', dataFolder)
igorpro.wave.create (name, shape = (,), value = None, type = igorpro.float32, folder = None, overwrite = False)
Creates a new Igor wave relative to the current data folder, and returns a igorpro.wave. See Make.
Parameters
| name | Name of the wave. This can include a full or relative path, in order to create the Igor wave in a specific location. Otherwise, it will be created in the current data folder. | |
| shape | Optional. Tuple containing the size of each dimension, or a single number specifying the number of points for a 1D wave. Default is a 1D, 128 point wave. | |
| value | Optional. Value to fill the new wave with. Default is None, which will resolve to 0 for numeric waves, an empty string for text waves, or a null wave for wave reference and data folder reference waves. | |
| type | Optional. Data type for the wave. If not specified, the wave type will be inferred from the value argument. If value was not specified either, the wave type will default to 32 bit floating point. | |
| folder | igorpro.folder to create the wave in. If name is a relative path, it is based off of this folder. If no data folder is provided, folder it is interpreted as the current data folder. | |
| overwrite | Optional. Overwrite the wave if it already exists. | |
Details
This method is static, and thus is intended to be called without an instance of igorpro.wave. Calling it from an existing igorpro.wave instance will have no effect on the wave creation or parameters.
The wave type will be inferred if it isn't specified using the type argument. In this case, if value was specified, the wave type will be the same as value. If neither type nor value was specified, the wave will be a 32 bit floating point wave.
Examples
# Create an Igor wave with default settings
# 128 points, 32 bit float
w = igorpro.wave.create('defaultWave')
# Create an Igor 2D wave 100 x 200, filled with the value 3.141, as a 64 bit float wave type
w = igorpro.wave.create('customWave', (100,200), 3.141, igorpro.float64)
# Overwriting an existing wave, 50 x 100, filled with the value 100
w = igorpro.wave.create('customWave', (50,100), value = 100, overwrite = True)
igorpro.wave.createfrom (name, source, folder = None, overwrite = False)
Creates a new Igor wave from a source array-like object. Acceptable array-like objects include Python arrays, NumPy arrays, lists, and tuples. The array data is copied into a new Igor wave, which will then be accessible in the data browser.
Parameters
| name | Name of the wave. This can include a full or relative path, in order to create the Igor wave in a specific location. Otherwise, it will be created in the current data folder. | |
| source | Source array-like object. Can be a numpy array, built-in Python array (array.array), list, or tuple. | |
| folder | igorpro.folder to create the wave in. If name is a relative path, it is based off of this folder. If no data folder is provided, folder it is interpreted as the current data folder. | |
| overwrite | Optional. Overwrite the wave if it already exists. | |
Details
The underlying data types of the input array will be converted into the most appropriate Igor wave type, or raise an exception if the data type cannot be converted. Arrays with mixed data types are not supported.
For creating a NumPy array from an Igor wave, see asarray.
Examples
import numpy as np
# Create a wave from a NumPy array of a sine wave
sinwave = np.sin([2 * x * np.pi/256 for x in range(256)])
w = igorpro.wave.createfrom('data', sinwave)
Methods
asarray () → numpy.ndarray
Creates a NumPy array from the Igor wave, with the same dimensionality and data type.
Details
Since the NumPy array holds a copy of the wave data, any subsequent change to the Igor wave will have no effect on the new NumPy array. However, the NumPy array will not carry any of the Igor wave's meta-data, such as it's scaling, units, or note.
asarray() only works for numeric and text waves.
For creating an Igor wave from a NumPy array, see igorpro.wave.createfrom.
dims () → int
Returns the number of dimensions in the Igor wave. See WaveDims.
exists () → bool
Returns the truth that the underlying Igor wave exists. See WaveExists.
kill () → None
Kills the Igor wave if it isn't in use.
labels (dimension) → list
Returns a list of the wave's dimension labels for the specified dimension. See GetDimLabel.
Parameters
| dimension | Dimension number to get the dimension labels for (0-3). The characters 'x', 'y', 'z', and 't' are also accepted. To get the labels for the overall dimension, use -1 or 'd'. | |
name () → str
Returns the name of the Igor wave as a string, without its path.
note () → str
Returns the Igor wave's note as a string. See Functions[note].
path () → str
Returns the full path to the Igor wave as a string, without the name. See GetWavesDataFolder.
points () → int
Returns the number of points in the Igor wave. See numpnts
redimension (shape) → None
Changes the shape of the Igor wave. See Operations[Redimension].
Parameters
| shape | Requested dimensions for the wave. This can be either a tuple of numbers that specify the number of points in each dimension of a multi-dimensional wave, or a single number specifying the number of points in a 1D wave. | |
scale (dimension) → tuple
Returns a tuple containing the scaling offset (start value) and delta for the indicated dimension.
Parameters
| dimension | Dimension number to set the scale of. The characters 'x', 'y', 'z', and 't' are also accepted. | |
set_data (source) → None
Sets the wave data as source.
Parameters
| source | Data source to set the wave with. This can be another igorpro.wave, or a supported array-like object (NumPy array, built-in Python array (array.array), list, or tuple). | |
Details
If an array-like object is used as source, the wave data (including the dimensions) will be set to that of the source as long as the source data and the wave have compatible types (See Python to Igor type conversions). For example, conversions between text waves and numeric arrays will throw an exception. Complex waves, real numeric waves, text waves, wave reference waves, and data folder reference waves generally do not inter-convert. However, conversions between numeric types, such as unsigned 8 bit integer to 64 bit floating point, are allowed. In these cases, the wave data type will never change to accomodate the source data. Instead, the source data will be converted into the destination wave's data type.
If an igorpro.wave is used as source, the same rules apply for converting the source data into the destination wave's data type.
Example
import numpy as np
# Create a default 1D wave
w = igorpro.wave.create('dd')
# Create a 2D NumPy array of random values
a = np.random.rand(128, 128)
# Set the wave's data to the NumPy array
w.set_data(a)
# Set the wave's data to a list
w.set_data([np.sin(2 * np.pi * x/50) for x in range(50)])
set_label (dimension, index, label) → None
Sets the wave's dimension label at the specified dimension and index. See SetDimLabel.
Parameters
| dimension | Dimension number (0-3). The characters 'x', 'y', 'z', and 't' are also accepted. | |
| index | Index along the specified dimension to set the label. Use -1 to set the overall dimension label. | |
| label | Label string to set. | |
set_scale (dimension, start, value, mode) → None
Sets the wave scaling for the indicated dimension. See SetScale.
Parameters
| dimension | Dimension number to set the scale of. The characters 'x', 'y', 'z', and 't' are also accepted. | |
| start | Start value (offset) for the dimension scaling. | |
| value | End value or delta value for the dimension scaling, depending on the mode. | |
| mode | 'range' : value is the end value for the dimension. 'delta' : value is the delta value between points for the dimension. | |
Details
mode = 'range' corresponds to the Igor procedure code SetScale /I, whereas mode = 'delta' corresponds to SetScale /P. If mode = 'range', the delta value between points will be automatically calculated.
set_units (dimension, unit) → None
set_units (wave) → None
Sets the wave's unit string for the indicated dimension. See SetScale.
Parameters
| dimension | Dimension number to set the unit string for (0-3). The characters 'x', 'y', 'z', and 't' are also accepted. To set the unit string for the data dimension, use -1 or 'd'. | |
| unit | Unit string to set. | |
| wave | Source igorpro.wave. The unit strings for all dimensions are copied from the source wave. | |
shape () → tuple
Returns a tuple with the size of each dimension in the Igor wave.
stats (xRange, yRange, zRange, tRange) → dict
Returns the statistics of the Igor wave as a dictionary. See WaveStats.
Parameters
| xRange | Optional. List or tuple containing the start and end points in the range for the x dimension. | |
| yRange | Optional. List or tuple containing the start and end points in the range for the y dimension. | |
| zRange | Optional. List or tuple containing the start and end points in the range for the z dimension. | |
| tRange | Optional. List or tuple containing the start and end points in the range for the t dimension. | |
Details
Each range argument can either be a tuple () or a list []. If a tuple is used, this method will treat the range as scaled values for the given dimension. If a list is used, this method treats the range values as point indices. Omit all arguments to calculate the statistics of the entire wave. Use an '...' ellipsis input to specify the boundary of any dimension.
Example
# Performs stats() on all rows up to and including row 3,
# for columns 5-10, inclusive.
stats = igorpro.stats([..., 3],[5, 10])
type () → igorpro.WaveType
Returns the Igor wave type as a WaveType enumerator. See igorpro.WaveType
units (dimension) → str
Returns the unit string for the specified dimension.
Parameters
| dimension | Dimension number (0-3). The characters 'x', 'y', 'z', and 't' are also accepted. To set the unit string for the data dimension, use -1 or 'd'. | |
Indexing
[ row, column, layer, chunk ] → object
Subscript operator. Returns the contained value at the given index.
[ row, column, layer, chunk ] = value
Subscript assignment operator. Assigns value to given index.
igorpro.WaveType
Enumeration of the possible data types for an igorpro.wave:
| none | Invalid type | |
| text | Text wave | |
| float32 | 32 bit floating point | |
| float64 | 64 bit floating point | |
| int8 | 8 bit signed integer | |
| uint8 | 8 bit unsigned integer | |
| int16 | 16 bit signed integer | |
| uint16 | 16 bit unsigned integer | |
| int32 | 32 bit signed integer | |
| uint32 | 32 bit unsigned integer | |
| complex64 | 32 bit floating point, complex | |
| complex128 | 64 bit floating point, complex | |
| wref | Wave reference | |
| dfref | Data folder reference | |
These can be accessed as, for example:
igorpro.float32
or
igorpro.WaveType.float32
igorpro.folder
igorpro.folder is the Python representation of an Igor data folder (see Data Folders). This class allows users to access all Igor objects within a data folder, and provides methods for navigating through Igor's folder hierarchy (see The Data Browser).
igorpro.folder (path, folder = None) → igorpro.folder
Constructs a new igorpro.folder that refers to an existing Igor data folder at path.
Parameters
| path | Full or relative Igor path to the data folder. | |
| folder | Optional. Parent igorpro.folder to retrieve the Igor data folder from. If path is a relative path, it is based off of this folder. If no data folder is provided, folder is interpreted as the current data folder. | |
Details
igorpro.folder provides access to an existing Igor data folder and its contents. Free data folders are currently not supported. The existence of a igorpro.folder does not prevent its underlying Igor data folder from being deleted. If a igorpro.folder attempts to use a data folder that has been deleted, it will raise an exception. A igorpro.folder doesn't directly hold the underlying data folder data, so any changes to the Igor data folder will be tracked by the igorpro.folder.
igorpro.folder.create (path, overwrite = False) → igorpro.folder
Creates a new Igor data folder at path. See NewDataFolder.
Parameters
| path | Full or relative Igor path to the data folder. | |
| overwrite | Optional. Overwrite the folder if it already exists. Note, setting overwrite to True won't delete the contents of the folder. | |
Details
This method is static, and thus is intended to be called without an instance of igorpro.folder. Calling it from an existing igorpro.folder instance will have no effect on the folder creation or parameters.
igorpro.folder.current () → igorpro.folder
Gets the current data folder and returns it as a igorpro.folder.
Methods
exists () → bool
Returns the truth that the underlying Igor data folder exists. See DataFolderExists.
kill (ignoreErrors = False) → None
Kills the Igor data folder, if possible. See KillDataFolder.
Parameters
| ignoreErrors | If True, ignores errors if the folder doesn't exist. | |
name () → str
Returns the name of the Igor data folder.
num_subfolders () → int
Returns the number of subfolders inside the Igor data folder.
num_waves () → int
Returns the number of waves inside the Igor data folder.
parent () → igorpro.folder
Returns the parent igorpro.folder.
Details
Calling parent() on the root directory will return the root directory itself.
path () → str
Returns the full path to the Igor data folder.
set () → None
Sets the Igor data folder as the current data folder.
subfolder (name) → igorpro.folder
Returns the named subfolder in the Igor data folder as a igorpro.folder, if it exists.
subfolders () → list
Returns a list of the immediate subfolders in the Igor data folder as a list of igorpro.folders.
waves () → list
Returns a list of the waves inside the Igor data folder as a list of igorpro.waves.
igorpro.string
igorpro.string is the Python representation of an Igor string variable. This class provides methods for reading and writing to global Igor string variables.
igorpro.string (path, folder = None)
Constructs a new igorpro.string that refers to an existing Igor string variable at path.
Parameters
| path | Full or relative Igor path to the string variable, including its name. | |
| folder | Optional. Parent igorpro.folder to retrieve the Igor string variable from. If path is a relative path, it is based off of this folder. If no data folder is provided, folder is interpreted as the current data folder. | |
igorpro.string.create (path, value, folder = None, overwrite = False)
Creates a new Igor string at path, and returns a igorpro.string. See String.
Parameters
| path | Full or relative Igor path to the string variable, including its name. | |
| value | String to set the variable to. | |
| folder | Optional. igorpro.folder to create the string variable in. If name is a relative path, it is based off of this folder. If no data folder is provided, folder it is interpreted as the current data folder. | |
| overwrite | Optional. Overwrite the string variable if it already exists. | |
Details
This method is static, and thus is intended to be called without an instance of igorpro.string. Calling it from an existing igorpro.string instance will have no effect on the string creation or parameters.
Methods
exists () → bool
Returns the truth that the underlying Igor string variable exists. See SVAR_Exists.
name () → str
Returns the name of the Igor string variable.
path () → str
Returns the full path to the Igor string variable.
set (str) → None
Sets the value of the Igor string variable.
Parameters
| str | New value for the Igor string variable. | |
value () → str
Returns the value of the string.
igorpro.variable
igorpro.variable is the Python representation of an Igor numeric variable. This class provides methods for reading and writing to global Igor numeric variables.
igorpro.variable (path, folder = None)
Constructs a new igorpro.variable that refers to an existing Igor numeric variable at path.
Parameters
| path | Full or relative Igor path to the numeric variable, including its name. | |
| folder | Optional. Parent igorpro.folder to retrieve the Igor numeric variable from. If path is a relative path, it is based off of this folder. If no data folder is provided, folder is interpreted as the current data folder. | |
igorpro.variable.create (path, value, folder = None, overwrite = False)
Creates a new Igor numeric variable at path, and returns a igorpro.variable. See Variable.
Parameters
| path | Full or relative Igor path to the numeric variable, including its name. | |
| value | Real or complex number to set the variable to. If a complex number is provided, a complex Igor variable will be created. Otherwise, a non-complex variable is created. | |
| folder | Optional. igorpro.folder to create the numeric variable in. If name is a relative path, it is based off of this folder. If no data folder is provided, folder it is interpreted as the current data folder. | |
| overwrite | Optional. Overwrite the variable if it already exists. | |
Details
This method is static, and thus is intended to be called without an instance of igorpro.variable. Calling it from an existing igorpro.variable instance will have no effect on the variable creation or parameters.
Methods
exists () → bool
Returns the truth that the underlying Igor numeric variable exists. See NVAR_Exists.
imag () → int | float
Returns the imaginary part of the complex number.
iscomplex () → bool
Returns the truth that the Igor numeric variable is a complex type.
name () → str
Returns the name of the Igor numeric variable.
path () → str
Returns the full path to the Igor numeric variable.
real () → int | float
Returns the real part of the complex numberic variable.
Details
If the variable is not complex, this method returns value().
set (value) → None
Sets the value of the Igor numeric variable.
Parameters
| value | New value for the Igor numeric variable, which can be a real or a complex number. | |
Details
If the variable is complex, but value is not, the real part will be set to value, and the imaginary part will be set to 0. If the variable is not complex, but value is complex, an invalid data type exception will be thrown.
value () → int | float
Returns the value of the Igor numeric variable.