Functionality Guide

# libraries
library(isoorbi) #load isoorbi R package
library(dplyr) # for mutating data frames

Read raw files

# raw files directory
raw_folder <- system.file(package = "isoorbi", "extdata")

# read files
raw_files <-
  raw_folder |> 
  orbi_find_raw(pattern = "nitrate") |> 
  orbi_read_raw(include_spectra = c(1, 10, 100)) |>
  suppressMessages()

# show summary for the read files
raw_files
──────────────── 2 raw files - combine with orbi_aggregate_raw() ───────────────
1. nitrate_test_10scans.raw has 10 scans with 126 peaks; + loaded 2 spectra
(618 points)
2. nitrate_test_1scan.raw   has  1 scans with  12 peaks; + loaded 1 spectrum
(325 points)

Combine (aggregate) data

# aggregate raw data
agg_data <- raw_files |> orbi_aggregate_raw()
✔ [172ms] orbi_aggregate_raw() aggregated file_info (2), scans (11), peaks
(138), and spectra (943) from 2 files using the standard aggregator
agg_data
─────── aggregated data from 2 raw files - retrieve with orbi_get_data() ───────
→ file_info (2): uidx, filepath, filename, creation_date, in_aquisition,
Operator, FileDescription, MassResolution, SpectraCount, FirstSpectrum,
LastSpectrum, StartTime, EndTime, LowMass, HighMass, InstrumentCount,
InstrumentModel, InstrumentName, SerialNumber, SoftwareVersion,
HardwareVersion, RawFileVersion, InstrumentUnits, Comment, SampleId,
SampleName, SampleType, SampleWeight, SampleVolume, Barcode, RowNumber, Vial,
InjectionVolume, DilutionFactor, IstdAmount, CalibrationLevel,
InstrumentMethodFile, CalibrationFile, ProcessingMethodFile, UserText0,
UserText1, UserText2, UserText3, UserText4
→ scans (11): uidx, scan.no, time.min, tic, it.ms, resolution, microscans,
basePeakMz, basePeakIntensity, lowMass, highMass, rawOvFtT, intensCompFactor,
agc, agcTarget, numberLockmassesFound, analyzerTemperature; (not aggregated:
IsCentroidScan, ScanType, Scan Description, Multiple Injection, Multi Inject
Info, Scan Segment, Scan Event, Master Index, Master Scan Number, Charge State,
Monoisotopic M/Z, Error in isotopic envelope fit, Max. Ion Time (ms), MS2
Isolation Width, MS2 Isolation Offset, HCD Energy, HCD Energy V, === Mass
Calibration: ===, Conversion Parameter B, Conversion Parameter C, Temperature
Comp. (ppm), RF Comp. (ppm), Space Charge Comp. (ppm), Resolution Comp. (ppm),
Number of Lock Masses, Lock Mass #1 (m/z), Lock Mass #2 (m/z), Lock Mass #3
(m/z), LM Search Window (ppm), LM Search Window (mmu), Last Locking (sec), LM
m/z-Correction (ppm), === Ion Optics Settings: ===, S-Lens RF Level, ====
Diagnostic Data: ====, Application Mode, Mild Trapping Mode, APD, Res. Dep.
Intens, Q Trans Comp, PrOSA NumF, PrOSA Comp, PrOSA ScScr, Dynamic RT Shift
(min), Analytical OT usage (%), LC FWHM parameter, PS Inj. Time (ms), AGC PS
Mode, AGC PS Diag, AGC Target Adjust, AGC Diag 1, AGC Diag 2, HCD abs. Offset,
Source CID eV, AGC Fill, Injection t0, t0 FLP, Iso Para R, Inj Para R, Access
Id, Analog In A (V), Analog In B (V), FAIMS Attached, FAIMS Voltage On, FAIMS
CV)
→ peaks (138): uidx, scan.no, mzMeasured, intensity, baseline, peakNoise,
peakResolution, isRefPeak, isLockPeak
→ spectra (943): uidx, scan.no, mz, intensity
→ problems: has no issues

Optional: use a different aggregator

The minimal aggregator contains a smaller set of columns to aggregate. The extended aggregator is more elaborate, providing access to additional columns from the raw data files.

# example: minimal vs. extended aggregator
orbi_get_aggregator("minimal")
────────────────────────────── Aggregator minimal ──────────────────────────────
Dataset file_info:
 → filename = as.character(sub(FileName, pattern = ".raw", replacement = "",
fixed = TRUE))
 → creation_date = as.POSIXct(CreationDate)
 → in_aquisition = as.logical(InAquisition)
Dataset scans:
 → scan.no = as.integer(scan.no)
 → time.min = as.numeric(StartTime)
 → tic = as.numeric(TIC)
 → it.ms = as.numeric(`Ion Injection Time (ms)`)
 → resolution = as.numeric(one_of(`FT Resolution`, `Orbitrap Resolution`))
 → microscans = as.integer(`Micro Scan Count`)
Dataset peaks:
 → scan.no = as.integer(scan.no)
 → mzMeasured = as.numeric(mass)
 → intensity = as.numeric(intensity)
 → baseline = as.numeric(baseline)
 → peakNoise = as.numeric(noise)
 → peakResolution = as.numeric(resolution)
 → isRefPeak = as.logical(is_ref)
 → isLockPeak = as.logical(is_lock_peak)
Dataset spectra:
 → scan.no = as.integer(scan.no)
 → mz = as.numeric(mass)
 → intensity = as.numeric(intensity)
orbi_get_aggregator("extended")
────────────────────────────── Aggregator extended ─────────────────────────────
Dataset file_info:
 → filename = as.character(sub(FileName, pattern = ".raw", replacement = "",
fixed = TRUE))
 → creation_date = as.POSIXct(CreationDate)
 → in_aquisition = as.logical(InAquisition)
 → (.*) = as.character(all_matches("(.*)"))
Dataset scans:
 → scan.no = as.integer(scan.no)
 → time.min = as.numeric(StartTime)
 → tic = as.numeric(TIC)
 → it.ms = as.numeric(`Ion Injection Time (ms)`)
 → resolution = as.numeric(one_of(`FT Resolution`, `Orbitrap Resolution`))
 → microscans = as.integer(`Micro Scan Count`)
 → basePeakMz = as.numeric(BasePeakMass)
 → basePeakIntensity = as.numeric(BasePeakIntensity)
 → lowMass = as.numeric(LowMass)
 → highMass = as.numeric(HighMass)
 → rawOvFtT = as.numeric(RawOvFtT)
 → intensCompFactor = as.numeric(`OT Intens Comp Factor`)
 → agc = as.character(AGC)
 → agcTarget = as.integer(`AGC Target`)
 → numberLockmassesFound = as.integer(`Number of LM Found`)
 → analyzerTemperature = as.numeric(`Analyzer Temperature`)
 → (.*) = as.character(all_matches("(.*)"))
Dataset peaks:
 → scan.no = as.integer(scan.no)
 → mzMeasured = as.numeric(mass)
 → intensity = as.numeric(intensity)
 → baseline = as.numeric(baseline)
 → peakNoise = as.numeric(noise)
 → peakResolution = as.numeric(resolution)
 → isRefPeak = as.logical(is_ref)
 → isLockPeak = as.logical(is_lock_peak)
Dataset spectra:
 → scan.no = as.integer(scan.no)
 → mz = as.numeric(mass)
 → intensity = as.numeric(intensity)
# using the extended aggregator instead of the default (standard)
raw_files |> orbi_aggregate_raw(aggregator = "extended")
✔ [298ms] orbi_aggregate_raw() aggregated file_info (2), scans (11), peaks
(138), and spectra (943) from 2 files using the extended aggregator
─────── aggregated data from 2 raw files - retrieve with orbi_get_data() ───────
→ file_info (2): uidx, filepath, filename, creation_date, in_aquisition,
Operator, FileDescription, MassResolution, SpectraCount, FirstSpectrum,
LastSpectrum, StartTime, EndTime, LowMass, HighMass, InstrumentCount,
InstrumentModel, InstrumentName, SerialNumber, SoftwareVersion,
HardwareVersion, RawFileVersion, InstrumentUnits, Comment, SampleId,
SampleName, SampleType, SampleWeight, SampleVolume, Barcode, RowNumber, Vial,
InjectionVolume, DilutionFactor, IstdAmount, CalibrationLevel,
InstrumentMethodFile, CalibrationFile, ProcessingMethodFile, UserText0,
UserText1, UserText2, UserText3, UserText4
→ scans (11): uidx, scan.no, time.min, tic, it.ms, resolution, microscans,
basePeakMz, basePeakIntensity, lowMass, highMass, rawOvFtT, intensCompFactor,
agc, agcTarget, numberLockmassesFound, analyzerTemperature, IsCentroidScan,
ScanType, Scan Description, Multiple Injection, Multi Inject Info, Scan
Segment, Scan Event, Master Index, Master Scan Number, Charge State,
Monoisotopic M/Z, Error in isotopic envelope fit, Max. Ion Time (ms), MS2
Isolation Width, MS2 Isolation Offset, HCD Energy, HCD Energy V, === Mass
Calibration: ===, Conversion Parameter B, Conversion Parameter C, Temperature
Comp. (ppm), RF Comp. (ppm), Space Charge Comp. (ppm), Resolution Comp. (ppm),
Number of Lock Masses, Lock Mass #1 (m/z), Lock Mass #2 (m/z), Lock Mass #3
(m/z), LM Search Window (ppm), LM Search Window (mmu), Last Locking (sec), LM
m/z-Correction (ppm), === Ion Optics Settings: ===, S-Lens RF Level, ====
Diagnostic Data: ====, Application Mode, Mild Trapping Mode, APD, Res. Dep.
Intens, Q Trans Comp, PrOSA NumF, PrOSA Comp, PrOSA ScScr, Dynamic RT Shift
(min), Analytical OT usage (%), LC FWHM parameter, PS Inj. Time (ms), AGC PS
Mode, AGC PS Diag, AGC Target Adjust, AGC Diag 1, AGC Diag 2, HCD abs. Offset,
Source CID eV, AGC Fill, Injection t0, t0 FLP, Iso Para R, Inj Para R, Access
Id, Analog In A (V), Analog In B (V), FAIMS Attached, FAIMS Voltage On, FAIMS
CV
→ peaks (138): uidx, scan.no, mzMeasured, intensity, baseline, peakNoise,
peakResolution, isRefPeak, isLockPeak
→ spectra (943): uidx, scan.no, mz, intensity
→ problems: has no issues

Optional: check for problems

There were no problems reading and/or aggregating the raw data so these are empty.

raw_files |> orbi_get_problems()
# A tibble: 0 × 6
# ℹ 6 variables: uidx <int>, file <chr>, type <chr>, call <chr>, message <chr>,
#   condition <list>
agg_data |> orbi_get_problems()
# A tibble: 0 × 6
# ℹ 6 variables: uidx <int>, file <chr>, type <chr>, call <chr>, message <chr>,
#   condition <list>

Identify isotopocules

# list of isotopocules (can alternatively be in a tsv/csv/xlsx file)
isotopocules <- tibble(
    compound = "nitrate",
    isotopolog = c("M0", "15N", "17O", "18O"),
    mass = c(61.9878, 62.9850, 62.9922, 63.9922),
    tolerance = 1,
    charge = 1
  )

# identify
data <- agg_data |> orbi_identify_isotopocules(isotopocules)
✔ [12ms] orbi_identify_isotopocules() identified 44/138 peaks (32%)
representing 100% of the total ion current (TIC) as isotopocules M0, 15N, 17O,
and 18O

Check satellite peaks

# this can happen here or later on in the workflow
# in the case of these files there are no satellite peaks
data |> orbi_flag_satellite_peaks() |> orbi_plot_satellite_peaks()
✔ [4ms] orbi_flag_satellite_peaks() confirmed there are no satellite peaks
`geom_line()`: Each group consists of only one observation.
ℹ Do you need to adjust the group aesthetic?

Check coverage

# this can happen here or later on in the workflow
data |> orbi_get_isotopocule_coverage()
# A tibble: 8 × 10
   uidx filename        compound isotopocule data_stretch n_points start_scan.no
  <int> <fct>           <fct>    <fct>              <int>    <int>         <int>
1     1 nitrate_test_1… nitrate  M0                     0       10             1
2     1 nitrate_test_1… nitrate  15N                    0       10             1
3     1 nitrate_test_1… nitrate  17O                    0       10             1
4     1 nitrate_test_1… nitrate  18O                    0       10             1
5     2 nitrate_test_1… nitrate  M0                     0        1             1
6     2 nitrate_test_1… nitrate  15N                    0        1             1
7     2 nitrate_test_1… nitrate  17O                    0        1             1
8     2 nitrate_test_1… nitrate  18O                    0        1             1
# ℹ 3 more variables: end_scan.no <int>, start_time.min <dbl>,
#   end_time.min <dbl>
data |> orbi_plot_isotopocule_coverage()

Retrieve (get) data

agg_data |> orbi_get_data(peaks = everything())
✔ [4ms] orbi_get_data() retrieved 138 records from the combination of file_info
(2) and peaks (138) via uidx
# A tibble: 138 × 10
    uidx filename scan.no mzMeasured intensity baseline peakNoise peakResolution
   <int> <chr>      <int>      <dbl>     <dbl>    <dbl>     <dbl>          <dbl>
 1     1 nitrate…       1       62.0     1211.     8.32      513.          70900
 2     1 nitrate…       1       62.0     1463.     8.32      513.          94100
 3     1 nitrate…       1       62.0     1172.     8.31      513.          80300
 4     1 nitrate…       1       62.0     1116.     8.30      513.          87900
 5     1 nitrate…       1       62.0  4046979      8.28      513.         114902
 6     1 nitrate…       1       62.0     1798.     8.26      513.          86300
 7     1 nitrate…       1       62.0     1444.     8.26      513.          93200
 8     1 nitrate…       1       62.0     1346.     8.25      513.          84700
 9     1 nitrate…       1       62.0     1469.     8.25      513.          92400
10     1 nitrate…       1       62.1     1043.     8.16      513.          89900
# ℹ 128 more rows
# ℹ 2 more variables: isRefPeak <lgl>, isLockPeak <lgl>