Add paper-aligned trap metrics, top-sector parameter, and layer aggregation with tests

[charlesmartin14]

Motivation

• Align trap analysis outputs with the paper definitions by exposing normalized trap strength, IPR-based concentration, top-sector overlap, and a combined variance-burden metric for each detected trap.
• Allow callers to specify the top-sector size via a top_sector_l parameter so top-sector overlap can be computed reproducibly and aggregated per layer.
• Surface these metrics in the DataFrame and add unit tests to validate the helper computations, column presence, formula consistency, and per-layer aggregation.

Description

• Added a new top_sector_l parameter to analyze_traps in both the top-level API and internal trap_analysis.analyze_traps, with validation that it is >= 1.
• Implemented helper methods on WeightWatcher: compute_trap_delta, compute_trap_ipr_q, compute_top_sector_overlap, and compute_trap_variance_burden, and used them when constructing each trap row to populate new columns trap_delta, trap_ipr, trap_q, trap_diffuseness, top_sector_l, top_sector_l_effective, trap_top_sector_overlap, and trap_variance_burden.
• Added an aggregated per-layer column layer_trap_variance_burden computed by grouping trap_variance_burden by layer_id in trap_analysis.analyze_traps and included the new metric columns in _trap_result_columns so they appear in details.
• Expanded tests/test_analyze_traps.py with unit tests that exercise the helper functions, assert the presence of the new paper-aligned columns, validate top_sector_l behavior, verify the variance-burden formula rowwise, and check the per-layer aggregation.

Testing

• Ran the trap analysis unit tests with pytest tests/test_analyze_traps.py and the updated test suite for the helper functions, and all tests passed.
• The new tests cover compute_trap_delta, compute_trap_ipr_q, compute_top_sector_overlap, the presence of new DataFrame columns, the top_sector_l argument behavior, the rowwise variance-burden formula, and the layer_trap_variance_burden aggregation.

---

Codex Task