jirametrics 2.13 → 2.30

data/lib/jirametrics/throughput_chart.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'cgi'
+
 class ThroughputChart < ChartBase
   include GroupableIssueChart
 
@@ -10,42 +12,54 @@ class ThroughputChart < ChartBase
 
     header_text 'Throughput Chart'
     description_text <<-TEXT
-      <div class="p">
-        This chart shows how many items we completed per week
+      <div>Throughput data is very useful for#{' '}
+        <a href="https://blog.mikebowler.ca/2024/06/02/probabilistic-forecasting/">probabilistic forecasting</a>,
+        to determine when we'll be done. Try it now with the
+        <a href="<%= throughput_forecaster_url %>" target="_blank" rel="noopener noreferrer">
+        Focused Objective throughput forecaster,</a> to see how long it would take to complete all of the
+        <%= @not_started_count %> items you currently have in your backlog.
       </div>
       #{describe_non_working_days}
     TEXT
+    @x_axis_title = nil
+    @y_axis_title = 'Count of items'
 
     init_configuration_block(block) do
-      grouping_rules do |issue, rule|
-        rule.label = issue.type
-        rule.color = color_for type: issue.type
-      end
+      grouping_rules { |issue, rule| default_grouping_rules(issue, rule) }
     end
   end
 
   def run
+    # This is saved as an instance variable so that it's accessible later when rendering the description text
+    @not_started_count = issues.count { |issue| issue.started_stopped_times.first.nil? }
+
     completed_issues = completed_issues_in_range include_unstarted: true
     rules_to_issues = group_issues completed_issues
     data_sets = []
-    if rules_to_issues.size > 1
-      data_sets << weekly_throughput_dataset(
-        completed_issues: completed_issues,
-        label: 'Totals',
-        color: CssVariable['--throughput_chart_total_line_color'],
-        dashed: true
-      )
-    end
+    total_data_set = weekly_throughput_dataset(
+      completed_issues: completed_issues,
+      label: 'Totals',
+      color: CssVariable['--throughput_chart_total_line_color'],
+      dashed: true
+    )
+    @throughput_samples = total_data_set[:data].collect { |d| d[:y] }
+    data_sets << total_data_set if rules_to_issues.size > 1
 
     rules_to_issues.each_key do |rules|
       data_sets << weekly_throughput_dataset(
-        completed_issues: rules_to_issues[rules], label: rules.label, color: rules.color
+        completed_issues: rules_to_issues[rules], label: rules.label, color: rules.color,
+        label_hint: rules.label_hint
       )
     end
 
     wrap_and_render(binding, __FILE__)
   end
 
+  def default_grouping_rules issue, rule
+    rule.label = issue.type
+    rule.color = color_for type: issue.type
+  end
+
   def calculate_time_periods
     first_day = @date_range.begin
     first_day = case first_day.wday
@@ -65,10 +79,22 @@ class ThroughputChart < ChartBase
     end
   end
 
-  def weekly_throughput_dataset completed_issues:, label:, color:, dashed: false
+  def calculate_custom_periods
+    last_days = @issue_periods.values.compact.uniq.sort
+    last_days.each_with_index.map do |last_day, i|
+      first_day = i.zero? ? @date_range.begin : last_days[i - 1] + 1
+      first_day..last_day
+    end
+  end
+
+  def weekly_throughput_dataset completed_issues:, label:, color:, dashed: false, label_hint: nil
+    periods = @issue_periods&.values&.any? ? calculate_custom_periods : calculate_time_periods
     result = {
       label: label,
-      data: throughput_dataset(periods: calculate_time_periods, completed_issues: completed_issues),
+      label_hint: label_hint,
+      data: throughput_dataset(
+        periods: periods, completed_issues: completed_issues, label_hint: label_hint
+      ),
       fill: false,
       showLine: true,
       borderColor: color,
@@ -79,20 +105,44 @@ class ThroughputChart < ChartBase
     result
   end
 
-  def throughput_dataset periods:, completed_issues:
+  def throughput_forecaster_url
+    params = {
+      throughputMode: 'data',
+      samplesText: @throughput_samples.join(','),
+      storyLow: @not_started_count,
+      storyHigh: @not_started_count
+    }
+
+    query = params.map { |k, v| "#{k}=#{CGI.escape(v.to_s)}" }.join('&')
+    "https://focusedobjective.com/throughput?#{query}"
+  end
+
+  def throughput_dataset periods:, completed_issues:, label_hint: nil
+    custom_mode = @issue_periods&.values&.any?
     periods.collect do |period|
       closed_issues = completed_issues.filter_map do |issue|
-        stop_date = issue.board.cycletime.started_stopped_dates(issue).last
-        [stop_date, issue] if stop_date && period.include?(stop_date)
+        stop_date = issue.started_stopped_dates.last
+        next unless stop_date
+
+        if custom_mode
+          [stop_date, issue] if @issue_periods[issue] == period.end
+        elsif period.include?(stop_date)
+          [stop_date, issue]
+        end
       end
 
       date_label = "on #{period.end}"
       date_label = "between #{period.begin} and #{period.end}" unless period.begin == period.end
 
-      { y: closed_issues.size,
+      with_label_hint = label_hint ? " with #{label_hint}" : ''
+      {
+        y: closed_issues.size,
         x: "#{period.end}T23:59:59",
-        title: ["#{closed_issues.size} items completed #{date_label}"] +
-          closed_issues.collect { |_stop_date, issue| "#{issue.key} : #{issue.summary}" }
+        title: ["#{closed_issues.size} items closed#{with_label_hint} #{date_label}"] +
+          closed_issues.collect do |_stop_date, issue|
+            hint = @issue_hints&.fetch(issue, nil)
+            "#{issue.key} : #{issue.summary}#{" #{hint}" if hint}"
+          end
       }
     end
   end

data/lib/jirametrics/time_based_histogram.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require 'jirametrics/groupable_issue_chart'
+
+class TimeBasedHistogram < ChartBase
+  include GroupableIssueChart
+
+  attr_reader :show_stats
+
+  def initialize
+    super
+
+    percentiles [50, 85, 98]
+    @show_stats = true
+  end
+
+  def percentiles percs = nil
+    @percentiles = percs unless percs.nil?
+    @percentiles
+  end
+
+  def disable_stats
+    @show_stats = false
+  end
+
+  def run
+    histogram_items = all_items
+    rules_to_items = group_issues histogram_items
+
+    the_stats = {}
+
+    overall_histogram = histogram_data_for(items: histogram_items).transform_values(&:size)
+    the_stats[:all] = stats_for histogram_data: overall_histogram, percentiles: @percentiles
+    data_sets = rules_to_items.keys.collect do |rules|
+      the_label = rules.label
+      the_histogram = histogram_data_for(items: rules_to_items[rules])
+      if @show_stats
+        the_stats[the_label] = stats_for(
+          histogram_data: the_histogram.transform_values(&:size), percentiles: @percentiles
+        )
+      end
+
+      data_set_for(
+        histogram_data: the_histogram,
+        label: the_label,
+        color: rules.color
+      )
+    end
+
+    if data_sets.empty?
+      return "<h1 class='foldable'>#{@header_text}</h1>" \
+             '<div>No data matched the selected criteria. Nothing to show.</div>'
+    end
+
+    wrap_and_render(binding, __FILE__)
+  end
+
+  def histogram_data_for items:
+    items_hash = {}
+    items.each do |item|
+      days = value_for_item item
+      (items_hash[days] ||= []) << item if days.positive?
+    end
+    items_hash
+  end
+
+  def stats_for histogram_data:, percentiles:
+    return {} if histogram_data.empty?
+
+    total_values = histogram_data.values.sum
+
+    # Calculate the average
+    weighted_sum = histogram_data.reduce(0) { |sum, (value, frequency)| sum + (value * frequency) }
+    average = total_values.zero? ? 0 : weighted_sum.to_f / total_values
+
+    # Find the mode (or modes!) and the spread of the distribution
+    sorted_histogram = histogram_data.sort_by { |_value, frequency| frequency }
+    max_freq = sorted_histogram[-1][1]
+    mode = sorted_histogram.select { |_v, f| f == max_freq }
+
+    minmax = histogram_data.keys.minmax
+
+    # Calculate percentiles
+    sorted_values = histogram_data.keys.sort
+    cumulative_counts = {}
+    cumulative_sum = 0
+
+    sorted_values.each do |value|
+      cumulative_sum += histogram_data[value]
+      cumulative_counts[value] = cumulative_sum
+    end
+
+    percentile_results = {}
+    percentiles.each do |percentile|
+      rank = (percentile / 100.0) * total_values
+      percentile_value = sorted_values.find { |value| cumulative_counts[value] >= rank }
+      percentile_results[percentile] = percentile_value
+    end
+
+    {
+      average: average,
+      mode: mode.collect(&:first).sort,
+      min: minmax[0],
+      max: minmax[1],
+      percentiles: percentile_results
+    }
+  end
+
+  def sort_items items
+    items
+  end
+
+  def label_for_item item, hint:
+    raise NotImplementedError, "#{self.class} must implement label_for_item"
+  end
+
+  def data_set_for histogram_data:, label:, color:
+    {
+      type: 'bar',
+      label: label,
+      data: histogram_data.keys.sort.filter_map do |days|
+        items = histogram_data[days]
+        next if items.empty?
+
+        {
+          x: days,
+          y: items.size,
+          title: [title_for_item(count: items.size, value: days)] +
+            sort_items(items).collect do |item|
+              hint = @issue_hints&.fetch(item, nil)
+              label_for_item(item, hint: hint)
+            end
+        }
+      end,
+      backgroundColor: color,
+      borderRadius: 0
+    }
+  end
+end

data/lib/jirametrics/time_based_scatterplot.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require 'jirametrics/groupable_issue_chart'
+
+class TimeBasedScatterplot < ChartBase
+  include GroupableIssueChart
+
+  def initialize
+    super
+
+    @percentage_lines = []
+    @highest_y_value = 0
+  end
+
+  def run
+    items = all_items
+    data_sets = create_datasets items
+    overall_percent_line = calculate_percent_line(items)
+    @percentage_lines << [overall_percent_line, CssVariable['--cycletime-scatterplot-overall-trendline-color']]
+
+    return "<h1 class='foldable'>#{@header_text}</h1><div>No data matched the selected criteria. Nothing to show.</div>" if data_sets.empty?
+
+    wrap_and_render(binding, __FILE__)
+  end
+
+  def create_datasets items
+    data_sets = []
+
+    group_issues(items).each do |rules, items_by_type|
+      label = rules.label
+      color = rules.color
+      percent_line = calculate_percent_line items_by_type
+      data = items_by_type.filter_map { |item| data_for_item(item, rules: rules) }
+      data_sets << {
+        label: "#{label} (85% at #{label_days(percent_line)})",
+        data: data,
+        fill: false,
+        showLine: false,
+        backgroundColor: color
+      }
+
+      data_sets << trend_line_data_set(label: label, data: data, color: color)
+
+      @percentage_lines << [percent_line, color]
+    end
+    data_sets
+  end
+
+  def show_trend_lines
+    @show_trend_lines = true
+  end
+
+  def trend_line_data_set label:, data:, color:
+    points = data.collect do |hash|
+      [Time.parse(hash[:x]).to_i, hash[:y]]
+    end
+
+    # The trend calculation works with numbers only so convert Time to an int and back
+    calculator = TrendLineCalculator.new(points)
+    data_points = calculator.chart_datapoints(
+      range: time_range.begin.to_i..time_range.end.to_i,
+      max_y: @highest_y_value
+    )
+    data_points.each do |point_hash|
+      point_hash[:x] = chart_format Time.at(point_hash[:x])
+    end
+
+    {
+      type: 'line',
+      label: "#{label} Trendline",
+      data: data_points,
+      fill: false,
+      borderWidth: 1,
+      markerType: 'none',
+      borderColor: color,
+      borderDash: [6, 3],
+      pointStyle: 'dash',
+      hidden: !@show_trend_lines
+    }
+  end
+
+  def minimum_y_value
+    nil
+  end
+
+  def data_for_item item, rules: nil
+    y = y_value(item)
+    min = minimum_y_value
+    return nil if min && y < min
+
+    @highest_y_value = y if @highest_y_value < y
+
+    {
+      y: y,
+      x: chart_format(x_value(item)),
+      title: [title_value(item, rules: rules)]
+    }
+  end
+
+  def calculate_percent_line items
+    min = minimum_y_value
+    times = items.collect { |item| y_value(item) }
+    times.reject! { |y| min && y < min }
+    index = times.size * 85 / 100
+    times.sort[index]
+  end
+end

data/lib/jirametrics/wip_by_column_chart.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+require 'jirametrics/chart_base'
+
+class WipByColumnChart < ChartBase
+  attr_accessor :possible_statuses, :board_id
+
+  ColumnStats = Struct.new(:name, :min_wip_limit, :max_wip_limit, :wip_history, keyword_init: true)
+
+  def initialize block
+    super()
+    header_text 'WIP by column'
+    description_text <<-HTML
+      <p>
+        This chart shows how much time each board column has spent at different WIP (Work in Progress) levels.
+      </p>
+      <p>
+        Each row on the Y axis is a WIP level (the number of items in that column at the same time).
+        Each column on the X axis is a board column.
+        The horizontal bars show what percentage of the total time that column spent at that WIP level —
+        a wider bar means more time was spent there.
+      </p>
+      <p>
+        A column whose widest bar is at WIP&nbsp;1 was almost always working on one item at a time, often called
+        single-piece-flow. This team is likely collaborating very well and might have been
+        <a href="https://blog.mikebowler.ca/2021/06/19/pair-programming/">pairing</a> or
+        <a href="https://blog.mikebowler.ca/2023/04/22/ensemble-programming/">mobbing/ensembling</a>
+        and these teams tend to be very effective.
+      </p>
+      <p>
+        A column with wide bars at high WIP levels usually indicates a team that is highly siloed. Where each person
+        is working by themselves.
+      </p>
+      <p>
+        The dashed lines show the minimum and maximum WIP limits configured on the board.
+        If the widest bar sits well above the maximum limit, the limit may be set too low or not being respected.
+        If the widest bar sits below the minimum limit, consider whether that limit is still meaningful.
+      </p>
+      <p>
+        Hover over any bar to see the exact percentage.
+      </p>
+      <% if @all_boards[@board_id].team_managed_kanban? %>
+        <p>
+          If the data looks a bit off then that's probably because you're using a Team Managed project in "kanban mode".
+          For this specific case, we are unable to tell if an item is actually visible on the board and so we may
+          be reporting more items started than you actually see on the board. See
+          <a href="https://jirametrics.org/faq/#team-managed-kanban-backlog">the FAQ</a>.
+        </p>
+      <% end %>
+    HTML
+
+    instance_eval(&block)
+  end
+
+  def show_recommendations
+    @show_recommendations = true
+  end
+
+  def run
+    @header_text += " on board: #{current_board.name}"
+    stats = column_stats
+    @column_names = stats.collect(&:name)
+    @wip_data = stats.collect do |stat|
+      total = stat.wip_history.sum { |_wip, seconds| seconds }.to_f
+      next [] if total.zero?
+
+      stat.wip_history.collect { |wip, seconds| { 'wip' => wip, 'pct' => format_pct(seconds, total) } }
+    end
+    @max_wip = stats.flat_map { |s| s.wip_history.collect { |wip, _| wip } }.max || 0
+    @wip_limits = stats.collect { |s| { 'min' => s.min_wip_limit, 'max' => s.max_wip_limit } }
+    @recommendations = @show_recommendations ? compute_recommendations(stats) : Array.new(stats.size)
+
+    trim_zero_end_columns
+    @recommendation_texts = @show_recommendations ? build_recommendation_texts : []
+
+    wrap_and_render(binding, __FILE__)
+  end
+
+  def column_stats
+    board = current_board
+    columns = board.visible_columns
+    status_to_column = build_status_to_column_map(columns)
+    relevant_issues = @issues.select { |issue| issue.board.id == @board_id }
+
+    current_column = initial_column_state(relevant_issues, status_to_column)
+    events = events_within_range(relevant_issues, status_to_column)
+    column_wip_seconds = compute_wip_seconds(columns, current_column, events)
+
+    columns.collect.with_index do |column, index|
+      ColumnStats.new(
+        name: column.name,
+        min_wip_limit: column.min,
+        max_wip_limit: column.max,
+        wip_history: column_wip_seconds[index].sort.to_a
+      )
+    end
+  end
+
+  private
+
+  def trim_zero_end_columns
+    all_zero = @wip_data.map { |col| col.none? { |e| e['wip'].positive? } }
+    first = all_zero.index(false)
+    return unless first
+
+    last = all_zero.rindex(false)
+    @column_names    = @column_names[first..last]
+    @wip_data        = @wip_data[first..last]
+    @wip_limits      = @wip_limits[first..last]
+    @recommendations = @recommendations[first..last]
+    @max_wip         = @wip_data.flat_map { |col| col.map { |e| e['wip'] } }.max || 0
+  end
+
+  def compute_recommendations stats
+    stats.collect do |stat|
+      next nil if stat.wip_history.empty?
+
+      total = stat.wip_history.sum { |_wip, seconds| seconds }.to_f
+      next nil if total.zero?
+
+      cumulative = 0
+      stat.wip_history.sort.find do |_wip, seconds|
+        cumulative += seconds
+        cumulative / total >= 0.85
+      end&.first
+    end
+  end
+
+  def build_recommendation_texts
+    @column_names.each_with_index.filter_map do |name, i|
+      rec = @recommendations[i]
+      next if rec.nil?
+
+      next "Almost nothing passes through column '#{name}'. Do we still need it?" if rec.zero?
+
+      max = @wip_limits[i]['max']
+      if max.nil?
+        "Add a WIP limit to column '#{name}' — suggested maximum: #{rec}"
+      elsif rec < max
+        "Lower the WIP limit for '#{name}' from #{max} to #{rec}"
+      elsif rec > max
+        "Raise the WIP limit for '#{name}' from #{max} to #{rec}"
+      end
+    end
+  end
+
+  def format_pct seconds, total
+    raw = seconds / total * 100.0
+    (1..10).each do |decimals|
+      rounded = raw.round(decimals)
+      next if rounded.zero? && raw.positive?
+      next if rounded >= 100.0 && raw < 100.0
+
+      return rounded
+    end
+    raw
+  end
+
+  def build_status_to_column_map columns
+    columns.each_with_object({}).with_index do |(column, map), index|
+      column.status_ids.each { |id| map[id] = index }
+    end
+  end
+
+  def initial_column_state relevant_issues, status_to_column
+    relevant_issues.each_with_object({}) do |issue, hash|
+      started_time, stopped_time = issue.board.cycletime.started_stopped_times(issue)
+      in_wip = started_time &&
+               started_time <= time_range.begin &&
+               (stopped_time.nil? || stopped_time > time_range.begin)
+      unless in_wip
+        hash[issue] = nil
+        next
+      end
+
+      last_change = issue.status_changes.reverse.find { |c| c.time <= time_range.begin }
+      hash[issue] = last_change ? status_to_column[last_change.value_id] : nil
+    end
+  end
+
+  def events_within_range relevant_issues, status_to_column
+    events = []
+    relevant_issues.each do |issue|
+      started_time, stopped_time = issue.board.cycletime.started_stopped_times(issue)
+      next unless started_time
+
+      # Issue starts within the window: add an explicit event to enter WIP in its current column
+      if started_time > time_range.begin && started_time <= time_range.end
+        last_change = issue.status_changes.reverse.find { |c| c.time <= started_time }
+        events << [started_time, issue, last_change ? status_to_column[last_change.value_id] : nil]
+      end
+
+      # Status changes while the issue is actively in WIP and within the window
+      issue.status_changes.each do |change|
+        next unless change.time > time_range.begin
+        next if change.time > time_range.end
+        next unless change.time >= started_time
+        next if stopped_time && change.time >= stopped_time
+
+        events << [change.time, issue, status_to_column[change.value_id]]
+      end
+
+      # Issue stops within the window: add an explicit event to exit WIP
+      if stopped_time && stopped_time > time_range.begin && stopped_time <= time_range.end
+        events << [stopped_time, issue, nil]
+      end
+    end
+    events.sort_by!(&:first)
+  end
+
+  def compute_wip_seconds columns, current_column, events
+    wip_counts = Array.new(columns.size, 0)
+    current_column.each_value { |col| wip_counts[col] += 1 unless col.nil? }
+
+    column_wip_seconds = Array.new(columns.size) { Hash.new(0) }
+    prev_time = time_range.begin
+
+    events.each do |time, issue, new_col|
+      elapsed = (time - prev_time).to_i
+      if elapsed.positive?
+        wip_counts.each_with_index { |wip, idx| column_wip_seconds[idx][wip] += elapsed }
+        prev_time = time
+      end
+
+      old_col = current_column[issue]
+      wip_counts[old_col] -= 1 unless old_col.nil?
+      wip_counts[new_col] += 1 unless new_col.nil?
+      current_column[issue] = new_col
+    end
+
+    elapsed = (time_range.end - prev_time).to_i
+    wip_counts.each_with_index { |wip, idx| column_wip_seconds[idx][wip] += elapsed } if elapsed.positive?
+
+    column_wip_seconds
+  end
+end