Enhance entity mapping with flexible aggregation methods

[nwoodruff-co]

Summary

The current map_to_entity method only supports column-based mapping and uses a fixed aggregation method (sum). This limits flexibility for complex analysis workflows that need custom values or different aggregation approaches.

Proposed solution

Enhance the entity mapping system to support:

1. Custom values parameter: Allow mapping arbitrary value arrays instead of requiring existing columns
2. Flexible aggregation methods: Support multiple aggregation strategies via the how parameter:
   • Person → Group: sum (default), first
   • Group → Person: project (default), divide
   • Group → Group: sum, first, project, divide

Use cases

• Map imputed or calculated values that don't exist as columns
• Split household-level values equally among persons
• Take representative values from groups (first person's age, etc.
• Control aggregation behaviour for different analytical scenarios

Implementation details

• Add base class to eliminate code duplication between UK and US models
• Extend core function with and enhanced parameters
• Update both and to inherit from base class
• Add comprehensive documentation with examples
• Maintain backward compatibility with existing code

Benefits

• More flexible data analysis workflows
• Reduced code duplication
• Better support for custom analytical scenarios
• Clearer documentation of entity mapping capabilities
  EOF
  )