# 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

    ──────────────── [1m2 raw files - combine with orbi_aggregate_raw()[22m ───────────────

    1. [34mnitrate_test_10scans.raw[39m has 10 [32mscans[39m with 126 [32mpeaks[39m; + loaded 2 [32mspectra[39m
    (618 points)
    2. [34mnitrate_test_1scan.raw[39m   has  1 [32mscans[39m with  12 [32mpeaks[39m; + loaded 1 [32mspectrum[39m
    (325 points)

# Combine (aggregate) data

    # aggregate raw data
    agg_data <- raw_files |> orbi_aggregate_raw()

    [32m✔[39m [38;5;249m[172ms][39m [1morbi_aggregate_raw()[22m aggregated [34mfile_info[39m (2), [34mscans[39m (11), [34mpeaks[39m
    (138), and [34mspectra[39m (943) from 2 files using the [1m[3mstandard[23m[22m aggregator

    agg_data

    ─────── [1maggregated data from 2 raw files - retrieve with orbi_get_data()[22m ───────

    → [34mfile_info[39m (2): [32muidx[39m, [32mfilepath[39m, [32mfilename[39m, [32mcreation_date[39m, [32min_aquisition[39m,
    [32mOperator[39m, [32mFileDescription[39m, [32mMassResolution[39m, [32mSpectraCount[39m, [32mFirstSpectrum[39m,
    [32mLastSpectrum[39m, [32mStartTime[39m, [32mEndTime[39m, [32mLowMass[39m, [32mHighMass[39m, [32mInstrumentCount[39m,
    [32mInstrumentModel[39m, [32mInstrumentName[39m, [32mSerialNumber[39m, [32mSoftwareVersion[39m,
    [32mHardwareVersion[39m, [32mRawFileVersion[39m, [32mInstrumentUnits[39m, [32mComment[39m, [32mSampleId[39m,
    [32mSampleName[39m, [32mSampleType[39m, [32mSampleWeight[39m, [32mSampleVolume[39m, [32mBarcode[39m, [32mRowNumber[39m, [32mVial[39m,
    [32mInjectionVolume[39m, [32mDilutionFactor[39m, [32mIstdAmount[39m, [32mCalibrationLevel[39m,
    [32mInstrumentMethodFile[39m, [32mCalibrationFile[39m, [32mProcessingMethodFile[39m, [32mUserText0[39m,
    [32mUserText1[39m, [32mUserText2[39m, [32mUserText3[39m, [32mUserText4[39m

    → [34mscans[39m (11): [32muidx[39m, [32mscan.no[39m, [32mtime.min[39m, [32mtic[39m, [32mit.ms[39m, [32mresolution[39m, [32mmicroscans[39m,
    [32mbasePeakMz[39m, [32mbasePeakIntensity[39m, [32mlowMass[39m, [32mhighMass[39m, [32mrawOvFtT[39m, [32mintensCompFactor[39m,
    [32magc[39m, [32magcTarget[39m, [32mnumberLockmassesFound[39m, [32manalyzerTemperature[39m; ([3mnot aggregated[23m:
    [3m[33mIsCentroidScan[39m[23m, [3m[33mScanType[39m[23m, [3m[33mScan Description[39m[23m, [3m[33mMultiple Injection[39m[23m, [3m[33mMulti Inject[39m[23m
    [3m[33mInfo[39m[23m, [3m[33mScan Segment[39m[23m, [3m[33mScan Event[39m[23m, [3m[33mMaster Index[39m[23m, [3m[33mMaster Scan Number[39m[23m, [3m[33mCharge State[39m[23m,
    [3m[33mMonoisotopic M/Z[39m[23m, [3m[33mError in isotopic envelope fit[39m[23m, [3m[33mMax. Ion Time (ms)[39m[23m, [3m[33mMS2[39m[23m
    [3m[33mIsolation Width[39m[23m, [3m[33mMS2 Isolation Offset[39m[23m, [3m[33mHCD Energy[39m[23m, [3m[33mHCD Energy V[39m[23m, [3m[33m=== Mass[39m[23m
    [3m[33mCalibration: ===[39m[23m, [3m[33mConversion Parameter B[39m[23m, [3m[33mConversion Parameter C[39m[23m, [3m[33mTemperature[39m[23m
    [3m[33mComp. (ppm)[39m[23m, [3m[33mRF Comp. (ppm)[39m[23m, [3m[33mSpace Charge Comp. (ppm)[39m[23m, [3m[33mResolution Comp. (ppm)[39m[23m,
    [3m[33mNumber of Lock Masses[39m[23m, [3m[33mLock Mass #1 (m/z)[39m[23m, [3m[33mLock Mass #2 (m/z)[39m[23m, [3m[33mLock Mass #3[39m[23m
    [3m[33m(m/z)[39m[23m, [3m[33mLM Search Window (ppm)[39m[23m, [3m[33mLM Search Window (mmu)[39m[23m, [3m[33mLast Locking (sec)[39m[23m, [3m[33mLM[39m[23m
    [3m[33mm/z-Correction (ppm)[39m[23m, [3m[33m=== Ion Optics Settings: ===[39m[23m, [3m[33mS-Lens RF Level[39m[23m, [3m[33m====[39m[23m
    [3m[33mDiagnostic Data: ====[39m[23m, [3m[33mApplication Mode[39m[23m, [3m[33mMild Trapping Mode[39m[23m, [3m[33mAPD[39m[23m, [3m[33mRes. Dep.[39m[23m
    [3m[33mIntens[39m[23m, [3m[33mQ Trans Comp[39m[23m, [3m[33mPrOSA NumF[39m[23m, [3m[33mPrOSA Comp[39m[23m, [3m[33mPrOSA ScScr[39m[23m, [3m[33mDynamic RT Shift[39m[23m
    [3m[33m(min)[39m[23m, [3m[33mAnalytical OT usage (%)[39m[23m, [3m[33mLC FWHM parameter[39m[23m, [3m[33mPS Inj. Time (ms)[39m[23m, [3m[33mAGC PS[39m[23m
    [3m[33mMode[39m[23m, [3m[33mAGC PS Diag[39m[23m, [3m[33mAGC Target Adjust[39m[23m, [3m[33mAGC Diag 1[39m[23m, [3m[33mAGC Diag 2[39m[23m, [3m[33mHCD abs. Offset[39m[23m,
    [3m[33mSource CID eV[39m[23m, [3m[33mAGC Fill[39m[23m, [3m[33mInjection t0[39m[23m, [3m[33mt0 FLP[39m[23m, [3m[33mIso Para R[39m[23m, [3m[33mInj Para R[39m[23m, [3m[33mAccess[39m[23m
    [3m[33mId[39m[23m, [3m[33mAnalog In A (V)[39m[23m, [3m[33mAnalog In B (V)[39m[23m, [3m[33mFAIMS Attached[39m[23m, [3m[33mFAIMS Voltage On[39m[23m, [3m[33mFAIMS[39m[23m
    [3m[33mCV[39m[23m)

    → [34mpeaks[39m (138): [32muidx[39m, [32mscan.no[39m, [32mmzMeasured[39m, [32mintensity[39m, [32mbaseline[39m, [32mpeakNoise[39m,
    [32mpeakResolution[39m, [32misRefPeak[39m, [32misLockPeak[39m

    → [34mspectra[39m (943): [32muidx[39m, [32mscan.no[39m, [32mmz[39m, [32mintensity[39m

    → [34mproblems[39m: has [32mno issues[39m

## 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")

    ────────────────────────────── [1mAggregator [3mminimal[23m[22m ──────────────────────────────

    [1mDataset[22m [34mfile_info[39m:
     → [32mfilename[39m = [3mas.character(sub(FileName, pattern = ".raw", replacement = "",[23m
    [3mfixed = TRUE))[23m
     → [32mcreation_date[39m = [3mas.POSIXct(CreationDate)[23m
     → [32min_aquisition[39m = [3mas.logical(InAquisition)[23m
    [1mDataset[22m [34mscans[39m:
     → [32mscan.no[39m = [3mas.integer(scan.no)[23m
     → [32mtime.min[39m = [3mas.numeric(StartTime)[23m
     → [32mtic[39m = [3mas.numeric(TIC)[23m
     → [32mit.ms[39m = [3mas.numeric(`Ion Injection Time (ms)`)[23m
     → [32mresolution[39m = [3mas.numeric(one_of(`FT Resolution`, `Orbitrap Resolution`))[23m
     → [32mmicroscans[39m = [3mas.integer(`Micro Scan Count`)[23m
    [1mDataset[22m [34mpeaks[39m:
     → [32mscan.no[39m = [3mas.integer(scan.no)[23m
     → [32mmzMeasured[39m = [3mas.numeric(mass)[23m
     → [32mintensity[39m = [3mas.numeric(intensity)[23m
     → [32mbaseline[39m = [3mas.numeric(baseline)[23m
     → [32mpeakNoise[39m = [3mas.numeric(noise)[23m
     → [32mpeakResolution[39m = [3mas.numeric(resolution)[23m
     → [32misRefPeak[39m = [3mas.logical(is_ref)[23m
     → [32misLockPeak[39m = [3mas.logical(is_lock_peak)[23m
    [1mDataset[22m [34mspectra[39m:
     → [32mscan.no[39m = [3mas.integer(scan.no)[23m
     → [32mmz[39m = [3mas.numeric(mass)[23m
     → [32mintensity[39m = [3mas.numeric(intensity)[23m

    orbi_get_aggregator("extended")

    ────────────────────────────── [1mAggregator [3mextended[23m[22m ─────────────────────────────

    [1mDataset[22m [34mfile_info[39m:
     → [32mfilename[39m = [3mas.character(sub(FileName, pattern = ".raw", replacement = "",[23m
    [3mfixed = TRUE))[23m
     → [32mcreation_date[39m = [3mas.POSIXct(CreationDate)[23m
     → [32min_aquisition[39m = [3mas.logical(InAquisition)[23m
     → [35m(.*)[39m = [3mas.character(all_matches("(.*)"))[23m
    [1mDataset[22m [34mscans[39m:
     → [32mscan.no[39m = [3mas.integer(scan.no)[23m
     → [32mtime.min[39m = [3mas.numeric(StartTime)[23m
     → [32mtic[39m = [3mas.numeric(TIC)[23m
     → [32mit.ms[39m = [3mas.numeric(`Ion Injection Time (ms)`)[23m
     → [32mresolution[39m = [3mas.numeric(one_of(`FT Resolution`, `Orbitrap Resolution`))[23m
     → [32mmicroscans[39m = [3mas.integer(`Micro Scan Count`)[23m
     → [32mbasePeakMz[39m = [3mas.numeric(BasePeakMass)[23m
     → [32mbasePeakIntensity[39m = [3mas.numeric(BasePeakIntensity)[23m
     → [32mlowMass[39m = [3mas.numeric(LowMass)[23m
     → [32mhighMass[39m = [3mas.numeric(HighMass)[23m
     → [32mrawOvFtT[39m = [3mas.numeric(RawOvFtT)[23m
     → [32mintensCompFactor[39m = [3mas.numeric(`OT Intens Comp Factor`)[23m
     → [32magc[39m = [3mas.character(AGC)[23m
     → [32magcTarget[39m = [3mas.integer(`AGC Target`)[23m
     → [32mnumberLockmassesFound[39m = [3mas.integer(`Number of LM Found`)[23m
     → [32manalyzerTemperature[39m = [3mas.numeric(`Analyzer Temperature`)[23m
     → [35m(.*)[39m = [3mas.character(all_matches("(.*)"))[23m
    [1mDataset[22m [34mpeaks[39m:
     → [32mscan.no[39m = [3mas.integer(scan.no)[23m
     → [32mmzMeasured[39m = [3mas.numeric(mass)[23m
     → [32mintensity[39m = [3mas.numeric(intensity)[23m
     → [32mbaseline[39m = [3mas.numeric(baseline)[23m
     → [32mpeakNoise[39m = [3mas.numeric(noise)[23m
     → [32mpeakResolution[39m = [3mas.numeric(resolution)[23m
     → [32misRefPeak[39m = [3mas.logical(is_ref)[23m
     → [32misLockPeak[39m = [3mas.logical(is_lock_peak)[23m
    [1mDataset[22m [34mspectra[39m:
     → [32mscan.no[39m = [3mas.integer(scan.no)[23m
     → [32mmz[39m = [3mas.numeric(mass)[23m
     → [32mintensity[39m = [3mas.numeric(intensity)[23m

    # using the extended aggregator instead of the default (standard)
    raw_files |> orbi_aggregate_raw(aggregator = "extended")

    [32m✔[39m [38;5;249m[298ms][39m [1morbi_aggregate_raw()[22m aggregated [34mfile_info[39m (2), [34mscans[39m (11), [34mpeaks[39m
    (138), and [34mspectra[39m (943) from 2 files using the [1m[3mextended[23m[22m aggregator

    ─────── [1maggregated data from 2 raw files - retrieve with orbi_get_data()[22m ───────

    → [34mfile_info[39m (2): [32muidx[39m, [32mfilepath[39m, [32mfilename[39m, [32mcreation_date[39m, [32min_aquisition[39m,
    [32mOperator[39m, [32mFileDescription[39m, [32mMassResolution[39m, [32mSpectraCount[39m, [32mFirstSpectrum[39m,
    [32mLastSpectrum[39m, [32mStartTime[39m, [32mEndTime[39m, [32mLowMass[39m, [32mHighMass[39m, [32mInstrumentCount[39m,
    [32mInstrumentModel[39m, [32mInstrumentName[39m, [32mSerialNumber[39m, [32mSoftwareVersion[39m,
    [32mHardwareVersion[39m, [32mRawFileVersion[39m, [32mInstrumentUnits[39m, [32mComment[39m, [32mSampleId[39m,
    [32mSampleName[39m, [32mSampleType[39m, [32mSampleWeight[39m, [32mSampleVolume[39m, [32mBarcode[39m, [32mRowNumber[39m, [32mVial[39m,
    [32mInjectionVolume[39m, [32mDilutionFactor[39m, [32mIstdAmount[39m, [32mCalibrationLevel[39m,
    [32mInstrumentMethodFile[39m, [32mCalibrationFile[39m, [32mProcessingMethodFile[39m, [32mUserText0[39m,
    [32mUserText1[39m, [32mUserText2[39m, [32mUserText3[39m, [32mUserText4[39m

    → [34mscans[39m (11): [32muidx[39m, [32mscan.no[39m, [32mtime.min[39m, [32mtic[39m, [32mit.ms[39m, [32mresolution[39m, [32mmicroscans[39m,
    [32mbasePeakMz[39m, [32mbasePeakIntensity[39m, [32mlowMass[39m, [32mhighMass[39m, [32mrawOvFtT[39m, [32mintensCompFactor[39m,
    [32magc[39m, [32magcTarget[39m, [32mnumberLockmassesFound[39m, [32manalyzerTemperature[39m, [32mIsCentroidScan[39m,
    [32mScanType[39m, [32mScan Description[39m, [32mMultiple Injection[39m, [32mMulti Inject Info[39m, [32mScan[39m
    [32mSegment[39m, [32mScan Event[39m, [32mMaster Index[39m, [32mMaster Scan Number[39m, [32mCharge State[39m,
    [32mMonoisotopic M/Z[39m, [32mError in isotopic envelope fit[39m, [32mMax. Ion Time (ms)[39m, [32mMS2[39m
    [32mIsolation Width[39m, [32mMS2 Isolation Offset[39m, [32mHCD Energy[39m, [32mHCD Energy V[39m, [32m=== Mass[39m
    [32mCalibration: ===[39m, [32mConversion Parameter B[39m, [32mConversion Parameter C[39m, [32mTemperature[39m
    [32mComp. (ppm)[39m, [32mRF Comp. (ppm)[39m, [32mSpace Charge Comp. (ppm)[39m, [32mResolution Comp. (ppm)[39m,
    [32mNumber of Lock Masses[39m, [32mLock Mass #1 (m/z)[39m, [32mLock Mass #2 (m/z)[39m, [32mLock Mass #3[39m
    [32m(m/z)[39m, [32mLM Search Window (ppm)[39m, [32mLM Search Window (mmu)[39m, [32mLast Locking (sec)[39m, [32mLM[39m
    [32mm/z-Correction (ppm)[39m, [32m=== Ion Optics Settings: ===[39m, [32mS-Lens RF Level[39m, [32m====[39m
    [32mDiagnostic Data: ====[39m, [32mApplication Mode[39m, [32mMild Trapping Mode[39m, [32mAPD[39m, [32mRes. Dep.[39m
    [32mIntens[39m, [32mQ Trans Comp[39m, [32mPrOSA NumF[39m, [32mPrOSA Comp[39m, [32mPrOSA ScScr[39m, [32mDynamic RT Shift[39m
    [32m(min)[39m, [32mAnalytical OT usage (%)[39m, [32mLC FWHM parameter[39m, [32mPS Inj. Time (ms)[39m, [32mAGC PS[39m
    [32mMode[39m, [32mAGC PS Diag[39m, [32mAGC Target Adjust[39m, [32mAGC Diag 1[39m, [32mAGC Diag 2[39m, [32mHCD abs. Offset[39m,
    [32mSource CID eV[39m, [32mAGC Fill[39m, [32mInjection t0[39m, [32mt0 FLP[39m, [32mIso Para R[39m, [32mInj Para R[39m, [32mAccess[39m
    [32mId[39m, [32mAnalog In A (V)[39m, [32mAnalog In B (V)[39m, [32mFAIMS Attached[39m, [32mFAIMS Voltage On[39m, [32mFAIMS[39m
    [32mCV[39m

    → [34mpeaks[39m (138): [32muidx[39m, [32mscan.no[39m, [32mmzMeasured[39m, [32mintensity[39m, [32mbaseline[39m, [32mpeakNoise[39m,
    [32mpeakResolution[39m, [32misRefPeak[39m, [32misLockPeak[39m

    → [34mspectra[39m (943): [32muidx[39m, [32mscan.no[39m, [32mmz[39m, [32mintensity[39m

    → [34mproblems[39m: has [32mno issues[39m

## Optional: check for problems

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

    raw_files |> orbi_get_problems()

    [38;5;246m# A tibble: 0 × 6[39m
    [38;5;246m# ℹ 6 variables: uidx <int>, file <chr>, type <chr>, call <chr>, message <chr>,[39m
    [38;5;246m#   condition <list>[39m

    agg_data |> orbi_get_problems()

    [38;5;246m# A tibble: 0 × 6[39m
    [38;5;246m# ℹ 6 variables: uidx <int>, file <chr>, type <chr>, call <chr>, message <chr>,[39m
    [38;5;246m#   condition <list>[39m

# 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)

    [32m✔[39m [38;5;249m[12ms][39m [1morbi_identify_isotopocules()[22m identified 44/138 peaks (32%)
    representing 100% of the total ion current (TIC) as isotopocules [32mM0[39m, [32m15N[39m, [32m17O[39m,
    and [32m18O[39m

# 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()

    [32m✔[39m [38;5;249m[4ms][39m [1morbi_flag_satellite_peaks()[22m confirmed there are no [33msatellite[39m peaks

    [1m[22m`geom_line()`: Each group consists of only one observation.
    [36mℹ[39m Do you need to adjust the [32mgroup[39m aesthetic?

# Check coverage

    # this can happen here or later on in the workflow
    data |> orbi_get_isotopocule_coverage()

    [38;5;246m# A tibble: 8 × 10[39m
       uidx filename        compound isotopocule data_stretch n_points start_scan.no
      [3m[38;5;246m<int>[39m[23m [3m[38;5;246m<fct>[39m[23m           [3m[38;5;246m<fct>[39m[23m    [3m[38;5;246m<fct>[39m[23m              [3m[38;5;246m<int>[39m[23m    [3m[38;5;246m<int>[39m[23m         [3m[38;5;246m<int>[39m[23m
    [38;5;250m1[39m     1 nitrate_test_1… nitrate  M0                     0       10             1
    [38;5;250m2[39m     1 nitrate_test_1… nitrate  15N                    0       10             1
    [38;5;250m3[39m     1 nitrate_test_1… nitrate  17O                    0       10             1
    [38;5;250m4[39m     1 nitrate_test_1… nitrate  18O                    0       10             1
    [38;5;250m5[39m     2 nitrate_test_1… nitrate  M0                     0        1             1
    [38;5;250m6[39m     2 nitrate_test_1… nitrate  15N                    0        1             1
    [38;5;250m7[39m     2 nitrate_test_1… nitrate  17O                    0        1             1
    [38;5;250m8[39m     2 nitrate_test_1… nitrate  18O                    0        1             1
    [38;5;246m# ℹ 3 more variables: end_scan.no <int>, start_time.min <dbl>,[39m
    [38;5;246m#   end_time.min <dbl>[39m

    data |> orbi_plot_isotopocule_coverage()

# Retrieve (get) data

    agg_data |> orbi_get_data(peaks = everything())

    [32m✔[39m [38;5;249m[4ms][39m [1morbi_get_data()[22m retrieved 138 records from the combination of [34mfile_info[39m
    (2) and [34mpeaks[39m (138) via [32muidx[39m

    [38;5;246m# A tibble: 138 × 10[39m
        uidx filename scan.no mzMeasured intensity baseline peakNoise peakResolution
       [3m[38;5;246m<int>[39m[23m [3m[38;5;246m<chr>[39m[23m      [3m[38;5;246m<int>[39m[23m      [3m[38;5;246m<dbl>[39m[23m     [3m[38;5;246m<dbl>[39m[23m    [3m[38;5;246m<dbl>[39m[23m     [3m[38;5;246m<dbl>[39m[23m          [3m[38;5;246m<dbl>[39m[23m
    [38;5;250m 1[39m     1 nitrate…       1       62.0     [4m1[24m211.     8.32      513.          [4m7[24m[4m0[24m900
    [38;5;250m 2[39m     1 nitrate…       1       62.0     [4m1[24m463.     8.32      513.          [4m9[24m[4m4[24m100
    [38;5;250m 3[39m     1 nitrate…       1       62.0     [4m1[24m172.     8.31      513.          [4m8[24m[4m0[24m300
    [38;5;250m 4[39m     1 nitrate…       1       62.0     [4m1[24m116.     8.30      513.          [4m8[24m[4m7[24m900
    [38;5;250m 5[39m     1 nitrate…       1       62.0  4[4m0[24m[4m4[24m[4m6[24m979      8.28      513.         [4m1[24m[4m1[24m[4m4[24m902
    [38;5;250m 6[39m     1 nitrate…       1       62.0     [4m1[24m798.     8.26      513.          [4m8[24m[4m6[24m300
    [38;5;250m 7[39m     1 nitrate…       1       62.0     [4m1[24m444.     8.26      513.          [4m9[24m[4m3[24m200
    [38;5;250m 8[39m     1 nitrate…       1       62.0     [4m1[24m346.     8.25      513.          [4m8[24m[4m4[24m700
    [38;5;250m 9[39m     1 nitrate…       1       62.0     [4m1[24m469.     8.25      513.          [4m9[24m[4m2[24m400
    [38;5;250m10[39m     1 nitrate…       1       62.1     [4m1[24m043.     8.16      513.          [4m8[24m[4m9[24m900
    [38;5;246m# ℹ 128 more rows[39m
    [38;5;246m# ℹ 2 more variables: isRefPeak <lgl>, isLockPeak <lgl>[39m