Python

In this section you'll find documentation for iolite's python application programming interface (API) and the various ways you can use it to extend iolite. The API is continuously evolving and having new features added so may change without notice, however we will try very hard not to make any significant changes to existing functionality.

The following documentation assumes that you're comfortable coding in python. If you are unfamiliar with python, there are many online resources to learn from, e.g., Python for Everybody. You can find many smaller examples using python in our notes. We also recommend reading through the python examples in our GitHub repository to see how the API can be used in a variety of plugins.

For more visual, hands-on learners, we recommend that you check out our python for LA-ICP-MS course. This includes webinars, live coding examples and exercises covering the most useful parts of iolite's API and the various plugin types. For those that prefer text, read on below!

Integration

There are several ways you can use python in iolite:

  1. Short one-off commands written in the python console.

  2. Longer scripts meant to be reused in the workspace.

  3. Plugins:

  4. Processing template actions.

For the python console, workspace, and processing template actions there are no expectations or requirements for the code. In each environment, four objects are generally available by default: data, imaging, db and IoLog. Scripts used as plugins require certain functions to be defined and can expect certain variables and objects to be available.

Plugins

User plugins for iolite are python scripts. In order for iolite to recognize and use these scripts as plugins, they must be put in particular folders and contain specific functions (in most cases). The folders that iolite will check for plugins can be configured via the Paths section of iolite's preferences (shown below). By placing the script in the correct folder, iolite will try to parse some metadata at the top of the script when it starts. If appropriate metadata are found, iolite will try to load the plugin, however, if the script contains syntax errors or does not define the required functions it will not work as expected. If

Metadata

Importers, data reduction schemes, QA/QC modules and UI plugins all require metadata at the top of the script. The format for the metadata is shown below where the lines start with '#/' followed by the field name and a colon.

#/ Type: Importer
#/ Name: My Custom Importer
#/ Authors: Joe Petrus
#/ Description: An importer for my custom data files
#/ References: None
#/ Version: 0.1
#/ Contact: joe@iolite-software.com

Notably, the Type field must match the type of plugin the script is being loaded as. There are no specific requirements on the remaining fields, but they can be helpful to keep track of who wrote the script, how to contact the author and what the script does.

Importers

An importer plugin requires two functions to be defined: correct_format and import_data:

def correct_format():
        """
        This method will be called by iolite when the user selects a file
        to import. Typically, it uses the provided name (stored in
        importer.fileName) and parses as much of it as necessary to determine
        if this importer is appropriate to import the data. For example,
        although X Series II and Agilent data are both comma separated
        value files, they can be distinguished by the characteristic
        formatting in each. In our implementation, distinguishing the
        two is done with 'regular expressions' (QRegularExpression)
        parsing of the first several lines of the file.

        Keep in mind that there is nothing stopping you from just
        returning True (thus supporting all files!) or simply checking
        the file extension, but such generic checks can yield unexpected
        results. You cannot be sure which order the various importer
        plugins will be checked for compatibility.

        This method must return either True or False.
        """

def import_data():
        """
        This method uses the provided file name (stored in importer.fileName),
        parses its contents, and registers time series data with iolite by
        emitting the timeSeriesData signal or by calling data.addDataToInput

        Importer progress can be updated via the 'message' and 'progress'
        signals. These will be displayed in the iolite interface.
        When finished, the 'finished' signal should be emitted.
        """

In an importer script you can expect the following variables to be defined: data, IoLog, and importer. Notably, you can get the fileName to import via importer.fileName.

For an importer to be detected and used by iolite

class api.plugins.Importer

This is about the importer object.

Exporters

An exporter has no required functions. export_filepath is a string containing the path to the folder and the filename selected by the user when prompted.

Data reduction schemes

A data reduction scheme requires two functions to be defined: runDRS and settingsWidget:

def runDRS():
        """
        This method will be called by iolite when the user clicks
        Crunch Data in the DRS window or as part of a processing
        template. It should transform 'input' data into 'output'
        data using the provided settings.
        DRS progress can be updated via the 'message' and 'progress'
        signals. These will be displayed in the iolite interface.
        When finished, the 'finished' signal should be emitted.
        As an example, we will do baseline subtraction of all
        input channels using a DRS helper function.
        """

def settingsWidget():
        """
        This function puts together a user interface to configure the DRS.

        It is important to have the last line of this function call:
        drs.setSettingsWidget(widget)
        """

The following objects will be defined: data, IoLog, and drs.

class api.plugins.DataReductionScheme

This is about drs object.

baselineSubtract(baseline_group, inputs, mask, start_progress, end_progress)
Parameters:

  • baseline_group (iolite.SelectionGroupPyInterface) -- group to use for baseline subtraction (i.e. which group's spline to use for baseline subtraction)

  • inputs (list of iolite.TimeSeriesDataPyInterface) -- List of channels to be baseline subtracted (typically all input channels)

  • mask (numpy array) -- Array to use to mask resultant channels

  • start_progress (int) -- Value to show at start of baseline subtraction in progress indicator

  • end_progress (int) -- Value to show at end of baseline subtraction in progress indicator

Returns:

None

createBeamSecondsFromLaserLog(trim)

Creates the BeamSeconds channel using the laser log samples already imported into the session.

Parameters:

trim (float) -- Number of seconds before/after sample starts/ends to start BeamSeconds. Default is 0 s.

Returns None:

createMaskFromCutoff(channel, cutoff, trim)
Parameters:

  • channel (iolite.TimeSeriesDataPyInterface) -- channel to base the mask on. The cutoff will be based on this channel's values.

  • cutoff (float) -- Values within channel less than or equal to this value will be masked (i.e. set to Not A Number)

  • trim (float) -- Number of seconds before/after the channel passes through cutoff to also set to 1. Default is 0 s.

Returns:

the mask as an array

Return type:

numpy array

createMaskFromLaserLog(trim)
Parameters:

trim (float) -- Number of seconds before/after the channel passes through cutoff to also set to 1. Default is 0 s.

Returns:

the mask as an array

Return type:

numpy array

name()

Returns the name of the DRS.

Returns:

Name of DRS

Return type:

str

run()

Runs the DRS.

Returns:

None

setIndexChannel(channel)

Sets the Index Channel.

Parameters:

channel (iolite.TimeSeriesDataPyInterface) -- the channel to set as Index Channel

setSetting(name, value)
Parameters:

  • name (str) -- Name of setting to set

  • value (various (str, float, etc)) -- The value to set

Returns:

None

setSettings(settings)
Parameters:

settings (dict) -- A dictionary of settings for this DRS

Returns:

None

setSettingsWidget(widget)
Parameters:

widget (QWidget) -- a QWidget that will be shown in the settings panel of the DRS View

Returns:

None

settings()
Returns:

a dictionary of this DRS' settings

settingsWidget()

This function puts together a user interface to configure the DRS.

Returns:

the settings widget

Return type:

QWidget

updateSplines(groups, channels)

Tell iolite to recalculate splines for given groups and channels

Parameters:
Returns:

None

QA/QC modules

def update():
        """
        This method will be called by iolite when the user triggers
        the module to run in the QA/QC UI or as part of a processing
        template. It should analyze current results to evaluate whether
        the instruments were performing as expected.
        When finished, the 'finished' signal should be emitted with a status code,
        e.g. qaqc.Success, qaqc.Error, qaqc.SuccessWithWarnings
        As an example, we will compare the group stats of the specified
        selection group and channel to a target value. If they're within
        uncertainty, finish with success.
        """

def settingsWidget():
        """
        This function puts together a user interface to configure the QA/QC module.
        The widget should be kept as small as possible and will be shown as a popup
        when the user clicks the settings button.
        It is important to have the last line of this function call:
        qaqc.setSettingsWidget(widget)
        """
class api.plugins.QAQCModule

This is about the qaqc object.

User interface

class api.plugins.UI

This is about the ui object.

Image inspectors

class api.plugins.ImageInspector

This is about the inspector object.

Database scripts

Coming soon...

Using Qt

Coming soon...

Using modules

Coming soon...

API Documentation

class iolite.TimeSeriesDataType

Specifies a type for TimeSeriesData objects.

class iolite.SelectionGroupType

Specifies a type for SelectionGroup objects.

class iolite.Signal

A qt signal.

connect(callable)

Used to connect signal to a callable function or lambda.

class iolite.IolitePythonInterface

Main interface to iolite data via python.

An instance of this is typically available in iolite's python interpreter as 'data'. So, e.g.,

channel = data.timeSeries('U238')

channels = data.timeSeriesList(data.Input)

groups = data.selectionGroups(data.ReferenceMaterial)

Parameters:

  • Input (class:TimeSeriesDataType) -- Type for input channels.

  • Intermediate (class:TimeSeriesDataType) -- Type for intermediate channels.

  • Output (class:TimeSeriesDataType) -- Type for output channels.

  • Baseline (class:SelectionGroupType) -- Type for baseline groups.

  • ReferenceMaterial (class:SelectionGroupType) -- Type for reference material groups.

  • Sample (class:SelectionGroupType) -- Type for sample groups.

  • activeSelectionChanged (class:Signal) -- A signal that can be used to react when the active selection is changed to another selection. For example, data.activeSelectionChanged.connect(my_function)

addDataToInput(channelName, inputTime, inputData, options)

Inserts data into an input channel.

Parameters:

  • channelName (str) -- name for channel

  • inputTime (numpy array) -- time for channel in seconds since epoch, for each datapoint

  • inputData (numpy array) -- datapoints for channel

  • options (dict) -- dictionary of channel properties

Returns:

None

addManyDataToInput(channelNames, inputTime, inputData, options)

Adds multiple data to input channels.

Parameters:

  • channelNames (list of str) -- list of channel names

  • inputTime (numpy array) -- time for channels in seconds since epoch, for each datapoint

  • inputData (numpy array) -- datapoints for channels

  • options (dict) -- dictionary of channel properties

Returns:

None

activeSelection()

Returns the currently active selection.

Returns:

the active selection

Return type:

iolite.SelectionPyInterface

activeSelectionChanged()

A signal that can be used to react when the active selection is changed to another selection. For example, data.activeSelectionChanged.connect(my_function)

activeSelectionGroup()

Returns the active selection group.

Returns:

the active selection group

Return type:

iolite.SelectionGroupPyInterface

activeSelectionGroupChanged()

A signal that can be used to react when the active selection group is changed to another group. For example, data.activeSelectionGroupChanged.connect(my_function)

associatedResult(selection, resultName)

Returns an 'associated result' for the given selection. An associated result is a value (stored as a result object) that is not directly calculated from the data within the selection interval. Instead, it is a result that is directly related to the selection, but not necessarily associated with any one channel. An example is the error correlation of a selection. This is based on two channels (rather than one particular channel), but is unique to that selection, hence it is an 'associated result'. Associated results are accessed by selection and the name of the associated result

Parameters:

  • selection (iolite.SelectionPyInterface) -- selection to return the associated result for

  • resultName (str) -- name of associated result

Returns:

a result object

Return type:

result

associatedResultNames()
Returns:

A list of associated result names

Return type:

list of strings

calculateTotalBeam()

Recalculates TotalBeam.

Returns:

None

channelCreated(name)

A signal emitted from iolite's Data Manager (class:IolitePythonInterface) that can be used to react when a new channel is created. For example, data.channelCreated.connect(myFunc)

Parameters:

name (str) -- name of channel that has been changed (this is emitted)

Returns:

None

channelChanged(name)

A signal emitted from iolite's Data Manager (class:IolitePythonInterface) that can be used to react when a channel has changed. For example, data.channelChanged.connect(myFunc)

Parameters:

name (str) -- name of channel that has been changed (this is emitted)

Returns:

None

channelDeleted(name)

A signal emitted from iolite's Data Manager (class:IolitePythonInterface) that can be used to react when a channel is deleted. For example, data.channelDeleted.connect(myFunc)

Parameters:

name (str) -- name of channel that has been deleted (this is emitted)

Returns:

None

checkSelections(groups)

Checks the selections in the given groups.

Parameters:

groups (list of iolite.SelectionGroupPyInterface) -- list of selection groups to check

Returns:

None

clearCachedResults()

Clears all results currently stored in the Results Manager.

Returns:

None

clearCachedSplines()

Clears all splines stored in the spline manager

Returns:

None

createBeamSeconds(method, methodProps={})

Creates a beam seconds time series using the specified method. method should be one of "log", "cutoff", or "jump". See the iolite documentation for more information on the different methods.

Parameters:

  • method (str) -- method to use for creating beam seconds

  • methodProps (dict) -- properties for the method

Returns:

A new time series data object

Return type:

iolite.TimeSeriesDataPyInterface

createFileSampleMetadata(sampleName, Q_fileStartTime, Q_fileEndTime, filePath)

Creates a mass spec file sample, using QDateTimes

Parameters:

  • sampleName (str) -- sample name

  • Q_fileStartTime (QDateTime) -- sample start time

  • Q_fileEndTime (QDateTime) -- sample end time

  • filePath (str) -- full file path for the file containing the sample

Returns:

a iolite.SampleMetadataPyInterface object

Return type:

iolite.SampleMetadataPyInterface

createImportedFileMetadata(Q_fileStartTime, Q_fileEndTime, filePath, Q_fileImportTime, nPoints, channelNames)

Records a file import using QDateTimes.

Parameters:

  • Q_fileStartTime (QDateTime) -- file start time

  • Q_fileEndTime (QDateTime) -- file end time

  • filePath (str) -- full file path

  • Q_fileImportTime (QDateTime) -- datetime of file import

  • nPoints (int) -- number of data points within the file

  • channelNames (list of strings) -- channel names

Returns:

a iolite.FileMetadataPyInterface object

Return type:

iolite.FileMetadataPyInterface

createLaserLog(filePath, data)

Creates a laser log file from a list of dicts. Each dict represents a laser log file sample, and should have the following values:

  • 'startTime': datetime,

  • 'endTime': datetime,

  • 'name': str,

  • 'repRate': float,

  • 'width': float,

  • 'height': float,

  • 'shape': int

  • 'scanSpeed': float,

  • 'angle': float,

  • 'startX': float,

  • 'startY': float,

  • 'endX': float,

  • 'endY': float

Parameters:

  • filePath (str) -- full path to file

  • data (list of dicts) -- list of laser log samples, including their start/end time etc. See above for all the required values and key names.

Returns:

None

createSelection(group, startTime, endTime, name)
Parameters:

  • group (iolite.SelectionGroupPyInterface) -- the selection group to add to

  • startTime (QDateTime) -- selection start time. TIP: You can import QDateTime with from iolite.QtCore import QDateTime, and then create a QDateTime with (for example) QDateTime.fromMSecsSinceEpoch(start_ms)

  • endTime (QDateTime) -- selection end time

  • name (str) -- selection label

Returns:

selection object

Return type:

iolite.SelectionPyInterface

createSelectionGroup(name, type)
Parameters:

  • name (str) -- name of selection group

  • type (SelectionGroupType) -- the selection group type (e.g. data.Baseline)

Returns:

selection group object

Return type:

iolite.SelectionGroupPyInterface

createSelections(group, startTimes, endTimes, names)
Parameters:

  • group (iolite.SelectionGroupPyInterface) -- the selection group to add to

  • startTime (list of QDateTimes) -- selection start times. TIP: You can import QDateTime with from iolite.QtCore import QDateTime, and then create a QDateTime with (for example) QDateTime.fromMSecsSinceEpoch(start_ms)

  • endTime (list of QDateTimes) -- selection end times

  • name (list of str) -- selection labels

Returns:

list of selection objects

Return type:

list of iolite.SelectionPyInterface

createTimeSeries(name, type, time=None, data=None, properties={})
Parameters:

  • name (str) -- name for channel

  • type (TimeSeriesDataType) -- the time series type (e.g. data.Input)

  • time (numpy array) -- time array for data. In seconds since epoch. If None, will use Index_Time

  • data (numpy array) -- channel data

  • properties (dict) -- name for channel

Returns:

A new time series data object

Return type:

iolite.TimeSeriesDataPyInterface

createTimeSeriesFromMetadata(name, propertyName, selections, defaultValue, missingValue)

Creates a time series from metadata.

Parameters:

  • name (str) -- name for channel

  • propertyName (str) -- property name

  • selections (list of iolite.SelectionPyInterface) -- list of selections

  • defaultValue (float) -- default value

  • missingValue (float) -- missing value

Returns:

A new time series data object

Return type:

iolite.TimeSeriesDataPyInterface

createTimeSeriesFromResults(name, channel, selections, defaultValue)

Creates a time series from results.

Parameters:
Returns:

A new time series data object

Return type:

iolite.TimeSeriesDataPyInterface

createTimeSeriesFromSums(name, baseChannel, selections, interval, gap=0.0, overwrite=False, interpMethod='None')

Creates a new channel by summing intervals along a base channel.

Parameters:

  • name (str) -- The name of the channel to be created.

  • baseChannel (iolite.TimeSeriesDataPyInterface) -- The channel holding the values to be summed.

  • selections (list of iolite.SelectionPyInterface) -- A list of the selections during which the intervals will be summed

  • interval (float) -- The duration of the intervals to be summed (in seconds)

  • gap (float) -- The gap between intervals (in seconds). Optional.

  • overwrite (bool) -- Whether to overwrite any existing channel(s) of the same name as name. Defaults to False

  • interpMethod (str) -- Interpolation method. Defaults to "None"

Returns:

The created channel

Return type:

iolite.TimeSeriesDataPyInterface

compileDownhole(group, channel, bsMax=60)

Returns a tuple containing a numpy array for both the time and mean downhole trend for the given channel and selection group. Values where Beam_Seconds is less than 0 and greater than bsMax are ignored.

Parameters:
Returns:

a tuple of (time, data), where

Return type:

tuple of numpy arrays

dataChanged()

The signal indicating that the data has changed. Connect to this signal to call functions when the data has changed.

For example, data.dataChanged.connect(my_function)

Returns:

None

dataReductionScheme(name)

Returns DRS object for named DRS.

Parameters:

name (str) -- name of DRS

Returns:

a DRS object

Return type:

iolite.DRSPyInterface

dataReductionSchemeNames()
Returns:

a list of currently available Data Reduction Scheme names

Return type:

drsFinished()

The signal that is emitted when the data reduction scheme has finished. Connect to this signal to call functions when the DRS has finished.

For example, data.drsFinished.connect(my_function)

Returns:

None

emitDataChanged()

Emits a signal indicating that the data has changed. This will update iolite's user interface.

Returns:

None

exportFavorite(name)

Gets an Export "Favourite" (configuration) by name.

Parameters:

name (str) -- name of the favorite to export

Returns:

favorite configuration

Return type:

dict

exportFavorites()

Gets all Export Favorites (configurations).

Returns:

list of favorite configurations

Return type:

list of dicts

exportFile(config)

Exports data to a file, using the given Favourite (configuration).

Parameters:

config (dict) -- export Favourite (configuration)

Returns:

None

getH5Array(filePath, dataPath)

Returns an HDF5 array from the HDF5 file at the provided filepath.

Parameters:

  • filePath (str) -- full file path to HDF5 file.

  • dataPath (str) -- data path within the file

Returns:

HDF5 array

Return type:

numpy array

getH5Attr(filePath, attrPath)

Returns an HDF5 attribute from the HDF5 file at the provided filepath.

Parameters:

  • filePath (str) -- full file path

  • attrPath (str) -- attribute path within the file

Returns:

HDF5 attribute

Return type:

numpy array

globalEndTime()

Returns the global end time.

Returns:

global end time

Return type:

QDateTime

globalStartTime()

Returns the global start time.

Returns:

global start time

Return type:

QDateTime

frame(selections, selection_props, channels, channel_stats, channel_props=[], associated_results=[])

Returns a pandas data frame for the specified selections (rows of the data frame). Each selection property will become a column, as will each channel stat. Supported channel stats include: ['mean', 'int2se', 'prop2se', 'rminc', 'median', 'longerich', 'howell', 'pettke', 'noutliers', 'npoints', 'nfinite']. Channel properties will become rows at the bottom of the data frame. Associated results will become columns.

Parameters:

  • selections (list of iolite.SelectionPyInterface) -- A list of selections to include in the data frame

  • selection_props (list of strings) -- A list of strings naming the selection properties to include

  • channels (list of iolite.TimeSeriesDataPyInterface) -- A list of channels to include in the data frame

  • channel_stats (list of strings) -- A list of the stats to include for each channel, see above for options

  • channel_props (list of strings) -- A list of channel properties to include in the data frame

  • associated_results (list of strings) -- A list of the associated results to include in the data frame

Returns:

a pandas data frame including the specified data

Return type:

pandas.DataFrame

groupResult(group, channel)
Returns a result object with the mean channel value for the group,

with no outlier rejection. For example, to get the mean value for Sr88 for the group 'C_MMC', use ``grpRes = data.groupResult(data.selectionGroup('C_MMC'),

data.timeSeries('Sr88'))``,

then to access the mean, use grpRes.mean(), and the uncertainty using grpRes.uncertainty().

Parameters:
Returns:

a result object, with the value equal to the mean for the group

Return type:

result

importData(filePath)

Imports data from the specified file.

Parameters:

filePath (str) -- full file path

Returns:

True if import was successful, otherwise False

Return type:

bool

importLog(filePath, syncChannelName='TotalBeam')

Imports a log file and synchronizes it with the specified channel.

Parameters:

  • filePath (str) -- full file path

  • syncChannelName (str) -- name of the channel to synchronize with

Returns:

True if import was successful, otherwise False

Return type:

bool

importISValues(filePath)

Imports IS values from the specified file.

Parameters:

filePath (str) -- full file path

Returns:

dictionary of imported IS values

Return type:

dict

importedFiles()
Returns:

a list of iolite.FileMetadataPyInterface objects for

all imported mass spec files :rtype: list of iolite.FileMetadataPyInterface

importedLogs()
Returns:

a list of iolite.FileMetadataPyInterface objects for

all imported laser log files :rtype: list of iolite.FileMetadataPyInterface

laserData(onIndexTime=False)

Returns a ditionary with entries for each laser log file sample loaded.

laserLogSamples()
Returns:

a list of iolite.SampleMetadataPyInterface objects

for all imported laser log samples :rtype: list of iolite.SampleMetadataPyInterface

massSpecSamples()
Returns:

a list of iolite.SampleMetadataPyInterface objects for all imported mass spec (data) samples

Return type:

list of iolite.SampleMetadataPyInterface

oxideToElementFactor(formula)

Returns the oxide to element concentration factor. Uses the oxide formula provided to determine the factor. For example, to get the factor for SrO, use data.oxideToElementFactor('SrO'). The formula used is: factor = (nE x mE + nO x mO) / (nE x mE), where nE and mE are the number of element atoms in the formula and the element's atomic mass, and nO and mO are the number of oxygen atoms in the formula and the atomic mass of oxygen.

e.g. for SrO, the factor is (1 x 87.62 + 1 x 16.00) / (1 x 87.62) = 1.18

If the formula is just a single element, e.g. 'Sr', the most common oxide form is used to determine the factor, e.g. SrO. If using the element instead of the formula, you should check the value used matches the oxide you are interested in.

Parameters:

formula (str) -- oxide formula

Returns:

oxide to element concentration factor

Return type:

float

propagateErrors(selectionGroups, channels, nonDriftCorrectedChannel, referenceMaterialName)

Progagates errors for a list of selection groups onto a list of channels based on results of a reference material for a non drift corrected channel

Parameters:
Returns:

None

qaqc(name)

Returns a QAQC object for the specified name.

Parameters:

name (str) -- name of the QAQC module

Returns:

a QAQC object

Return type:

iolite.QAQCPyInterface

qaqcNames()

Returns a list of available QAQC module names.

Returns:

list of QAQC module names

Return type:

list of str

referenceMaterialData(name)
Parameters:

name (str) -- the name of the reference material

Returns:

dictionary of values for the reference material

Return type:

dict

referenceMaterialNames()
Returns:

a list of reference material names

Return type:

list of strings

registerAssociatedResult(name, pyObj)

Registers a function/lambda to be called when accessing an associated result with associatedResult(). Once this association is stored, calling the associated result will return the result of the callable object as a Result object.

Parameters:

  • name (str) -- name of associated result

  • pyObj -- any callable python object, e.g. function or lambda

Returns:

None

removeAssociatedResult(name)

Removes an associated result.

Parameters:

name (str) -- name of the associated result

Returns:

None

removeSelectionGroup(name)

Removes a selection group by name.

Parameters:

name (str) -- name of the selection group to remove

Returns:

None

removeTimeSeries(name)
Parameters:

name (str) -- name of channel to remove

Returns:

None

resetSession()

Resets the current session, i.e. creates a new empty session.

Returns:

None

result(selection, channel)
returns a result object. You can then get the value,

uncertainty etc for this result.

For example, you can get the 'Sr88' result for the first selection in the C_MMC group using `res = data.result(data.selectionGroup('C_MMC').selections()[0],

data.timeSeries('Sr88'))`

See iolite.Result for more details about Results

You can then access the value, uncertainty, number of points, etc using res.value(), res.uncertainty(), res.numMeasurements(), etc

Parameters:
Returns:

result object

Return type:

result

saveSession(filePath)

Saves the current session to the specified file path.

Parameters:

filePath (str) -- path to save the session file

Returns:

None

selectionChanged()

The signal indicating that a selection has changed. Connect to this signal to call functions when a selection has changed.

For example, data.selectionChanged.connect(my_function)

Returns:

None

selectionGroup(name)
Parameters:

name (str) -- name of selection group

Returns:

Selection group if name exists, otherwise None

Return type:

iolite.SelectionGroupPyInterface

selectionGroupList(type, criteria={})
Parameters:

  • type (SelectionGroupType) -- the selection group type (e.g. data.Baseline)

  • criteria (dict) -- currently unused

Returns:

List of selection groups matching type

Return type:

list of iolite.SelectionGroupPyInterface

selectionGroupNames(type, criteria={})
Parameters:

  • type (SelectionGroupType) -- the selection group type (e.g. data.ReferenceMaterial)

  • criteria (dict) -- currently unused

Returns:

List of selection groups matching type

Return type:

list of strings

selectionGroupsChanged()

The signal emitted indicating that the selection groups have changed. Connect to this signal to call functions when the selection groups have changed.

For example, data.selectionGroupsChanged.connect(my_function)

Returns:

None

setLaserLogData(filePath, attrName, value)

Sets laser log data.

Parameters:

  • filePath (str) -- full path to file

  • attrName (str) -- attribute name

  • value (float) -- value to set

Returns:

None

setLaserLogArray(filePath, attrName, array)

Sets laser log array.

Parameters:

  • filePath (str) -- full path to file

  • attrName (str) -- attribute name

  • array (numpy array) -- array to set

Returns:

None

spline(x, y, w, splineTypeName, sx=None)

Creates a spline from the given data.

Parameters:

  • x (numpy array) -- x-coordinates of the data points

  • y (numpy array) -- y-coordinates of the data points

  • w (numpy array) -- weights for the data points

  • splineTypeName (str) -- name of the spline type to use. See data.splineOptions() for a list of available options.

  • sx (numpy array, optional) -- optional x-coordinates for the spline evaluation. This is often indexTime.

Returns:

a spline object

Return type:

iolite.TimeSeriesDataPyInterface

splineOptions()

Returns a list of available spline options.

Returns:

list of spline options

Return type:

list of str

timeOffset(atime, adata, btime, bdata)

Calculates the time offset between two time series.

Parameters:

  • atime (numpy array) -- time array for the first series

  • adata (numpy array) -- data array for the first series

  • btime (numpy array) -- time array for the second series

  • bdata (numpy array) -- data array for the second series

Returns:

time offset

Return type:

float

timeSeries(name)
Parameters:

name (str) -- Name of the time series channel to retrieve.

timeSeriesByMass(type, mass, tol)

Returns a time series data object for the specified mass and type within the given tolerance.

For example, to get the time series data for the mass 88Sr within a tolerance of 0.1, use data.timeSeriesByMass(data.Input, 88, 0.1).

Parameters:

  • type (TimeSeriesDataType) -- Type of time series data (e.g., data.Input)

  • mass (float) -- Mass to search for

  • tol (float) -- Tolerance for the mass search

Returns:

A time series data object

Return type:

iolite.TimeSeriesDataPyInterface

timeSeriesList(type, criteria={})
Parameters:

type (TimeSeriesDataType) -- Type of timeseries.

Returns:

A list of TimeSeriesDataPyInterface objects.

Return type:

List of iolite.TimeSeriesDataPyInterface

timeSeriesNames(type, criteria={})
Parameters:

type (TimeSeriesDataType) -- Type of timeseries.

Returns:

A list of time series names of the specified type.

Return type:

list of strings.

updateResults()

Updates all results for all selections and channels

Returns:

None

addCitationToSession(text)

Adds a citation to the session.

Parameters:

text (str) -- citation text

Returns:

None

thingsToCite()

Returns a list of things to cite.

Returns:

list of citations

Return type:

list of str

version()

Returns the version of the software.

Returns:

version information

Return type:

list

sessionFilePath()

Returns the file path of the current session.

Returns:

session file path

Return type:

str

sessionUUID()

Returns the UUID of the current session.

Returns:

session UUID

Return type:

str

elements = {}

This is a dictionary containing information about each element in the periodic table. You can access the information about each element using e.g. data.element['Sr'], which returns a dictionary with the following fields:

CI: Chondrite normalised value (float)

MORB: MORB normalised value (float)

MUQ: MUQ normalised concentration (float)

atomicNumber: Atomic Number (int)

atomicRadius: Atomic Radius (float)

atomicWeight: Atomic Weight (float)

boilingPoint: Boiling Point (float)

density: Density (float)

electronAffinity: Electron Affinity (float)

geochemicalClass: Geochemical Class

goldschmidtClass: Goldschmidt Classification (string)

group: Periodic Table Group (int)

ionizationEnergies: A list of Ionization Energies for each isotope

in isotopes (list of floats)

isotopes: A list of dicts. Each dict represents an isotope

and has the following keys: 'abundance' (float), 'mass' (float), 'massNumber' (int)

meltingPoint: Melting Point in K (float)

name: Full name of element (string)

period: Periodic Table Period (int)

series: (int)

symbol: Element's symbol (string)

class iolite.DBPythonInterface

Interface to iolite's database functionality.

An instance of this is typically available in iolite's python interpreter as 'db'. So, e.g.,

Pb206 = db.column('Pb206', db.All)

The DBPythonInterface has a Query enum that specifies what data to return from the database:

  • All: returns all data for the selected column

  • Model: returns data that match the currently displayed

  • Specified: returns data the match the query provided

e.g. db.column('Pb206', db.All) returns all values from the database in the column 'Pb206'. db.column('Pb206', db.Specified, 'SELECT * FROM Results WHERE `Pb206_CPS < 100')` returns only the data matching the query text ('SELECT * FROM Results WHERE Pb206_CPS < 100') Note that the following query would return a list where each value is None: db.column('U238', db.Specified, 'SELECT `Pb206 FROM Results WHERE Pb206_CPS < 100')` because only Pb206 values are selected by the query. Use this instead: db.column('U238', db.Specified, 'SELECT `U238 FROM Results WHERE Pb206_CPS < 100')`

appendColumn(column_name, values, query_mode, specified_query)

Inserts a list of values into the database as a new column. Can optionally specify which rows of the new column to insert values using a specified SQL query. If the number of results of the query does not match the number of values being inserted, an error is raised, and no data are added. Changes to the database are committed upon successful insertion of the data

Parameters:

  • column_name (str) -- name of new column

  • values -- list of values to insert

;type values: iterable such as list or numpy array :param query_mode: type of query. See class:iolite.DBPythonInterface :param specified_query: Query text if `query_mode is db.Specified. Default is ""

Must be valid SQL query

Returns:

None

column(column_name, query_mode, specified_query)

Return a column from the database as a list of values

Parameters:

  • column_name (str) -- name of column to return

  • query_mode -- type of query. See class:iolite.DBPythonInterface. Default is db.All

  • specified_query (str) -- Query text if `query_mode is db.Specified. Default is "" Must be valid SQL query

Returns:

a list of values from the column

Return type:

List

dataFrame(query_mode, specified_query)

Return a data from the database as a pandas dataframe

Parameters:

  • query_mode -- type of query. See class:iolite.DBPythonInterface. Default is db.All

  • specified_query (str) -- Query text if `query_mode is db.Specified. Default is "" Must be valid SQL query

Returns:

a pandas dataframe of the entire database, or a subset of the database if query_mode is db.Model or db.Specified.

Return type:

Pandas dataframe

class iolite.FileMetadataPyInterface

Data File objects. For example, if a file of mass spec data is loaded, metadata about the file will be stored in a FileMetaData object. Specifically the metadata stored is the file path and filename, and the start and end time for data within the file. For some file types (e.g. iCap), there may be multile samples within a single file, whereas other file types (e.g. Agilent) contain only a single sample within each file. See iolite.SampleMetadataPyInterface for more information about samples.

Variables:

  • filePath -- Full path to file

  • fileName (str) -- Filename

  • startTime (QDateTime) -- Time of first data point within the file

  • endTime (QDateTime) -- Time of last data point within the file

filePath()
fileName()
startTime()
endTime()
properties()
property(name)
propertyChanged()
setProperty(name, value)
removeProperty(name)
class iolite.IoLog

Interface to iolite's logging/messages system settings.

saveLogToFile(file_name)

Saves contents of current log to JSON file

Parameters:

file_name (str) -- path/filename to save to

Returns:

None

newEntry(message, time)

Add new entry to iolite's log

Parameters:

  • message (str) -- message to log

  • time (QDateTime) -- timestamp associated with log message. Default is current time

Returns:

None

newEntryWithOrigin(message, origin, time)

Add new entry to iolite's log with label indicating the origin of the log message

Parameters:

  • message (str) -- message to log

  • origin (str) -- message origin (e.g. function name)

  • time (QDateTime) -- timestamp associated with log message. Default is current time

Returns:

None

information(message, time)

Add new entry to iolite's log of type "Information"

Parameters:

  • message (str) -- message to log

  • time (QDateTime) -- timestamp associated with log message. Default is current time

Returns:

None

informationWithOrigin(message, origin, time)

Add new entry to iolite's log of type "Information"

Parameters:

  • message (str) -- message to log

  • origin (str) -- message origin (e.g. function name)

  • time (QDateTime) -- timestamp associated with log message. Default is current time

Returns:

None

debug(message, time)

Add new entry to iolite's log of type "Debug", i.e. not shown in Messages by default

Parameters:

  • message (str) -- message to log

  • time (QDateTime) -- timestamp associated with log message. Default is current time

Returns:

None

debugWithOrigin(message, origin, time)

Add new entry to iolite's log of type "Debug", i.e. not shown in Messages by default

Parameters:

  • message (str) -- message to log

  • origin (str) -- message origin (e.g. function name)

  • time (QDateTime) -- timestamp associated with log message. Default is current time

Returns:

None

warning(message, time)

Add new entry to iolite's log of type "Warning"

Parameters:

  • message (str) -- message to log

  • time (QDateTime) -- timestamp associated with log message. Default is current time

Returns:

None

warningWithOrigin(message, origin, time)

Add new entry to iolite's log of type "Warning"

Parameters:

  • message (str) -- message to log

  • origin (str) -- message origin (e.g. function name)

  • time (QDateTime) -- timestamp associated with log message. Default is current time

Returns:

None

error(message, time)

Add new entry to iolite's log of type "Error"

Parameters:

  • message (str) -- message to log

  • time (QDateTime) -- timestamp associated with log message. Default is current time

Returns:

None

errorWithOrigin(message, origin, time)

Add new entry to iolite's log of type "Error"

Parameters:

  • message (str) -- message to log

  • origin (str) -- message origin (e.g. function name)

  • time (QDateTime) -- timestamp associated with log message. Default is current time

Returns:

None

clear()

Clears all messages in current session.

Returns:

None

messageCount()

Returns number of messages currently in log

Returns:

Number of messages currently in session log

Return type:

int

class iolite.Result

Results object that store the result (mean, uncertainty etc) for a selecion and a particular channel.

value()

Returns the mean as a float

valueInPPM()

Converts the mean to ppm before returning as a float

setValue(val)

Sets the value of this result

Parameters:

val (float) -- Value to set

Returns:

None

uncertainty()
Returns:

the uncertainty (as 2 SD) of the result as a float

Return type:

float

setUncertainty(u)

Sets the uncertainty (2 SD) for this result

Parameters:

u (float) -- Uncertainty to set

Returns:

None

uncertaintyAs2SE()
Returns:

the uncertainty for this result as 2 standard errors

Return type:

float

propagatedUncertainty()

Returns the propagate uncertainty for this result as a float

longerichLOD()

Returns the LOD for this result (as a float) calculating using the Longerich et al. (1996) method.

howellLOD()

Returns the LOD for this result (as a float) calculating using the Howell et al. (2013) method.

pettkeLOD()

Returns the LOD for this result (as a float) calculating using the Pettke et al. (2012) method.

sum()
Returns:

the sum of datapoints in the selection interval for this channel.

Return type:

float

numFinite()
Returns:

the number of finite (i.e. not null/NaN) datapoints used to calculate this result

Return type:

int

numOutliers()
Returns:

the number of datapoints classified as outliers when calculating this result

Return type:

int

numMeasurements()
Returns:

the total number of datapoints in the selection interval for

this channel. This is the same as numFinite() + numOutliers() :rtype: int

class iolite.SampleMetadataPyInterface

Sample objects. Files may be subdivided into Samples. For some file types (e.g. iCap), there may be multile samples within a single file, whereas other file types (e.g. Agilent) contain only a single sample within each file.

Variables:

  • sampleName (str) -- Name of sample

  • startTime (QDateTime) -- Start time of sample

  • endTime (QDateTime) -- End time of sample

sampleName()
startTime()
endTime()
setStartTime(time)
setEndTime(time)
setSampleName(name)
properties()
class iolite.SelectionPyInterface

Selection objects.

Variables:

  • name (str) -- Name.

  • comment (str) -- Comment.

  • startTime (QDateTime) -- Start time.

  • endTime (QDateTime) -- End time.

  • duration (int) -- Duration in ms.

  • midTimeInMilliSec (int) -- Selection's mid-time in milliseconds since Epoch

  • midTimeInSec (int) -- Selection's mid-time in seconds since Epoch

group()
Returns:

The group associated with this selection.

Return type:

iolite.SelectionGroupPyInterface

setGroup(group)
Parameters:

group (iolite.SelectionGroupPyInterface) -- The group to associate with this selection.

properties()
Returns:

A dict of properties associated with this selection.

Return type:

dict

setProperties(properties)
Parameters:

properties (dict) -- A dict of properties to associate with this selection.

property(propertyName)

Retrieves a single property by name.

Parameters:

propertyName (str) -- Name of property to retrieve.

Returns:

The property if it exists, otherwise None.

setProperty(propertyName, propertyValue)

Sets a single property by name.

Parameters:

  • propertyName -- Name of property to set.

  • propertyValue -- Value of property.

class iolite.SelectionGroupPyInterface

Selection group objects

Variables:

  • name (str) -- Name.

  • count (int) -- Number of selections

  • type (SelectionGroupType) -- type of Selection Group e.g. data.Baselines

property(propName)

Returns the named group property.

Parameters:

propName (str) -- the name of the property to return

selection(index)

Returns the selection at index.

Parameters:

index (int) -- the selection's index

Returns:

a selection object

Return type:

iolite.SelectionPyInterface

selections()

Returns a list of selection in the group.

Returns:

a list selection objects

Return type:

list of iolite.SelectionPyInterface

removeSelection(selection)

Removes the passed selection

Parameters:

selection (iolite.SelectionPyInterface) -- the name of the property to return

Returns:

None

class iolite.TimeSeriesDataPyInterface

Channel data are stored as Time Series Data (TSD) objects, although other things may be stored as TSD objects too (e.g. spline data). Each TSD has a time array, and a data array, as well as a set of properties.

Variables:

  • name (str) -- Name of channel

  • data (numpy array) -- Array of data points

  • time (numpy array) -- The array of time points associated with the data

properties()
Returns:

A dict of properties associated with this channel.

Return type:

dict

property(propertyName)

Retrieves a single property by name.

Parameters:

propertyName (str) -- Name of property to retrieve.

Returns:

The property if it exists, otherwise None.

setProperty(propertyName, propertyValue)

Sets a single property by name.

Parameters:

  • propertyName -- Name of property to set.

  • propertyValue -- Value of property.

dataForSelection(selection)

Returns an array of the values for this channel during a selection's interval. Here is a very basic example that gets the values within the first selection in the NIST612 group for the Sr88 channel:

selgrp = data.selectionGroup('G_NIST612')
sel = selgrp.selections()[0]
sr88 = data.timeSeries('Sr88')
sr88.dataForSelection(sel)      #returns an array of data for Sr88
channel within the selections start and end time
sr88.timeForSelection(sel)      #also get the associated time
values
Parameters:

selection -- The selection, for which results between the

selection start and end times will be returned. :type selection: iolite.SelectionPyInterface

Returns:

An array of channel values

Return type:

numpy array

timeForSelection(selection)

Returns an array of the time points for this channel during a selection's interval. See dataForSelection() for an example

Parameters:

selection -- The selection, for which time points between the

selection start and end times will be returned. :type selection: iolite.SelectionPyInterface

Returns:

An array of time values

Return type:

numpy array

selectionIndices(selection)

Returns an array of the indices for this channel during a selection's interval.

Parameters:

selection -- The selection, for which indices between the selection start and end times will be returned.

iolite.SelectionPyInterface

Returns:

An array of indices

Return type:

numpy array

class iolite.ImagingPyInterface

An interface to iolite's imaging plugin. With this object you can make changes to the global configuration of the imaging module as well as get objects representing individual images, ROI, or profiles.

image(name)
Parameters:

name (string) -- Name of the image object to retrieve.

Returns:

The named image.

Return type:

iolite.IoliteImagePyInterface

imageNames()
Returns:

Names of the available images.

Return type:

list of strings

matrix(group, channel, p_dict)

See function overload for listing of the p_dict options.

Parameters:
Returns:

Matrix of data representing the image.

Return type:

numpy matrix

physicalMin()
Returns:

The physical coordinates of the currently imaged group's top left corner.

Return type:

QPointF

physicalSize()
Returns:

The physical size of the currently imaged group.

Return type:

QSizeF

pixmap(name)
Parameters:

name (string) -- The name of the image pixmap to retrieve.

Returns:

Pixmap of the requested image.

Return type:

QPixmap

profile(index)
Parameters:

index (int) -- The index of the profile to retrieve.

Returns:

The requested profile.

Return type:

iolite.ProfilePyInterface

profiles()
Returns:

A list of the profiles.

Return type:

list of iolite.ProfilePyInterface

roi(index)
Parameters:

index (int) -- The index of the ROI to retrieve.

Returns:

The requested region of interest

Return type:

iolite.ROIPyInterface

rois()
Returns:

A list of the regions of interest

Return type:

list of iolite.ROIPyInterface

setGroup(name)
Parameters:

name (string) -- The name of the group to image.

spaceMask()
Returns:

An array of channel data/time indices corresponding to the imaged group.

Return type:

numpy array

class iolite.IoliteImagePyInterface

Object representing an image. See iolite.ImagingPyInterface for ways to obtain such objects.

channel()
Returns:

The channel associated with this image.

Return type:

iolite.TimeSeriesDataPyInterface

data()
Returns:

The matrix of data representing this image.

Return type:

numpy matrix

externalCropRect()
Returns:

The cropping rectangle to use on the external image associated with this image object.

Return type:

QRectF

externalPath()
Returns:

The path of the external image file associated with this image object.

Return type:

string

externalPixmap()
Returns:

The pixmap of the external image associated with this image object.

Return type:

QPixmap

externalSize()
Returns:

The size of the external image associated with this image object.

Return type:

QSizeF

externalTopLeft()
Returns:

The top left coordinate of the external image associated with this image object in physical units.

Return type:

QPointF

externalTransform()
Returns:

The transform associated with the external image associated with this image object.

Return type:

QTransform

externalUsesGrayscale()
Returns:

Whether the external image associated with this image object should be displayed as intensity.

Return type:

bool

gradient()
Returns:

The color gradient associated with this image object.

Return type:

QCPColorGradient

group()
Returns:

The group associated with this image object.

Return type:

iolite.SelectionGroupPyInterface

infoColor()
Returns:

The color to be used for information overlays on the image.

Return type:

QColor

limits()
Returns:

The current limits of this image object respecting the specified limit types.

Return type:

tuple of floats

lowerLimitType()
Returns:

The lower limit type of this image object..

Return type:

string

name()
Returns:

The name of this image object.

Return type:

string

scaleType()
Returns:

The scale type of this image object.

Return type:

string

scalebarLength()
Returns:

The physical length of the scale bar of this image object..

Return type:

float

scalebarPosition()
Returns:

Scalebar position.

Return type:

string

scalebarStyle()
Returns:

The scalebar style of this image object.

Return type:

string

setExternalCropRect(crop_rect)
Parameters:

copr_rect -- Sets the rectangle to crop the external image with.

setExternalPath(path)
Parameters:

path (string) -- Sets the external image path.

setExternalPixmap(pixmap)
Parameters:

pixmap (QPixmap) -- Sets the external image pixmap.

setExternalSize(size)
Parameters:

size (QSizeF) -- Sets the physical size of the external pixmap.

setExternalTopLeft(top_left)
Parameters:

top_left (QPointF) -- Sets the physical top left coordinate of the external image.

setExternalTransform(transform)
Parameters:

transform (QTransform) -- Sets the transform to be used on the external image.

setExternalUsesGreyscale(use_greyscale)
Parameters:

use_greyscale (bool) -- Sets whether to use the intensity of the external image rather than the image itself.

setGradient(gradient)
Parameters:

gradient (QCPColorGradient) -- Sets the color gradient to be used for this image object.

setInfoColor(color)
Parameters:

color (QColor) -- Sets the color to use for drawing info overlays on this image object.

setLimits(lower, upper)

Sets the lower and upper limit values to be used when the limit types are 'Value'.

Parameters:

  • lower (float) -- The lower limit.

  • upper (float) -- The upper limit.

setLowerLimitType(limit_type)
Parameters:

limit_type (string) -- One of: 'Auto', 'Value', 'TwoSDOfMean', 'TwoSDOfMedian', 'PercentileX', where X is one of 90, 95, 99, 99p9.

setScaleType(scale_type)
Parameters:

scale_type (string) -- One of: 'Linear', 'Logarithmic' or 'ECDF'

setScalebarLength(length)
Parameters:

length (float) -- Physical length for the image's scalebar.

setScalebarPosition(position)
Parameters:

position (string) -- One of: 'None', 'TopLeft', 'TopRight', 'BottomLeft' or 'BottomRight'.

setScalebarStyle(style)
Parameters:

style (string) -- One of: 'Bar', 'HalfBar', 'Arrow' or 'Plain'.

setUpperLimitType()
Parameters:

limit_type (string) -- One of: 'Auto', 'Value', 'TwoSDOfMean', 'TwoSDOfMedian', 'PercentileX', where X is one of 90, 95, 99, 99p9.

upperLimitType()
Returns:

The upper limit type of this image object.

Return type:

string

class iolite.ProfilePyInterface

Object representing an imaging profile. Profiles in iolite's imaging module are defined by a list of vertices that represent the backbone of the profile, on which sub-ROI are generated according to a specified physical width and height (in microns).

dist()
Returns:

A list of floats representing the distance between each of the profile's sub-ROI.

Return type:

list of float

name()
Returns:

The name of this profile object.

Return type:

string

rois()
Returns:

A list of the sub-ROI comprising this profile.

Return type:

list of iolite.ROIPyInterface

sectionHeight()
Returns:

The physical height of each sub-ROI section.

Return type:

float

sectionWidth()
Returns:

The physical width of each sub-ROI section.

Return type:

float

totalLength()
Returns:

The total physical length of the ROI in microns.

Return type:

float

vertices()
Returns:

A list of vertices defining the profile in physical (micron) units.

Return type:

list of QPointF

class iolite.ROIPyInterface

Object representing an imaging region of interest (ROI).

centroid()
Returns:

The centroid of this ROI object.

Return type:

QPointF

mask()

You can use this function to get an array of values contributing to the ROI, e.g.:

U238 = data.timeSeries('U238').data()
roi_mean = U238[roi.mask()].mean()
Returns:

An array of the indices of each channel contributing to this ROI.

Return type:

numpy array

name()
Returns:

The name of this ROI object.

Return type:

string

numberOfPoints()
Returns:

An array of channel values

Return type:

int

physicalArea()
Returns:

The physical area contained by this ROI in um^2.

Return type:

float

polygons()
Returns:

A list of QPolygonF objects that are part of this ROI.

Return type:

list of QPolygonF