Skip to contents

Changelog

Source: NEWS.md

isoorbi 1.6.0

This release switches to version 0.3 of the isoraw raw file reader, which changes how peak flags are reported and which peaks are read by default.

Breaking changes

  • the isoraw raw file reader now requires version 0.3.0 or later (orbi_check_isoraw() upgrades automatically). Version 0.3 no longer reports the is_ref and is_lock_peak columns and instead reports the raw Thermo PeakOptions bitmask in a flags column, from which these and every other flag can be derived.
  • version 0.3 of the reader also reads all peaks by default, including the ones the centroider flagged as problematic (saturated, fragmented, merged, exception, modified). Previously these were silently discarded during the read, so expect noticeably more peaks than before - for the example file bundled with the package the peak count goes from 126 to 307. Filter them out after aggregation (see below) if you do not want them.
  • as a result of the above, the peaks dataset of the aggregators now provides a readable centroiderFlags column (a factor with values such as "none", "reference" or "exception + fragmented") instead of the previous isRefPeak and isLockPeak columns. The name makes clear that these flags come from the instrument’s centroider, as opposed to the peaks isoorbi itself flags later on (satellite peaks, weak isotopocules and outliers).
  • orbi_define_block_for_flow_injection() is deprecated in favor of the new orbi_define_blocks(), which is not specific to flow injection and can define several blocks at once. The old function still works, warns, and forwards to the new one.
  • orbi_adjust_block() is deprecated in favor of the new orbi_adjust_blocks(), which can adjust several blocks at once and identifies the file with in_filename instead of filename (like orbi_define_blocks()). The old function still works, warns (once every 8 hours), and forwards to the new one.
  • the sample_name column created by the block definition functions (orbi_define_blocks_for_dual_inlet(), orbi_define_block_for_flow_injection() and orbi_adjust_block()) is now called block_name to reflect that it names the block rather than necessarily a sample. The sample_name argument of orbi_define_block_for_flow_injection() is renamed to block_name accordingly - the old argument still works but is deprecated and warns - and orbi_summarize_results() groups by block_name instead of sample_name by default.
  • raw file caches (.raw.cache.zip) created with an earlier version of the reader are detected and the corresponding raw file is read anew (with a warning). If the original .raw file is no longer available next to such a cache, the read reports a cannot find this .raw file problem (see orbi_get_problems()) - copy the .raw file back in or obtain an up to date cache.

New features

  • new status_log dataset with the instrument status log, i.e. the instrument readbacks that are recorded independently of the scans (typically every couple of seconds): ion source and ion optics settings, temperatures (ambient, Orbitrap block, detector, …) and diagnostic data (vacuum pressures, supply voltages, fan and turbopump status, …). It is read by orbi_read_raw() whenever the raw file reader stored one (isoraw 0.3.1+) and is simply empty for files and caches that don’t have one.

    Which channels a status log holds depends entirely on the instrument, so none of the included aggregators take anything from it. The status log is still reported by orbi_aggregate_raw() like every other dataset, with all of its information listed as not aggregated. Aggregate the channels of interest with a custom aggregator, e.g.:

    my_aggregator <- orbi_get_aggregator("standard") |>
  orbi_add_to_aggregator("status_log", "time.min", source = "StartTime", cast = "as.numeric") |>
  orbi_add_to_aggregator(
    "status_log", "ambientTemperature",
    source = "Ambient temp. (°C)", cast = "as.numeric"
  )

raw_files |> orbi_aggregate_raw(aggregator = my_aggregator) |>
  orbi_get_data(status_log = c("time.min", "ambientTemperature"))

  • printing aggregated data variables now only says how many columns of each dataset were not aggregated (instead of listing them) since the status log alone can easily have 200 channels. Use print(agg_data, show_all = TRUE) to list all of them - the printout suggests this code with the name of your variable.

  • new orbi_peak_flags_include() function works with the peak flags. To filter for an exact set of flags, compare the centroiderFlags column directly (it is a factor, so this is fast), e.g. dplyr::filter(peaks, centroiderFlags == "none") keeps only the peaks without any flags and centroiderFlags %in% c("lock peak", "reference") only those that are exclusively either a lock mass or a reference peak. Use orbi_peak_flags_include(centroiderFlags, "reference") on that column to find every peak carrying the reference flag whether or not it carries others.

  • new orbi_adjust_blocks() that replaces orbi_adjust_block() and can adjust multiple blocks at once. The adjustments can be given as vectors (orbi_adjust_blocks(block = c(1, 4), shift_start_time.min = c(2, NA), set_end_time.min = c(NA, 44))) or as a blocks_table data frame with a block column and any of the in_filename, shift_* and set_* columns. Without an in_filename, a block is adjusted in all files that have it. The summary message now also correctly reports which other blocks were shortened or removed entirely by an adjustment (previously, extending a block into the unused scans before it could report the preceding block as removed).

  • new orbi_define_blocks() that replaces orbi_define_block_for_flow_injection() and can define multiple blocks in one call. The block boundaries can be given as vectors (orbi_define_blocks(start_time.min = c(0.1, 0.5), end_time.min = c(0.4, 0.8), block_name = c("first", "second"))) or as a blocks_table data frame with any of the start_time.min, end_time.min, start_scan.no, end_scan.no and block_name columns. Each block is defined either by time or by scan number (they can be mixed between blocks) and the resulting blocks are listed in a summary message. Use Inf for end_time.min or end_scan.no to let a block last until the end of each file. Blocks are added to all files by default, use in_filename (also as a blocks_table column) to add a block only to specific file(s), e.g. orbi_define_blocks(start_time.min = 0.1, end_time.min = 0.4, in_filename = c("file1", "file2")).

  • orbi_check_isoraw() now confirms which reader version is ready for use instead of staying silent when nothing needs to be installed. Set show_version = FALSE to suppress that message (the automatic checks during a raw file read already do).

Restoring the isRefPeak / isLockPeak columns

If you rely on the previous boolean columns, add them back with a custom aggregator:

my_aggregator <- orbi_get_aggregator("standard") |>
  orbi_add_to_aggregator(
    "peaks", "isRefPeak", source = "flags",
    func = "orbi_peak_flags_include", args = list(flag = "reference"),
    cast = "as.logical"
  ) |>
  orbi_add_to_aggregator(
    "peaks", "isLockPeak", source = "flags",
    func = "orbi_peak_flags_include", args = list(flag = "lock peak"),
    cast = "as.logical"
  )

raw_files |> orbi_aggregate_raw(aggregator = my_aggregator)

Register it with my_aggregator |> orbi_register_aggregator("my_aggregator") to be able to refer to it by name in orbi_aggregate_raw().

Bug fixes & improvements

  • fixed orbi_define_blocks_for_dual_inlet() emitting a spurious “Adding missing grouping variables” message from dplyr.
  • fixed time durations in messages rounding up to 60s instead of the next minute (e.g. 43m 60s instead of 44m).
  • orbi_plot_raw_data() no longer tries to draw lines for groups of data (e.g. data groups) that consist of only a single data point, which caused ggplot2’s “Each group consists of only one observation” message. These data points are still shown with show_points = TRUE.
  • new show_points argument for orbi_plot_raw_data() to show the individual data points in addition to the lines connecting them - the new point_size argument sets the size of these points and of the outlier points (by default the ggplot2 default size is used).
  • new use_data_block_names argument for orbi_add_blocks_to_plot() and orbi_plot_raw_data(): set use_data_block_names = TRUE to color code the block backgrounds of the data blocks by their block_name (e.g. reference vs. sample in dual inlet data) instead of showing them all as data. Other blocks (e.g. changeover or unused) are always shown by their data type.
  • time based x-axes in orbi_plot_raw_data(), orbi_plot_satellite_peaks() and orbi_plot_isotopocule_coverage() (x = "time.min") are now labeled as durations with pretty time intervals (e.g. 0:30 min, 1:00 min or 0:20 hours) instead of decimal minutes. The default x_breaks = NULL picks the breaks automatically (use n_x_breaks to change how many) and short_time_labels = TRUE switches to compact labels (e.g. 1:30m), scan number based x-axes are unchanged. The time ranges in the block messages are likewise shown as durations (e.g. 3m to 4m 30s).
  • removed the dependency on the prettyunits package. Large numbers in info messages are now consistently abbreviated (e.g. 12.3k scans with 185k peaks) and pluralized correctly (e.g. 1 scan instead of 1 scans, 4.32k peaks instead of 4.32k peak).
  • fixed the included aggregators only removing a lower case .raw extension from the filename (e.g. s3744.RAW stayed s3744.RAW while dual_inlet.raw became dual_inlet). The extension is now removed in any capitalization and only from the end of the file name.
  • fixed the order of the legends in orbi_add_blocks_to_plot() and orbi_plot_shot_noise(). Without an explicit order ggplot2 does not guarantee a stable sequence, so the same plot could come out with its legends swapped on different operating systems or ggplot2 versions.
  • fixed orbi_plot_spectra() including lock mass peaks with a missing intensity when show_ref_and_lock_peaks = TRUE (an operator precedence issue in the peak selection).
  • documentation is now generated with roxygen2 8.0.0.
  • deprecation warnings now show on every call to a deprecated function or argument instead of only once every 8 hours (this requires lifecycle 1.0.2 or later).

isoorbi 1.5.3

This is a minor update to support the latest version of testthat and address a few small bugs.

Bug fixes & improvements

  • updated snapshots for continuous integration tests to work with testthat 3.3.0
  • changed orbi_export_data_to_excel() to only export file_info and summary by default to avoid uintentionally enormous excel files when exporting large datasets (#106)
  • fixed issue with orbi_define_basepeak() not correctly handling unidentified peaks, they are now automatically filtered out when this function is called (#114)
  • improved error messages in functions that need an isotopocule defintion ifisotopocules have not yet been identified
  • clarified installation instructions

isoorbi 1.5.2

CRAN release: 2025-10-03

This is a minor update to decrease package size for CRAN.

Enhancements

  • added orbi_get_example_files() that can download additional example files to provide easier access to test files for users

isoorbi 1.5.1

This is a minor update to enhance usability.

Enhancements

  • show panel lables in spectral plots, i.e. M+1, M+2, etc. (#93)
  • align x-axes in spectral plots (#98)
  • introduce default_tolerance and default_charge parameters for orbi_identify_isotopocules (#95)
  • automatically calculate ions during orbi_identify_isotopocules
  • provide a stastic of ion counts identified when running orbi_identify_isotopocules (#94)
  • provide more informative error when orbi_read_raw fails because the raw file is still being acquired
  • provide orbi_get_example_files function as a one-point stop to get both system package test files as well as downloadable test files
  • orbi_find_raw now finds both .raw and .RAW extensions (i.e. no longer case-sensitive)

isoorbi 1.5.0

Breaking changes

There are no breaking changes in this release (all changes and new features are backwards compatible).

New features

  • implemented an optimized and expanded raw file reader (isoraw) that is packaged with isoorbi and is used in orbi_read_raw()
  • implemented versatile isotopocule mapping via orbi_identifiy_isotopocule() from csv, tsv, and excel inputs
  • implemented orbi_calculate_ions() to calculate ions from peak intensities and noise with flexible CN and RN parameters
  • implemented orbi_plot_spectra() to plot

Enhancements

  • upgraded all data processing and plotting functions to be compatible with both isox and raw file datasets
  • improved default print outputs for S3 classes used in the package
  • improved package structure documentation
  • expanded orbi_flag_outliers() functionality (contributed by Florian Rubach)

Bug fixes

  • fixed incompatibility with ggplot2 version 4.0.0 (#69)

isoorbi 1.4.0

Breaking changes

There are no breaking changes in this release (all changes and new features are backwards compatible).

New features

  • implemented direct reading and caching of orbitrap IRMS raw files (orbi_read_read()) via the rawrr package
  • use CLI for clearer and more informative info messages for all functions

Enhancements

isoorbi 1.3.1

CRAN release: 2024-08-27

This is a patch containing compatibility updates.

isoorbi 1.3.0

CRAN release: 2023-11-09

This is a minor release adding new features.

Breaking changes

There are no breaking changes in this release (all changes and new features are backwards compatible).

New features

Plotting functions:

Information functions:

Enhancements

Bug Fixes

isoorbi 1.2.0

This is a minor release adding new features.

Breaking changes

There are no breaking changes in this release (all changes and new features are backwards compatible).

New features

Enhancements

  • all loading and utility functions provide more details in the info message about what has been done, what was affected, and how long it took
  • all loading and utility functions catch processing errors and report the information back to the user
  • orbi_read_isox() now can read multiple .isox files at once and includes the .isox filepath in the resulting tibble

Bug fixes

  • data frame groupings introduced in flagging/filtering functions are now removed again at the end of the function

isoorbi 1.1.0

CRAN release: 2023-06-24

This is a minor release adding new features and fixing a few bugs.

Breaking changes

There are no breaking changes in this release (all changes and new features are backwards compatible).

New features

Enhancements

  • removed dependency on stringr
  • implemented native pipe |> (R version requirement increased to 4.1.0) and removed dependency on magrittr
  • added .by parameter for orbi_summarize_results() for option to manually adjust grouping

Bug fixes

  • dplyr changes to joins with explicit multiple argument. multiple now defaults to “all”, and the options of “error” and “warning” are now deprecated in favor of using relationship.