Added online documentation.

2 files changed, 58 insertions, 7 deletions

diff --git a/src/bm/bmrequest.cpp b/src/bm/bmrequest.cpp
index f5efdc1..e82a969 100644
--- a/src/bm/bmrequest.cpp
+++ b/src/bm/bmrequest.cpp
@@ -7160,11 +7160,48 @@ void BMRequest_GetIXHistories::handleReply_HTML(const QStringList &args) const
     reply += "<span style=\"font-size:18\">Main Index Value Contributors</span>";
 
     reply += "<br /><br /><table><tr><td style=\"background-color:#eeeeee\">";
+
     reply += QString(
         "This page shows the %1 result histories that contributed most significantly ")
         .arg(doc.elementsByTagName("resultHistory").size());
     reply += QString("to the index value at timestamp %1 (%2)")
         .arg(evalTimestamp).arg(evalDateTime.toString());
+
+    reply += "<br /><br />";
+
+    reply += "The result histories are ranked according to the following steps:<br /><ol>";
+
+    reply += "<li>Let <i>baseVal</i> be the first median smoothed value found.</li>";
+
+    reply += "<li>Let <i>val</i><sub>1</sub> and <i>val</i><sub>2</sub> be the the ";
+    reply += "median smoothed values at the ";
+    reply += "previous and current evaluation time respectively.</li>";
+
+    reply += "<li>Let <i>diffChange</i> be the change in metric-adjusted log2 difference ";
+    reply += "from the previous to the current evaluation time: ";
+    reply += "ma_log<sub>2</sub>(<i>val</i><sub>2</sub>&nbsp;/&nbsp;<i>baseVal</i>)";
+    reply += "&nbsp;-&nbsp;";
+    reply += "ma_log<sub>2</sub>(<i>val</i><sub>1</sub>&nbsp;/&nbsp;<i>baseVal</i>) ";
+    reply += "<br />(<b>Note:</b> a metric-adjusted log2 value eliminates the distinction ";
+    reply += "between \"lower is better\" and \"higher is better\"by ensuring that e.g. ";
+    reply += "-1, 0, 1, and 2 always mean halved, unchanged, doubled, and quadrupled performance ";
+    reply += "respectively).";
+
+    reply += "<li>Rank in descending order on either <i>diffChange</i> or -<i>diffChange</i> ";
+    reply += "depending on whether the index value went up or down from the previous to the ";
+    reply += "current evaluation time respectively.</li>";
+
+    reply += "</ol>";
+
+    reply += "The data points used for <i>baseVal</i>, <i>val</i><sub>1</sub>, and ";
+    reply += "<i>val</i><sub>2</sub> are indicated in the graph as a blue circle, a red ";
+    reply += "square, and a red circle respectively. <b>Note:</b> due to the nature of ";
+    reply += "median smoothing, there is no guarantee that these three data points are ordered ";
+    reply += "in a particular way with respect to time.";
+
+    reply += "<br /><br />";
+    reply += "The current evaluation time is indicated with a blue vertical line.";
+
     reply += "</td></tr></table>\n";
 
 
diff --git a/src/bm/plotter.cpp b/src/bm/plotter.cpp
index 215dd9d..129bc81 100644
--- a/src/bm/plotter.cpp
+++ b/src/bm/plotter.cpp
@@ -913,7 +913,7 @@ bool HistoriesPlotter::drawScenes(
         }
 
         if (basePos) {
-            // Highlight base position ...
+            // Highlight base position as a blue circle (for now) ...
 
             const int bPos = basePos->at(rh);
 
@@ -931,7 +931,8 @@ bool HistoriesPlotter::drawScenes(
         }
 
         if (extraPos) {
-            // Highlight extra positions ...
+            // Highlight extra positions - the first one as a red square and the others
+            // as red circles (for now) ...
 
             QList<int> exPos = extraPos->at(rh);
 
@@ -940,12 +941,25 @@ bool HistoriesPlotter::drawScenes(
 
             for (int i = 0; i < exPos.size(); ++i) {
                 QPainterPath path;
-                path.addEllipse(
-                    x.at(exPos.at(i)) - dpSize_large_2,
-                    y.at(exPos.at(i)) - dpSize_large_2,
-                    dpSize_large, dpSize_large);
-                scene_far->addPath(
+
+                if (i == 0) {
+                    path.addRect(
+                        x.at(exPos.at(i)) - dpSize_large_2,
+                        y.at(exPos.at(i)) - dpSize_large_2,
+                        dpSize_large, dpSize_large);
+                } else {
+                    path.addEllipse(
+                        x.at(exPos.at(i)) - dpSize_large_2,
+                        y.at(exPos.at(i)) - dpSize_large_2,
+                        dpSize_large, dpSize_large);
+                }
+
+                QGraphicsItem *extraPosItem = scene_far->addPath(
                     path, QPen(QColor(255, 0, 0, 255)), QBrush(QColor(255, 200, 200, 255)));
+
+                // Ensure the circle is above the square ...
+                if (i > 1)
+                    extraPosItem->setZValue(1);
             }
         }