Add top-mass and bulk-reference metrics for traps; make remove_traps accept traps DataFrame and return verification

[charlesmartin14]

Motivation

• Extend trap analysis to report the fraction of a trap's mass concentrated in the top 5%/10% and provide bulk-mode reference statistics for localization and top-mass, enabling richer diagnostics and comparisons between traps and bulk modes.
• Improve the remove_traps API to accept the older traps DataFrame shape for compatibility and to support post-removal verification and optional returned analysis.

Description

• Added top-mass computations and bulk reference metrics: implemented _top_percent_abs_mass and integrated top_5_mass and top_10_mass per-trap, and added compute_bulk_trap_reference_metrics to compute bulk_mode_count, bulk_localization_mean, bulk_localization_std, bulk_top_5_mass_mean, bulk_top_5_mass_std, bulk_top_10_mass_mean, and bulk_top_10_mass_std returned with each trap row and included in the WeightWatcher result columns.
• Extended the remove_traps flow with _trap_indices_from_traps_df to accept a traps DataFrame-like argument (backwards-compatible PR359 path) and to normalize indices; added verify_traps and return_analyze options so remove_traps can perform post-removal artifact collection and return a verification DataFrame when requested.
• Updated WeightWatcher wrapper signatures to accept traps, verify_traps, and return_analyze, and delegated behavior to the new remove_traps implementation in remove_traps.py.
• Minor imports and test updates: added pandas import where needed and updated expected trap-analysis columns in tests/test_analyze_traps.py and added tests/test_remove_traps.py::test_remove_traps_accepts_traps_dataframe_and_returns_verify_df to exercise the DataFrame/verify path.

Testing

• Ran the updated unit tests in tests/test_analyze_traps.py which assert new trap columns are present and reproducibility behavior remains unchanged, and these tests passed.
• Ran updated and new tests in tests/test_remove_traps.py, including test_remove_traps_accepts_traps_dataframe_and_returns_verify_df, which passed and verifies the DataFrame input and returned verification frame behavior.
• Executed the modified remove_traps/analyze_traps code paths used by the new tests to confirm end-to-end behavior in the updated test suite.

---

Codex Task