fundamentalista 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 37f787ea99f5a949329fb943c8994bc1fa3cb3b9f0ed357757926b4bb661fb57
-  data.tar.gz: f974e488c25c1b0628e9c6fbca2400b6aa86c99705d8d274d008591a0a93d52e
+  metadata.gz: 0d6101d9bee968831b3ffb75a7e6663deb2bb1fc925a2c01b7a4cfcfcfb50fd4
+  data.tar.gz: 52119b52c85c8bf846516846f9af7e11612bdd6c27048940007c5c798bd368e9
 SHA512:
-  metadata.gz: a8f4e210ea59fac412647858620bd23f880785fb723c902770e81b295bdfd0671884affb0b1a849e165f49f0d2dc90660c5978374f673b5038b8e5ef6002cf6b
-  data.tar.gz: 438bf83861f879aa1c4f4b47468ffdb974ab1d3700aaa5ea8ec8375a8da891e689bc21bbc7ce11b1e50b290351342da399040e185fd5c6f06d4e2392389e46b5
+  metadata.gz: fc67da833989bdf483cc1fdabf382bd0f62cdd64539ae7edca030008c94f5380952224b0f83f1e2adc14651d851e2fcea8b03289e4f731a218432e8ed97f924b
+  data.tar.gz: b6125c1afde39ba4ba9298c3080ce4141ed3afeaecab18bd5a8aa1e10fefd939f68bf3f9d3d91ec8b04a1dbfb4822ad8cca5eb4512953101e057bce92d7434fa

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # 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.

data/README.md

@@ -285,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 |
@@ -294,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/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.rb

@@ -44,6 +44,10 @@ 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],

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/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.3.0'
+  VERSION = '0.4.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fundamentalista
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Bruno Costanzo
@@ -105,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