feat(Dr. Rai Reports): Optimize Titration Indicator Data (#5650)

**Story card:**
[sc-16391](https://app.shortcut.com/simpledotorg/story/16391/optimize-data-load-for-titration-indicator)

## Because

Running the SQL query within the reqyest lifecycle causes a timeout in
environments which have plenty data.

## This addresses

- Creating a table / model which would hold the data for the indicator
- Load in the data from teh SQL query
- Adding a rake task for populating the data; manually and on schedule

## Test instructions

suite-tests

Author: igbanam

app/components/dashboard/dr_rai_report.html.erb

@@ -249,7 +249,7 @@
       } else {
         if (target.ui == 'percent') {
           var previousPercentage
-          if (indicator.previous_numerator < 1) {
+          if (indicator.previous_numerator < 1 || indicator.denominator == '' || indicator.denominator === undefined) {
             previousPercentage = 0
           } else {
             previousPercentage = Math.round(indicator.previous_numerator / indicator.denominator * 100)

app/models/concerns/dr_rai/chartable.rb

@@ -0,0 +1,47 @@
+# Contains methods required to transform data from their normal form to chartable data
+module DrRai
+  module Chartable
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def chartable_internal_keys *keys
+        @chartable_internal_keys = keys.map(&:to_sym)
+      end
+
+      def chartable_period_key key
+        @chartable_period_key = key.to_sym
+      end
+
+      def chartable_outer_grouping key
+        @chartable_outer_grouping = key.to_sym
+      end
+
+      def chartable
+        result = {}
+        all.each do |record|
+          period_key = @chartable_period_key
+          the_period = Period.quarter(record.send(period_key))
+
+          internal_keys = @chartable_internal_keys
+          internal_data = internal_keys.map { |k| [k, record.send(k)] }.to_h
+
+          outer_grouping = record.send @chartable_outer_grouping
+          if result.has_key? outer_grouping
+            if result[outer_grouping].has_key?(the_period)
+              internal_keys.each do |k|
+                result[outer_grouping][the_period][k] += record.send(k)
+              end
+            else
+              result[outer_grouping][the_period] = internal_data
+            end
+          else
+            result[outer_grouping] = {
+              the_period => internal_data
+            }
+          end
+        end
+        result
+      end
+    end
+  end
+end

app/models/dr_rai/data.rb

@@ -0,0 +1,5 @@
+module DrRai::Data
+  def self.table_name_prefix
+    "dr_rai_data_"
+  end
+end

app/models/dr_rai/data/titration.rb

@@ -0,0 +1,9 @@
+class DrRai::Data::Titration < ApplicationRecord
+  include DrRai::Chartable
+
+  default_scope { where(month_date: 1.year.ago..Date.today) }
+
+  chartable_internal_keys :follow_up_count, :titrated_count
+  chartable_period_key :month_date
+  chartable_outer_grouping :facility_name
+end

app/models/dr_rai/titration_indicator.rb

@@ -4,8 +4,8 @@ class TitrationIndicator < Indicator
 
     def datasource(region)
       @region = region
-      @query ||= TitrationQuery.new(region).call
-      @query[region.name]
+      @source ||= DrRai::Data::Titration.chartable
+      @source[region.name]
     end
 
     def display_name
@@ -17,11 +17,11 @@ def target_type_frontend
     end
 
     def numerator_key
-      "titrated"
+      :titrated_count
     end
 
     def denominator_key
-      "patients"
+      :follow_up_count
     end
 
     def action_passive

app/queries/dr_rai/query_factory.rb

@@ -0,0 +1,70 @@
+module DrRai
+  # Query Factory
+  #
+  # When creating SQL-backed indicators, these indicators come with their own
+  # queries. The query factory tells the query necessary for certain
+  # indicators. By default, it vends one query for inserting, and another for
+  # updating. The primary client for this is the DrRai::DataService which uses
+  # this to populate the data in the tables.
+  class QueryFactory
+    attr_reader :from_date, :to_date
+
+    class << self
+      def for klazz, from: nil, to: nil
+        raise unless klazz < ApplicationRecord
+
+        instance = nil
+
+        if klazz <= Data::Titration
+          instance = DrRai::TitrationQueryFactory.new(from, to)
+        else
+          raise "Unsupported"
+        end
+
+        instance
+      end
+    end
+
+    def initialize from, to
+      @from = from
+      @to = to
+
+      set_date_boundaries!
+    end
+
+    def inserter
+      # Format should be
+      #   insert into <tbl> ([...columns]) [..query]
+      raise "Unimplemented"
+    end
+
+    def updater
+      # Format should be
+      #   merge into <tbl> as t
+      #   using [...query]
+      #   on month_date
+      #   when not matched and [column compare - insert clause] then
+      #     insert values ([select values])
+      #   when matched and [column compare - update clause] then
+      #     update set [col = old_col <op> new_col];
+      # see https://www.postgresql.org/docs/current/sql-merge.html#id-1.9.3.156.9
+      raise "Unimplemented"
+    end
+
+    private
+
+    def set_date_boundaries!
+      @from_date = if @from.nil?
+        1.year.ago.to_date
+      else
+        @from
+      end
+
+      @to_date = if @to.nil?
+        Date.today
+      else
+        @to
+      end
+    end
+  end
+end

app/queries/dr_rai/titration_query_factory.rb

@@ -0,0 +1,99 @@
+module DrRai
+  class TitrationQueryFactory < QueryFactory
+    def inserter
+      base_query do
+        "insert into public.dr_rai_data_titrations (month_date, facility_name, follow_up_count, titrated_count, titration_rate)"
+      end
+    end
+
+    def updater
+      <<-SQL
+      merge into public.dr_rai_data_titrations as existing
+      using (#{base_query { "" }}) as incoming
+      on existing.month_date = incoming.month_date and existing.facility_name = incoming.facility_name
+      when not matched
+        insert (
+          month_date,
+          facility_name,
+          follow_up_count,
+          titrated_count,
+          titration_rate,
+          created_at,
+          updated_at
+        )
+        values (
+          incoming.month_date,
+          incoming.facility_name,
+          incoming.follow_up_count,
+          incoming.titrated_count,
+          incoming.titration_rate,
+          now(), -- for created_at
+          now(), -- for updated_at
+        )
+      when matched and existing.titration_rate != incoming.titration_rate
+        update
+          set
+            follow_up_count = incoming.follow_up_count,
+            titrated_count = incoming.titrated_count,
+            titration_rate = incoming.titration_rate;
+      SQL
+    end
+
+    private
+
+    def base_query
+      <<~SQL
+        with facility_titrations as (
+          select
+            reporting_patient_states.month_date,
+            facility_name,
+            count(*) as follow_up_count,
+            count(*) filter (where titrated) as titrated_count,
+            count(*) filter (where titrated)::float / count(*) * 100 as titration_rate
+          from reporting_patient_states
+          inner join reporting_facilities
+          on reporting_facilities.facility_id = reporting_patient_states.bp_facility_id
+          where 1 = 1
+            and "public"."reporting_patient_states"."month_date" between date '#{from_date}' and date '#{to_date}'
+            and reporting_patient_states.months_since_bp = 0
+            and reporting_patient_states.last_bp_state = 'uncontrolled'
+            and reporting_patient_states.months_since_registration > 0
+          group by 1, 2
+          order by 1, 2
+        ),
+
+        selected_facility_titrations as (
+          select
+            month_date,
+            facility_name,
+            follow_up_count,
+            titrated_count,
+            titration_rate
+          from facility_titrations
+          where facility_name in (
+            select facility_name
+            from reporting_facilities
+          )
+        ),
+
+        averages as (
+          select
+            month_date,
+            'average' as facility_name,
+            sum(follow_up_count) as follow_up_count,
+            sum(titrated_count) as titrated_count,
+            (sum(titrated_count)::float / sum(follow_up_count)) * 100 as titration_rate
+          from facility_titrations
+          group by month_date
+        )
+
+        #{yield}
+        (
+          select * from selected_facility_titrations
+          union all
+          select * from averages
+        );
+      SQL
+    end
+  end
+end

app/services/dr_rai/data_service.rb

@@ -0,0 +1,36 @@
+module DrRai
+  class DataService
+    class << self
+      def populate klazz, timeline: nil
+        raise "Can only populate models" unless klazz < ApplicationRecord
+        if timeline.present?
+          raise "timeline must be Date range" unless timelines.is_a?(Range)
+        end
+        new(klazz, timeline).populate!
+      end
+    end
+
+    def initialize klazz, timeline
+      @klazz = klazz
+      @timeline = timeline
+      @timeline = 1.year.ago.to_date..Date.today if @timeline.nil?
+      @query_factory = QueryFactory.for(klazz, from: @timeline.begin, to: @timeline.end)
+    end
+
+    def populate!
+      @query = if inserting?
+        @query_factory.inserter
+      else
+        @query_factory.updater
+      end
+
+      ApplicationRecord.connection.exec_query(@query)
+    end
+
+    private
+
+    def inserting?
+      @klazz.where(month_date: @timeline).count == 0
+    end
+  end
+end

config/schedule.rb

@@ -88,6 +88,12 @@ def local(time)
   rake "exotel_tasks:update_all_patients_phone_number_details"
 end
 
+every :day, at: local("03:00 am"), roles: [:cron] do
+  from = 1.month.ago.to_date.to_s
+  to = Date.today.to_s
+  rake "dr_rai:populate_titration_data[#{from}, #{to}]"
+end
+
 every :day, at: local("01:00 am"), roles: [:cron] do
   runner "MarkPatientMobileNumbers.call"
 end

db/migrate/20250813062338_create_dr_rai_data_titrations.rb

@@ -0,0 +1,13 @@
+class CreateDrRaiDataTitrations < ActiveRecord::Migration[6.1]
+  def change
+    create_table :dr_rai_data_titrations do |t|
+      t.string :facility_name
+      t.integer :titrated_count
+      t.integer :follow_up_count
+      t.datetime :month_date
+      t.decimal :titration_rate, precision: 5, scale: 2
+
+      t.timestamps default: -> { "CURRENT_TIMESTAMP" }, null: false
+    end
+  end
+end