Feat/episode sparklines #1386

radical-ube · 2025-11-24T19:43:18Z

This PR adds sparklines and trend numbers to the episode cards on the Podcast dashboard. With the updated designs, I am slowly refactoring the podcast_metrics_controller and various apex stimulus controllers because some of the code can still be repurposed. The updated podcast dashboard has several charts in it, so I plan on using the podcast_metrics_controller to handle as much of the metrics querying as possible so as not to bloat the podcast_controller.

With the case of the sparklines, each episode card has its own turbo frame, which sources from podcast_metrics#episode_sparkline for each of their individual querying needs. alltime_downloads pulls data for the sparkline itself, while the episode_trend include the dropdate queries for the episode and the previously published episode.

There is a little bit of a question around what is our opinion of trending_flat, and the threshhold we would consider whether a change is significant enough to signal trend in a particular direction.

@cavis for code review
@brandonhundt for design review

app/controllers/concerns/metrics_utils.rb

app/controllers/podcast_metrics_controller.rb

radical-ube · 2025-11-24T20:37:21Z

app/controllers/podcast_metrics_controller.rb

-  end
+  def calculate_episode_trend(episode, prev_episode)
+    return nil if (episode.first_rss_published_at + 1.day) > Date.utc_today
+    return nil unless episode.present? && prev_episode.present?


2 guards here: first, don't calculate a trend if the episode just dropped and it hasn't been 24 hours. second, don't calculate a trend if there isn't a previous episode to calculate from.

Should this be Time.now, not Date.utc_today?

If it's first_rss_published_at is 12/2 9:18 UTC... are we waiting until 12/3 00:00 UTC or 12/3 9:18 UTC to show it?

radical-ube · 2025-11-24T20:41:05Z

app/controllers/podcast_metrics_controller.rb

-        uniques_selection: "last_7_rolling"
-      )
-      .merge(metrics_params)
+    ((ep_sum.to_f / prev_ep_sum.to_f) - 1).round(2)


correct math/thinking? the staging data numbers seem a bit outlandish (> 10% changes) because of how extreme the differences seem, but i'm not sure if this looks tamer in prod.

i think i'm still missing some guards to prevent weird edge cases like this. maybe something around the case where one of the dropday queries doesn't return anything?

Is there a chance we can load this against a prod db? This way we might be able to see the edge cases a little easier.

radical-ube · 2025-11-24T20:44:53Z

app/controllers/podcasts_controller.rb

    text.gsub(/[&<>]/, "&" => "&amp;", "<" => "&lt;", ">" => "&gt;")
  end
+
+  def episode_trend_pairs(episodes)


trying not to do extra querying in podcast_metrics_controller so i pair episodes with their previous episode here.

radical-ube · 2025-11-24T20:49:03Z

app/helpers/metrics_helper.rb

  end

+  def parse_trend(trend)
+    return if trend.nil?


for the view, i use this helper to determine the visuals. for trending_flat i've arbitrarily chosen 5%, but could easily change it to 2 or 3% or whichever number we decide on makes sense.

@radical-ube 5% seems a good place to start.

i wonder about this at various tiers though. like a podcast going from 2000 to 2100 (5% increase) maybe feels kinda small and not too significant. but 20000 to 21000 (still 5%) might be a bit more notable. so are there certain threshholds, maybe based on the size of the podcast or some other characteristics, where we do want to highlight, "hey, your latest episode is trending (up or down) much larger than usual" that might not be solely based on the percentage?

or should it be equal across all podcasts?

radical-ube · 2025-11-24T20:50:50Z

app/javascript/controllers/apex_sparkline_controller.js

@@ -1,27 +1,34 @@
 import { Controller } from "@hotwired/stimulus"
-import { buildDateTimeChart, buildDownloadsSeries, dynamicBarAndAreaType } from "util/apex"
+import { buildSparklineChart, destroyChart } from "util/apex"


repurposing this controller for the sparklines charts.

radical-ube · 2025-11-24T20:53:01Z

app/views/metrics/_episode_sparkline.html.erb

+  <% trend = parse_trend(episode_trend) %>
+  <div class="d-flex align-items-center <%= trend[:color] %>">
+    <span><%= trend[:percent] if trend.present? %></span>
+    <span class="material-icons ms-1" aria-hidden="true"><%= trend[:direction] if trend.present? %></span>


trend shouldn't render unless it has passed all the conditionals

radical-ube · 2025-11-24T20:54:37Z

app/views/metrics/_episode_sparkline.html.erb

+    data-controller="apex-downloads"
+    data-apex-downloads-id-value="<%= episode.guid %>"
+    data-apex-downloads-downloads-value="<%= downloads.to_json %>">
+    <div data-apex-downloads-target="chart"></div>


the sparkline chart is positioned/translated to fill the episode card. it has the tooltip removed and also z-index 0 so that it is not interactable and doesn't interfere with clicking the episode link.

Functionally great! Thanks for disabling the interactions for this.

Have you attempted updating the styling of the chart? Adding the gradient from the design file?:
?

there is currently a vertical gradient on the chart. i can make the border line transparent if that's helpful in seeing it.

+1 to making the the border line transparent.

Can we change the colors in the gradient?

what colors do you want?

#F3EAFF #DBFBFB

The light-blue would represent the higher value

radical-ube · 2025-11-24T20:57:18Z

app/views/metrics/_episodes_card.html.erb

-    <%= form.date_field :date_end, class: "d-none", data: {apex_nav_target: "endDate", action: "change->click#submit"}, value: date_end %>
-    <%= form.select :interval, interval_options, {selected: interval}, class: "d-none", data: {apex_nav_target: "interval", action: "change->click#submit", path: "episodes"} %>
-    <%= form.submit class: "d-none", data: {click_target: "submit"} %>
+<div class="episode-card-info inside-card flex-fill px-3 py-2 position-relative">


repurposing this partial for the published episode cards.

radical-ube · 2025-11-24T20:57:50Z

app/views/metrics/_error_card.html.erb

+      Clickhouse not connected
+    </div>
+  <% end %>
+<% elsif card_type == "blank" %>


don't render anything for the sparklines if clickhouse is not connected.

radical-ube · 2025-11-24T20:59:25Z

app/views/podcasts/show.html.erb

-                  <h2 class="h5 episode-card-title m-0"><%= link_to ep.title, episode_path(ep) %></h2>
-                </div>
-              </div>
+          <% if Rails.env.development? %>


keeping the sparklines in development until we release metrics > feeder.

cavis

Structurally, I think this all looks right. My questions are about the specific data/calculations. (Also see: slack thread in tech-feeder!)

app/controllers/concerns/metrics_utils.rb

app/controllers/podcast_metrics_controller.rb

cavis · 2025-12-03T20:24:31Z

app/controllers/podcast_metrics_controller.rb

-  end
+  def calculate_episode_trend(episode, prev_episode)
+    return nil if (episode.first_rss_published_at + 1.day) > Date.utc_today
+    return nil unless episode.present? && prev_episode.present?


Should this be Time.now, not Date.utc_today?

If it's first_rss_published_at is 12/2 9:18 UTC... are we waiting until 12/3 00:00 UTC or 12/3 9:18 UTC to show it?

app/controllers/podcast_metrics_controller.rb

radical-ube · 2025-12-04T21:47:13Z

app/controllers/podcasts_controller.rb


-    @recently_published = @podcast.episodes.published.dropdate_desc.limit(3)
+    @recently_published_episodes = @podcast.episodes.published.dropdate_desc.limit(4)
+    @trend_episodes = @podcast.default_feed.episodes.published.dropdate_desc.where.not(first_rss_published_at: nil).offset(1).limit(4)


here i am pulling the episodes to be compared against in the trend calculation. offset by 1 because i don't want the most recent one.

radical-ube · 2025-12-04T21:49:37Z

app/controllers/podcasts_controller.rb

    text.gsub(/[&<>]/, "&" => "&amp;", "<" => "&lt;", ">" => "&gt;")
  end
+
+  def episode_trend_pairs(episodes, trend_episodes)


and here i realized that i didn't want to necessarily pair episode and trend episode 1:1. i still needed to check if an episode should have a trend number at all, and then count which trend_episodes have been used in pairing. in most cases this should still line up 1:1, but should catch the cases where there's an episode that is not in the default feed and needs to be skipped in trend calculation.

Since these are in separate turbo requests, you could just find which episode you should compare to in that other request? It avoids any kind of N+1, not attempting to pair them all upfront. And makes the outer request quicker.

Episode.where(podcast_id: ep.podcast_id, first_rss_published_at: ..ep.first_rss_published_at).order(first_rss_published_at: :desc).first

(Not a request for change in this PR, just something to think about ... optimize for the outer/first GET request).

added to #1400

cavis

Couple minor things on data loading, but otherwise this is looking good! Also, I understand what a sparkline is now.

app/controllers/podcast_metrics_controller.rb

radical-ube · 2025-12-15T21:48:08Z

app/controllers/podcast_metrics_controller.rb

-  before_action :set_date_range, except: %i[dropdays]
-  before_action :set_uniques, only: %i[show uniques]
-  before_action :set_dropday_range, only: %i[show dropdays]
+  # before_action :check_clickhouse, except: %i[show]


kind of an aside (for me) for later, but i frequently (but not consistently always) get errors when trying to refresh the view and get aclickhouse_connected "no method" error. including ClickhouseUtils module both in this controller and the MetricsUtils concern didn't seem to fix, so i'll have to take a closer look in a future PR.

radical-ube · 2025-12-15T21:49:02Z

app/controllers/podcast_metrics_controller.rb

-        dropday_range: 7
-      )
-      .merge(metrics_params)
+  def publish_hour(episode)


is this accurate? trying to address the .beginning_of_hour comment but also catching episodes that don't have .first_rss_published_at.

I would probably just return a 0 / empty array, instead of querying clickhouse at all, if that's nil.

The implication is, this episode was never written to the default feed. So you're not going to find any data in Clickhouse.

Kind of surprised it got to querying clickhouse - i thought you had some early-returns when first_rss_published_at was nil?

added to #1400

cavis

👍 looks good to me! Onwards!

cavis · 2025-12-16T16:16:02Z

app/controllers/podcast_metrics_controller.rb

-        dropday_range: 7
-      )
-      .merge(metrics_params)
+  def publish_hour(episode)


I would probably just return a 0 / empty array, instead of querying clickhouse at all, if that's nil.

The implication is, this episode was never written to the default feed. So you're not going to find any data in Clickhouse.

Kind of surprised it got to querying clickhouse - i thought you had some early-returns when first_rss_published_at was nil?

cavis · 2025-12-16T16:19:08Z

app/controllers/podcasts_controller.rb

    text.gsub(/[&<>]/, "&" => "&amp;", "<" => "&lt;", ">" => "&gt;")
  end
+
+  def episode_trend_pairs(episodes, trend_episodes)


Since these are in separate turbo requests, you could just find which episode you should compare to in that other request? It avoids any kind of N+1, not attempting to pair them all upfront. And makes the outer request quicker.

Episode.where(podcast_id: ep.podcast_id, first_rss_published_at: ..ep.first_rss_published_at).order(first_rss_published_at: :desc).first

(Not a request for change in this PR, just something to think about ... optimize for the outer/first GET request).

radical-ube added 4 commits November 21, 2025 11:59

Add sparkline chart into episode card

fffd32a

Move sparkline query into podcast metrics controller

1e807d4

Add trend percentages

c2237e2

Handle clickhouse

d4fa1cf

radical-ube commented Nov 24, 2025

View reviewed changes

app/controllers/concerns/metrics_utils.rb Show resolved Hide resolved

radical-ube commented Nov 24, 2025

View reviewed changes

app/controllers/podcast_metrics_controller.rb Show resolved Hide resolved

radical-ube commented Nov 24, 2025

View reviewed changes

radical-ube requested review from brandonhundt and cavis November 24, 2025 21:00

radical-ube added 2 commits November 25, 2025 16:14

Add gradient colors to sparkline

caf92ad

Add positive and negative signs to trend numbers

65237da

cavis requested changes Dec 3, 2025

View reviewed changes

radical-ube added 2 commits December 4, 2025 13:21

Fix lowerbound on episode trend query

d767717

Account for default feed episodes in trend numbers

2c4452c

radical-ube commented Dec 4, 2025

View reviewed changes

app/controllers/podcast_metrics_controller.rb Show resolved Hide resolved

Account for episodes that should not have a trend pair

7f056b4

radical-ube commented Dec 4, 2025

View reviewed changes

radical-ube added 2 commits December 5, 2025 15:47

Add one more guard

5a68772

Add async to dropday querying

fc723ad

radical-ube mentioned this pull request Dec 11, 2025

Feat/podcast scorecards dashboard #1395

Open

2 tasks

Fix query to remove between upperbound

d6e5b62

cavis requested changes Dec 12, 2025

View reviewed changes

Fix bounds on sparkline query and rounding error

84330c3

radical-ube commented Dec 15, 2025

View reviewed changes

cavis reviewed Dec 16, 2025

View reviewed changes

radical-ube mentioned this pull request Dec 16, 2025

metrics > feeder: controller fine-tuning #1400

Open

4 tasks

radical-ube merged commit cc30a2f into main Dec 16, 2025
3 checks passed

radical-ube deleted the feat/episode_sparklines branch December 16, 2025 16:46

Feat/episode sparklines #1386

Feat/episode sparklines #1386

Uh oh!

Conversation

radical-ube commented Nov 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

radical-ube Nov 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

radical-ube Nov 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cavis left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cavis left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

radical-ube commented Nov 24, 2025 •

edited

Loading

radical-ube Nov 25, 2025 •

edited

Loading

radical-ube Nov 24, 2025 •

edited

Loading