Class: EstimateAccuracyChart

Inherits:
ChartBase show all
Defined in:
lib/jirametrics/estimate_accuracy_chart.rb

Constant Summary collapse

SINGLE_ISSUE_RADIUS =

Chart.js sizes a bubble by its radius but the eye reads it by area, so the radius has to go as the square root of the count. This multiplier is the radius of a single issue and everything else scales up from there.

4

Constants inherited from ChartBase

ChartBase::LABEL_POSITIONS, ChartBase::OKABE_ITO_PALETTE

Instance Attribute Summary

Attributes inherited from ChartBase

#aggregated_project, #all_boards, #atlassian_document_format, #board_id, #canvas_height, #canvas_width, #color_palette, #data_quality, #date_range, #file_system, #fix_versions, #holiday_dates, #issues, #settings, #time_range, #timezone_offset, #x_axis_title, #y_axis_title

Instance Method Summary collapse

Methods inherited from ChartBase

#aggregated_project?, #before_run, #call_before_run, #canvas, #canvas_responsive?, #collapsible_issues_panel, #color_block, #color_for, #comma_and, #completed_issues_in_range, #current_board, #cycletime, #cycletime_for_issue, #daily_chart_dataset, #date_annotation, #describe_non_working_days, #description_text, #expand_template, #expanded_header_text, #format_integer, #format_status, #header_text, #holidays, #html_directory, #icon_span, #link_to_issue, #next_id, #next_palette_color, #no_data_text, #non_working_day?, #normalize_annotation_datetime, #not_visible_icon, #not_visible_text, #ordinal, #percentile_of, #render, #render_axis_title, #render_binding, #render_header, #render_no_data, #render_top_text, #resolve_status, #stagger_label_positions, #status_category_color, #to_human_readable, #working_days_annotation, #wrap_and_render

Methods included from ChartFormat

#chart_format

Constructor Details

#initialize(configuration_block) ⇒ EstimateAccuracyChart

Returns a new instance of EstimateAccuracyChart.



4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
 
# File 'lib/jirametrics/estimate_accuracy_chart.rb', line 4

def initialize configuration_block
  super()

  header_text 'Estimate Accuracy'
  description_text <<~HTML
    <div class="p">
      This chart graphs estimates against actual recorded cycle times. Since
      estimates can change over time, we're graphing the estimate at the time that the story started.
    </div>
    <div class="p">
      The #{color_block '--estimate-accuracy-chart-completed-fill-color'} completed dots indicate
      cycletimes.
      <% if @has_aging_data %>
        The #{color_block '--estimate-accuracy-chart-active-fill-color'} aging arrows
        (click on the legend to turn them on) show the current
        age of items, which will give you a hint as to where they might end up. They point right
        because those items haven't finished yet, so every one of them will keep moving that way
        until it does. If they're already far to the right then you know you have a problem.
      <% end %>
    </div>
    <% if @correlation_coefficient %>
      <div class="p">
        The completed items here have a correlation coefficient of <b><%= @correlation_coefficient.round(3) %></b>.
        The closer it is to +1, the stronger the positive correlation. The closer it is to -1,
        the stronger the negative correlation. Zero would mean no correlation at all.
      </div>
    <% elsif @estimates_are_numeric == false %>
      <div class="p">
        There's no correlation coefficient here because these estimates are categories rather than
        numbers. Working one out means measuring the gaps between values, and there's no defined
        gap between one category and the next, so any number we showed you would be invented.
      </div>
    <% end %>
  HTML

  @x_axis_title = 'Cycletime (days)'
  @y_axis_title = 'Estimate'

  @y_axis_type = 'linear'
  @y_axis_block = ->(issue, start_time) { estimate_at(issue: issue, start_time: start_time)&.to_f }
  @y_axis_sort_order = nil

  instance_eval(&configuration_block)
end

Instance Method Details

#bubble_radius(issue_count) ⇒ Object 



114
115
116
 
# File 'lib/jirametrics/estimate_accuracy_chart.rb', line 114

def bubble_radius issue_count
  (SINGLE_ISSUE_RADIUS * Math.sqrt(issue_count)).round 1
end

#bucket_issue_by_estimate(issue, completed_hash:, aging_hash:) ⇒ Object 



137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
 
# File 'lib/jirametrics/estimate_accuracy_chart.rb', line 137

def bucket_issue_by_estimate issue, completed_hash:, aging_hash:
  cycletime = issue.board.cycletime
  start_time, stop_time = cycletime.started_stopped_times(issue)

  return unless start_time

  hash = stop_time ? completed_hash : aging_hash

  estimate = @y_axis_block.call issue, start_time
  cycle_time = ((stop_time&.to_date || date_range.end) - start_time.to_date).to_i + 1

  return if estimate.nil?

  key = [estimate, cycle_time]
  (hash[key] ||= []) << issue
end

#correlation_coefficient(completed_hash) ⇒ Object 



215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
 
# File 'lib/jirametrics/estimate_accuracy_chart.rb', line 215

def correlation_coefficient completed_hash
  list1 = []
  list2 = []
  completed_hash.each do |(estimate, cycle_time), issues|
    issues.size.times do
      list1 << estimate
      list2 << cycle_time
    end
  end

  n = list1.size
  return nil if n < 2

  mean1 = list1.sum.to_f / n
  mean2 = list2.sum.to_f / n

  numerator = list1.zip(list2).sum { |x, y| (x - mean1) * (y - mean2) }
  sum_sq1 = list1.sum { |x| (x - mean1)**2 }
  sum_sq2 = list2.sum { |y| (y - mean2)**2 }

  denominator = Math.sqrt(sum_sq1 * sum_sq2)
  return nil if denominator.zero?

  numerator / denominator
end

#estimate_at(issue:, start_time:, estimation_configuration: current_board.estimation_configuration) ⇒ Object 



179
180
181
182
183
184
185
186
187
188
189
190
191
 
# File 'lib/jirametrics/estimate_accuracy_chart.rb', line 179

def estimate_at issue:, start_time:, estimation_configuration: current_board.estimation_configuration
  estimate = nil

  issue.changes.each do |change|
    return estimate if change.time >= start_time

    if change.field == estimation_configuration.display_name || change.field == estimation_configuration.field_id
      estimate = change.value
      estimate = estimate.to_f / (24 * 60 * 60) if estimation_configuration.units == :seconds
    end
  end
  estimate
end

#estimate_label(estimate:, estimation_units:) ⇒ Object 



118
119
120
121
122
123
124
125
126
127
128
 
# File 'lib/jirametrics/estimate_accuracy_chart.rb', line 118

def estimate_label estimate:, estimation_units:
  if @y_axis_type == 'linear'
    if estimation_units == :story_points
      estimate_label = "#{estimate}pts"
    elsif estimation_units == :seconds
      estimate_label = label_days estimate
    end
  end
  estimate_label = estimate.to_s if estimate_label.nil?
  estimate_label
end

#hash_sorter ⇒ Object 



154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
 
# File 'lib/jirametrics/estimate_accuracy_chart.rb', line 154

def hash_sorter
  lambda do |arg1, arg2|
    estimate1 = arg1[0][0]
    estimate2 = arg2[0][0]
    sample_count1 = arg1.size
    sample_count2 = arg2.size

    if @y_axis_sort_order
      index1 = @y_axis_sort_order.index estimate1
      index2 = @y_axis_sort_order.index estimate2

      if index1.nil?
        comparison = 1
      elsif index2.nil?
        comparison = -1
      else
        comparison = index1 <=> index2
      end
      return comparison unless comparison.zero?
    end

    sample_count2 <=> sample_count1
  end
end

#numeric_estimates?(completed_hash) ⇒ Boolean

Correlation coefficient is calculated using the Pearson Correlation Coefficient r = Σ((xi - x̄)(yi - ȳ)) / sqrt(Σ(xi - x̄)² · Σ(yi - ȳ)²) A Pearson coefficient is arithmetic on the distances between values, so it needs a scale where those distances mean something. T-shirt sizes are ordered but not spaced: nothing says the gap from M to L matches the gap from S to M. Summing them used to raise and take the export with it.

Returns:

  • (Boolean) 


209
210
211
212
213
 
# File 'lib/jirametrics/estimate_accuracy_chart.rb', line 209

def numeric_estimates? completed_hash
  return false if completed_hash.empty?

  completed_hash.keys.all? { |estimate, _cycle_time| estimate.is_a? Numeric }
end

#run ⇒ Object 



49
50
51
52
53
54
55
56
57
58
59
 
# File 'lib/jirametrics/estimate_accuracy_chart.rb', line 49

def run
  if @y_axis_title.nil?
    text = current_board.estimation_configuration.units == :story_points ? 'Story Points' : 'Days'
    @y_axis_title = "Estimated #{text}"
  end
  data_sets = scan_issues

  return render_no_data if data_sets.empty?

  wrap_and_render(binding, __FILE__)
end

#scan_issues ⇒ Object 



61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
 
# File 'lib/jirametrics/estimate_accuracy_chart.rb', line 61

def scan_issues
  completed_hash, aging_hash = split_into_completed_and_aging issues: issues
  @estimates_are_numeric = numeric_estimates? completed_hash
  @correlation_coefficient = correlation_coefficient(completed_hash) if @estimates_are_numeric
  estimation_units = current_board.estimation_configuration.units
  @has_aging_data = !aging_hash.empty?

  [
    [completed_hash, 'Completed', 'completed', false],
    [aging_hash, 'Still in progress', 'active', true]
  ].filter_map do |hash, label, completed_or_active, starts_hidden|
    fill_color = CssVariable["--estimate-accuracy-chart-#{completed_or_active}-fill-color"]
    border_color = CssVariable["--estimate-accuracy-chart-#{completed_or_active}-border-color"]

    # We sort so that the smaller circles are in front of the bigger circles.
    data = hash.sort(&hash_sorter).collect do |key, values|
      estimate, cycle_time = *key

      title = [
        "Estimate: #{estimate_label(estimate: estimate, estimation_units: estimation_units)}, " \
          "Cycletime: #{label_days(cycle_time)}, " \
          "#{values.size} issues"
      ] + values.collect { |issue| "#{issue.key}: #{issue.summary}" }

      {
        'x' => cycle_time,
        'y' => estimate,
        'r' => bubble_radius(values.size),
        'title' => title
      }
    end
    next if data.empty?

    {
      'label' => label,
      'data' => data,
      'fill' => false,
      'showLine' => false,
      'backgroundColor' => fill_color,
      'borderColor' => border_color,
      'hidden' => starts_hidden,
      # The active series is drawn as right pointing arrows rather than discs, because its
      # cycletime is a lower bound that keeps growing. The erb needs to know which one that is.
      'still_in_progress' => completed_or_active == 'active'
    }
  end
end

#split_into_completed_and_aging(issues:) ⇒ Object 



130
131
132
133
134
135
 
# File 'lib/jirametrics/estimate_accuracy_chart.rb', line 130

def split_into_completed_and_aging issues:
  aging_hash = {}
  completed_hash = {}
  issues.each { |issue| bucket_issue_by_estimate issue, completed_hash: completed_hash, aging_hash: aging_hash }
  [completed_hash, aging_hash]
end

#y_axis(label:, sort_order: nil, &block) ⇒ Object 



193
194
195
196
197
198
199
200
201
202
 
# File 'lib/jirametrics/estimate_accuracy_chart.rb', line 193

def y_axis label:, sort_order: nil, &block
  @y_axis_sort_order = sort_order
  @y_axis_label = label
  if sort_order
    @y_axis_type = 'category'
  else
    @y_axis_type = 'linear'
  end
  @y_axis_block = block
end