fundamentalista 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 37f787ea99f5a949329fb943c8994bc1fa3cb3b9f0ed357757926b4bb661fb57
-  data.tar.gz: f974e488c25c1b0628e9c6fbca2400b6aa86c99705d8d274d008591a0a93d52e
+  metadata.gz: 60ef7c2913952daa4c9a4bcf633813d421326b9cc9ccc55755731ef536c51785
+  data.tar.gz: 712549d9e3a33d73e2ce21ca19c5780267cdb64a02261b546dff0e62ac05c3e2
 SHA512:
-  metadata.gz: a8f4e210ea59fac412647858620bd23f880785fb723c902770e81b295bdfd0671884affb0b1a849e165f49f0d2dc90660c5978374f673b5038b8e5ef6002cf6b
-  data.tar.gz: 438bf83861f879aa1c4f4b47468ffdb974ab1d3700aaa5ea8ec8375a8da891e689bc21bbc7ce11b1e50b290351342da399040e185fd5c6f06d4e2392389e46b5
+  metadata.gz: a5d017ed989ad8ba888720041675e15bd683fdf391dcfb9dbdf5d14918f9acc88581854eeef5ed4995f69b3ad25074f5e60f1df63e420e03481ed387b342a302
+  data.tar.gz: f839a5b66257300a5b139fac8d303b031ebfd282878b16bdaa6a79dd643d59a905b89499d1ab93195f623190b74d5c66cd5cf4fe36792ceddde8c4c4e0af364b

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.5.0
+
+- Exchange `Rates` from FMP or your own, and comparisons in one currency that convert amounts and leave ratios alone.
+
+## 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

@@ -190,7 +190,15 @@ peers.rank(:pe, ascending: true)
 peers.magic_formula
 ```
 
-Tickers the provider cannot resolve are logged and left out, so one bad symbol does not spoil a screen. Absolute figures such as revenue stay in each company's reporting currency; ratios compare across currencies, amounts do not.
+Tickers the provider cannot resolve are logged and left out, so one bad symbol does not spoil a screen.
+
+Ratios and multiples compare across currencies as they are; amounts do not. Pass `currency:` and the amounts, revenue, market cap, book value per share and the rest, are converted through exchange `Rates`, fetched from FMP or given by you on EDGAR, while everything that is a rate or a multiple stays untouched.
+
+```ruby
+rates = Fundamentalista::Rates.new({ "DKK" => 0.156, "EUR" => 1.16 }, to: "USD")
+Fundamentalista.compare("AAPL", "NVO", "SAP", currency: "USD", rates: rates).values(:revenue)
+Fundamentalista.compare("AAPL", "NVO", currency: "USD", provider: :fmp).table(:revenue, :net_margin)   # rates from FMP
+```
 
 ## Provenance
 
@@ -285,6 +293,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 +322,8 @@ 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 |
+| Exchange rates | No, bring Rates | 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/comparison.rb

@@ -3,12 +3,15 @@
 module Fundamentalista
   # Several companies side by side: any ratio, valuation figure, score or
   # line item as a table, rankings on any of them, and Greenblatt's magic
-  # formula ranking.
+  # formula ranking. With a +currency+, amounts such as revenue or market
+  # cap are converted into it through Rates, while ratios and multiples
+  # stay as they are.
   #
   #   peers = Fundamentalista.compare("AAPL", "MSFT", prices: { "AAPL" => 320, "MSFT" => 500 })
   #   peers.table(:roe, :pe, :piotroski)   # => {"AAPL" => {roe: ..., pe: ..., piotroski: 8}, ...}
   #   peers.rank(:pe, ascending: true)     # => ["MSFT", "AAPL"]
   #   peers.magic_formula                  # => ["AAPL", "MSFT"]
+  #   Fundamentalista.compare("AAPL", "NVO", currency: "USD").values(:revenue)
   #
   class Comparison
     include Enumerable
@@ -20,9 +23,25 @@ module Fundamentalista
 
     attr_reader :companies
 
-    def initialize(companies, prices: {})
+    # The currency amounts are converted into, or +nil+ to leave each
+    # company in its own.
+    attr_reader :currency
+
+    def initialize(companies, prices: {}, currency: nil, rates: nil)
       @companies = companies.to_h { |company| [company.ticker, company] }
       @prices = prices.transform_keys(&:to_s)
+      @currency = currency
+      @rates = rates
+    end
+
+    # The Rates in use, fetched from the first company's provider when
+    # none were given.
+    def rates
+      return nil unless currency
+
+      @rates ||= companies.values.first.provider.rates(companies.values.map do |company|
+        company.latest_period.currency
+      end, to: currency)
     end
 
     def each(&)
@@ -67,10 +86,18 @@ module Fundamentalista
       period = company.latest_period
       valuation = valuation_of(company, period)
       return period.ratios.public_send(name) if Ratios::ALL.include?(name)
-      return valuation&.public_send(name) if Valuation::ALL.include?(name)
+      if Valuation::ALL.include?(name)
+        return converted(valuation&.public_send(name), period, amount: Valuation::AMOUNTS.include?(name))
+      end
       return SCORES[name].call(period, valuation) if SCORES.key?(name)
 
-      period.metric(name)
+      converted(period.metric(name), period, amount: !name.end_with?('shares_outstanding', 'diluted_shares'))
+    end
+
+    def converted(value, period, amount:)
+      return value if value.nil? || !amount || currency.nil? || period.currency == currency
+
+      rates.convert(value, from: period.currency)
     end
 
     def valuation_of(company, period)

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, and exchange Rates. Subclasses
+  # get an HTTP client with retries and error mapping.
   class Provider
     class << self
       # The symbol the provider is registered under.
@@ -39,6 +39,14 @@ module Fundamentalista
       raise NotImplementedError
     end
 
+    def segments(company, by:)
+      raise NotImplementedError
+    end
+
+    def rates(currencies, to:)
+      raise NotImplementedError
+    end
+
     private
 
     def get(url, params = {}, headers: {})

data/lib/fundamentalista/providers/edgar.rb

@@ -44,6 +44,14 @@ 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
+
+      def rates(_currencies, **)
+        raise QuoteUnavailableError, 'EDGAR has no exchange rates; pass Rates'
+      end
+
       private
 
       STATEMENTS = { income: [IncomeStatement, Tags::INCOME], balance: [BalanceSheet, Tags::BALANCE],

data/lib/fundamentalista/providers/fmp.rb

@@ -4,7 +4,8 @@ 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, revenue segments and
+    # exchange rates.
     class FMP < Provider
       BASE_URL = 'https://financialmodelingprep.com/stable/'
 
@@ -39,6 +40,22 @@ 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 rates(currencies, to: 'USD')
+        pairs = currencies.map(&:to_s).uniq - [to]
+        return Rates.new({}, to: to) if pairs.empty?
+
+        rows = fetch('batch-quote-short', symbols: pairs.map { |currency| "#{currency}#{to}" }.join(','))
+        Rates.new(rows.to_h { |row| [row['symbol'].delete_suffix(to), row['price']] }, to: to)
+      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/rates.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Fundamentalista
+  # Exchange rates into one base currency: how many units of the base one
+  # unit of each currency buys. Converts amounts so companies reporting in
+  # different currencies can be put side by side.
+  #
+  #   rates = Fundamentalista::Rates.new({ "EUR" => 1.16, "JPY" => 0.0068 }, to: "USD")
+  #   rates.convert(36_800_000_000, from: "EUR")     # => 0.42688e11
+  #
+  class Rates
+    include Inspectable
+
+    # The ISO code every amount converts into.
+    attr_reader :base
+
+    def initialize(rates, to: 'USD')
+      @base = to
+      @rates = rates.to_h { |currency, rate| [currency.to_s, Decimal.wrap(rate)] }
+    end
+
+    # Returns the rate of +currency+ into the base, 1 for the base itself,
+    # or +nil+ when unknown.
+    def [](currency)
+      currency.to_s == base ? BigDecimal('1') : @rates[currency.to_s]
+    end
+
+    def known?(currency)
+      !self[currency].nil?
+    end
+
+    # Returns +amount+ in the base currency, or +nil+ when the amount or
+    # the rate is missing.
+    def convert(amount, from:)
+      rate = self[from]
+      amount && rate && (Decimal.wrap(amount) * rate)
+    end
+
+    def inspect_attributes # :nodoc:
+      { base: base, currencies: @rates.keys }
+    end
+  end
+end

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

@@ -18,7 +18,8 @@ module Fundamentalista
 
     MULTIPLES = %i[pe forward_pe pb ps ev_to_ebitda ev_to_ebit ev_to_sales peg].freeze
     YIELDS = %i[earnings_yield ebit_yield fcf_yield dividend_yield shareholder_yield payout_ratio].freeze
-    ALL = (MULTIPLES + YIELDS + %i[market_cap enterprise_value book_value_per_share graham_number]).freeze
+    AMOUNTS = %i[market_cap enterprise_value book_value_per_share graham_number].freeze
+    ALL = (MULTIPLES + YIELDS + AMOUNTS).freeze
 
     attr_reader :period, :quote, :estimate
 
@@ -179,6 +180,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.5.0'
 end

data/lib/fundamentalista.rb

@@ -36,9 +36,10 @@ module Fundamentalista
     end
 
     # Returns a Comparison of the companies behind +tickers+, valued at
-    # +prices+ where given. Tickers the provider cannot resolve are logged
-    # and left out.
-    def compare(*tickers, prices: {}, provider: config.default_provider)
+    # +prices+ where given, with amounts converted into +currency+ through
+    # the provider's Rates or the +rates+ you pass. Tickers the provider
+    # cannot resolve are logged and left out.
+    def compare(*tickers, prices: {}, currency: nil, rates: nil, provider: config.default_provider)
       source = provider(provider)
       companies = tickers.flatten.filter_map do |ticker|
         source.company(ticker)
@@ -46,7 +47,7 @@ module Fundamentalista
         logger.warn("Skipping #{ticker}: #{e.message}")
         nil
       end
-      Comparison.new(companies, prices: prices)
+      Comparison.new(companies, prices: prices, currency: currency, rates: rates)
     end
 
     # Returns an instance of the provider registered under +slug+.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fundamentalista
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Bruno Costanzo
@@ -101,10 +101,12 @@ files:
 - lib/fundamentalista/providers/edgar/tags.rb
 - lib/fundamentalista/providers/fmp.rb
 - lib/fundamentalista/quote.rb
+- lib/fundamentalista/rates.rb
 - lib/fundamentalista/ratios.rb
 - 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