fundamentalista 0.1.0

data/lib/fundamentalista/ratios.rb

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+module Fundamentalista
+  # The financial ratios of one Period. Margins, returns and yields are
+  # rates, so 0.25 means 25%; the working capital cycle is in days. Balance
+  # sheet denominators use the average of the period and the prior one
+  # when a prior period is known, and the period's ending balance
+  # otherwise. Every ratio is +nil+ when a figure it needs is missing.
+  #
+  #   ratios = period.ratios
+  #   ratios.roe               # => 0.15e1
+  #   ratios.current_ratio     # => 0.89e0
+  #   ratios.to_h              # every ratio keyed by name
+  #
+  class Ratios
+    include Inspectable
+    include Serializable
+
+    PROFITABILITY = %i[gross_margin operating_margin net_margin ebitda_margin roe roa roic return_on_capital].freeze
+    LIQUIDITY = %i[current_ratio quick_ratio cash_ratio].freeze
+    LEVERAGE = %i[debt_to_equity debt_to_assets net_debt_to_ebitda interest_coverage equity_multiplier].freeze
+    EFFICIENCY = %i[asset_turnover inventory_turnover receivables_turnover].freeze
+    WORKING_CAPITAL = %i[days_sales_outstanding days_inventory_outstanding days_payables_outstanding
+                         cash_conversion_cycle].freeze
+    CASH = %i[fcf_margin cash_conversion capex_to_revenue accrual_ratio].freeze
+    BANKING = %i[net_interest_margin efficiency_ratio loan_to_deposit cost_of_risk allowance_to_loans].freeze
+    ALL = (PROFITABILITY + LIQUIDITY + LEVERAGE + EFFICIENCY + WORKING_CAPITAL + CASH + BANKING).freeze
+
+    attr_reader :period
+
+    def initialize(period)
+      @period = period
+    end
+
+    def gross_margin
+      Decimal.ratio(income.gross_profit, income.revenue)
+    end
+
+    def operating_margin
+      Decimal.ratio(income.operating_income, income.revenue)
+    end
+
+    def net_margin
+      Decimal.ratio(income.net_income, income.revenue)
+    end
+
+    def ebitda_margin
+      Decimal.ratio(income.ebitda, income.revenue)
+    end
+
+    # Return on equity: net income over average equity.
+    def roe
+      Decimal.ratio(income.net_income, average(:equity))
+    end
+
+    # Return on assets: net income over average total assets.
+    def roa
+      Decimal.ratio(income.net_income, average(:total_assets))
+    end
+
+    # Return on invested capital: after tax operating income over average
+    # debt plus equity.
+    def roic
+      nopat = income.operating_income && income.tax_rate && (income.operating_income * (1 - income.tax_rate))
+      Decimal.ratio(nopat, Decimal.sum(average(:total_debt), average(:equity)))
+    end
+
+    # Greenblatt's return on capital: operating income over net working
+    # capital plus net fixed assets.
+    def return_on_capital
+      Decimal.ratio(income.operating_income, Decimal.sum(average(:net_working_capital), average(:ppe)))
+    end
+
+    def current_ratio
+      Decimal.ratio(balance.current_assets, balance.current_liabilities)
+    end
+
+    # Current assets net of inventory over current liabilities.
+    def quick_ratio
+      Decimal.ratio(Decimal.subtract(balance.current_assets, balance.inventory || BigDecimal('0')), balance.current_liabilities)
+    end
+
+    def cash_ratio
+      Decimal.ratio(balance.liquid_assets, balance.current_liabilities)
+    end
+
+    def debt_to_equity
+      Decimal.ratio(balance.total_debt, balance.equity)
+    end
+
+    def debt_to_assets
+      Decimal.ratio(balance.total_debt, balance.total_assets)
+    end
+
+    def net_debt_to_ebitda
+      Decimal.ratio(balance.net_debt, income.ebitda)
+    end
+
+    # Operating income over interest expense.
+    def interest_coverage
+      Decimal.ratio(income.operating_income, income.interest_expense)
+    end
+
+    # Average total assets over average equity, the leverage leg of DuPont.
+    def equity_multiplier
+      Decimal.ratio(average(:total_assets), average(:equity))
+    end
+
+    def asset_turnover
+      Decimal.ratio(income.revenue, average(:total_assets))
+    end
+
+    def inventory_turnover
+      Decimal.ratio(income.cost_of_revenue, average(:inventory))
+    end
+
+    def receivables_turnover
+      Decimal.ratio(income.revenue, average(:receivables))
+    end
+
+    # Days of revenue tied up in receivables.
+    def days_sales_outstanding
+      days(average(:receivables), income.revenue)
+    end
+
+    # Days of cost of revenue held as inventory.
+    def days_inventory_outstanding
+      days(average(:inventory), income.cost_of_revenue)
+    end
+
+    # Days of cost of revenue owed to suppliers.
+    def days_payables_outstanding
+      days(average(:payables), income.cost_of_revenue)
+    end
+
+    # Days between paying suppliers and collecting from customers.
+    def cash_conversion_cycle
+      Decimal.subtract(Decimal.sum(days_sales_outstanding, days_inventory_outstanding), days_payables_outstanding)
+    end
+
+    def fcf_margin
+      Decimal.ratio(cash_flow.free_cash_flow, income.revenue)
+    end
+
+    # Operating cash flow over net income; above one means earnings are
+    # backed by cash.
+    def cash_conversion
+      Decimal.ratio(cash_flow.operating_cash_flow, income.net_income)
+    end
+
+    def capex_to_revenue
+      Decimal.ratio(cash_flow.capital_expenditure, income.revenue)
+    end
+
+    # Sloan's accrual ratio: earnings not backed by operating cash flow,
+    # over average total assets. High values flag low earnings quality.
+    def accrual_ratio
+      Decimal.ratio(Decimal.subtract(income.net_income, cash_flow.operating_cash_flow), average(:total_assets))
+    end
+
+    # Net interest income over average total assets, the bank's spread.
+    def net_interest_margin
+      Decimal.ratio(banking.net_interest_income, average(:total_assets))
+    end
+
+    # Noninterest expense over net interest plus noninterest income; lower
+    # is leaner.
+    def efficiency_ratio
+      Decimal.ratio(banking.noninterest_expense, banking.revenue)
+    end
+
+    def loan_to_deposit
+      Decimal.ratio(banking.loans, banking.deposits)
+    end
+
+    # Credit provisions over average loans.
+    def cost_of_risk
+      Decimal.ratio(banking.provision_for_credit_losses, average(:loans, of: :banking))
+    end
+
+    def allowance_to_loans
+      Decimal.ratio(banking.allowance_for_credit_losses, banking.loans)
+    end
+
+    # The DuPont decomposition of ROE: net margin times asset turnover times
+    # the equity multiplier.
+    def dupont
+      { net_margin: net_margin, asset_turnover: asset_turnover, equity_multiplier: equity_multiplier, roe: roe }
+    end
+
+    # Returns every ratio keyed by name; the banking ones only for banks.
+    def to_h
+      names = period.bank? ? ALL : ALL - BANKING
+      names.to_h { |name| [name, public_send(name)] }
+    end
+
+    def inspect_attributes # :nodoc:
+      to_h
+    end
+
+    private
+
+    def income
+      period.income
+    end
+
+    def balance
+      period.balance
+    end
+
+    def cash_flow
+      period.cash_flow
+    end
+
+    def banking
+      period.banking
+    end
+
+    def average(field, of: :balance)
+      current = period.public_send(of).public_send(field)
+      return current unless period.prior
+
+      Decimal.average(current, period.prior.public_send(of).public_send(field))
+    end
+
+    def days(balance_figure, flow)
+      turnover = Decimal.ratio(balance_figure, flow)
+      turnover && (turnover * period.days)
+    end
+  end
+end

data/lib/fundamentalista/scores/altman_z.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Fundamentalista
+  module Scores
+    # The Altman Z-score, the 1968 formulation for listed companies. Above
+    # 2.99 is the safe zone, below 1.81 the distress zone, and the grey zone
+    # lies in between.
+    #
+    #   z = period.altman_z(market_cap: 4_700_000_000_000)
+    #   z.score   # => 0.9e1
+    #   z.zone    # => :safe
+    #
+    class AltmanZ
+      include Inspectable
+      include Serializable
+
+      SAFE_ABOVE = BigDecimal('2.99')
+      DISTRESS_BELOW = BigDecimal('1.81')
+
+      attr_reader :period, :market_cap
+
+      def initialize(period, market_cap:)
+        @period = period
+        @market_cap = Decimal.wrap(market_cap)
+      end
+
+      # The score, or +nil+ when a component is missing.
+      def score
+        weighted = components.zip(WEIGHTS).map { |value, weight| value && (value * weight) }
+        Decimal.sum(*weighted)
+      end
+
+      # +:safe+, +:grey+, +:distress+, or +nil+ without a score.
+      def zone
+        return nil unless score
+
+        if score > SAFE_ABOVE then :safe
+        elsif score < DISTRESS_BELOW then :distress
+        else :grey
+        end
+      end
+
+      def to_h
+        { score: score, zone: zone }
+      end
+
+      def inspect_attributes # :nodoc:
+        to_h
+      end
+
+      private
+
+      WEIGHTS = [BigDecimal('1.2'), BigDecimal('1.4'), BigDecimal('3.3'), BigDecimal('0.6'), BigDecimal('1.0')].freeze
+      private_constant :WEIGHTS
+
+      def components
+        balance = period.balance
+        assets = balance.total_assets
+        [
+          Decimal.ratio(balance.working_capital, assets),
+          Decimal.ratio(balance.retained_earnings, assets),
+          Decimal.ratio(period.income.operating_income, assets),
+          Decimal.ratio(market_cap, balance.total_liabilities),
+          Decimal.ratio(period.income.revenue, assets)
+        ]
+      end
+    end
+  end
+end

data/lib/fundamentalista/scores/beneish.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Fundamentalista
+  module Scores
+    # The Beneish M-score, the eight variable model that flags earnings
+    # likely to be manipulated. Every index compares the period with the
+    # prior one, so it needs a prior period. Above -1.78 is the warning
+    # zone.
+    #
+    #   m = period.beneish
+    #   m.score                 # => -0.25e1
+    #   m.likely_manipulator?   # => false
+    #   m.indices               # => {dsri: ..., gmi: ..., ...}
+    #
+    class Beneish
+      include Inspectable
+      include Serializable
+
+      THRESHOLD = BigDecimal('-1.78')
+      INTERCEPT = BigDecimal('-4.84')
+      WEIGHTS = {
+        dsri: BigDecimal('0.92'), gmi: BigDecimal('0.528'), aqi: BigDecimal('0.404'), sgi: BigDecimal('0.892'),
+        depi: BigDecimal('0.115'), sgai: BigDecimal('-0.172'), tata: BigDecimal('4.679'), lvgi: BigDecimal('-0.327')
+      }.freeze
+
+      attr_reader :period
+
+      def initialize(period)
+        @period = period
+      end
+
+      # The score, or +nil+ without a prior period or a component.
+      def score
+        weighted = WEIGHTS.map { |index, weight| indices[index] && (indices[index] * weight) }
+        Decimal.sum(INTERCEPT, *weighted)
+      end
+
+      # Whether the score sits above the warning threshold; +nil+ without
+      # a score.
+      def likely_manipulator?
+        score && score > THRESHOLD
+      end
+
+      # The eight indices keyed by their usual initials.
+      def indices
+        @indices ||= { dsri: dsri, gmi: gmi, aqi: aqi, sgi: sgi, depi: depi, sgai: sgai, tata: tata, lvgi: lvgi }
+      end
+
+      def to_h
+        indices.merge(score: score, likely_manipulator: likely_manipulator?)
+      end
+
+      def inspect_attributes # :nodoc:
+        { score: score, likely_manipulator: likely_manipulator? }
+      end
+
+      private
+
+      def prior
+        period.prior
+      end
+
+      def dsri
+        change { |candidate| Decimal.ratio(candidate.balance.receivables, candidate.income.revenue) }
+      end
+
+      def gmi
+        change(inverted: true) { |candidate| candidate.ratios.gross_margin }
+      end
+
+      def aqi
+        change do |candidate|
+          balance = candidate.balance
+          hard = Decimal.sum(balance.current_assets, balance.ppe)
+          hard && balance.total_assets && (1 - (hard / balance.total_assets))
+        end
+      end
+
+      def sgi
+        change { |candidate| candidate.income.revenue }
+      end
+
+      def depi
+        change(inverted: true) do |candidate|
+          depreciation = candidate.income.depreciation_amortization
+          Decimal.ratio(depreciation, Decimal.sum(depreciation, candidate.balance.ppe))
+        end
+      end
+
+      def sgai
+        change { |candidate| Decimal.ratio(candidate.income.sga, candidate.income.revenue) }
+      end
+
+      def tata
+        Decimal.ratio(Decimal.subtract(period.income.net_income, period.cash_flow.operating_cash_flow),
+                      period.balance.total_assets)
+      end
+
+      def lvgi
+        change { |candidate| Decimal.ratio(candidate.balance.total_liabilities, candidate.balance.total_assets) }
+      end
+
+      def change(inverted: false)
+        return nil unless prior
+
+        current = yield(period)
+        previous = yield(prior)
+        inverted ? Decimal.ratio(previous, current) : Decimal.ratio(current, previous)
+      end
+    end
+  end
+end

data/lib/fundamentalista/scores/piotroski.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Fundamentalista
+  module Scores
+    # The Piotroski F-score: nine yes-or-no signals of profitability,
+    # leverage and efficiency, scored from 0 to 9. Six of them compare the
+    # period with the prior one, so a period without a prior scores on the
+    # remaining three and reports the others as +nil+.
+    #
+    #   score = period.piotroski
+    #   score.score     # => 7
+    #   score.signals   # => {positive_income: true, positive_cash_flow: true, ...}
+    #
+    class Piotroski
+      include Inspectable
+      include Serializable
+
+      SIGNALS = %i[positive_income positive_cash_flow improving_roa cash_exceeds_income
+                   falling_leverage improving_liquidity no_dilution improving_margin improving_turnover].freeze
+
+      attr_reader :period
+
+      def initialize(period)
+        @period = period
+      end
+
+      # The number of signals that hold, 0 to 9.
+      def score
+        signals.values.count(true)
+      end
+
+      # Every signal keyed by name: +true+, +false+, or +nil+ when it cannot
+      # be evaluated.
+      def signals
+        SIGNALS.to_h { |signal| [signal, send(:"#{signal}?")] }
+      end
+
+      def to_h
+        signals.merge(score: score)
+      end
+
+      def inspect_attributes # :nodoc:
+        { score: score }
+      end
+
+      private
+
+      def positive_income?
+        positive(period.income.net_income)
+      end
+
+      def positive_cash_flow?
+        positive(period.cash_flow.operating_cash_flow)
+      end
+
+      def improving_roa?
+        improvement { |candidate| candidate.ratios.roa }
+      end
+
+      def cash_exceeds_income?
+        above(period.cash_flow.operating_cash_flow, period.income.net_income)
+      end
+
+      def falling_leverage?
+        improvement(direction: :down) do |candidate|
+          Decimal.ratio(candidate.balance.long_term_debt, candidate.balance.total_assets)
+        end
+      end
+
+      def improving_liquidity?
+        improvement { |candidate| candidate.ratios.current_ratio }
+      end
+
+      def no_dilution?
+        return nil unless prior
+
+        above(prior.balance.shares_outstanding, period.balance.shares_outstanding, or_equal: true)
+      end
+
+      def improving_margin?
+        improvement { |candidate| candidate.ratios.gross_margin }
+      end
+
+      def improving_turnover?
+        improvement { |candidate| candidate.ratios.asset_turnover }
+      end
+
+      def prior
+        period.prior
+      end
+
+      def positive(value)
+        value&.positive?
+      end
+
+      def above(left, right, or_equal: false)
+        return nil if left.nil? || right.nil?
+
+        or_equal ? left >= right : left > right
+      end
+
+      def improvement(direction: :up)
+        return nil unless prior
+
+        current = yield(period)
+        previous = yield(prior)
+        direction == :up ? above(current, previous) : above(previous, current)
+      end
+    end
+  end
+end

data/lib/fundamentalista/serializable.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Fundamentalista
+  # Turns a value object into plain data. #to_h keeps every figure a
+  # BigDecimal; #as_json turns figures into Floats and dates into ISO
+  # strings, which is what JSON consumers expect, so +to_json+ and Rails'
+  # +render json:+ work out of the box.
+  module Serializable
+    def as_json(*)
+      Serializable.plain(to_h)
+    end
+
+    def to_json(*args)
+      JSON.generate(as_json, *args)
+    end
+
+    def self.plain(value) # :nodoc:
+      case value
+      when Hash then value.transform_values { |inner| plain(inner) }
+      when Array then value.map { |inner| plain(inner) }
+      when Serializable then value.as_json
+      else scalar(value)
+      end
+    end
+
+    def self.scalar(value) # :nodoc:
+      case value
+      when BigDecimal then value.to_f
+      when Date, Time then value.iso8601
+      else value
+      end
+    end
+  end
+end

data/lib/fundamentalista/source.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Fundamentalista
+  # Where a line item came from: the XBRL concept, the filing that
+  # reported it, and whether the figure was reported as is, summed from
+  # split concepts, or derived from year to date values.
+  class Source
+    include Inspectable
+
+    attr_reader :concept, :form, :filed, :derivation
+
+    def initialize(concept:, form:, filed:, derivation: :reported)
+      @concept = concept
+      @form = form
+      @filed = filed
+      @derivation = derivation
+    end
+
+    def reported?
+      derivation == :reported
+    end
+
+    def inspect_attributes # :nodoc:
+      { concept: concept, form: form, filed: filed, derivation: derivation }
+    end
+  end
+end

data/lib/fundamentalista/statement.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Fundamentalista
+  # Base class of the three financial statements. Subclasses declare their
+  # line items with ::field; every reader returns a BigDecimal or +nil+.
+  class Statement
+    include Inspectable
+    include Serializable
+
+    class << self
+      # Declares line items. Each becomes a reader and a keyword argument
+      # of ::new.
+      def field(*names)
+        names.each do |name|
+          fields << name
+          attr_reader name
+        end
+      end
+
+      # The declared line items, in order.
+      def fields
+        @fields ||= []
+      end
+
+      # Returns a statement adding up the reported items of +statements+,
+      # as the trailing twelve months does with four quarters. An item is
+      # +nil+ when any statement lacks it.
+      def sum(statements)
+        new(**fields.to_h { |field| [field, Decimal.sum(*statements.map { |statement| statement.public_send(field) })] })
+      end
+    end
+
+    def initialize(**values)
+      unknown = values.keys - self.class.fields
+      raise ArgumentError, "Unknown #{self.class.name} fields: #{unknown.join(', ')}" if unknown.any?
+
+      self.class.fields.each { |field| instance_variable_set(:"@#{field}", Decimal.wrap(values[field])) }
+    end
+
+    # Returns every line item, derived ones included, keyed by name.
+    def to_h
+      self.class.fields.to_h { |field| [field, public_send(field)] }
+    end
+
+    def inspect_attributes # :nodoc:
+      to_h
+    end
+  end
+end