tracer_pull_analysis: Analyze the Marginal Effect (Pull) of Individual Tracers

In OceanTracer: Marine Source Unmixing Toolkit

Analyze the Marginal Effect (Pull) of Individual Tracers

Description

Evaluates the directional bias introduced by individual tracers within Consistent Tracer Selection (CTS) subset models. This function unpacks unconstrained source apportionments to reveal if specific tracers are systematically pulling source contributions into physically impossible spaces (e.g., >1 or <0).

Usage

tracer_pull_analysis(cts_result)

Arguments

cts_result

A data frame containing the output from a CTS run. It must contain an id column with space-separated tracer names, and weight columns named w1, w2, etc.

Details

Global unmixing models (using all tracers simultaneously) can suffer from "tracer compensation," where extreme mathematical contradictions between non-conservative tracers cancel each other out, resulting in a misleadingly plausible central solution.

This function exposes that illusion. By taking the output of a CTS run (e.g., CTS_n_sources), it isolates every debate a specific tracer participated in. It then calculates the marginal effect (median, mean, and SD) that the tracer has on the fractional weight of each source.

Visualizations are automatically generated and stored in the returned list:

• boxplot: Displays the distribution of calculated weights for each source, grouped by tracer. Red dashed lines denote the physical boundaries of 0 and 1.

• heatmap: Displays the median weight pull. Deep red indicates a strong positive pull (overestimation), while deep blue indicates a negative pull (pushing the source into negative mass space).

Value

A named list containing four elements:

summary

A tibble containing the Mean, Median, and SD of the weights forced by each tracer on each source.

boxplot

A ggplot object showing the distribution of source weights grouped by tracer.

heatmap

A ggplot object visualizing the median tracer bias across all sources.

raw_expanded

A tibble of the raw, pivoted data used for calculations and plotting.

Examples

# Create a toy dataset mimicking a CTS model output
cts_out <- data.frame(
  id = c("TracerA TracerB", "TracerA TracerC", "TracerB TracerC"),
  w1 = c(0.3, 0.4, 0.2),
  w2 = c(0.7, 0.6, 0.8)
)

# Analyze tracer pull
pull_results <- tracer_pull_analysis(cts_out)

# View summary statistics and display boxplot
print(pull_results$summary)
print(pull_results$boxplot)

OceanTracer documentation built on Oct. 15, 2026, 5:09 p.m.