Package 'IsoFishR'

Description

Copies runfiles into the project's ⁠raw/⁠ folder and registers them as new runs, so a project can be built up batch by batch. Each file is read first with the project's import settings. A file that can't be read is not added and is reported, without stopping the rest of the batch. If a file's header doesn't match the import settings (e.g. lines missing after a bad save on the instrument), the start of its data is found automatically and the file is added with a note.

Usage

add_runfiles(
  project,
  paths,
  sample_ids = NULL,
  source_names = basename(paths),
  mode = c("add", "replace")
)

Arguments

Details

Files identical to one already in the project are always skipped. For a file whose name matches a run already in the project but whose content differs (e.g. a re-exported runfile):

• mode = "add" skips it and reports it;

• mode = "replace" gives that run the new file and starts it afresh: its edits (trims, status, flag, comment, changepoint and per-sample settings) and regions are removed. Its run type, reference material and session are kept. The previous file is moved to ⁠raw/removed/⁠ and the replacement is logged.

Value

The updated project. A message summarises what happened; the attribute "import_report" holds one row per file with file, sample_id, result ("added", "replaced", "skipped" or "failed") and detail.

Description

Apply trims and profile direction

Usage

apply_edits(data, edits = NULL)

Arguments

Value

The edited data, sorted by sample and distance.

Description

Measures every run of the primary reference material (mean 87Sr/86Sr of its points after trims and outlier rejection, uncorrected) and fits the correction factor accepted / measured through time within each session, using calibration$fit:

Usage

calibration_model(project)

Arguments

Details

• "regression": a least-squares line through the primary runs' measured means against time (instrument drift); the factor is accepted / predicted. Its uncertainty is the standard error of the regression line at each time (with 2 runs, the runs' own SE).

• "linear": linear interpolation between the primary runs bracketing each point (standard-sample bracketing); constant before the first and after the last primary run of the session.

• "spline": a smoothing spline through the session's primary runs (needs at least 4; with fewer, linear interpolation is used).

• "step": the factor of the most recent primary run ("step forward").

• "mean" (default): one factor per session, the mean of its primary runs.

Value

NULL when no primary reference material is set; otherwise a list with primary, accepted, uncertainty_2s, fit and points (one row per primary run: sample_id, session, time (run midpoint), measured, se, n, factor, u_rel).

Description

Validate settings

Usage

check_settings(settings)

Arguments

Value

settings, invisibly; errors describe the first problem found.

Description

Mass bias is calculated per cycle from the measured 86Sr/88Sr ratio using the exponential law, and applied to the Rb-corrected 87Sr/86Sr ratio. 87Rb is estimated from 85Rb with the natural 85Rb/87Rb ratio, corrected for the same mass bias.

Usage

correct_ratios(data, sr86_sr88_ref = 0.1194, rb85_rb87 = 2.59712)

Arguments

Value

data with added ratio columns. sr87_sr86 is the fully corrected ratio; sr84_sr86_mb is 84Sr/86Sr corrected for mass bias (v1 only reported the uncorrected sr84_sr86).

Description

Creates a project from the example runfiles that come with IsoFishR: five Chinook salmon otolith transects from Putah Creek, California, and one white seabass otolith, measured on a Nu Plasma MC-ICP-MS at UC Davis. It is a quick way to try the app or the package functions without data of your own.

Usage

create_example_project(
  path = file.path(tempfile("IsoFishR_"), "Example_project"),
  user = default_user()
)

Arguments

Details

The project uses the default settings and the "Nu_UCDavis" import preset, with a run speed of 5 um/s as in the example project of IsoFishR v1.

Value

The open project (see open_project()).

Examples

p <- create_example_project()
p
head(summarise_project_samples(p))
close_project(p)

Description

Reference materials IsoFishR recognises in run names, with default accepted 87Sr/86Sr values set by the IsoFishR authors. They are only used to suggest marking runs (see suggest_reference_runs()); the value can be changed when the suggestion is applied, and afterwards under Calibration.

Usage

default_reference_materials()

Value

A tibble with name (also the text looked for in run names) and value.

Description

Settings are a nested list with four sections: sample (metadata that does not affect calculations), import (runfile layout), reduction (data reduction parameters) and regions (default region labels). Projects store them as project.yml; individual samples only store values that differ from these defaults.

Usage

default_settings()

Value

A nested list of settings.

Description

Writes the summary tables to a new time-stamped folder in the project's ⁠exports/⁠ folder, together with export_report.md (a record of the settings, calibration and reference materials). Earlier exports are kept.

Usage

export_project(
  project,
  files = setdiff(EXPORT_FILES, "data"),
  include_excluded = FALSE
)

EXPORT_FILES

Arguments

Details

Files written:

• samples.csv: summarise_project_samples()

• regions.csv: summarise_project_regions()

• changepoints.csv: summarise_project_changepoints()

• settings.csv: project_settings_table()

• profiles.csv: project_profiles(), every point of every profile

• runs.csv: project_runs(), all runs in acquisition order with type and session

• reference_materials.csv and reference_material_summary.csv (when the project has reference material runs): reference_material_results() and summarise_reference_materials()

• export_report.md (always): export_report() as Markdown, a record of the export: all project settings, the calibration method, the primary and secondary reference materials with their number of runs, mean and SD, the sessions, and per-sample setting overrides.

• data.csv (not by default): all reduction columns per point (raw voltages, mass bias, intermediate ratios), for checking the reduction itself.

Value

The path of the export folder, invisibly.

Description

Everything needed to understand and reproduce the exported values, as written to export_report.md by export_project(): the project, IsoFishR version and user; the runs and sessions; the calibration (method, baseline mode, session gap, and for the primary and each secondary reference material its accepted value, number of runs and the mean and SD of its run means before and after correction, overall and per session); all project settings; and the samples with their own setting overrides.

Usage

export_report(
  project,
  files = character(),
  include_excluded = FALSE,
  n_samples = NA_integer_
)

Arguments

Value

A nested list.

Description

Runs changepoint::cpt.mean() on each sample and adds the segment number and segment mean. Segment means are calculated within each sample (v1 pooled samples that shared a segment number).

Usage

find_changepoints(
  data,
  method = "PELT",
  penalty = 5e-05,
  value = "sr87_sr86_value"
)

Arguments

Value

data with cp_segment and cp_mean added (NA where the value is missing).

Description

Lists files with the runfile extension of the import settings in a folder and all its subfolders.

Usage

find_runfiles(dir, import = default_settings()$import)

Arguments

Value

A tibble with path, file, sample_id, folder (relative to dir) and duplicate (TRUE when another file in the folder tree has the same name; such files can't be told apart and are not added).

Description

A preset is a named runfile layout: header and footer lines to skip, the separator, and which column holds each mass and the time. IsoFishR ships with "Nu_UCDavis"; users can save their own presets, which are stored as YAML files in their IsoFishR config folder (import_preset_dir()) and can be shared by copying the file.

Usage

list_import_presets()

get_import_preset(name)

save_import_preset(name, import, description = "", overwrite = FALSE)

delete_import_preset(name)

import_preset_dir()

Arguments

Details

A project records the name of the preset it was set up with, and a full copy of its values, so a project keeps working even where the preset is not installed.

Value

list_import_presets(): a tibble with name, description and builtin.

get_import_preset(): the import settings of the preset, with preset set to its name.

save_import_preset(): the path of the preset file, invisibly.

import_preset_dir(): the folder holding user presets. Set the option isofishr.preset_dir to use a different (e.g. shared) folder.

Description

Reads the ⁠<project>_settings.csv⁠ written by IsoFishR v1 and returns the equivalent v2 settings list.

Usage

import_v1_settings(path)

Arguments

Value

A settings list.

Description

Averages blocks of n consecutive cycles within each sample. A shorter final block is kept. Blocks never span two samples (in v1 they could).

Usage

integrate_cycles(raw, n = 1L)

Arguments

Value

A tibble with one row per block and columns sample_id, time_s, raw88 to raw83 and n_cycles.

Description

Combine settings with overrides

Usage

merge_settings(settings, overrides = list())

Arguments

Value

The combined settings, validated with check_settings().

Description

The 87Sr/86Sr profile of one sample against distance, with the smoothed line and its uncertainty band, rejected outliers, regions and changepoint means, plus strips for total Sr, 83Kr and 85Rb/88Sr below it. Drag along the x axis to select a range.

Usage

profile_plot(
  data,
  regions = NULL,
  show = c("points", "outliers", "ma", "spline", "band", "strips"),
  source = "profile",
  lines = numeric(),
  smoothing = NULL
)

Arguments

Details

Point traces are drawn with WebGL and values are rounded to the precision shown, which keeps redraws fast for long profiles.

Value

A built plotly object (see plotly::plotly_build()).

Description

A project is a folder chosen by the user. It holds the original runfiles and every choice made about them; reduced data and exports are derived from these and can always be regenerated.

Usage

create_project(
  path,
  settings = default_settings(),
  user = default_user(),
  import_preset = NULL
)

open_project(path, user = default_user(), read_only = FALSE, force = FALSE)

close_project(project)

Arguments

Details

MyProject/
  project.yml   project settings (see default_settings())
  raw/          copies of the original runfiles, never modified
  samples.csv   one row per sample: status, flag, comment, edits, setting overrides
  regions.csv   regions per sample, in seconds of analysis time
  log.csv       every change: time, user, action, sample, field, old and new value
  cache/        reduced data per sample (safe to delete)
  exports/      generated tables and plots
  .lock         who has the project open for editing

create_project() makes a new project folder and opens it. open_project() opens an existing one and takes the lock, so only one person edits a project at a time (useful for shared Dropbox folders). close_project() releases the lock.

Functions that change a project write to disk immediately, add entries to log.csv and return the updated project object.

Value

An isofishr_project object (close_project() returns NULL).

Description

Mean voltages of each baseline (gas blank) run, after its trims, with its acquisition time and session. Used when calibration$baseline is "baseline_runs": the blank subtracted from a run is then interpolated linearly in time between the baseline runs of its session, at the run's start time (and held constant before the first and after the last).

Usage

project_baselines(project)

Arguments

Value

A tibble with sample_id, session, acquired, n_cycles and blk88 to blk83.

Description

Reduces each sample with its own settings and applies its trims and direction. Results are cached in the project's ⁠cache/⁠ folder, keyed by the raw file, the sample's import and reduction settings, the run speed and the IsoFishR version. A sample is only reduced again when one of those changes, so adding samples or changing one sample's settings does not reprocess the others.

Usage

project_data(project, sample_ids = NULL, edited = TRUE, calibrate = TRUE)

Arguments

Value

A tibble of reduced data. Any warnings raised during reduction (e.g. no blank cycles) are attached as the "warnings" attribute, a character vector named by sample.

Description

One row per measurement point for every sample, after trims and reversal: the profile as plotted in the app, in a single table.

Usage

project_profiles(project, data = NULL, include_excluded = FALSE)

Arguments

Details

Columns: sample_id, distance_um, time_s, sr87_sr86 (the point, NA if rejected), sr87_sr86_outlier (rejected value), sr87_sr86_ma and sr87_sr86_ma_se (moving average and its SE) and sr87_sr86_spline and sr87_sr86_spline_se (spline and its SE), each filled when the sample's smoothing method (in smoothing) uses it, region (region name(s) the point falls in, separated by ⁠;⁠), cp_segment and cp_mean (for samples with changepoints enabled), and the signal columns total_sr_v, kr83_v, rb85_sr88 and sr84_sr86.

Value

A tibble.

Description

Region statistics for project samples

Usage

project_regions(project, sample_ids = NULL)

Arguments

Value

One row per sample and region; see summarise_regions().

Description

Lists the runs of a project in the order they were measured, with their type and analytical session. Sessions are found automatically: a new session starts when the gap between two runs is longer than calibration$session_gap_h hours (default 6). A session set with set_session() replaces the automatic one for that run.

Usage

project_runs(project)

Arguments

Value

A tibble with sequence, sample_id, acquired (POSIXct, UTC), run_type, reference_material, rm_role ("primary", "secondary" or ""), status, session_auto and session.

Description

Summary tables for the samples in a project, as written by export_project().

Usage

summarise_project_samples(project, data = NULL, include_excluded = FALSE)

summarise_project_regions(project, data = NULL, include_excluded = FALSE)

summarise_project_changepoints(project, data = NULL, include_excluded = FALSE)

project_settings_table(project, include_excluded = FALSE)

Arguments

Details

• summarise_project_samples(): one row per sample with its status, comment, edits, profile statistics and setting overrides.

• summarise_project_regions(): one row per sample and region.

• summarise_project_changepoints(): one row per changepoint segment, for samples with changepoint detection enabled.

• project_settings_table(): the settings each sample was reduced with.

Means, standard deviations and standard errors are calculated from the individual 87Sr/86Sr points (outliers removed). Smoothed values are autocorrelated, so their standard error would understate the uncertainty; the mean of the smoothed values is reported alongside as mean_smoothed.

When a primary reference material is set (see calibration_model()), all 87Sr/86Sr values are corrected, and the tables add mean_uncorrected, correction_factor, correction_status and se_combined: the SE combined with the uncertainty of the correction.

Value

A tibble.

Description

Reads the date and time a run was started from its header, using the timestamp_line and timestamp_format of the import settings (for Nu Plasma files: line 45, e.g. ⁠"08/12/2017","04:31:02 PM"⁠). Quotes are removed and commas or tabs between the date and time become spaces before the line is parsed with base::strptime() format. Times are treated as the instrument clock and returned in UTC, so daylight saving changes never reorder runs.

Usage

read_acquisition_times(paths, import = default_settings()$import)

Arguments

Value

A POSIXct vector (NA where there is no timestamp line or it could not be parsed).

Description

Read the project session log

Usage

read_log(project)

Arguments

Value

A tibble with one row per recorded change.

Description

Reads the cycle data from one or more instrument runfiles, using the column layout in the import section of the settings.

Usage

read_runfiles(
  paths,
  import = default_settings()$import,
  sample_ids = tools::file_path_sans_ext(basename(paths))
)

Arguments

Value

A tibble with one row per measurement cycle and columns sample_id, cycle, time_s and raw88 to raw83 (volts).

Description

Runs the full data reduction for one or more samples: integration, blank correction, voltage thresholds, distance, Rb interference and mass bias correction, outlier rejection and smoothing. Every step is applied within each sample.

Usage

reduce_runs(raw, settings = default_settings(), blank = NULL)

Arguments

Value

A list with data (one row per integrated cycle) and blank (mean blank voltages per sample, or NULL without blank correction).

Description

One panel per reference material, against run order or acquisition time. For the primary reference material: each run's measured (uncorrected) mean with 2 SE, the fitted correction line (by default the linear regression) and the corrected run means. For secondary reference materials: uncorrected and corrected run means, with the corrected session averages as horizontal lines. The accepted values are dashed lines.

Usage

reference_material_plot(model, results, x = c("order", "time"), runs = NULL)

Arguments

Details

On a time axis, sessions that are days or months apart leave each session's lines too short to see; in run order (the default) every run takes the same space.

Value

A plotly object.

Description

One row per reference material run: the measured (uncorrected) and corrected mean 87Sr/86Sr, standard errors with and without the correction uncertainty, and the deviation from the accepted value. For secondary reference materials this is the accuracy check of the correction; primary runs are corrected to their accepted value by construction (exactly so with the linear and step fits).

Usage

reference_material_results(project)

summarise_reference_materials(project)

Arguments

Value

A tibble.

summarise_reference_materials(): one row per reference material and session: number of runs, mean and SD of the run means before and after correction, accepted value and deviation in ppm (of the corrected mean).

Description

Flags cycles that deviate from the rolling median by more than sd rolling standard deviations. Rejected values move from sr87_sr86 to sr87_sr86_outlier.

Usage

reject_outliers(data, sd = 3, window = 20L)

Arguments

Value

data with is_outlier and sr87_sr86_outlier added.

Description

Removes samples, their regions and cached results from the project. The raw runfile is not deleted but moved to ⁠raw/removed/⁠, so a removed sample can be recovered and the same file can be added again later. To keep a sample but leave it out of exports, set its status to "excluded" with update_sample() instead.

Usage

remove_samples(project, sample_ids)

Arguments

Value

The updated project.

Description

Renders export_report() as a Markdown document (export_report.md in every export): readable in any text editor, rendered on GitHub and in RStudio, and easy to copy into a lab notebook or a methods section.

Usage

report_markdown(report)

Arguments

Value

A character vector of Markdown lines.

Description

Opens IsoFishR in a browser. The app walks through six steps: Project (create or open), Settings, Runfiles, Calibration, Workspace and Export. Every change is saved immediately, and a project reopens on the step it was last worked on.

Usage

run_app(project = NULL, user = default_user(), ...)

Arguments

Value

A Shiny app object; printing it (or calling at the console) runs it.

Description

set_reference_material() adds a reference material or updates its accepted value. remove_reference_material() removes one that no run is assigned to. The primary reference material, used to correct samples, is chosen with update_project_settings(p, list(calibration = list(primary = name))); all others are secondary and are reported as accuracy checks.

Usage

set_reference_material(
  project,
  name,
  value,
  uncertainty_2s = NA_real_,
  note = ""
)

remove_reference_material(project, name)

Arguments

Value

The updated project.

Description

Replaces all regions of one sample. Regions are given in seconds of analysis time (the time_s column of reduced data), so they stay in place if the run speed changes.

Usage

set_regions(project, sample_id, regions)

Arguments

Value

The updated project.

Description

Marks runs as samples, baseline (gas blank) runs, or measurements of a reference material. Reference materials must first be defined with set_reference_material().

Usage

set_run_type(project, sample_ids, run_type, reference_material = "")

Arguments

Value

The updated project.

Description

set_sample_settings() overrides project reduction settings, or the run speed, for one sample (e.g. a different blank time). Pass NULL to go back to the project value. sample_settings() returns the settings a sample is reduced with.

Usage

set_sample_settings(project, sample_id, ...)

sample_settings(project, sample_id)

Arguments

Value

set_sample_settings(): the updated project. sample_settings(): a settings list.

Description

Overrides the automatic session of runs, e.g. to split a long day into two sessions after re-tuning. Corrections are calculated within sessions.

Usage

set_session(project, sample_ids, session)

Arguments

Value

The updated project.

Description

Settings files are YAML. Values missing from the file fall back to default_settings(), so older settings files keep working when new settings are added.

Usage

read_settings(path)

write_settings(settings, path)

Arguments

Description

Centred moving average with standard deviation, standard error and 95% confidence interval. Missing values (e.g. rejected outliers) are skipped and the standard error uses the number of values actually in each window (v1 always divided by the full window width).

Usage

smooth_ma(data, window = 10L)

Arguments

Value

data with sr87_sr86_ma, ⁠_ma_sd⁠, ⁠_ma_n⁠, ⁠_ma_se⁠, ⁠_ma_ci95_low⁠ and ⁠_ma_ci95_up⁠ added.

Description

Fits a penalised regression spline against distance for each sample, with the amount of smoothing chosen from the data:

Usage

smooth_spline(data)

Arguments

Details

• The penalty is estimated by restricted maximum likelihood (mgcv::bam, method = "fREML"), so noisy profiles are smoothed more and clean ones less.

• The penalty is adaptive (bs = "ad"): it varies along the profile, so the curve stays smooth on plateaus but can follow sharp transitions.

• Points are weighted by their total Sr signal, so low-signal (noisier) stretches pull the curve less.

• The basis size grows with the profile length (one basis function per 10 points, 10 to 80); it only caps how wiggly the curve can be.

Profiles of fewer than 60 points get a thin plate spline (bs = "tp") instead, which needs fewer data. The fitted effective degrees of freedom (how flexible the curve ended up, 1 = a straight line) are in sr87_sr86_spline_edf.

Value

data with sr87_sr86_spline, sr87_sr86_spline_se (standard error of the fitted curve) and sr87_sr86_spline_edf added.

Description

Finds runs whose name contains pattern (case-insensitive), e.g. "SBO" for the seabass otolith reference material run at UC Davis (see default_reference_materials()). apply_reference_suggestion() marks them as runs of that reference material, defines it with value if it isn't defined yet, and makes it the primary reference material if none is set.

Usage

suggest_reference_runs(project, pattern = "SBO")

apply_reference_suggestion(
  project,
  pattern = "SBO",
  name = pattern,
  value = default_rm_value(name)
)

Arguments

Value

suggest_reference_runs(): sample IDs of matching runs that are still samples. apply_reference_suggestion(): the updated project.

Description

Uses the cycles recorded before blank_time_s whose 88Sr signal is below raw88_min_v (i.e. before the laser hits the sample).

Usage

summarise_blank(data, blank_time_s, raw88_min_v)

Arguments

Value

A tibble with sample_id, blk88 to blk83 and n_blank.

Description

Summarise regions of a profile

Usage

summarise_regions(data, regions, value = "sr87_sr86_value")

Arguments

Value

One row per sample and region with the mean, standard deviation, number of points, standard error and distance range.

Description

Change project settings

Usage

update_project_settings(project, overrides)

Arguments

Value

The updated project.

Description

Change a sample's status, comment or edits

Usage

update_sample(project, sample_id, ...)

Arguments

Value

The updated project.