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:
- Short one-off commands written in the python console.
- Longer scripts meant to be reused in the workspace.
- Plugins:
- 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
.
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
- baseline_group (
-
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
- channel (
-
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: - groups (list of
iolite.TimeSeriesDataPyInterface
) -- list of groups to update - channels -- list of channels to update
Returns: None
- groups (list of
-
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.
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
-
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
- selection (
-
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)¶
-
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={})¶
-
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
objectReturn type:
-
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
objectReturn type:
-
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: - group (
-
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:
-
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
- group (
-
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:
-
createTimeSeriesFromMetadata
(name, propertyName, selections, defaultValue, missingValue)¶
-
createTimeSeriesFromResults
(name, channel, selections, defaultValue)¶
-
createTimeSeriesFromSums
(name, baseChannel, selections, interval, gap=0.0, overwrite=False)¶ Creates a new channel by summing intervals along a base channel. The intervals are calculated within the selections passed, and have a duration (interval) and an optional gap between intervals. Both the duration and gap are in seconds. If the overwrite flag is set to True, if a channel of the same name already exists it will be overwritten. The resulting channel is interpolated onto Index Time and is returned.
Parameters: - name (string) -- The name of the channel to be created. If a channel with the same name already exists and the overwrite flag is not set, an error will be raised.
- 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 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
Returns: The created channel
Return type:
-
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: - group (
iolite.SelectionGroupPyInterface
) -- group of selections to determine the avg downhole trend for - channel (
iolite.TimeSeriesDataPyInterface
) -- channel to determine the avg downhole trend for - bsMax (double) -- maximum beam seconds, beyond which the data are ignored
Returns: a tuple of (time, data), where
Return type: tuple of numpy arrays
- group (
-
dataChanged
()¶
-
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
()¶
-
emitDataChanged
()¶
-
exportFavorite
(name)¶
-
exportFavorites
()¶
-
exportFile
(config)¶
-
getH5Array
(filePath, dataPath)¶
-
getH5Attr
(filePath, attrPath)¶
-
globalEndTime
()¶
-
globalStartTime
()¶
-
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
- selections (list of
-
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 usinggrpRes.uncertainty()
.
Parameters: - group (
iolite.SelectionGroupPyInterface
) -- selection group to return a result for - channel (
iolite.TimeSeriesDataPyInterface
) -- channel to return a result for
Returns: a result object, with the value equal to the mean for the group
Return type: result
-
importData
(filePath)¶
-
importLog
(filePath, syncChannelName='TotalBeam')¶
-
importISValues
(filePath)¶
-
importedFiles
()¶ Returns: a list of iolite.FileMetadataPyInterface
objects forall imported mass spec files :rtype: list of
iolite.FileMetadataPyInterface
-
importedLogs
()¶ Returns: a list of iolite.FileMetadataPyInterface
objects forall 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
objectsfor all imported laser log samples :rtype: list of
iolite.SampleMetadataPyInterface
-
massSpecSamples
()¶ Returns: a list of iolite.SampleMetadataPyInterface
objects for all imported mass spec (data) samplesReturn type: list of iolite.SampleMetadataPyInterface
-
oxideToElementFactor
(formula)¶
-
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: - selectionGroups (list of
iolite.SelectionGroupPyInterface
) -- list of selection groups to apply the excess uncertainty to - channels (list of
iolite.TimeSeriesDataPyInterface
) -- list of channels to apply the excess uncertainty to - nonDriftCorrectedChannel (
iolite.TimeSeriesDataPyInterface
) -- channel to determine the excess uncertainty from. Should be a non-drift corrected channel - referenceMaterialName (str) -- name of reference material to determine the excess error from
Returns: None
- selectionGroups (list of
-
qaqc
(name)¶
-
qaqcNames
()¶
-
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
-
removeSelectionGroup
(name)¶
-
removeTimeSeries
(name)¶ Parameters: name (str) -- name of channel to remove Returns: None
-
resetSession
()¶
-
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 ResultsYou can then access the value, uncertainty, number of points, etc using res.value(), res.uncertainty(), res.numMeasurements(), etc
Parameters: - selection (
iolite.SelectionPyInterface
) -- selection to return a result for - channel (
iolite.TimeSeriesDataPyInterface
) -- channel to return a result for
Returns: result object
Return type: result
-
saveSession
(filePath)¶
-
selectionChanged
()¶
-
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
- type (SelectionGroupType) -- the selection group type (e.g.
-
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
- type (SelectionGroupType) -- the selection group type (e.g.
-
selectionGroupsChanged
()¶
-
setLaserLogData
(filePath, attrName, value)¶
-
setLaserLogArray
(filePath, attrName, array)¶
-
spline
(x, y, w, splineTypeName, sx=None)¶
-
timeOffset
(atime, adata, btime, bdata)¶
-
timeSeries
(name)¶ Parameters: name (str) -- Name of the time series channel to retrieve.
-
timeSeriesByMass
(type, mass, tol)¶
-
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
-
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 queryReturns: 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
()¶
-
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: -
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 returnReturns: 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: -
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 exampleParameters: 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. 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: - group (
iolite.SelectionGroupPyInterface
) -- The group to create an image matrix for. - channel (
iolite.TimeSeriesDataPyInterface
) -- The channel to create an image matrix for. - p_dict (dict) -- A dict of parameters for the matrix generating algorithm.
Returns: Matrix of data representing the image.
Return type: numpy matrix
- group (
-
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
-