| Title: | Extract and Analyze EchoMS Data from Sciex Wiff Files |
|---|---|
| Description: | Read raw and processed data from acoustic ejection mass spectrometry (AEMS) files produced by the Sciex EchoMS instrument. Includes functions to create interactive reader objects, extract raw intensity measurements, mass spectra, and fully-processed mass-transition intensity areas. Methods for data processing and analysis are described in Rimmer et al. (2025) <doi:10.1021/acs.analchem.5c03730>. Supports both multiple reaction monitoring (MRM) and full-scan (neutral loss and precursor ion) data formats. |
| Authors: | Mary Ashley Rimmer [aut], Nathaniel Twarog [aut, cre], Lei Yang [aut] |
| Maintainer: | Nathaniel Twarog <[email protected]> |
| License: | GPL (>= 3) |
| Version: | 0.2.4 |
| Built: | 2026-05-15 07:18:56 UTC |
| Source: | https://github.com/cran/rtmsEcho |
An object of class rtmsWiffReader produced by running newWiffReader on
a .wiff and .wiff.scan file. The files in question contain multiple reaction
monitoring (MRM) data measuring three mass transitions, corresponding to the
detection of the compounds carbamazepine, warfarin, and verapamil. The
EchoMS run included measurements of 320 ejections, each three seconds apart
from 320 wells of a 384-well plate.
exampleWiffexampleWiff
A data structure of type rtmsWiffReader; a description of the
format can be found in the description for newWiffReader
Note that the wiff reader object does not contain all data from the .wiff and .wiff.scan files. It included to demonstrate some of the basic function in the package.
Get the total area for given masses for all wells
getAllFullScanAreas(scanfile, tic, sample, ejections, peaks)getAllFullScanAreas(scanfile, tic, sample, ejections, peaks)
scanfile |
A file path to a Sciex raw scan file (extension .wiff.scan) containing the raw data referenced by the .wiff file from which the other parameters were extracted |
tic |
A total ion chromatogram of the format outputby |
sample |
The particular object from the |
ejections |
An ejection table listing the timing and boundaries of the
total ion chromatogram peaks for all shots in the run, as returned by
|
peaks |
A named list of peak objects of class |
The table returned includes a measurement of total area for each of the mass
transitions listed in sample. It contains one row for each measured shot
each mass transition, with the following columns:
shotorder: The order of the peak within the shots fired during the run
well: The alphanumeric well name of the well from which the shot was
fired
time: The time (in seconds) after the beginning of the run at which the
intensity from the shot was at its peak
massindex: The index of the measured mass transition in the set of masses
in the given sample
mass: The name of the mass transition measured (often a compound name or
id)
area: The intensity area (in counts) for that particular mass transition
from that ejection
A data frame containing the total intensity for each rtmsPeak given
and each ejection; see Details for column specifics.
Extract mass spectra for all wells
getAllFullScanSpectra(scanfile, tic, sample, ejections)getAllFullScanSpectra(scanfile, tic, sample, ejections)
scanfile |
A file path to a Sciex raw scan file (extension .wiff.scan) containing the raw data referenced by the .wiff file from which the other parameters were extracted |
tic |
A total ion chromatogram of the format outputby |
sample |
The particular object from the |
ejections |
An ejection table listing the timing and boundaries of the
total ion chromatogram peaks for all shots in the run, as returned by
|
A list of objects of class rtmsSpectrum containing the full
extracted mass spectra for each ejection
Extract the peak areas for MRM mass transitions for all wells
getAllMRMAreas(scanfile, tic, sample, ejections, removeBaseline = TRUE)getAllMRMAreas(scanfile, tic, sample, ejections, removeBaseline = TRUE)
scanfile |
A file path to a Sciex raw scan file (extension .wiff.scan) containing the raw data referenced by the .wiff file from which the other parameters were extracted |
tic |
A total ion chromatogram data.frame as extracted by |
sample |
A "sample" object representing a run in a .wiff file, from the
|
ejections |
An ejection table listing the timing and boundaries of the
total ion chromatogram peaks for all shots in the run, as returned by
|
removeBaseline |
If TRUE, baseline intensity for each mass transition will be subtracted from the intensities in each ejection, to account for baseline intensities measured near the lower limit of quantitation |
The table return includes a measurement of total area for each of the mass
transitions listed in sample. It contains one row for each measured shot
each mass transition, with the following columns:
shotorder: The order of the peak within the shots fired during the run
well: The alphanumeric well name of the well from which the shot was
fired
time: The time (in seconds) after the beginning of the run at which the
intensity from the shot was at its peak
massindex: The index of the measured mass transition in the set of masses
in the given sample
mass: The name of the mass transition measured (often a compound name or
id)
area: The intensity area (in counts) for that particular mass transition
from that ejection
A data frame containing the total intensity for each mass transition and each ejection; see Details for column specifics.
Extract all total ion chromatograms from a Wiff file
getAllTIC(wiff)getAllTIC(wiff)
wiff |
A wiff reader object of class |
A list of total ion chromatograms of the format extracted by
getTIC(), one for each run in the given .wiff file
wiff <- exampleWiff tics <- getAllTIC(wiff) tic <- tics[[1]]wiff <- exampleWiff tics <- getAllTIC(wiff) tic <- tics[[1]]
Get the total area for given masses for a particular well
getFullScanAreas(scanfile, tic, sample, ejections, peaks, well)getFullScanAreas(scanfile, tic, sample, ejections, peaks, well)
scanfile |
A file path to a Sciex raw scan file (extension .wiff.scan) containing the raw data referenced by the .wiff file from which the other parameters were extracted |
tic |
A total ion chromatogram of the format outputby |
sample |
The particular object from the |
ejections |
An ejection table listing the timing and boundaries of the
total ion chromatogram peaks for all shots in the run, as returned by
|
peaks |
A named list of peak objects of class |
well |
The well (a string) or well index (an integer) to be measured |
The table return includes a measurement of total area for each of the mass
transitions listed in sample. It contains one row for each measured shot
each mass transition, with the following columns:
shotorder: The order of the peak within the shots fired during the run
well: The alphanumeric well name of the well from which the shot was
fired
time: The time (in seconds) after the beginning of the run at which the
intensity from the shot was at its peak
massindex: The index of the measured mass transition in the set of masses
in the given sample
mass: The name of the mass transition measured (often a compound name or
id)
area: The intensity area (in counts) for that particular mass transition
from that ejection
A data frame containing the total intensity for rtmsPeak gvien
and each ejection; see Details for column specifics.
Extract raw Wiff full scan data
getFullScanData(scanfile, tic, sample, removeZeros = FALSE)getFullScanData(scanfile, tic, sample, removeZeros = FALSE)
scanfile |
A file path to a Sciex raw scan file (extension .wiff.scan) containing the raw data referenced by the .wiff file from which the other parameters were extracted |
tic |
A (possibly partial) total ion chromatogram of the format output
by |
sample |
The particular object from the |
removeZeros |
If |
The data frame output by the function contains all the intensity data compressed into the .wiff.scan file for the given range of times; it has the following columns:
index: The particular row of ptic the measurement corresponds to
time: The time (in seconds) after the beginning of the run at which the
measurement was taken
mz: The mass to charge value (in m/z) which the measurement corresponds
to
intensity: The intensity (in counts per second) that was measured for
the given time and m/z value
A data frame containing all raw data for the given range (see Details)
Extract a full mass spectrum for a given well
getFullScanSpectrum(scanfile, tic, sample, ejections, well)getFullScanSpectrum(scanfile, tic, sample, ejections, well)
scanfile |
A file path to a Sciex raw scan file (extension .wiff.scan) containing the raw data referenced by the .wiff file from which the other parameters were extracted |
tic |
A total ion chromatogram of the format outputby |
sample |
The particular object from the |
ejections |
An ejection table listing the timing and boundaries of the
total ion chromatogram peaks for all shots in the run, as returned by
|
well |
The well (a string) or well index (an integer) to be measured |
An object of class rtmsSpectrum representing the full mass
spectrum for the given well
Extract the peak areas for MRM mass transitions for a given well
getMRMAreas(scanfile, tic, sample, ejections, well, removeBaseline = TRUE)getMRMAreas(scanfile, tic, sample, ejections, well, removeBaseline = TRUE)
scanfile |
A file path to a Sciex raw scan file (extension .wiff.scan) containing the raw data referenced by the .wiff file from which the other parameters were extracted |
tic |
A total ion chromatogram data.frame as extracted by |
sample |
A "sample" object representing a run in a .wiff file, from the
|
ejections |
An ejection table listing the timing and boundaries of the
total ion chromatogram peaks for all shots in the run, as returned by
|
well |
The well (a string) or well index (an integer) to be measured |
removeBaseline |
If TRUE, baseline intensity for each mass transition will be subtracted from the intensities in each ejection, to account for baseline intensities measured near the lower limit of quantitation |
The table return includes a measurement of total area for each of the mass
transitions listed in sample. It contains one row for each measured shot
each mass transition, with the following columns:
shotorder: The order of the peak within the shots fired during the run
well: The alphanumeric well name of the well from which the shot was
fired
time: The time (in seconds) after the beginning of the run at which the
intensity from the shot was at its peak
massindex: The index of the measured mass transition in the set of masses
in the given sample
mass: The name of the mass transition measured (often a compound name or
id)
area: The intensity area (in counts) for that particular mass transition
from that shot's peak
A data frame containing the total intensity for each mass transition and each ejection; see Details for column specifics.
Extract full chromatograms for each mass transition
getMRMChromatograms(scanfile, tic, sample)getMRMChromatograms(scanfile, tic, sample)
scanfile |
A file path to a Sciex raw scan file (extension .wiff.scan) containing the raw data referenced by the .wiff file from which the other parameters were extracted |
tic |
A total ion chromatogram data.frame as extracted by |
sample |
A "sample" object representing a run in a .wiff file, from the
|
A single data frame expressing all chromatograms in a "long" format, with the following columns:
massindex: The index of the measured mass transition in the set of masses
in the given sample
mass: The name of the mass transition measured (often a compound name or
id)
time: The time (in seconds) at which the intensity was measured
intensity: The intensity for the given mass transition at the given time
Extract a total ion chromatogram (TIC) from a Wiff file
getTIC(wiff, index = 1)getTIC(wiff, index = 1)
wiff |
A wiff reader object of class |
index |
The particular run within the wiff file for which the TIC should be extracted. Defaults to 1, the first (and often only) run. |
The total ion chromatogram data in a .wiff file contains data for every moment at which the EchoMS took a measurement. Each measurement is represented by a single row in the returned data frame, with the following four values:
time: The time (in seconds) after the beginning of the run at which the
measurement was taken
intensity: The total ion intensity across all masses measured
full: Either 0 (indicating data is stored as a discrete set of targeted
intensities) or 1 (indicating the data is stored as a compressed full
spectrum)
offset: The binary offset within this run's data block in the associated
.wiff.scan file at which this measurement's raw data can be found
size: The size (in bytes) of this measurment's raw data in the associated
.wiff.scan file.
A data frame containing the TIC data (see Details)
wiff <- exampleWiff tic <- getTIC(wiff) # Plot the first 60 seconds of the total ion chromatgram using [ggplot2] ggplot2::ggplot(tic,ggplot2::aes(x=time,y=intensity))+ ggplot2::geom_line(color="red")+ ggplot2::xlim(0,60)wiff <- exampleWiff tic <- getTIC(wiff) # Plot the first 60 seconds of the total ion chromatgram using [ggplot2] ggplot2::ggplot(tic,ggplot2::aes(x=time,y=intensity))+ ggplot2::geom_line(color="red")+ ggplot2::xlim(0,60)
List of Shot Names in a given Wiff File
getWiffShots(wiff)getWiffShots(wiff)
wiff |
A wiff reader object of class |
The .wiff file includes these shot names in the order in which they were input by the user. They are generally names of wells in a plate, but the order in which they are given by the user is not necessarily the order in which the EchoMS will sample them. By default, the EchoMS will use a more "efficient" ordering, moving back and forth across the rows of the plate. So the shot names here may not correlate in order with the measurements represented by the intensities in the total ion chromatogram.
A character vector containing the shot names for all shots fired in each run in a given file. Note: not necessarily in the correct order (see Details).
wiff <- exampleWiff shots <- getWiffShots(wiff)wiff <- exampleWiff shots <- getWiffShots(wiff)
Measure total ion chromatogram peaks to estimate ejection time
measureEjections( wiff, efficientPath = TRUE, center = 3, guess = NULL, index = 1, shots = NULL ) ## S3 method for class 'rtmsWiffReader' measureEjections( wiff, efficientPath = TRUE, center = 3, guess = NULL, index = 1, shots = NULL ) ## Default S3 method: measureEjections( wiff, efficientPath = TRUE, center = 3, guess = NULL, index = 1, shots = NULL )measureEjections( wiff, efficientPath = TRUE, center = 3, guess = NULL, index = 1, shots = NULL ) ## S3 method for class 'rtmsWiffReader' measureEjections( wiff, efficientPath = TRUE, center = 3, guess = NULL, index = 1, shots = NULL ) ## Default S3 method: measureEjections( wiff, efficientPath = TRUE, center = 3, guess = NULL, index = 1, shots = NULL )
wiff |
Either an ojbect of class |
efficientPath |
If |
center |
A guess at the timing (in seconds) between EchoMS shots. Most runs are 3 seconds apart, but the EchoMS does permit a fast mode. If a fast mode is used, 0.3 seconds should be added to fast mode timing, as the Echo requires those 0.3 to eject a droplet |
guess |
If included, used as the guess for the timing of the first
shot. If desired this can usually be estimated visually from a plot of the
total ion chromatogram intensity. Actual shot timing will still be
optimized to align with TIC intensities. If |
index |
The particular run within the wiff file for which the TIC should be extracted. Defaults to 1, the first (and often only) run. |
shots |
A list of shot names as extracted by |
The function assumes equally timed ejections, approximately center seconds
apart, can be found in the total ion chromatogram. Once the timing of these
peaks is selected, the chromatogram is analyzed to locate the boundaries of
these peaks, using baseline noise or local minima to draw these boundaries.
The function returns a data frame with one row for each peak, with the
following columns:
shotorder: The order within the run in which the peaks appeared
shot: The full shot name found in shots
marker: TRUE if the shot is indicated as coming from a marker well
well: The standard alphanumeric well name found in the shot name
time: The time (in seconds) after the beginning of the run at which the
peak is expected to reach its maximum
minTime: The time (in seconds) after the beginning of the run at which
the peak is measured to begin
maxTime: The time (in seconds) after the beginning of the run at which
the peak is measured to end
area: The total area (in counts, as intensity is counts per second and
the extend of the peak is measured in seconds) of the peak
height: The maximum height of the peak (in counts per second)
width: The total width of the peak (in seconds)
halfWidth: The width of the peak at half of its maximum intensity (in
seconds)
A data frame of measured ejections (see Details)
wiff <- exampleWiff # Works if file is run with 3 seconds between peaks and shots are fired # from wells in the efficient "back-and-forth" path ejections <- measureEjections(wiff)wiff <- exampleWiff # Works if file is run with 3 seconds between peaks and shots are fired # from wells in the efficient "back-and-forth" path ejections <- measureEjections(wiff)
Open a Sciex EchoMS wiff File for Reading
newWiffReader(wiffFile, wiffScanFile = NULL)newWiffReader(wiffFile, wiffScanFile = NULL)
wiffFile |
A valid file path to the Sciex data file (extension .wiff) containing the metadata for one or more EchoMS runs |
wiffScanFile |
An optional file path the the Sciex scan file (extension .wiff.scan) containing the full raw EchoMS data |
The reader object produced by this function is of class rtmsWiffReader,
and contains the information necessary to extract more detailed data from
this file and the associated .wiff.scan file. It contains the following
fields:
wiff: The path to the .wiff file being used
wiffScan: If given, the path of the associated .wiff.scan file. Some but
not all functions require this file; this will be specified in their
documentation.
cfbf: A list of values used to parse the .wiff file's internal CFBF
structure
samples: The "sample" list for the .wiff file. It is important to note
that these are actually different runs whose data have been stored in one
file. Contains data on the specific masses measured in each run.
An object of class rtmsWiffReader (see Details)
A convenient wrapper function to extract all full scan areas from a file without storing the intermediate reader and ejection data structures.
processAllFullScanAreas(wiffFile, wiffScanFile, peaks, ...)processAllFullScanAreas(wiffFile, wiffScanFile, peaks, ...)
wiffFile |
A valid file path to the Sciex data file (extension .wiff) containing the metadata for one or more EchoMS runs |
wiffScanFile |
An file path the the Sciex scan file (extension .wiff.scan) containing the full raw EchoMS data |
peaks |
A named list of peak objects of class |
... |
Additional arguments passed to |
A list with two objects: ejections, a data frame listing all
ejections for all samples in the WIFF file, with an additional wiffSample
column specifying which sample each ejection was extracted from; and
massAreas, a data frame of the format returned by getAllFullScanAreas(),
also with an additional wiffSample column
This is a convenience function that performs an end to end analysis of an Sciex MRM run; it can be used when the intermediate data structures (total ion chromatograms, shot lists, .wiff file readers) are not required.
processAllMRMAreas(wiffFile, wiffScanFile, removeBaseline = TRUE, ...)processAllMRMAreas(wiffFile, wiffScanFile, removeBaseline = TRUE, ...)
wiffFile |
A valid file path to the Sciex data file (extension .wiff) containing the metadata for one or more EchoMS runs |
wiffScanFile |
An valid file path the the Sciex scan file (extension .wiff.scan) containing the full raw EchoMS data |
removeBaseline |
If TRUE, baseline intensity for each mass transition will be subtracted from the intensities in each ejection, to account for baseline intensities measured near the lower limit of quantitation |
... |
Additional optional parameters to be passed to |
A list containing two data frames: ejections, with all extracted
TIC peaks for all runs, as output by measureEjections(), and massAreas,
containing the measured areas for all mass transitoins and all peaks in all
runs, as output by getMRMAreas(). Both data frames contain an addtional
wiffSample column indicating which run within the file the values were
extracted from.