fundamentalista 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0d6101d9bee968831b3ffb75a7e6663deb2bb1fc925a2c01b7a4cfcfcfb50fd4
-  data.tar.gz: 52119b52c85c8bf846516846f9af7e11612bdd6c27048940007c5c798bd368e9
+  metadata.gz: 60ef7c2913952daa4c9a4bcf633813d421326b9cc9ccc55755731ef536c51785
+  data.tar.gz: 712549d9e3a33d73e2ce21ca19c5780267cdb64a02261b546dff0e62ac05c3e2
 SHA512:
-  metadata.gz: fc67da833989bdf483cc1fdabf382bd0f62cdd64539ae7edca030008c94f5380952224b0f83f1e2adc14651d851e2fcea8b03289e4f731a218432e8ed97f924b
-  data.tar.gz: b6125c1afde39ba4ba9298c3080ce4141ed3afeaecab18bd5a8aa1e10fefd939f68bf3f9d3d91ec8b04a1dbfb4822ad8cca5eb4512953101e057bce92d7434fa
+  metadata.gz: a5d017ed989ad8ba888720041675e15bd683fdf391dcfb9dbdf5d14918f9acc88581854eeef5ed4995f69b3ad25074f5e60f1df63e420e03481ed387b342a302
+  data.tar.gz: f839a5b66257300a5b139fac8d303b031ebfd282878b16bdaa6a79dd643d59a905b89499d1ab93195f623190b74d5c66cd5cf4fe36792ceddde8c4c4e0af364b

data/CHANGELOG.md

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

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
 
@@ -315,6 +323,7 @@ valuation.residual_income_value(cost_of_equity: 0.09, growth: 0.04, years: 10)
 | 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/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

@@ -3,8 +3,8 @@
 module Fundamentalista
   # The contract every data source implements: resolve a Company, return
   # 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.
+  # 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.
@@ -43,6 +43,10 @@ module Fundamentalista
       raise NotImplementedError
     end
 
+    def rates(currencies, to:)
+      raise NotImplementedError
+    end
+
     private
 
     def get(url, params = {}, headers: {})

data/lib/fundamentalista/providers/edgar.rb

@@ -48,6 +48,10 @@ module Fundamentalista
         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, daily prices and revenue segments.
+    # quotes, analyst estimates, daily prices, revenue segments and
+    # exchange rates.
     class FMP < Provider
       BASE_URL = 'https://financialmodelingprep.com/stable/'
 
@@ -47,6 +48,14 @@ module Fundamentalista
         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/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
 

data/lib/fundamentalista/version.rb

@@ -2,5 +2,5 @@
 
 module Fundamentalista
   # The version of the fundamentalista gem, as a string.
-  VERSION = '0.4.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.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Bruno Costanzo
@@ -101,6 +101,7 @@ 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