Burndown Chart

- Added debug output showing calculations.
- Made the bias configurable, defaulting to 0.666.
- Added 'burndown.bias' to the taskrc.5 man page.

doc/man/taskrc.5

@@ -306,6 +306,16 @@ comparison of the data.  This can be in either the 'side' style, which compares
 values side-by-side in a table, or 'diff' style, which uses a format similar to
 the 'diff' command.
 
+.TP
+.B burndown.bias=0.666
+The burndown bias is a number that lies within the range 0 <= bias <= 1.  The bias
+is the fraction of the find/fix rates derived from the short-term data (last
+25% of the report) versus the longer term data (last 50% of the report).  A
+value of 0.666 (the default) means that the short-term rate has twice the weight
+of the longer-term rate.  The calculation is as follows:
+
+    rate = (long-term-rate * (1 - bias)) + (short-term-rate * bias)
+
 .TP
 .B debug=off
 Taskwarrior has a debug mode that causes diagnostic output to be displayed.

src/Config.cpp

@@ -80,6 +80,7 @@ std::string Config::defaults =
   "recurrence.indicator=R                         # What to show as a task recurrence indicator\n"
   "recurrence.limit=1                             # Number of future recurring pending tasks\n"
   "undo.style=side                                # Undo style - can be 'side', or 'diff'\n"
+  "burndown.bias=0.666                            # Weighted mean bias toward recent data\n"
   "\n"
   "# Dates\n"
   "dateformat=m/d/Y                               # Preferred input and display date format\n"

src/burndown.cpp

@@ -25,7 +25,6 @@
 //
 ////////////////////////////////////////////////////////////////////////////////
 
-#include <iostream>  // TODO Remove
 #include <sstream>
 #include <algorithm>
 #include <math.h>
@@ -409,7 +408,6 @@ std::string Chart::render ()
     return "No matches.\n";
 
   // Create a grid, folded into a string.
-  // TODO Upgrade grid to a vector of strings, for simpler optimization.
   grid = "";
   for (int i = 0; i < height; ++i)
     grid += std::string (width, ' ') + "\n";
@@ -893,36 +891,45 @@ void Chart::calculateRates (std::vector <time_t>& sequence)
   float fix_rate_50 = 1.0 * total_removed_50 / half_days;
   float fix_rate_75 = 1.0 * total_removed_75 / quarter_days;
 
-  // TODO Make configurable.
-  float bias = 0.666;
+  // Make configurable.
+  float bias = (float) context.config.getReal ("burndown.bias");
 
   find_rate = (find_rate_50 * (1.0 - bias) + find_rate_75 * bias);
   fix_rate  = (fix_rate_50  * (1.0 - bias) + fix_rate_75 * bias);
 
-  // find rate = ((N added / N days) + 2 * (N added / N days)) / 3.0
-  // fix rate = ((N removed / N days) + 2 * (N removed / N days)) / 3.0
+  // Q: Why is this equation written out as a debug message?
+  // A: People are going to want to know how the rates and the completion date
+  //    are calculated.  This may also help debugging.
   std::stringstream rates;
   rates << "Chart::calculateRates find rate: "
         << "("
         << total_added_50
         << " added / "
         << half_days
-        << " days) + 2 * ("
+        << " days) * (1.0 - "
+        << bias
+        << ") + ("
         << total_added_75
         << " added / "
         << quarter_days
-        << " days)) / 3.0 = "
+        << " days) * "
+        << bias
+        << ") = "
         << find_rate
         << "\nChart::calculateRates fix rate: "
         << "("
         << total_removed_50
         << " removed / "
         << half_days
-        << " days) + 2 * ("
+        << " days) * (1.0 - "
+        << bias
+        << ") + ("
         << total_removed_75
         << " added / "
         << quarter_days
-        << " days)) / 3.0 = "
+        << " days) * "
+        << bias
+        << ") = "
         << fix_rate;
   context.debug (rates.str ());