fundamentalista 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0d6101d9bee968831b3ffb75a7e6663deb2bb1fc925a2c01b7a4cfcfcfb50fd4
-  data.tar.gz: 52119b52c85c8bf846516846f9af7e11612bdd6c27048940007c5c798bd368e9
+  metadata.gz: eeff95349adcf9312850781f5792f603793c0a104cd49a370d7895eddb9bf334
+  data.tar.gz: 1268d8bd7117f7a874de9d8fd65b51f13d70d2b5b1aae5b106e0426b20b1f852
 SHA512:
-  metadata.gz: fc67da833989bdf483cc1fdabf382bd0f62cdd64539ae7edca030008c94f5380952224b0f83f1e2adc14651d851e2fcea8b03289e4f731a218432e8ed97f924b
-  data.tar.gz: b6125c1afde39ba4ba9298c3080ce4141ed3afeaecab18bd5a8aa1e10fefd939f68bf3f9d3d91ec8b04a1dbfb4822ad8cca5eb4512953101e057bce92d7434fa
+  metadata.gz: db32e147665acf8f33c7a0d8afe0df06377bd4273b70a33064f077919bf8a7684e06885a17c25b54921578dcf8e66863b921cb481c947e987b2e4181edfa2f2f
+  data.tar.gz: aa1d5c94637e79a7f215b3bf7d0532ca1f6636a8ca5df2c233621b3237af58ac39fcf0664600d5baf5634a6c191378f79a9cf5a87434b3bddfb30e05155a529e

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.6.0
+
+- Derived fourth quarters keep the annual weighted average shares and compute diluted EPS instead of subtracting year to date values; the `:year_to_date` derivation says so on the `Source`.
+- Fourth quarters an older 10-K labels `Q4`, revenue read from the concept the latest filing uses, currency from the statements rather than USD by default, and one currency per company when a filer tags several.
+- Concepts for IFRS depreciation, borrowings, sales of goods, CECL credit provisions, insurance reserves summed from claims and future policy benefits, premiums receivable and reinsurance recoverables.
+- Expenses and outflows as magnitudes whichever sign the filer gave them; `bank?` requires positive net interest income.
+- Dividends per share on the cash flow statement, read from the filing before it is derived.
+- NOPAT on the income statement, ROIC and Greenblatt's return on capital built on it, net working capital without inventory, and a floor on negative working capital.
+- `DCF` rejects missing inputs and earnings power value is `nil` at a zero discount rate; the residual income model grows earnings before charging for the book.
+- `Company#financials` raises `NoFinancialsError` when a filer has no statements, and every error inherits `Fundamentalista::Error`.
+- `Company` and `Source` serialize, `Period#to_h` carries its sources, `Valuation#to_h` carries the price, and `as_json` returns string keys.
+- Companies looked up by CIK, comparisons over trailing twelve months with `period: :ttm`, and one company facts document per company per provider.
+
+## 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

@@ -51,6 +51,7 @@ apple = Fundamentalista.company("AAPL")
 apple = Fundamentalista.company("AAPL", provider: :fmp)
 apple.name   # => "Apple Inc."
 apple.cik    # => 320193
+exxon = Fundamentalista.company(34088)   # a CIK, for registrants the ticker list no longer carries
 ```
 
 `financials` returns the reporting history as `Financials`, an `Enumerable` of `Period`s ordered newest first. Each `Period` carries its `income`, `balance` and `cash_flow` statements and knows the period before it, which is what average balances, growth and the Piotroski score are built on.
@@ -84,7 +85,7 @@ ttm.growth(:revenue)                # against the previous twelve months
 apple.valuation(price: 320, period: ttm).pe
 ```
 
-EDGAR reports quarterly cash flows only year to date, and the fourth quarter only as the annual figure. Fundamentalista reads a quarter directly when the filing has a three month value and derives it otherwise as the difference between two year to date values that share a fiscal year start.
+EDGAR reports quarterly cash flows only year to date, and the fourth quarter only as the annual figure. Fundamentalista reads a quarter directly when the filing has a three month value and derives it otherwise as the difference between two year to date values that share a fiscal year start. Weighted average shares are not additive, so a derived fourth quarter keeps the annual average, and diluted EPS is computed from net income and shares rather than derived.
 
 ### Statements
 
@@ -94,9 +95,9 @@ EDGAR reports quarterly cash flows only year to date, and the fourth quarter onl
 | `BalanceSheet` | cash, short term investments, receivables, inventory, current assets, PP&E, total assets, payables, current liabilities, total liabilities, short and long term debt, total debt, equity, minority interest, retained earnings, shares outstanding | total liabilities, total debt, liquid assets, net debt, working capital, net working capital |
 
 EBIT is operating income when the company reports one, and income before tax plus interest expense otherwise, which is what pharmaceutical and oil companies leave you; interest coverage, EV/EBIT, Greenblatt's yield and return on capital and the Altman Z-score all use it. Figures follow the line as reported: receivables are trade receivables, PP&E excludes lease right-of-use assets, cost of revenue is the company's own line.
-| `CashFlowStatement` | operating cash flow, capital expenditure, free cash flow, dividends paid, share repurchases | free cash flow, shareholder returns |
+| `CashFlowStatement` | operating cash flow, capital expenditure, free cash flow, dividends paid, dividends per share, share repurchases | free cash flow, shareholder returns |
 
-Outflows are positive amounts: `capital_expenditure` is what was spent.
+Outflows are positive amounts whichever sign the filer gave them: `capital_expenditure` is what was spent.
 
 ## Banks
 
@@ -190,11 +191,19 @@ 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. Comparisons read the latest fiscal year; pass `period: :ttm` to compare trailing twelve months instead.
+
+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
 
-Every EDGAR line item remembers where it came from. `period.source(:revenue)` returns the XBRL concept, the form and filing date it was read from, and whether the figure was reported as is, summed from split concepts, or derived from year to date values.
+Every EDGAR line item remembers where it came from. `period.source(:revenue)` returns the XBRL concept, the form and filing date it was read from, and whether the figure was reported as is, summed from split concepts, derived from year to date values, or, for a weighted average, carried from the year to date figure.
 
 ```ruby
 year.source(:revenue)
@@ -315,11 +324,12 @@ 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.
 
-Foreign filers report under IFRS in 20-F and 40-F filings with their own taxonomy; the same line items map to it, and `Period#currency` says what the figures are in. Quarterly data is a 10-Q affair, so IFRS filers get annual periods.
+Foreign filers report under IFRS in 20-F and 40-F filings with their own taxonomy; the same line items map to it, and `Period#currency` says what the figures are in, `nil` when the filing reports revenue and assets in no currency at all. Filers that tag several currencies, such as a Chinese company reporting in CNY with USD convenience figures, are read in the currency of their own statements. Quarterly data is a 10-Q affair, so IFRS filers get annual periods.
 
 ### Coverage
 
@@ -332,9 +342,13 @@ The concept map is measured, not guessed. `script/coverage` reads the latest ann
 | diluted EPS, income before tax, interest expense, depreciation and amortization, diluted shares | 5% to 7% |
 | shares outstanding, PP&E, capital expenditure | 11% to 14% |
 
-What is missing beyond that is mostly absent from the filing itself: inventory and cost of revenue at service and financial companies, buybacks and dividends at companies that do none, a classified balance sheet at banks and insurers. Companies with no annual filing yet, such as a fresh listing, raise `NoFinancialsError`.
+What is missing beyond that is mostly absent from the filing itself: inventory and cost of revenue at service and financial companies, buybacks and dividends at companies that do none, a classified balance sheet at banks and insurers. Companies with no annual filing yet, such as a fresh listing, raise `NoFinancialsError` from `financials`.
+
+Every error inherits `Fundamentalista::Error`. Provider errors are typed: `CompanyNotFoundError`, `UnauthorizedError`, `RateLimitError`, `ServerError`, each carrying the HTTP `response`. Transient failures are retried, and EDGAR requests are spaced to the SEC's rate limit.
+
+### Limitations
 
-Provider errors are typed: `CompanyNotFoundError`, `UnauthorizedError`, `RateLimitError`, `ServerError`, each carrying the HTTP `response`. Transient failures are retried, and EDGAR requests are spaced to the SEC's rate limit.
+The figures are as filed. A stock split is restated only in filings made after it, so per share history before the split is in pre-split shares. Companies with several share classes tag the totals per class, so `diluted_shares` and `shares_outstanding` can be missing for them. A company in its first year of filing may label two quarters the same way, and one of them is dropped. Expenses a filer negates, such as a released credit provision, keep their sign.
 
 ### Caching
 

data/lib/fundamentalista/balance_sheet.rb

@@ -40,8 +40,9 @@ module Fundamentalista
 
     # Working capital net of cash and debt: receivables plus inventory minus
     # payables, the operating capital Greenblatt's return on capital uses.
+    # A company with no inventory line has none.
     def net_working_capital
-      Decimal.subtract(Decimal.sum(receivables, inventory), payables)
+      Decimal.subtract(Decimal.sum(receivables, inventory || BigDecimal('0')), payables)
     end
   end
 end

data/lib/fundamentalista/banking.rb

@@ -19,9 +19,11 @@ module Fundamentalista
       new(**summed.to_h, **balances)
     end
 
-    # Whether the company reports net interest income, the mark of a bank.
+    # Whether the company earns net interest income, the mark of a bank;
+    # an insurer or industrial tagging its net interest expense there is
+    # not one.
     def bank?
-      !net_interest_income.nil? && !net_interest_income.zero?
+      !net_interest_income.nil? && net_interest_income.positive?
     end
 
     # Net interest income plus noninterest income, a bank's revenue.

data/lib/fundamentalista/cash_flow_statement.rb

@@ -2,9 +2,11 @@
 
 module Fundamentalista
   # One period of the cash flow statement. Outflows are positive amounts:
-  # +capital_expenditure+ is what was spent, +dividends_paid+ what was paid.
+  # +capital_expenditure+ is what was spent, +dividends_paid+ what was paid,
+  # and +dividends_per_share+ what was declared on each share.
   class CashFlowStatement < Statement
-    field :operating_cash_flow, :capital_expenditure, :free_cash_flow, :dividends_paid, :share_repurchases
+    field :operating_cash_flow, :capital_expenditure, :free_cash_flow, :dividends_paid, :dividends_per_share,
+          :share_repurchases
 
     # Free cash flow, derived from operating cash flow and capital
     # expenditure when not reported.

data/lib/fundamentalista/company.rb

@@ -16,6 +16,7 @@ module Fundamentalista
   #
   class Company
     include Inspectable
+    include Serializable
 
     attr_reader :ticker, :name, :cik, :currency, :provider
 
@@ -34,9 +35,12 @@ module Fundamentalista
     end
 
     # Returns the Financials, newest first. +period+ is +:annual+ or
-    # +:quarterly+ and +limit+ the number of periods.
+    # +:quarterly+ and +limit+ the number of periods. Raises
+    # NoFinancialsError when the provider has none, as with a fresh listing.
     def financials(period: :annual, limit: 5)
-      @financials[[period, limit]] ||= provider.financials(self, period: period, limit: limit)
+      @financials[[period, limit]] ||= provider.financials(self, period: period, limit: limit).tap do |financials|
+        raise NoFinancialsError, "#{provider.class.slug} has no #{period} statements for #{ticker}" if financials.none?
+      end
     end
 
     # Returns the PriceHistory between +from+ and +to+. Raises
@@ -100,7 +104,8 @@ module Fundamentalista
     # Returns the Valuation of the latest annual period at +price+, or at
     # the provider's quote when no price is given, with the next fiscal
     # year's Estimate when the provider has one.
-    def valuation(price: nil, period: latest_period)
+    def valuation(price: nil, period: nil)
+      period ||= latest_period
       Valuation.new(period, price ? Quote.new(price: price) : quote, estimate: estimate(after: period.ended_on))
     end
 
@@ -109,14 +114,17 @@ module Fundamentalista
       latest_period.ratios
     end
 
-    # The latest annual Period. Raises NoFinancialsError when the provider
-    # has no annual statements for the company, as with a fresh listing.
+    # The latest annual Period.
     def latest_period
-      financials.latest || raise(NoFinancialsError, "#{provider.class.slug} has no annual statements for #{ticker}")
+      financials.latest
+    end
+
+    def to_h
+      { ticker: ticker, name: name, cik: cik, currency: currency, beta: beta, provider: provider.class.slug }
     end
 
     def inspect_attributes # :nodoc:
-      { ticker: ticker, name: name, cik: cik, provider: provider.class.slug }
+      to_h.slice(:ticker, :name, :cik, :provider)
     end
   end
 end

data/lib/fundamentalista/comparison.rb

@@ -3,12 +3,17 @@
 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, on the latest fiscal year or, with +period: :ttm+, on
+  # the trailing twelve months. 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", "MSFT", period: :ttm).values(:roe)
+  #   Fundamentalista.compare("AAPL", "NVO", currency: "USD").values(:revenue)
   #
   class Comparison
     include Enumerable
@@ -20,9 +25,30 @@ module Fundamentalista
 
     attr_reader :companies
 
-    def initialize(companies, prices: {})
+    # +:annual+ for the latest fiscal year, +:ttm+ for the trailing twelve
+    # months.
+    attr_reader :period
+
+    # The currency amounts are converted into, or +nil+ to leave each
+    # company in its own.
+    attr_reader :currency
+
+    def initialize(companies, prices: {}, period: :annual, currency: nil, rates: nil)
       @companies = companies.to_h { |company| [company.ticker, company] }
       @prices = prices.transform_keys(&:to_s)
+      @period = period
+      @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(&)
@@ -64,13 +90,25 @@ module Fundamentalista
     private
 
     def metric(company, name)
-      period = company.latest_period
+      period = period_of(company)
       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 period_of(company)
+      period == :ttm ? company.ttm : company.latest_period
+    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/dcf.rb

@@ -24,7 +24,9 @@ module Fundamentalista
       @terminal_growth = Decimal.wrap(terminal_growth)
       @years = years
       @fade = fade
+      raise ArgumentError, 'cash_flow, growth and discount_rate are required' if [@cash_flow, @growth, @discount_rate].any?(nil)
       raise ArgumentError, 'discount_rate must exceed terminal_growth' if @discount_rate <= @terminal_growth
+      raise ArgumentError, 'years must be at least 1' if years < 1
     end
 
     # Whether growth fades towards the terminal rate over the projection.

data/lib/fundamentalista/error.rb

@@ -1,8 +1,9 @@
 # frozen_string_literal: true
 
 module Fundamentalista
-  # Base class for errors raised while talking to a data provider. Carries
-  # the HTTP response when there is one.
+  # Base class of every error the gem raises, so one rescue catches them
+  # all. Errors raised while talking to a data provider carry the HTTP
+  # response when there is one.
   class Error < StandardError
     attr_reader :response
 
@@ -12,12 +13,12 @@ module Fundamentalista
     end
   end
 
-  class ConfigurationError < StandardError; end
+  class ConfigurationError < Error; end
   class CompanyNotFoundError < Error; end
   class UnauthorizedError < Error; end
   class RateLimitError < Error; end
   class ServerError < Error; end
-  class UnsupportedPeriodError < StandardError; end
-  class NoFinancialsError < StandardError; end
-  class QuoteUnavailableError < StandardError; end
+  class UnsupportedPeriodError < Error; end
+  class NoFinancialsError < Error; end
+  class QuoteUnavailableError < Error; end
 end

data/lib/fundamentalista/income_statement.rb

@@ -43,5 +43,13 @@ module Fundamentalista
     def tax_rate
       Decimal.ratio(income_tax, income_before_tax)
     end
+
+    # Net operating profit after tax: EBIT taxed at the effective rate,
+    # held between 0 and 100% so a tax benefit or a loss year does not
+    # inflate it.
+    def nopat
+      rate = tax_rate
+      ebit && rate && (ebit * (1 - rate.clamp(0, 1)))
+    end
   end
 end

data/lib/fundamentalista/period.rb

@@ -96,11 +96,11 @@ module Fundamentalista
       earlier && Decimal.cagr(earlier.metric(metric), self.metric(metric), 1)
     end
 
-    # Returns the period and its statements as a Hash.
+    # Returns the period, its statements and its sources 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,
-        insurance: insurance.to_h }
+        insurance: insurance.to_h, sources: sources.transform_values(&:to_h) }
     end
 
     # The days the period spans, for turning turnover into days.
@@ -137,19 +137,20 @@ module Fundamentalista
     # Returns the line item +name+ from whichever statement reports it, or
     # +nil+. Derived items such as +free_cash_flow+ count, so does
     # +owner_earnings+, and any of them followed by +_per_share+ is divided
-    # by the shares outstanding.
+    # by the shares outstanding, unless a statement reports it per share
+    # already, as with +dividends_per_share+.
     #
     #   period.metric(:revenue)                    # => 0.416161e12
     #   period.metric(:free_cash_flow_per_share)   # => 0.66854e1
     #
     def metric(name)
       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, insurance].find { |candidate| candidate.respond_to?(name) }
-      raise ArgumentError, "Unknown metric #{name.inspect}" unless statement
+      return statement.public_send(name) if statement
+      return per_share(name.to_s.delete_suffix('_per_share').to_sym) if name.end_with?('_per_share')
 
-      statement.public_send(name)
+      raise ArgumentError, "Unknown metric #{name.inspect}"
     end
 
     # Returns +name+ divided by the shares outstanding at the end of the

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/facts.rb

@@ -6,33 +6,40 @@ module Fundamentalista
       # Reads a companyfacts document. Every concept carries every value
       # ever filed, including restatements, so a line item is looked up by
       # the period it describes and the most recently filed value wins,
-      # while the fiscal year label comes from the original filing.
+      # while the fiscal year label comes from the original filing. Only
+      # the units of the reporting currency count, so a filer that tags
+      # figures in two currencies is read in one.
       #
       # Quarterly flows are not always reported as such: cash flow
       # statements in 10-Q filings are year to date, and the fourth quarter
       # only exists as the annual figure. A quarter is read directly when a
       # three month value exists, and derived otherwise as the difference
       # between two year to date values that share a fiscal year start.
+      # Weighted average share counts do not subtract, so the year to date
+      # average stands in for the quarter, and per share earnings are left
+      # for the statement to compute from it.
       class Facts # :nodoc:
         ANNUAL = (350..380)
         QUARTER = (80..100)
         ANNUAL_FORMS = %w[10-K 20-F 40-F].freeze
         QUARTERLY_FORMS = %w[10-K 10-Q].freeze
-        QUARTERS = { 'Q1' => 1, 'Q2' => 2, 'Q3' => 3, 'FY' => 4 }.freeze
+        QUARTERS = { 'Q1' => 1, 'Q2' => 2, 'Q3' => 3, 'Q4' => 4, 'FY' => 4 }.freeze
         TAXONOMIES = %w[us-gaap ifrs-full dei].freeze
+        CURRENCY = /\A[A-Z]{3}\b/
 
         def initialize(document)
           facts = document.fetch('facts', {})
           @facts = TAXONOMIES.map { |taxonomy| facts.fetch(taxonomy, {}) }
         end
 
-        # The ISO code of the currency revenue is reported in.
+        # The ISO code of the currency revenue, or failing that the balance
+        # sheet, is reported in; +nil+ when the document says nothing.
         def currency
-          Tags::INCOME[:revenue].each do |concept|
-            unit = units(concept).keys.find { |candidate| candidate.match?(/\A[A-Z]{3}\z/) }
-            return unit if unit
-          end
-          'USD'
+          return @currency if defined?(@currency)
+
+          @currency = (Tags::INCOME[:revenue] + ['Assets']).lazy.filter_map do |concept|
+            units(concept).keys.find { |unit| unit.match?(/\A[A-Z]{3}\z/) }
+          end.first
         end
 
         # The fiscal years on file, newest first, as [year, ended_on] pairs.
@@ -54,7 +61,7 @@ module Fundamentalista
             found = first_reported(alternatives) do |concept|
               instant?(item) ? instant(concept, ended_on, ANNUAL_FORMS) : yearly(concept, ended_on)
             end
-            [item, found || cover(item, year)]
+            [item, magnitude(item, found || cover(item, year))]
           end
         end
 
@@ -63,14 +70,16 @@ module Fundamentalista
         # [value, Source] pairs keyed by item.
         def quarterly(tags, ended_on, previous)
           tags.to_h do |item, alternatives|
-            [item, first_reported(alternatives) do |concept|
-              instant?(item) ? instant(concept, ended_on) : three_months(concept, ended_on, previous)
-            end]
+            [item, magnitude(item, first_reported(alternatives) { |concept| quarter(item, concept, ended_on, previous) })]
           end
         end
 
         private
 
+        def magnitude(item, found)
+          found && Tags::OUTFLOWS.include?(item) ? [found.first.abs, found.last] : found
+        end
+
         def cover(item, year)
           concept = Tags::COVER[item]
           return nil unless concept && year
@@ -125,16 +134,24 @@ module Fundamentalista
           end)
         end
 
-        def three_months(concept, ended_on, previous)
+        def quarter(item, concept, ended_on, previous)
+          return instant(concept, ended_on) if instant?(item)
+
           spans = ending(concept, ended_on).select { |entry| entry['start'] }
-          latest(concept, spans.select do |entry|
-            QUARTER.cover?(duration_of(entry))
-          end) || derived_quarter(concept, spans, previous)
+          latest(concept, spans.select { |entry| QUARTER.cover?(duration_of(entry)) }) ||
+            from_year_to_date(item, concept, spans, previous)
         end
 
-        def derived_quarter(concept, spans, previous)
+        def from_year_to_date(item, concept, spans, previous)
           year_to_date = spans.max_by { |entry| [duration_of(entry), entry['filed']] }
-          return nil unless year_to_date && previous
+          return nil if year_to_date.nil? || Tags::PER_SHARE.include?(item)
+          return [year_to_date['val'], source_of(concept, year_to_date, :year_to_date)] if Tags::AVERAGES.include?(item)
+
+          derived_quarter(concept, year_to_date, previous)
+        end
+
+        def derived_quarter(concept, year_to_date, previous)
+          return nil unless previous
 
           earlier = latest(concept, ending(concept, previous).select { |entry| entry['start'] == year_to_date['start'] })
           earlier && [year_to_date['val'] - earlier.first, source_of(concept, year_to_date, :derived)]
@@ -160,7 +177,7 @@ module Fundamentalista
         end
 
         def entries(concept)
-          units(concept).values.flatten
+          units(concept).select { |unit, _| !unit.match?(CURRENCY) || unit.start_with?(currency.to_s) }.values.flatten
         end
 
         def units(concept)

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

@@ -13,9 +13,9 @@ module Fundamentalista
       # concepts a date.
       module Tags
         INCOME = {
-          revenue: %w[RevenueFromContractWithCustomerExcludingAssessedTax Revenues SalesRevenueNet
+          revenue: %w[Revenues RevenueFromContractWithCustomerExcludingAssessedTax SalesRevenueNet
                       RevenueFromContractWithCustomerIncludingAssessedTax RevenuesNetOfInterestExpense Revenue
-                      RevenueFromContractsWithCustomers],
+                      RevenueFromContractsWithCustomers RevenueFromSaleOfGoods],
           cost_of_revenue: %w[CostOfRevenue CostOfGoodsAndServicesSold CostOfGoodsSold CostOfSales
                               CostOfGoodsAndServiceExcludingDepreciationDepletionAndAmortization],
           gross_profit: %w[GrossProfit],
@@ -34,7 +34,7 @@ module Fundamentalista
           net_income: %w[NetIncomeLoss ProfitLossAttributableToOwnersOfParent ProfitLoss],
           depreciation_amortization: ['DepreciationDepletionAndAmortization', 'DepreciationAndAmortization',
                                       'DepreciationAmortizationAndAccretionNet', 'DepreciationAmortizationAndOther',
-                                      'DepreciationAndAmortisationExpense',
+                                      'DepreciationAndAmortisationExpense', 'AdjustmentsForDepreciationAndAmortisationExpense',
                                       %w[DepreciationPropertyPlantAndEquipment AmortisationIntangibleAssetsOtherThanGoodwill],
                                       %w[Depreciation AmortizationOfIntangibleAssets], 'Depreciation'],
           eps_diluted: %w[EarningsPerShareDiluted DilutedEarningsLossPerShare],
@@ -66,7 +66,7 @@ module Fundamentalista
                             'ShorttermBorrowings', 'CurrentBorrowings'],
           long_term_debt: %w[LongTermDebtNoncurrent LongTermDebtAndCapitalLeaseObligations LongTermDebt LongTermNotesPayable
                              LongTermNotesAndLoans LongtermBorrowings NoncurrentBorrowings
-                             LongTermDebtAndCapitalLeaseObligationsIncludingCurrentMaturities],
+                             LongTermDebtAndCapitalLeaseObligationsIncludingCurrentMaturities Borrowings],
           equity: %w[StockholdersEquity StockholdersEquityIncludingPortionAttributableToNoncontrollingInterest
                      EquityAttributableToOwnersOfParent Equity],
           minority_interest: %w[MinorityInterest NoncontrollingInterests],
@@ -88,6 +88,7 @@ module Fundamentalista
           dividends_paid: %w[PaymentsOfDividends PaymentsOfDividendsCommonStock PaymentsOfOrdinaryDividends
                              DividendsCommonStockCash DividendsPaidClassifiedAsFinancingActivities
                              DividendsPaidToEquityHoldersOfParentClassifiedAsFinancingActivities DividendsPaid],
+          dividends_per_share: %w[CommonStockDividendsPerShareDeclared CommonStockDividendsPerShareCashPaid],
           share_repurchases: %w[PaymentsForRepurchaseOfCommonStock PaymentsForRepurchaseOfEquity
                                 TreasuryStockValueAcquiredCostMethod PaymentsForPurchaseOfTreasuryShares]
         }.freeze
@@ -96,7 +97,9 @@ module Fundamentalista
           net_interest_income: %w[InterestIncomeExpenseNet],
           interest_income: %w[InterestAndDividendIncomeOperating InterestIncome InterestAndFeeIncomeLoansAndLeases],
           provision_for_credit_losses: %w[ProvisionForLoanLeaseAndOtherLosses ProvisionForLoanAndLeaseLosses
-                                          ProvisionForCreditLosses ProvisionForLoanLossesExpensed],
+                                          ProvisionForCreditLosses ProvisionForLoanLossesExpensed
+                                          FinancingReceivableExcludingAccruedInterestCreditLossExpenseReversal
+                                          FinancingReceivableCreditLossExpenseReversal],
           noninterest_income: %w[NoninterestIncome],
           noninterest_expense: %w[NoninterestExpense],
           loans: %w[FinancingReceivableExcludingAccruedInterestAfterAllowanceForCreditLoss
@@ -119,14 +122,23 @@ module Fundamentalista
           benefits_and_expenses: %w[BenefitsLossesAndExpenses],
           investment_income: %w[NetInvestmentIncome GrossInvestmentIncomeOperating],
           investments: %w[Investments],
-          reserves: %w[LiabilityForFuturePolicyBenefitsAndUnpaidClaimsAndClaimsAdjustmentExpense
-                       LiabilityForClaimsAndClaimsAdjustmentExpense LiabilityForFuturePolicyBenefits],
+          reserves: [%w[LiabilityForClaimsAndClaimsAdjustmentExpense LiabilityForFuturePolicyBenefits],
+                     'LiabilityForFuturePolicyBenefitsAndUnpaidClaimsAndClaimsAdjustmentExpense'],
           unearned_premiums: %w[UnearnedPremiums],
-          premiums_receivable: %w[PremiumsReceivableAtCarryingValue],
-          reinsurance_recoverables: %w[ReinsuranceRecoverablesOnPaidAndUnpaidLosses]
+          premiums_receivable: %w[PremiumsReceivableAtCarryingValue PremiumsAndOtherReceivablesNet],
+          reinsurance_recoverables: %w[ReinsuranceRecoverablesOnPaidAndUnpaidLosses
+                                       ReinsuranceRecoverableForUnpaidClaimsAndClaimsAdjustments]
         }.freeze
 
         INSTANT = (BALANCE.keys + Banking::INSTANT + Insurance::INSTANT).freeze
+
+        # Expenses and outflows are magnitudes, whichever sign the filer gave them.
+        OUTFLOWS = %i[interest_expense capital_expenditure dividends_paid share_repurchases].freeze
+
+        # Weighted averages and per share figures, which no fourth quarter
+        # can be derived for by subtracting year to date values.
+        AVERAGES = %i[diluted_shares].freeze
+        PER_SHARE = %i[eps_diluted].freeze
       end
     end
   end

data/lib/fundamentalista/providers/edgar.rb

@@ -15,10 +15,15 @@ module Fundamentalista
       TICKERS_URL = 'https://www.sec.gov/files/company_tickers.json'
       FACTS_URL = 'https://data.sec.gov/api/xbrl/companyfacts/CIK%010d.json'
 
+      # Resolves a ticker, or a CIK given as digits for registrants the
+      # ticker list no longer carries, such as the predecessor of a company
+      # that reincorporated.
       def company(ticker)
         symbol = ticker.to_s.upcase.tr('.', '-')
-        entry = tickers[symbol] || raise(CompanyNotFoundError, "EDGAR lists no company under #{ticker.inspect}")
-        Company.new(ticker: symbol, name: entry['title'], cik: entry['cik_str'], provider: self)
+        entry = symbol.match?(/\A\d+\z/) ? registrant(symbol.to_i) : tickers[symbol]
+        raise CompanyNotFoundError, "EDGAR lists no company under #{ticker.inspect}" unless entry
+
+        Company.new(ticker: entry['ticker'], name: entry['title'], cik: entry['cik_str'], provider: self)
       end
 
       def financials(company, period: :annual, limit: 5)
@@ -48,6 +53,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],
@@ -78,8 +87,13 @@ module Fundamentalista
                    sources: sources, **statements)
       end
 
+      def registrant(cik)
+        tickers.values.find { |entry| entry['cik_str'] == cik } || { 'ticker' => cik.to_s, 'cik_str' => cik }
+      end
+
       def company_facts(company)
-        get(format(FACTS_URL, company.cik), headers: headers)
+        @documents ||= {}
+        @documents[company.cik] ||= get(format(FACTS_URL, company.cik), headers: headers)
       rescue CompanyNotFoundError => e
         raise CompanyNotFoundError.new("EDGAR has no XBRL facts for #{company.ticker}; it may not file financial statements",
                                        response: e.response)

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/ratios.rb

@@ -59,17 +59,18 @@ module Fundamentalista
       Decimal.ratio(income.net_income, average(:total_assets))
     end
 
-    # Return on invested capital: after tax operating income over average
-    # debt plus equity.
+    # Return on invested capital: net operating profit after tax 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)))
+      Decimal.ratio(income.nopat, Decimal.sum(average(:total_debt), average(:equity)))
     end
 
     # Greenblatt's return on capital: EBIT over net working capital plus net
-    # fixed assets.
+    # fixed assets. Negative working capital is financing, not capital, so
+    # it counts as zero, and there is no return on capital that is not there.
     def return_on_capital
-      Decimal.ratio(income.ebit, Decimal.sum(average(:net_working_capital), average(:ppe)))
+      capital = Decimal.sum(average(:net_working_capital)&.clamp(0..), average(:ppe))
+      capital&.positive? ? Decimal.ratio(income.ebit, capital) : nil
     end
 
     def current_ratio

data/lib/fundamentalista/serializable.rb

@@ -2,9 +2,9 @@
 
 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.
+  # BigDecimal under symbol keys; #as_json turns figures into Floats, dates
+  # into ISO strings and keys into strings, which is what JSON consumers
+  # and Rails expect, so +to_json+ and +render json:+ work out of the box.
   module Serializable
     def as_json(*)
       Serializable.plain(to_h)
@@ -16,7 +16,7 @@ module Fundamentalista
 
     def self.plain(value) # :nodoc:
       case value
-      when Hash then value.transform_values { |inner| plain(inner) }
+      when Hash then value.to_h { |key, inner| [key.to_s, plain(inner)] }
       when Array then value.map { |inner| plain(inner) }
       when Serializable then value.as_json
       else scalar(value)

data/lib/fundamentalista/source.rb

@@ -3,9 +3,11 @@
 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.
+  # split concepts, derived from year to date values, or is the year to
+  # date average standing in for a quarter.
   class Source
     include Inspectable
+    include Serializable
 
     attr_reader :concept, :form, :filed, :derivation
 
@@ -20,8 +22,10 @@ module Fundamentalista
       derivation == :reported
     end
 
-    def inspect_attributes # :nodoc:
+    def to_h
       { concept: concept, form: form, filed: filed, derivation: derivation }
     end
+
+    alias inspect_attributes to_h
   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
 
@@ -101,8 +102,10 @@ module Fundamentalista
       Decimal.ratio(cash_flow.free_cash_flow, market_cap)
     end
 
+    # Dividends declared per share over the price, or dividends paid over
+    # market capitalization when the filing has no per share figure.
     def dividend_yield
-      Decimal.ratio(cash_flow.dividends_paid, market_cap)
+      Decimal.ratio(cash_flow.dividends_per_share, price) || Decimal.ratio(cash_flow.dividends_paid, market_cap)
     end
 
     # Dividends plus buybacks over market capitalization.
@@ -134,10 +137,12 @@ module Fundamentalista
       period.altman_z(market_cap: market_cap)
     end
 
-    # The DCF value per share of the period's free cash flow, net of debt.
-    # Takes the same keywords as DCF.
-    def intrinsic_value(**options)
-      flow = cash_flow.free_cash_flow
+    # The DCF value per share of the period's free cash flow, or of the
+    # normalized +cash_flow+ you pass, net of debt. Takes the same keywords
+    # as DCF. +nil+ when the cash flow is not positive: there is nothing to
+    # discount, and the growth to apply to a loss is not a rate.
+    def intrinsic_value(cash_flow: self.cash_flow.free_cash_flow, **options)
+      flow = Decimal.wrap(cash_flow)
       return nil if flow.nil? || flow <= 0 || shares_outstanding.nil?
 
       equity = DCF.new(cash_flow: flow, **options).value - (balance.net_debt || 0)
@@ -184,17 +189,17 @@ module Fundamentalista
     # 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?
+      capitalized = Decimal.ratio(income.nopat, Decimal.wrap(discount_rate))
+      return nil if capitalized.nil? || shares_outstanding.nil?
 
-      equity = (nopat / Decimal.wrap(discount_rate)) - (balance.net_debt || 0)
-      equity / shares_outstanding
+      (capitalized - (balance.net_debt || 0)) / 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.
+    # value of each coming year's earnings above the +cost_of_equity+
+    # charge on the book value opening it, with earnings grown at +growth+
+    # for +years+ and retained at the payout ratio, and none after. 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
@@ -203,9 +208,8 @@ module Fundamentalista
       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)
+        value += (earnings - (rate * book)) / ((1 + rate)**year)
         book += earnings * (1 - (payout_ratio || 0))
       end
       value / shares_outstanding
@@ -229,7 +233,7 @@ module Fundamentalista
     end
 
     def to_h
-      ALL.to_h { |name| [name, public_send(name)] }
+      { price: price, **ALL.to_h { |name| [name, public_send(name)] } }
     end
 
     def inspect_attributes # :nodoc:

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.6.0'
 end

data/lib/fundamentalista.rb

@@ -36,9 +36,11 @@ 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, on the latest fiscal year or the trailing twelve
+    # months with +period: :ttm+, 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: {}, period: :annual, currency: nil, rates: nil, provider: config.default_provider)
       source = provider(provider)
       companies = tickers.flatten.filter_map do |ticker|
         source.company(ticker)
@@ -46,7 +48,7 @@ module Fundamentalista
         logger.warn("Skipping #{ticker}: #{e.message}")
         nil
       end
-      Comparison.new(companies, prices: prices)
+      Comparison.new(companies, prices: prices, period: period, 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.6.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