Refactor contact_matrix() to use assign_age_groups()

[sbfnk]

This PR closes #227.

Summary

• contact_matrix() now delegates all age processing (imputation, missing-age handling, age group assignment) to assign_age_groups(), replacing ~70 lines of duplicated inline logic
• New exported agegroups_to_limits() function (inverse of limits_to_agegroups()) recovers lower age limits from age group labels
• Simplified the representative-population branch in survey_pop_from_countries() since lower.age.limit is already set by assign_age_groups()
• Added unit tests for agegroups_to_limits() (round-trip with brackets/dashes, character input, single group)

Notes

• Minor ordering change: apply_data_filter() now runs after assign_age_groups() rather than between age processing steps. This means the top age group break is based on unfiltered max age, but empty groups don't affect results.
• When age_limits = NULL, limits are now inferred after contact factor-to-integer conversion (matching assign_age_groups() ordering) rather than before. This is more correct but could produce minor differences with factor contact ages — unlikely to affect real-world use.

Summary by CodeRabbit

• New Features
  • Added agegroups_to_limits() to convert age-group labels back to numeric lower limits.
• Behavioral Changes
  • contact matrix workflow now uses a centralized age-group assignment step for more consistent age handling.
  • Survey-related functions continue to emit unconditional deprecation warnings.
• Documentation
  • Added documentation for agegroups_to_limits().
• Tests
  • New tests covering age-group round-trip and edge cases.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds and exports agegroups_to_limits(); refactors contact_matrix() to delegate participant/contact age handling to assign_age_groups() and derive numeric age limits from assigned age-group labels; adjusts survey_pop_from_countries aggregation and removes a global variable; includes docs and tests.

Changes

Cohort / File(s)	Summary
New export & utility NAMESPACE, R/limits_to_agegroups.R	Added and exported agegroups_to_limits() to extract numeric lower limits from age-group labels; small refactor in limits_to_agegroups() return style.
Contact matrix logic R/contact_matrix.R, R/contact-matrix-utils.R	Replaced stepwise participant/contact age processing with a single assign_age_groups() call in contact_matrix(); derived age_limits from resulting age groups using agegroups_to_limits(); simplified survey_pop_from_countries() aggregation to rely on existing lower.age.limit.
Globals & symbols R/globals.R	Removed part_age from utils::globalVariables(...).
Docs & tests man/agegroups_to_limits.Rd, NEWS.md, tests/testthat/test-agegroups.r	Added roxygen-generated documentation and NEWS entry for agegroups_to_limits() and contact_matrix change; added tests covering round-trip conversions, character input, and single-group edge case.

Sequence Diagram(s)

sequenceDiagram
    participant CM as contact_matrix()
    participant AG as assign_age_groups()
    participant P as survey$participants
    participant C as survey$contacts
    participant AL as agegroups_to_limits()

    rect rgba(200,220,255,0.5)
    CM->>AG: pass participants + contacts + age group settings
    end
    AG-->>P: return participants with assigned age.group / lower.age.limit
    AG-->>C: return contacts with assigned age.group / lower.age.limit
    rect rgba(200,255,200,0.5)
    CM->>AL: extract numeric limits from P$age.group
    AL-->>CM: numeric age_limits
    end
    rect rgba(255,220,200,0.5)
    CM->>CM: apply filters, compute contact matrix using assigned groups and age_limits
    end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

Possibly related PRs

• Prepare for 0.5.0 release #276 — introduces assign_age_groups() which contact_matrix() now delegates to.
• Deprecate missing_contact_age = 'sample' option #274 — modifies interactions between assign_age_groups() and contact_matrix(); closely overlaps refactor.
• Add assign_age_groups() to consolidate age processing #246 — also consolidates age processing around assign_age_groups() and touches age-group utilities.

Poem

🐰 Hop-hop, labels trim and neat,
Groups to limits, numbers meet.
One call now guides both young and old,
Tests sing true, the docs unfold.
A rabbit celebrates, soft and fleet — hooray for tidy code, so sweet!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: refactoring contact_matrix() to use assign_age_groups() instead of inline age-processing logic, which is the primary objective of the PR.
Linked Issues check	✅ Passed	The PR directly addresses issue #227 by identifying interaction ordering in contact_matrix(), reordering steps (apply_data_filter now runs after assign_age_groups), and streamlining duplicated age-processing logic into a consolidated assign_age_groups() call.
Out of Scope Changes check	✅ Passed	All changes relate to the stated objectives: refactoring contact_matrix(), adding agegroups_to_limits(), simplifying survey_pop_from_countries(), and adding corresponding tests. No unrelated modifications detected.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch refactor-contact-matrix-age-groups

---

No actionable comments were generated in the recent review. 🎉

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

Refactors contact_matrix() to delegate participant/contact age processing and age-group assignment to assign_age_groups(), and introduces a new helper to recover lower age limits from age-group labels.

Changes:

• Replaced duplicated age-processing logic in contact_matrix() with a single call to assign_age_groups().
• Added exported agegroups_to_limits() (documented + tests) to extract lower age limits from age-group labels.
• Simplified representative-population handling in survey_pop_from_countries() and updated exports/changelog accordingly.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
R/contact_matrix.R	Delegates age processing to assign_age_groups() and derives age_limits from assigned age groups.
R/contact-matrix-utils.R	Simplifies representative survey population calculation using lower.age.limit.
R/limits_to_agegroups.R	Adds new exported agegroups_to_limits() helper and roxygen docs.
man/agegroups_to_limits.Rd	Generated documentation for the new exported function.
tests/testthat/test-agegroups.r	Adds unit tests for agegroups_to_limits().
NAMESPACE	Exports agegroups_to_limits.
NEWS.md	Notes refactor and new helper function in the dev changelog.
R/globals.R	Removes now-unneeded global variable entry related to the prior representative-population logic.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.