diff --git a/docs/img/score_10years.png b/docs/img/score_10years.png new file mode 100644 index 0000000000000000000000000000000000000000..bef922b8906ac6410650601351336f4909c11b43 Binary files /dev/null and b/docs/img/score_10years.png differ diff --git a/docs/img/score_1year.png b/docs/img/score_1year.png new file mode 100644 index 0000000000000000000000000000000000000000..50d579aabb7e771c656500b97f7c1f6997ecbf1d Binary files /dev/null and b/docs/img/score_1year.png differ diff --git a/docs/img/score_exp1k.png b/docs/img/score_exp1k.png new file mode 100644 index 0000000000000000000000000000000000000000..40a43e73ad235b16cec2ef562ddaae9fae9ae896 Binary files /dev/null and b/docs/img/score_exp1k.png differ diff --git a/docs/img/score_exp6.png b/docs/img/score_exp6.png new file mode 100644 index 0000000000000000000000000000000000000000..9262e8c05ca5e6c9a0b0262ff6bdc24946c09831 Binary files /dev/null and b/docs/img/score_exp6.png differ diff --git a/docs/img/score_formula.png b/docs/img/score_formula.png new file mode 100644 index 0000000000000000000000000000000000000000..131e4d8a5ed7b59c4ea92408f150cb7cdbe8f930 Binary files /dev/null and b/docs/img/score_formula.png differ diff --git a/docs/index.rst b/docs/index.rst index 05a6e669f3451c7c10c251928e4ae815a475d8c6..76d8172a76b2041530e95ebf3b6e986c82076ea3 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -14,6 +14,7 @@ Contents: usage deployment administration + scores api development hacker diff --git a/docs/scores.rst b/docs/scores.rst new file mode 100644 index 0000000000000000000000000000000000000000..529e74f7297b2f0410d63366676b0e6ce02fc688 --- /dev/null +++ b/docs/scores.rst @@ -0,0 +1,64 @@ +Memopol Scores +~~~~~~~~~~~~~~ + +Score computation +================= + +In Memopol, each representative has a score that shows how their votes match +the recommendations made by administrators on the instance. The total score +of a representative is the sum of their score on each dossier, which in turn is +the sum of their score on each proposal with a recommendation on the dossier. + +Each recommendation made by administrators has a weight: a number that tells how +important a specific proposal is. When the representative vote on a proposal +matches the recommendation, their score on the proposal is set to +weight. +Otherwise, it is set to -weight. + +Score decay parameters +====================== + +Memopol allows to set decay parameters so that older votes have a lower +importance in the total representative score. By default, those parameters are +set to values that disable the score decay, so that each vote contributes +identically to the total score no matter how old it is. + +The formula used to compute score is the following: + +.. image:: img/score_formula.png + +Where: + +* ``baseScore`` is the base score for the vote computed as explained above; +* ``voteAge`` is the age of the vote in days; +* ``decayNum`` and ``decayDenom`` define the decay rate; +* ``exponent`` define the steepness of the decay. + +The corresponding parameters can be set from the Memopol administration +interface (Memopol Settings > Settings); settings keys are ``SCORE_DECAY_NUM``, +``SCORE_DECAY_DENOM``, ``SCORE_EXPONENT``. Additionnaly, the ``SCORE_DECIMALS`` +parameter sets how many decimal places are visible when scores are displayed. + +The default values for those settings disable score decay by setting +``SCORE_DECAY_NUM`` to 0, ``SCORE_DECAY_DENOM`` and ``SCORE_EXPONENT`` to 1. + +If you want to use score decay, start by setting ``SCORE_DECAY_NUM`` to 1, and +``SCORE_DECAY_DENOM`` to the number of days you want votes to matter. The graph +below shows how a score of 1.0 will decay with a 1-year decay (the X axis is in +days). + +.. image:: img/score_1year.png + +Increasing ``SCORE_DECAY_DENOM`` will make votes matter longer. Here is the +same example but with a 10-year decay. + +.. image:: img/score_10years.png + +Increasing ``SCORE_EXPONENT`` instead will make the decay cutoff steeper. Here +is an example with a 1-year decay and the exponent set to 6. + +.. image:: img/score_exp6.png + +Increasing it dramatically will create a brutal cutoff; here is the same example +with the exponent set to 1000: + +.. image:: img/score_exp1k.png