fundamentalista 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 36260d14ca8a99975cc3c9717ecd1fa5694f2e2d29144aaeb8d51e9eed3a25a5
-  data.tar.gz: 920282a4dd650e6ed172638e02b85c37b3ac6e0166af5f7a837b4e69003d1c59
+  metadata.gz: 0d6101d9bee968831b3ffb75a7e6663deb2bb1fc925a2c01b7a4cfcfcfb50fd4
+  data.tar.gz: 52119b52c85c8bf846516846f9af7e11612bdd6c27048940007c5c798bd368e9
 SHA512:
-  metadata.gz: 698002a96de44e7c842e619fbce287758f2478f56f0e0a3c1fcbb131a635e88316b9609bfba710c7223627f6ea7ba67b5a3ad5cc5a9296cf34b061a65b76956f
-  data.tar.gz: 675e708b8b952f95aa50ef374165b37fa70f9d7d6e217ee8b14fb7a8157fec4c1402f8a0703aba8d4808fa33e0202a75eeafc43e2fd76a8bdba358b63f044763
+  metadata.gz: fc67da833989bdf483cc1fdabf382bd0f62cdd64539ae7edca030008c94f5380952224b0f83f1e2adc14651d851e2fcea8b03289e4f731a218432e8ed97f924b
+  data.tar.gz: b6125c1afde39ba4ba9298c3080ce4141ed3afeaecab18bd5a8aa1e10fefd939f68bf3f9d3d91ec8b04a1dbfb4822ad8cca5eb4512953101e057bce92d7434fa

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.4.0
+
+- Revenue by product line and by region from FMP as `Segments`, with shares and growth per segment.
+- Greenwald's earnings power value and the residual income model on the valuation.
+
+## 0.3.0
+
+- Insurance lines and ratios: premiums, claims, loss, expense and combined ratios, investment yield and the float, read from the concepts property and casualty insurers report.
+
 ## 0.2.0
 
 - Daily prices from FMP as a `PriceHistory` with dividend adjusted returns, the valuation of every fiscal year at its closing price, and the company beta.

data/README.md

@@ -113,7 +113,22 @@ jpm.ratios.cost_of_risk            # credit provisions over average loans
 jpm.ratios.allowance_to_loans
 ```
 
-The banking ratios appear in `ratios.to_h` only for banks, and the industrial ones that need inventory, cost of revenue or a classified balance sheet come back `nil` for them. Quarterly ratios are per quarter, not annualized; use the trailing twelve months for returns.
+The banking and insurance ratios appear in `ratios.to_h` only for banks and insurers, and the industrial ones that need inventory, cost of revenue or a classified balance sheet come back `nil` for them. Quarterly ratios are per quarter, not annualized; use the trailing twelve months for returns.
+
+## Insurers
+
+Insurers earn premiums and invest the float, so their lines live on `period.insurance`: premiums earned and written, claims incurred, total benefits and expenses, investment income, investments, reserves, unearned premiums, premiums receivable and reinsurance recoverables. `period.insurer?` says whether the company earns premiums, and `insurance.float` is Buffett's: reserves plus unearned premiums, less what policyholders and reinsurers still owe.
+
+```ruby
+trv = Fundamentalista.company("TRV").financials.latest
+trv.ratios.loss_ratio            # claims incurred over premiums earned
+trv.ratios.combined_ratio        # benefits, losses and expenses over premiums earned; below one, underwriting makes money
+trv.ratios.expense_ratio         # the difference between the two
+trv.ratios.investment_yield      # investment income over average investments
+trv.ratios.float_to_equity
+```
+
+These are property and casualty concepts. For life insurers, whose revenue is mostly investment income and whose reserves are future policy benefits, the combined ratio and the float mislead; read their investment yield and return on equity instead.
 
 ## Ratios
 
@@ -270,6 +285,26 @@ company.valuation_history(:pe, :pb, :fcf_yield)               # {2025 => {price:
 company.valuation_history(:pe, prices: prices)                # with a history you bring
 ```
 
+## Segments
+
+FMP serves revenue by product line and by region for every fiscal year, as `Segments`: what the company sells and where, and how each part grows. EDGAR's company facts carry no segments.
+
+```ruby
+segments = company.segments(by: :product)          # or :geography
+segments.latest                                     # {"iPhone" => ..., "Service" => ...}
+segments.share                                      # each segment's share of the latest year
+segments.growth("Service", years: 5)                # CAGR of one segment
+```
+
+### More valuation models
+
+Two models complement the DCF. Greenwald's earnings power value capitalizes today's after tax EBIT at the discount rate as if the company never grew, so the gap to the price is the growth being paid for. The residual income model starts from book value and adds only the earnings above the cost of equity's charge on it, so it rewards returns on equity above that cost and nothing else.
+
+```ruby
+valuation.earnings_power_value(discount_rate: 0.09)
+valuation.residual_income_value(cost_of_equity: 0.09, growth: 0.04, years: 10)
+```
+
 ## Providers
 
 | | EDGAR | Financial Modeling Prep |
@@ -279,6 +314,7 @@ company.valuation_history(:pe, prices: prices)                # with a history y
 | Quotes | No, pass a price | Yes |
 | Analyst estimates | No, pass an EPS | Yes |
 | Prices and beta | No, bring a PriceHistory and a beta | Yes |
+| Revenue segments | No | Yes |
 | Coverage | Companies filing with the SEC, US GAAP and IFRS, in their reporting currency | Global |
 
 EDGAR publishes every value a company ever tagged, restatements included. Fundamentalista reads each line item for the period it describes and keeps the most recently filed value, while the fiscal year label comes from the original filing. Companies tag the same idea under different XBRL concepts, so each line item has an ordered list of concepts in `Providers::Edgar::Tags`, and the first one reported wins. Debt excludes lease obligations, which FMP's `totalDebt` includes.

data/lib/fundamentalista/company.rb

@@ -12,6 +12,7 @@ module Fundamentalista
   #   company.valuation(price: 320).pe
   #   company.estimate.eps                   # FMP only
   #   company.valuation_history(:pe)         # {2025 => {price:, pe:}, ...}
+  #   company.segments(by: :geography).share # FMP only
   #
   class Company
     include Inspectable
@@ -65,6 +66,13 @@ module Fundamentalista
       end.to_h
     end
 
+    # Returns the revenue Segments by +:product+ or +:geography+. Raises
+    # UnsupportedPeriodError on EDGAR, whose company facts carry none.
+    def segments(by: :product)
+      @segments ||= {}
+      @segments[by] ||= provider.segments(self, by: by)
+    end
+
     # Returns the trailing twelve months as a Period, built from the last
     # +quarters+ quarterly periods; eight give it a prior period too.
     def ttm(quarters: 8)

data/lib/fundamentalista/financials.rb

@@ -92,7 +92,8 @@ module Fundamentalista
         currency: quarters.first.currency, balance: quarters.first.balance,
         income: IncomeStatement.sum(quarters.map(&:income)),
         cash_flow: CashFlowStatement.sum(quarters.map(&:cash_flow)),
-        banking: Banking.sum(quarters.map(&:banking))
+        banking: Banking.sum(quarters.map(&:banking)),
+        insurance: Insurance.sum(quarters.map(&:insurance))
       )
     end
 

data/lib/fundamentalista/insurance.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Fundamentalista
+  # The lines an insurer reports that the three classic statements do not
+  # carry: premiums, claims, investment income, reserves and the balances
+  # behind the float. Empty for companies that are not insurers. All in
+  # the reporting currency.
+  class Insurance < Statement
+    field :premiums_earned, :premiums_written, :claims_incurred, :benefits_and_expenses, :investment_income,
+          :investments, :reserves, :unearned_premiums, :premiums_receivable, :reinsurance_recoverables
+
+    INSTANT = %i[investments reserves unearned_premiums premiums_receivable reinsurance_recoverables].freeze
+
+    # Adds up +statements+, keeping the latest balances instead.
+    def self.sum(statements)
+      summed = super
+      balances = INSTANT.to_h { |field| [field, statements.first.public_send(field)] }
+      new(**summed.to_h, **balances)
+    end
+
+    # Whether the company earns premiums, the mark of an insurer.
+    def insurer?
+      !premiums_earned.nil? && !premiums_earned.zero?
+    end
+
+    # Buffett's float: reserves and unearned premiums, less what
+    # policyholders and reinsurers still owe. The money an insurer invests
+    # before it pays claims.
+    def float
+      return nil if reserves.nil?
+
+      reserves + (unearned_premiums || 0) - (premiums_receivable || 0) - (reinsurance_recoverables || 0)
+    end
+  end
+end

data/lib/fundamentalista/period.rb

@@ -27,6 +27,9 @@ module Fundamentalista
     # The Banking lines, empty for companies that are not banks.
     attr_reader :banking
 
+    # The Insurance lines, empty for companies that are not insurers.
+    attr_reader :insurance
+
     # Where each line item came from, keyed by item, as Source objects.
     # Empty when the provider does not say.
     attr_reader :sources
@@ -37,14 +40,15 @@ module Fundamentalista
     # The period before this one, or +nil+.
     attr_accessor :prior
 
-    def initialize(fiscal_year:, ended_on:, income:, balance:, cash_flow:, banking: Banking.new, sources: {},
-                   type: :annual, quarter: nil, currency: 'USD', prior: nil)
+    def initialize(fiscal_year:, ended_on:, income:, balance:, cash_flow:, banking: Banking.new, insurance: Insurance.new,
+                   sources: {}, type: :annual, quarter: nil, currency: 'USD', prior: nil)
       @fiscal_year = fiscal_year
       @ended_on = ended_on
       @income = income
       @balance = balance
       @cash_flow = cash_flow
       @banking = banking
+      @insurance = insurance
       @sources = sources
       @type = type
       @quarter = quarter
@@ -69,6 +73,11 @@ module Fundamentalista
       banking.bank?
     end
 
+    # Whether the company is an insurer, judged by premiums earned.
+    def insurer?
+      insurance.insurer?
+    end
+
     # Returns the Source of the line item +name+, or +nil+.
     def source(name)
       sources[name]
@@ -90,7 +99,8 @@ module Fundamentalista
     # Returns the period and its statements as a Hash.
     def to_h
       { fiscal_year: fiscal_year, quarter: quarter, type: type, ended_on: ended_on, currency: currency,
-        income: income.to_h, balance: balance.to_h, cash_flow: cash_flow.to_h, banking: banking.to_h }
+        income: income.to_h, balance: balance.to_h, cash_flow: cash_flow.to_h, banking: banking.to_h,
+        insurance: insurance.to_h }
     end
 
     # The days the period spans, for turning turnover into days.
@@ -136,7 +146,7 @@ module Fundamentalista
       return owner_earnings if name == :owner_earnings
       return per_share(name.to_s.delete_suffix('_per_share').to_sym) if name.end_with?('_per_share')
 
-      statement = [income, balance, cash_flow, banking].find { |candidate| candidate.respond_to?(name) }
+      statement = [income, balance, cash_flow, banking, insurance].find { |candidate| candidate.respond_to?(name) }
       raise ArgumentError, "Unknown metric #{name.inspect}" unless statement
 
       statement.public_send(name)

data/lib/fundamentalista/provider.rb

@@ -2,9 +2,9 @@
 
 module Fundamentalista
   # The contract every data source implements: resolve a Company, return
-  # its Financials, a Quote or +nil+, the analyst Estimates it has, and
-  # its PriceHistory. Subclasses get an HTTP client with retries and error
-  # mapping.
+  # its Financials, a Quote or +nil+, the analyst Estimates it has, its
+  # PriceHistory and its revenue Segments. Subclasses get an HTTP client
+  # with retries and error mapping.
   class Provider
     class << self
       # The symbol the provider is registered under.
@@ -39,6 +39,10 @@ module Fundamentalista
       raise NotImplementedError
     end
 
+    def segments(company, by:)
+      raise NotImplementedError
+    end
+
     private
 
     def get(url, params = {}, headers: {})

data/lib/fundamentalista/providers/edgar/tags.rb

@@ -111,7 +111,22 @@ module Fundamentalista
         # by fiscal year end, used when the balance sheet lacks the item.
         COVER = { shares_outstanding: 'EntityCommonStockSharesOutstanding' }.freeze
 
-        INSTANT = (BALANCE.keys + Banking::INSTANT).freeze
+        INSURANCE = {
+          premiums_earned: %w[PremiumsEarnedNet DirectPremiumsEarned],
+          premiums_written: %w[PremiumsWrittenNet DirectPremiumsWritten],
+          claims_incurred: %w[PolicyholderBenefitsAndClaimsIncurredNet
+                              LiabilityForUnpaidClaimsAndClaimsAdjustmentExpenseIncurredClaims1],
+          benefits_and_expenses: %w[BenefitsLossesAndExpenses],
+          investment_income: %w[NetInvestmentIncome GrossInvestmentIncomeOperating],
+          investments: %w[Investments],
+          reserves: %w[LiabilityForFuturePolicyBenefitsAndUnpaidClaimsAndClaimsAdjustmentExpense
+                       LiabilityForClaimsAndClaimsAdjustmentExpense LiabilityForFuturePolicyBenefits],
+          unearned_premiums: %w[UnearnedPremiums],
+          premiums_receivable: %w[PremiumsReceivableAtCarryingValue],
+          reinsurance_recoverables: %w[ReinsuranceRecoverablesOnPaidAndUnpaidLosses]
+        }.freeze
+
+        INSTANT = (BALANCE.keys + Banking::INSTANT + Insurance::INSTANT).freeze
       end
     end
   end

data/lib/fundamentalista/providers/edgar.rb

@@ -44,10 +44,15 @@ module Fundamentalista
         raise QuoteUnavailableError, "EDGAR has no prices for #{company.ticker}; pass a PriceHistory"
       end
 
+      def segments(company, **)
+        raise UnsupportedPeriodError, "EDGAR's company facts carry no segments for #{company.ticker}"
+      end
+
       private
 
       STATEMENTS = { income: [IncomeStatement, Tags::INCOME], balance: [BalanceSheet, Tags::BALANCE],
-                     cash_flow: [CashFlowStatement, Tags::CASH_FLOW], banking: [Banking, Tags::BANKING] }.freeze
+                     cash_flow: [CashFlowStatement, Tags::CASH_FLOW], banking: [Banking, Tags::BANKING],
+                     insurance: [Insurance, Tags::INSURANCE] }.freeze
       private_constant :STATEMENTS
 
       def annual_period(facts, year, ended_on)

data/lib/fundamentalista/providers/fmp.rb

@@ -4,7 +4,7 @@ module Fundamentalista
   module Providers
     # Financial Modeling Prep. Needs Configuration#fmp_api_key. Serves
     # annual and quarterly periods, company profiles with beta, live
-    # quotes, analyst estimates and daily prices.
+    # quotes, analyst estimates, daily prices and revenue segments.
     class FMP < Provider
       BASE_URL = 'https://financialmodelingprep.com/stable/'
 
@@ -39,6 +39,14 @@ module Fundamentalista
         PriceHistory.new(points)
       end
 
+      SEGMENTS = { product: 'revenue-product-segmentation', geography: 'revenue-geographic-segments' }.freeze
+
+      def segments(company, by: :product)
+        endpoint = SEGMENTS.fetch(by) { raise ArgumentError, "Segments come by :product or :geography, not #{by.inspect}" }
+        rows = fetch(endpoint, symbol: company.ticker, period: 'annual')
+        Segments.new(rows.to_h { |row| [row['fiscalYear'].to_i, row['data'] || {}] })
+      end
+
       def estimates(company)
         fetch('analyst-estimates', symbol: company.ticker, period: 'annual', limit: 10).map do |row|
           Estimate.new(fiscal_year_end: Date.parse(row['date']), eps: row['epsAvg'], eps_low: row['epsLow'],

data/lib/fundamentalista/ratios.rb

@@ -24,7 +24,8 @@ module Fundamentalista
                          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
+    INSURANCE = %i[loss_ratio expense_ratio combined_ratio investment_yield float_to_equity].freeze
+    ALL = (PROFITABILITY + LIQUIDITY + LEVERAGE + EFFICIENCY + WORKING_CAPITAL + CASH + BANKING + INSURANCE).freeze
 
     attr_reader :period
 
@@ -182,15 +183,42 @@ module Fundamentalista
       Decimal.ratio(banking.allowance_for_credit_losses, banking.loans)
     end
 
+    # Claims incurred over premiums earned.
+    def loss_ratio
+      Decimal.ratio(insurance.claims_incurred, insurance.premiums_earned)
+    end
+
+    # Everything the insurer spends beyond claims, over premiums earned.
+    def expense_ratio
+      Decimal.subtract(combined_ratio, loss_ratio)
+    end
+
+    # Benefits, losses and expenses over premiums earned; below one the
+    # underwriting itself makes money.
+    def combined_ratio
+      Decimal.ratio(insurance.benefits_and_expenses, insurance.premiums_earned)
+    end
+
+    # Net investment income over average investments.
+    def investment_yield
+      Decimal.ratio(insurance.investment_income, average(:investments, of: :insurance))
+    end
+
+    # The float over equity, the leverage an insurer's investing runs on.
+    def float_to_equity
+      Decimal.ratio(insurance.float, balance.equity)
+    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.
+    # Returns every ratio keyed by name; the banking ones only for banks,
+    # the insurance ones only for insurers.
     def to_h
-      names = period.bank? ? ALL : ALL - BANKING
+      names = ALL - (period.bank? ? [] : BANKING) - (period.insurer? ? [] : INSURANCE)
       names.to_h { |name| [name, public_send(name)] }
     end
 
@@ -216,6 +244,10 @@ module Fundamentalista
       period.banking
     end
 
+    def insurance
+      period.insurance
+    end
+
     def average(field, of: :balance)
       current = period.public_send(of).public_send(field)
       return current unless period.prior

data/lib/fundamentalista/segments.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Fundamentalista
+  # Revenue by product line or by region over the years: what a company
+  # actually sells and where. Amounts are in the reporting currency,
+  # keyed by fiscal year, newest first.
+  #
+  #   segments = company.segments(by: :product)            # FMP
+  #   segments.latest              # => {"iPhone" => 0.209586e12, "Service" => 0.109158e12, ...}
+  #   segments.share               # => {"iPhone" => 0.503e0, ...}
+  #   segments.growth("Service", years: 5)
+  #
+  class Segments
+    include Inspectable
+    include Serializable
+
+    def initialize(years)
+      @years = years.sort_by { |year, _| -year }.to_h do |year, amounts|
+        [year, amounts.transform_values do |amount|
+          Decimal.wrap(amount)
+        end]
+      end
+    end
+
+    # The fiscal years on file, newest first.
+    def years
+      @years.keys
+    end
+
+    # Every segment name that appears in any year.
+    def names
+      @years.values.flat_map(&:keys).uniq
+    end
+
+    # The amounts of +year+, the latest by default.
+    def [](year)
+      @years[year]
+    end
+
+    def latest
+      @years.values.first
+    end
+
+    # Returns each segment's share of the year's total, as rates.
+    def share(year = years.first)
+      amounts = @years.fetch(year, {})
+      total = amounts.values.sum(BigDecimal('0'))
+      amounts.transform_values { |amount| Decimal.ratio(amount, total) }
+    end
+
+    # Returns the compound annual growth of +name+ from the year +years+
+    # back to the latest, or over the whole history by default.
+    def growth(name, years: nil)
+      span = years ? [years, self.years.size - 1].min : self.years.size - 1
+      return nil if span < 1
+
+      first = self.years[span]
+      Decimal.cagr(@years.dig(first, name), @years.dig(self.years.first, name), self.years.first - first)
+    end
+
+    def to_h
+      @years
+    end
+
+    def inspect_attributes # :nodoc:
+      { years: years.size, latest: years.first, segments: names.size }
+    end
+  end
+end

data/lib/fundamentalista/valuation.rb

@@ -179,6 +179,38 @@ module Fundamentalista
       ((market_cap * equity_cost) + (debt * debt_cost)) / capital
     end
 
+    # Greenwald's earnings power value per share: the after tax EBIT the
+    # business earns today, capitalized at the +discount_rate+ as if it
+    # never grew, net of debt. What the company is worth with no growth
+    # priced in; compare it with the price to see how much growth is.
+    def earnings_power_value(discount_rate:)
+      nopat = income.ebit && income.tax_rate && (income.ebit * (1 - income.tax_rate))
+      return nil if nopat.nil? || shares_outstanding.nil?
+
+      equity = (nopat / Decimal.wrap(discount_rate)) - (balance.net_debt || 0)
+      equity / shares_outstanding
+    end
+
+    # The residual income value per share: book value plus the present
+    # value of the earnings above the +cost_of_equity+ charge on it, grown
+    # at +growth+ for +years+ and then fading to nothing. Rewards returns
+    # on equity above the cost of equity, and nothing else.
+    def residual_income_value(cost_of_equity:, growth: BigDecimal('0'), years: 10)
+      book = balance.equity
+      earnings = income.net_income
+      return nil if book.nil? || earnings.nil? || shares_outstanding.nil?
+
+      rate = Decimal.wrap(cost_of_equity)
+      value = book
+      (1..years).each do |year|
+        residual = earnings - (rate * book)
+        value += residual / ((1 + rate)**year)
+        earnings *= 1 + Decimal.wrap(growth)
+        book += earnings * (1 - (payout_ratio || 0))
+      end
+      value / shares_outstanding
+    end
+
     # The reverse DCF: the yearly free cash flow growth the price implies
     # under the given +discount_rate+ and the other DCF keywords. +nil+
     # when no growth between -50% and +100% reproduces the price.

data/lib/fundamentalista/version.rb

@@ -2,5 +2,5 @@
 
 module Fundamentalista
   # The version of the fundamentalista gem, as a string.
-  VERSION = '0.2.0'
+  VERSION = '0.4.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fundamentalista
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Bruno Costanzo
@@ -92,6 +92,7 @@ files:
 - lib/fundamentalista/financials.rb
 - lib/fundamentalista/income_statement.rb
 - lib/fundamentalista/inspectable.rb
+- lib/fundamentalista/insurance.rb
 - lib/fundamentalista/period.rb
 - lib/fundamentalista/price_history.rb
 - lib/fundamentalista/provider.rb
@@ -104,6 +105,7 @@ files:
 - lib/fundamentalista/scores/altman_z.rb
 - lib/fundamentalista/scores/beneish.rb
 - lib/fundamentalista/scores/piotroski.rb
+- lib/fundamentalista/segments.rb
 - lib/fundamentalista/serializable.rb
 - lib/fundamentalista/source.rb
 - lib/fundamentalista/statement.rb