🌌🧐 Macro evaluation

[mberr]

Adds an evaluator for computing macro averaged rank-based metrics.

Also enables docstr-coverage and darglint for pykeen.evaluation and adds missing docstrings.

Dependencies

• ⚖️🌡️ Weighted Rank-Based Metrics #837

[cthoyt]

Needs a bit of high-level documentation. can you add some notes on this in understanding_evaluation.rst (e.g., what issues are caused by micro evaluation? how does macro evaluation work and how does it solve these issues?) Maybe copy-paste some of the content that didn't make it into the metrics manuscript

[mberr]

Needs a bit of high-level documentation. can you add some notes on this in understanding_evaluation.rst (e.g., what issues are caused by micro evaluation? how does macro evaluation work and how does it solve these issues?) Maybe copy-paste some of the content that didn't make it into the metrics manuscript

e1d41fb - feel free to adjust / rephrase

[mberr]

some parts of the metric description in the understanding evaluation part is incorrect, but also duplicated from the class doc itself, e.g., here, where the section about adjusted mean rank describes the adjusted MRR, and the expectation is incorrect.

pykeen/docs/source/tutorial/understanding_evaluation.rst

Lines 128 to 160 in 9cb4899

	Adjusted Mean Rank
	******************
	The expectation of an inverse-uniform distributed variable $\frac{1}{X} \sim \mathcal{U}(\frac{1}{a},\frac{1}{b})$
	is $\mathbb{E}\left[\frac{1}{X}\right] = \frac{\ln b - \ln a}{b - a}$.
	Given our uniformly distributed variable $r_i$ with parameters $a=1$ and $b=N_i$ and its corresponding
	inverse-uniform distributed variable $r_i^{-1}$, we get:
	.. math::
	\mathbb{E}\left[r_i^{-1}\right]
	= \frac{\ln 1 - \ln N_i}{N_i - 1}
	= \frac{\ln N_i}{N_i - 1}
	\doteq \frac{\ln n}{n - 1}
	The expected value of the mean rank is then derived like:
	.. math::
	\mathbb{E}\left[\text{MRR}\right]
	= \mathbb{E}\left[\frac{1}{n} \sum \limits_{i=1}^n r_i^{-1}\right]
	= \frac{1}{n} \sum \limits_{i=1}^n \mathbb{E}\left[r_i^{-1}\right]
	= \mathbb{E}\left[r_i^{-1}\right]
	\doteq \frac{\ln n}{n - 1}
	The adjusted mean rank (AMR) was introduced by [berrendorf2020]_. It is defined as the ratio
	of the mean rank to the expected mean rank
	.. math::
	\text{MRR}^{*}(r_1,\ldots,r_n) = \frac{\text{MRR}(r_1,\ldots,r_n)}{\mathbb{E}\left[\text{MRR}\right] }
	It lies on the open interval $(0, 2)$ where lower is better.

maybe it is better to directly link to the class reference?

[cthoyt]

@mberr good idea