Reference semantics verification

reference-semantics-verification

Summary

Verify that a data filtering function respects reference semantics (copy_object=FALSE) by confirming that the original data object is mutated in-place rather than independently copied. This skill ensures memory-efficient chaining of filters on metabolomics peak tables.

When to use

When applying sequential filters to a large metabolomics peak table (e.g., mispicked ions, group, CV, or in-source filters) and you need to confirm that setting copy_object=FALSE actually modifies the input object in-place rather than creating a hidden copy. Use this skill after calling a filter function with copy_object=FALSE to validate that memory and performance gains are real, especially when chaining multiple filters on datasets with thousands of features.

When NOT to use

• When copy_object=TRUE is explicitly set — the function is designed to create an independent copy, so verifying reference semantics is not applicable.
• When the filter function is called for the first time without prior knowledge of its semantics — establish baseline semantics documentation first rather than relying on verification for every call.
• When dealing with small peak tables (< 100 rows) where memory efficiency gains are negligible and verification overhead is not justified.

Inputs

• metabolomics data object (mpactr object with peak table)
• filter function call with copy_object=FALSE parameter

Outputs

• confirmation of in-place mutation (boolean: row counts match)
• documentation of peak table row count before and after filtering

How to apply

Before calling the filter function, extract and record the peak table row count from the input data object using get_peak_table(). Call the filter function (e.g., filter_mispicked_ions) with copy_object=FALSE, storing the result in a new variable. Extract and record the peak table row count from the original input object again. Compare the row counts: if the original object's row count has decreased to match the filtered result's row count, the function is using reference semantics and mutating the original object in-place. If the original object's row count remains unchanged, the function is creating an independent copy despite copy_object=FALSE, indicating either a parameter misinterpretation or a bug. This verification is critical before committing to reference-semantic workflows in production pipelines.

Related tools

• mpactr (provides filter functions with copy_object parameter and get_peak_table accessor for verification) — https://github.com/mums2/mpactr
• R (language environment for executing filter calls and row count comparisons)

Examples

# Extract initial row count
initial_rows <- nrow(get_peak_table(data2))
# Call filter with copy_object=FALSE
data2_filtered <- filter_mispicked_ions(data2, ringwin=0.5, isowin=0.01, trwin=0.005, max_iso_shift=3, merge_peaks=TRUE, merge_method='sum', copy_object=FALSE)
# Verify in-place mutation: original object row count should match filtered result
final_rows <- nrow(get_peak_table(data2))
if (nrow(get_peak_table(data2_filtered)) == final_rows & final_rows < initial_rows) { print('Reference semantics confirmed') }

Evaluation signals

• Peak table row count of the original input object decreases after filtering, matching the row count of the filtered result object
• get_peak_table(original_object) and get_peak_table(filtered_result) return identical row counts, confirming they reference the same underlying data
• Repeated calls to get_peak_table on the original object after filtering return consistent (mutated) row counts, ruling out transient state changes
• Memory profiling shows no spike in memory consumption during filtering (compared to deep copy scenario), validating the reference-semantic claim
• Assignment of filter result to a new variable does not prevent mutations to the original object, confirming aliasing rather than copying

Limitations

• Row count comparison alone cannot detect selective column mutations; verify schema integrity separately if filter modifies peak table structure beyond row removal.
• This verification method assumes get_peak_table() is deterministic and reflects the true state of the underlying object; if the accessor itself creates copies or caches data, verification may be misleading.
• Reference semantics behavior may vary across filter functions (filter_mispicked_ions, filter_group, filter_cv, filter_insource_ions); verification must be performed independently for each filter type.
• Timing and memory profiling are environment-dependent (R garbage collection, OS memory management); verification via row count is more reliable than performance metrics alone.

Evidence

• [methods] in-place mutation confirmation via row count change: "Verify that get_peak_table(data2) row count matches get_peak_table(data2_mispicked) row count, confirming in-place mutation of the original object"
• [abstract] reference-semantics rationale for memory efficiency: "We recommend using the default copy_object = FALSE as this makes for an extremely fast and memory-efficient way to chain mpactr filters together"
• [abstract] filter_mispicked_ions with copy_object=FALSE parameter: "filter_mispicked_ions(data2, ringwin = 0.5, isowin = 0.01, trwin = 0.005, max_iso_shift = 3, merge_peaks = TRUE, merge_method = "sum", copy_object = FALSE)"
• [methods] demonstration of peak table row count reduction: "Running filter_mispicked_ions with copy_object=FALSE reduces the original data2 object's peak table from the initial row count to a smaller row count"