Implement explicit API for categorize()

[danielhuppmann]

Please confirm that this PR has done the following:

• Tests Added
• Documentation Added
• Name of contributors Added to AUTHORS.rst
• Description in RELEASE_NOTES.md Added

Description of PR

This PR implements the explicit signature for categorize() and marks the existing signature and the top-level function as deprecated (to be removed for release 3.0) similar to #804 for the validate() method.

For explanation: the rationale for the top-level function pyam.categorize(df) made sense only because it allowed to apply filters by other dimensions (model, scenario, region, unit) in addition to the criteria based on variable and years. The new signature allows to directly slice-and-validate on any dimension.

[codecov]

Codecov Report

Attention: Patch coverage is 94.11765% with 1 lines in your changes are missing coverage. Please review.

Project coverage is 95.0%. Comparing base (ddbb88e) to head (595be43).
Report is 5 commits behind head on main.

❗ Current head 595be43 differs from pull request most recent head b234348. Consider uploading reports for the commit b234348 to get more accurate results

Files	Patch %	Lines
pyam/core.py	88.8%	1 Missing ⚠️

Additional details and impacted files

@@          Coverage Diff          @@
##            main    #837   +/-   ##
=====================================
  Coverage   95.0%   95.0%           
=====================================
  Files         64      63    -1     
  Lines       6134    6134           
=====================================
+ Hits        5828    5831    +3     
+ Misses       306     303    -3     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[gidden]

As noted in #819, the feature was implemented as described. I'm indifferent whether this gets merged or the other.

[gidden]

LGTM, thanks @danielhuppmann also for adding some tests =)

[danielhuppmann]

Learned from the best about being careful of having complete documentation and good test coverage... And I didn't want to be all nitpicky about your PR.