active_reporter 0.5.8

data/lib/active_reporter/report/definition.rb

@@ -0,0 +1,195 @@
+require 'active_reporter/inflector'
+
+module ActiveReporter
+  class Report
+    module Definition
+      extend ActiveSupport::Concern
+
+      METRICS = %i[aggregator calculator dimension tracker evaluator].collect do |type|
+        metrics = Dir.glob(File.join(__dir__, '..', type.to_s, '*.rb')).collect { |file| File.basename(file, '.rb') }.without(*%w[base bin]).collect(&:to_sym).sort.freeze
+        [type, const_set(type.to_s.upcase, metrics)]
+      end.to_h.sort.freeze
+
+      delegate :report_model, to: :class
+
+      class_methods do
+        # Dimensions define what we are reporting about. For example, some common dimensions would be the Name of the
+        # data being reported on and the Date it happened, such as the Author name and the Published date of blog posts
+        # in an online blog.
+        # These dimension configurations are the data points that a report can be grouped by, data in the group will
+        # all be aggregated together using the configured aggregators. Multiple dimension types are available for
+        # different grouping methods.
+        #
+        # Category dimensions will do a normal GROUP BY on one specific field, this can also be used in conjunction
+        # with a filter to limit the GROUP BY values returned.
+        #
+        # Bin dimensions group many rows into "bins" of a specified width, this is helpful when grouping by a datetime
+        # value by allowing you to set this bin width to :days or :months. In addition to the Time dimension you can
+        # use the Number dimensions with a bin, grouping numeric values into larger groups such as 10s or 100s.
+        def dimension(name, dimension_class, opts = {})
+          dimensions[name.to_sym] = { axis_class: dimension_class, opts: opts }
+        end
+
+        def dimensions
+          @dimensions ||= { totals: { axis_class: Dimension::Category, opts: { _expression: "'totals'" } } }
+        end
+
+        # Aggregators calculate the statistical data for the report into each dimension group. After grouping the data
+        # the aggregators calculate the values to be reported on. For example, if we use the dimensions Author name and
+        # Published date of blog posts in an online blog, we can then use aggregators on the Likes value to get the Sum
+        # of all Likes on all posts for each Published date for each Author name. There are multiple ways to aggregate
+        # this data, and so multiple aggregator types are provided.
+        #
+        # Average aggregator would calculate the average value across all the data in the group.
+        # 
+        # Sum aggregator would calculate the sum total of all values across all the data in the group.
+        #
+        # Additional aggregators are also available for many other calculation types
+        def aggregator(name, aggregator_class, opts = {})
+          aggregators[name.to_sym] = { axis_class: aggregator_class, opts: opts }
+        end
+
+        def aggregators
+          @aggregators ||= {}
+        end
+
+        # Calculators are special aggregators that perform calculations between report dimension data and a parent
+        # report.
+        # This could be used when generating a drill-down report with more specific data based on a specific row of a
+        # different report, where the parent report has larger dimension bins or fewer dimensions defined. For example,
+        # a parent report could group by Author only, and aggregate total Likes across all blog posts, the child report
+        # could group by Author and Published to provided more specific details. A calculator could then calculate the
+        # Ratio of Likes on a specific Published date vs the parent report's total Likes for that same specific Author.
+        # It can also be used to calculate values between the report data and the Totals report data, where the Totals
+        # report is the aggregation of all the data in the report combined. For example, if the report groups by Author
+        # we can aggregate total Likes across all blog posts for each Author. The Totals report would aggregate total
+        # Likes across all blog posts for all Author. A calculator can calculate the ratio of Total Likes vs the
+        # Author's total Likes.
+        #
+        # A calculator only performs additional calculations on already aggregated data, so an :aggregator value
+        # matching the aggregator name must be passed in the opts. Additionally, you may optionally pass a
+        # :parent_aggregator if the name of this aggregator is different.
+        def calculator(name, calculator_class, opts = {})
+          calculators[name.to_sym] = { axis_class: calculator_class, opts: opts }
+        end
+
+        def calculators
+          @calculators ||= {}
+        end
+
+        # Trackers are special aggregators that perform calculations between sequential bin dimension data. In order to
+        # use a tracker the last dimension configured in your report must be a bin dimension that defines a bin width
+        # so the tracker can determine the bin sequence. If a bin dimension with a bin width is not the last dimension
+        # configured tracker data will not be calculated.
+        # Any other dimensions are also considered when tracking data, if the value in any other dimension value
+        # changes between two rows the tracker data is not calculated. For example, if dimensions Author and Published
+        # are configured and an aggregator to sum Likes is configured, a tracker to calculate Likes delta may also be
+        # used. Each Published date the delta will be calculated, as long as the previous row has a Published date
+        # sequentially immediately adjacent to the current row. If the bin with is date, the dates 2020/06/05 and
+        # 2020/06/06 are adjacent, but if there are no blog posts for 2020/06/07 then the dela will not be calculated
+        # on the 2020/06/08 row since 2020/06/06 is not adjacent. Additionally, when the Author changes no delta will
+        # be calculated, even if the Published date on the row is sequentially immediately adjacent.
+        #
+        # A tracker only performs additional calculations on already aggregated data, so an :aggregator value matching
+        # the aggregator name must be passed in the opts.
+        def tracker(name, tracker_class, opts = {})
+          trackers[name.to_sym] = { axis_class: tracker_class, opts: opts }
+        end
+
+        def trackers
+          @trackers ||= {}
+        end
+
+        # block_evaluator(:chargeback_ratio) { |row| supplemental_report_data.detect { |data| data[:id] == row[:id] }[:count] / row[:count] }
+        def evaluator(name, evaluator_class, opts = {})
+          raise 'needs block' unless opts.include?(:block)
+          evaluators[name.to_sym] = { axis_class: evaluator_class, opts: opts }
+        end
+
+        def evaluators
+          @evaluators ||= {}
+        end
+
+        def available_dimensions
+          dimensions.keys
+        end
+        alias_method :available_groupers, :available_dimensions
+
+        def available_aggregators
+          aggregators.keys + calculators.keys + trackers.keys
+        end
+
+        METRICS.each do |type, mertics|
+          mertics.each do |mertic|
+            class_eval <<-METRIC_HELPERS, __FILE__, __LINE__ + 1
+              def #{mertic}_#{type}(name, opts = {}, &block)
+                opts[:block] = block if block_given?
+                #{type}(name, #{(type.to_s + '/' + mertic.to_s.singularize(:_gem_active_reporter)).camelize.sub(/.*\./, "")}, opts)
+              end
+            METRIC_HELPERS
+          end
+        end
+
+        def default_report_model
+          name.demodulize.sub(/Report$/, '').constantize
+        rescue NameError
+          raise $!, "#{$!} cannot be used as `report_on` class, please configure `report_on` in the report class", $!.backtrace
+        end
+
+        def default_model
+          name.demodulize.sub(/Report$/, '').constantize
+        end
+
+        def report_model
+          @report_model ||= default_model
+        end
+
+        def report_on(class_or_name)
+          @report_model = class_or_name.to_s.constantize
+        rescue NameError
+          raise $!, "#{$!} cannot be used as `report_on` class", $!.backtrace
+        end
+
+        # ensure subclasses gain any aggregators or dimensions defined on their parents
+        def inherited(subclass)
+          instance_values.each { |var, val| subclass.instance_variable_set(:"@#{var}", val.dup) }
+        end
+
+        # autoreporting will automatically define dimensions based on columns
+        def autoreport_on(class_or_name)
+          report_on class_or_name
+          report_model.columns.each(&method(:autoreport_column))
+          count_aggregator(:count) if aggregators.blank?
+        end
+
+        # can override this method to skip or change certain column declarations
+        def autoreport_column(column)
+          return if column.name == report_model.primary_key
+
+          name, reflection = report_model.reflections.find { |_, reflection| reflection.foreign_key == column.name }
+          case
+          when reflection.present?
+            column_name = (reflection.klass.column_names & autoreport_association_name_columns(reflection)).first
+            if column_name.present?
+              category_dimension name, expression: "#{reflection.klass.table_name}.#{column_name}", relation: ->(r) { r.joins(name) }
+            else
+              category_dimension column.name
+            end
+          when %i[datetime timestamp time date].include?(column.type)
+            time_dimension column.name
+          when %i[integer float decimal].include?(column.type)
+            number_dimension column.name
+          else
+            category_dimension column.name
+          end
+        end
+
+        # override this to change which columns of the association are used to
+        # auto-label it
+        def autoreport_association_name_columns(reflection)
+          %w(name email title)
+        end
+      end
+    end
+  end
+end

data/lib/active_reporter/report/metrics.rb

@@ -0,0 +1,75 @@
+module ActiveReporter
+  class Report
+    module Metrics
+      delegate :table_name, to: :report_model
+
+      def dimensions
+        @dimensions ||= build_axes(self.class.dimensions)
+      end
+
+      def aggregators
+        @aggregators ||= build_axes(self.class.aggregators.slice(*Array(params.fetch(:aggregators, self.class.aggregators.keys)).collect(&:to_sym)))
+      end
+
+      def grouper_names
+        names = params.fetch(:groupers, [dimensions.except(:totals).keys.first])
+        names = names.is_a?(Hash) ? names.values : Array.wrap(names).compact
+        names.map(&:to_sym)
+      end
+
+      def groupers
+        @groupers ||= dimensions.values_at(*grouper_names)
+      end
+
+      def filters
+        @filters ||= dimensions.values.select(&:filtering?)
+      end
+
+      def relators
+        filters | groupers
+      end
+
+      def base_relation
+        params.fetch(:relation, report_model.all)
+      end
+
+      def relation
+        @relation ||= relators.reduce(base_relation) { |relation, dimension| dimension.relate(relation) }
+      end
+
+      def records
+        @records ||= filters.reduce(relation) { |relation, dimension| dimension.filter(relation) }
+      end
+
+      def groups
+        @groups ||= groupers.reduce(records) { |relation, dimension| dimension.group(relation) }
+      end
+
+      def calculators
+        @calculators ||= build_axes(self.class.calculators.slice(*Array(params[:calculators]).collect(&:to_sym)))
+      end
+
+      def trackers
+        @trackers ||= build_axes(self.class.trackers.slice(*Array(params[:trackers]).collect(&:to_sym)))
+      end
+
+      def evaluators
+        @evaluators ||= build_axes(self.class.evaluators.slice(*Array(params[:evaluators]).collect(&:to_sym)))
+      end
+
+      def fields
+        [groupers, calculators.keys, trackers.keys, evaluators.keys].inject(&:merge)
+      end
+
+      def total_report
+        @total_report ||= self.class.new(@params.except(:calculators).merge({ groupers: :totals })) unless @total_data.present?
+      end
+
+      private
+
+      def build_axes(axes)
+        axes.map { |name, h| [name, h[:axis_class].new(name, self, h[:opts])] }.to_h
+      end
+    end
+  end
+end

data/lib/active_reporter/report/validation.rb

@@ -0,0 +1,106 @@
+require 'active_reporter/inflector'
+require 'active_reporter/invalid_params_error'
+
+module ActiveReporter
+  class Report
+    module Validation
+      attr_accessor :errors
+
+      def validate_params!
+        validate_configuration!
+        validate_aggregators!
+        validate_groupers!
+        validate_calculators!
+        validate_trackers!
+        validate_parent_report!
+        validate_total_report!
+
+        raise_invalid_params_error! if errors.present? && errors.any?
+      end
+
+      def validate_configuration!
+        incomplete_message = ['You must declare at least one aggregator or tracker, and at lease one dimension to initialize a report', 'See the README for more details']
+
+        raise ActiveReporter::InvalidParamsError, ["#{self.class.name} does not declare any aggregators or trackers"].concat(incomplete_message).join(". ") if aggregators.empty?
+        raise ActiveReporter::InvalidParamsError, ["#{self.class.name} does not declare any dimensions"].concat(incomplete_message).join(". ") if dimensions.except(:totals).empty?
+        raise ActiveReporter::InvalidParamsError, 'parent_report must be included in order to process calculations' if calculators.any? && parent_report.nil?
+      end
+
+      def validate_aggregators!
+        (aggregators.keys - self.class.aggregators.keys).each do |aggregator|
+          add_invalid_param_error(:aggregator, ":#{aggregator} is not a valid aggregator (should be in #{self.class.aggregators.keys})")
+        end
+      end
+
+      def validate_calculators!
+        (calculators.keys - self.class.calculators.keys).each do |calculator|
+          add_invalid_param_error(:calculator, ":#{calculator} is not a valid calculator (should be in #{self.class.calculators.keys})")
+        end
+
+        calculators.values.each do |calculator|
+          if calculator.aggregator.nil?
+            add_invalid_param_error(:calculator, ":#{calculator.name} must define an aggregator (should be in #{self.class.aggregator.keys})")
+          elsif aggregators.exclude?(calculator.aggregator)
+            add_invalid_param_error(:calculator, ":#{calculator.name} defines an valid aggregator :#{calculator.aggregator} (should be in #{self.class.aggregators.keys})")
+          end
+        end
+      end
+
+      def validate_trackers!
+        (trackers.keys - self.class.trackers.keys).each do |tracker|
+          add_invalid_param_error(:tracker, ":#{tracker} is not a valid tracker (should be in #{self.class.trackers.keys})")
+        end
+
+        trackers.values.each do |tracker|
+          if tracker.aggregator.nil?
+            add_invalid_param_error(:tracker, ":#{tracker.name} must define an aggregator (should be in #{self.class.aggregator.keys})")
+          elsif aggregators.exclude?(tracker.aggregator)
+            add_invalid_param_error(:tracker, ":#{tracker.name} defines an valid aggregator :#{tracker.aggregator} (should be in #{self.class.aggregators.keys})")
+          end
+        end
+      end
+
+      def validate_groupers!
+        unless groupers.all?(&:present?)
+          invalid_groupers = grouper_names.zip(groupers).collect { |k,v| k if v.nil? }.compact
+          invalid_groupers_message = [
+            [
+              invalid_groupers.to_sentence,
+              (invalid_groupers.one? ? 'is not a' : 'are not'), 'valid', 'dimension'.pluralize(invalid_groupers.count, :_gem_active_reporter)
+            ].join(' '),
+            "declared dimension include #{dimensions.keys.to_sentence}"
+          ].join(". ")
+          add_invalid_param_error(:groupers, invalid_groupers_message)
+        end
+      end
+
+      def validate_parent_report!
+        add_invalid_param_error(:parent_report, 'must be an instance of ActiveReporter::Report') unless parent_report.nil? || parent_report.kind_of?(ActiveReporter::Report)
+      end
+
+      def validate_total_report!
+        add_invalid_param_error(:total_report, 'must be an instance of ActiveReporter::Report') unless @total_report.nil? || @total_report.kind_of?(ActiveReporter::Report)
+      end
+
+      private
+
+      def add_error(message)
+        self.errors ||= []
+        self.errors.push(message)
+      end
+
+      def add_invalid_param_error(param_key, message)
+        self.errors ||= []
+        self.errors.push("Invalid value for params[:#{param_key}]: #{message}")
+      end
+
+      def raise_invalid_params_error!
+        raise ActiveReporter::InvalidParamsError, error_message
+      end
+
+      def error_message
+        (["The report configuration contains the following #{'error'.pluralize(errors.count, :_gem_active_reporter)}:"] + errors).join("\n - ")
+      end
+    end
+  end
+end

data/lib/active_reporter/serializer.rb

@@ -0,0 +1,7 @@
+require 'active_reporter/serializer/base'
+require 'active_reporter/serializer/table'
+require 'active_reporter/serializer/csv'
+require 'active_reporter/serializer/form_field'
+require 'active_reporter/serializer/highcharts'
+require 'active_reporter/serializer/hash_table'
+require 'active_reporter/serializer/nested_hash'

data/lib/active_reporter/serializer/base.rb

@@ -0,0 +1,103 @@
+require 'active_reporter/inflector'
+
+module ActiveReporter
+  module Serializer
+    class Base
+      attr_reader :report
+
+      def initialize(report)
+        @report = report
+      end
+
+      # Consider overriding many of these methods to use I18n with keys based
+      # on the aggregators or dimension name.
+
+      def human_aggregator_label(aggregators)
+        aggregators.keys.collect { |aggregator| aggregator.to_s.humanize }.join(' ')
+      end
+
+      def human_dimension_label(dimension)
+        dimension.name.to_s.humanize
+      end
+
+      def human_null_value_label(dimension)
+        "No #{human_dimension_label(dimension)}"
+      end
+
+      def human_aggregator_value_label(aggregator, value)
+        value
+      end
+
+      def human_dimension_value_label(dimension, value)
+        return human_null_value_label(dimension) if value.nil?
+
+        case dimension
+        when ActiveReporter::Dimension::Category
+          human_category_value_label(dimension, value)
+        when ActiveReporter::Dimension::Number
+          human_number_value_label(dimension, value)
+        when ActiveReporter::Dimension::Time
+          human_time_value_label(dimension, value)
+        else
+          value
+        end
+      end
+
+      def human_category_value_label(dimension, value)
+        value
+      end
+
+      def human_number_value_label(dimension, value)
+        case value.bin_edges
+        when :min_and_max
+          "[#{value.min.round(2)}, #{value.max.round(2)})"
+        when :min
+          ">= #{value.min.round(2)}"
+        when :max
+          "< #{value.max.round(2)}"
+        else
+          human_null_value_label(dimension)
+        end
+      end
+
+      def time_formats
+        {
+          minutes: '%F %k:%M', hours: '%F %k', days: '%F',
+          weeks: 'week of %F', months: '%Y-%m', years: '%Y'
+        }
+      end
+
+      def human_time_value_label(dimension, value)
+        case value.bin_edges
+        when :min_and_max
+          time_formats.each { |step, format| return value.min.strftime(format) if value.max == value.min.advance(step => 1) } || "#{value.min} to #{value.max}"
+        when :min
+          "after #{value.min}"
+        when :max
+          "before #{value.max}"
+        else
+          human_null_value_label(dimension)
+        end
+      end
+
+      def record_type
+        report.table_name.singularize(:_gem_active_reporter).humanize
+      end
+
+      def axis_summary
+        y = human_aggregator_label(report.aggregators)
+        xes = report.groupers.map(&method(:human_dimension_label))
+        count = "#{report.records.count} #{record_type.pluralize(report.records.count, :_gem_active_reporter)}"
+        "#{y} by #{xes.to_sentence} for #{count}"
+      end
+
+      def filter_summary
+        report.filters.flat_map do |dimension|
+          human_dimension_label(dimension) + " = " + dimension.filter_values.map do |value|
+            human_dimension_value_label(dimension, value)
+          end.to_sentence(last_word_connector: ', or ')
+        end.join('; ')
+      end
+    end
+  end
+end