API Refactor - MatcherResults and metrics

[Archer6621]

This PR refactors the API #61 so that a MatcherResults object is returned which inherits from dict, instead of a plain dict, when using either valentine_match or valentine_batch_match. This should not break the existing API too much, as the return type is still a dict as before.

This dictionary is sorted upon instantiation according to its values, from high similarity to low similarity (dictionaries preserve sorting/insertion order starting from Python 3.6).

This MatcherResults object exposes the following API methods:

• get_metrics - gets metrics according to the matches
• one_to_one - transforms the matches so that they are one-to-one and returns a new MatcherResults with this
• take_top_percent - takes the top n percent of the matches and returns this as a new MatcherResults
• take_top_n - takes the top n matches and returns this as a new MatcherResults

Aside from this new MatcherResults object, the metrics API has been overhauled as well. Metrics are now classes that inherit from the abstract Metric class. These need to be instantiated with the appropriate parameters in order to be used, although all of these parameters should be keyword arguments and thus have a default.

The API for this is as follows:

from valentine.metrics import Precision, F1Score, PrecisionTopNPercent, METRICS_PRECISION_INCREASING_N

matches = valentine_match(df1, df2, ALGORITHM)

# Getting the default metrics, defined in `metrics.__init__`
metrics = matches.get_metrics(ground_truth)

# Using custom metrics, imported from `metrics`
metrics_custom = matches.get_metrics(ground_truth, metrics={Precision(), F1Score(one_to_one=False), PrecisionTopNPercent(n=25)}

# Using a predefined set
metrics_set = matches.get_metrics(ground_truth, metrics=METRICS_PRECISION_INCREASING_N)

A final minor change is that the Match class got converted to a dataclass.

Tests and numpy-style documentation have been added for the new additions, and the example + readme has been updated as well.

Furthermore, with this change, it will become easy to also integrate #55 into the MatcherResults class, where it fits much better.

[codecov]

Codecov Report

Attention: 4 lines in your changes are missing coverage. Please review.

Comparison is base (96430e7) 86.36% compared to head (5dc95df) 87.15%.

Files	Patch %	Lines
valentine/metrics/base_metric.py	88.23%	2 Missing ⚠️
valentine/algorithms/matcher_results.py	98.00%	1 Missing ⚠️
valentine/metrics/metric_helpers.py	96.29%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master      #70      +/-   ##
==========================================
+ Coverage   86.36%   87.15%   +0.79%     
==========================================
  Files          37       40       +3     
  Lines        1679     1760      +81     
==========================================
+ Hits         1450     1534      +84     
+ Misses        229      226       -3     

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

[kPsarakis]

@Archer6621 Is this ready to review?

[kPsarakis]

Looks good! Thanks Shaad!