Learn how to use Formatters to prepare series for charts.

Formatters

Having series of data available is cool, but you know whats even cooler? Having bunch of charts to visualize them. Sorry, I couldn't help myself.

The purpose of formatters is exactly that. To help you to prepare series for a charting library. Every library is different, but they all come together in requiring the data to be in a list of values. Sometimes this can be a list of simple values, list of hashes with x and y keys or list of lists with coordinates.

They plug seamelessly into Seriesand can be used through dot notation.

series = Trifle::Stats.series(...)
=> #<Trifle::Stats::Series:0x0000ffffa14256e8 @series={:at=>[2024-03-22 19:38:00 +0000, 2024-03-22 19:39:00 +0000], :values=>[{events: {count: 42, sum: 2184}}, {events: {count: 33, sum: 1553}}]}>
series.format.timeline(path: 'events.count')
=> [[2024-03-22 19:38:00 +0000, 42], [2024-03-22 19:39:00 +0000, 33]]

Note: path is a list of keys joined by dot. Ie orders.shipped.count would represent value at {orders: { shipped: { count: ... } } }.

Custom Formatters

You can use one of predefined formatters or write your own. Formatter needs to implement at least one method that accepts key parameters series:and path: and returns array of formatted results. The series:is passed in automatically.

class MyFormatter
  def format(series:, path:)
    series[:at].map do |at|
      [at.to_i, rand(1000)]
    end
  end
end

If you write your own formatter and would like to access it through dot notation, you need to register it through Trifle::Stats::Series.register_formatter(NAME, self) inside of your formatter class.

class MyFormatter
  Trifle::Stats::Series.register_formatter(:rand, self)

  def format(series:, path:)
    series[:at].map do |at|
      [at.to_i, rand(1000)]
    end
  end
end

And from there you can access it through series.format.rand(path: 'a.count')