Add CountryProcessor

[dc-almeida]

Closes #587. Adds a CountryProcessor to aggregate country-level data into regional levels (R5, R9, R10).
Currently implemented with importing common-definitions as a dependency.

[danielhuppmann]

Looks nice, a first round of suggestions and comments below.

[danielhuppmann]

Is this ready for review yet?

[dc-almeida]

Yes, I'll open it for final review. I left it as a draft because I was going to look into the minimum countries for aggregation question, but meanwhile looked at other tasks so best to close this one and tackle that a bit later.

[danielhuppmann]

A few comments inline, and one general question about the architecture - wouldn't it make sense to have a constructor that builds a RegionProcessor class and then applies that class?

Maybe add a RegionProcessor.from_codelist(hierarchy) constructor?

[phackstock]

A few comments inline, and one general question about the architecture - wouldn't it make sense to have a constructor that builds a RegionProcessor class and then applies that class?

Maybe add a RegionProcessor.from_codelist(hierarchy) constructor?

I'd agree with that approach. The current implementation produces quite a lot of code duplication which increases the chance of failure and makes future maintenance harder.
I'd suggest to either go with something along the lines of RegionProcessor.create_country_processor_from_codelist or making a CountryProcessor class that inherits from RegionProcessor to get all of the common functionality. As part of this, I'd suggest to directly create RegionAggregationMappings for the models that are specified in the config.

[phackstock]

In terms for functionality, I'd say this PR is where we want it to be with the exception of checking a minimum set of countries.
Implementation wise, I want to echo what @danielhuppmann said earlier in the discussion in this PR, CountryProcessor should either be implemented as a subclass of RegionProcessor or generated through a dedicated constructor as part of the RegionProcessor class. The RegionCodeList and model information should be used to generate model mappings on-the-fly that are then applied to incoming data.

[dc-almeida]

Applied review suggestions and:

• added a RegionProcessor.from_country_codelist factory method that creates a processor/aggregator for a list of hierarchies with country attributes
• added a create_country_processor function as a specific use case of the method above, for R5/R9/R10 regions
• initially added by_hierarchy RegionCodeList method but prioritised use of already existing filter CodeList method
• updated docs to have the country processor guide in RegionProcessor

[danielhuppmann]

Thanks, tests and implementation look good, but as detailed below, I would go for the proper subclass-strategy instead of a utility function.

[danielhuppmann]

Two minor comments, good from my side to merge after a review by @phackstock