fundamentalista 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 432e0a27a0bed71a2f55d3574bf27c0ac4a781d08217de34f2a9c9dfc3a4ea87
+  data.tar.gz: d8c0b9a22759ec8142e016c072b2d59a153b014f3811284c00ca0e86b34771a1
+SHA512:
+  metadata.gz: 8be12b7c9de524de12ec34b09d9216408d4c03211a2c63ff145132619ae5652ab74ce85009cf25f2ac9cbd91571328f6d7848250ae1f7265f237165a87276c2d
+  data.tar.gz: bb4e2193d2f9ba6f76491f0ca66fc6bc5d11a253fddc1ccc1f8a61e46dee5956a8292a032c16a489b434086ea2a934d7f6c9e7fd313fb811c49812e0cc6c1412

data/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 0.1.0
+
+- Financial statements as value objects with BigDecimal figures and derived line items.
+- Ratios: profitability, liquidity, leverage, efficiency, the working capital cycle in days, cash flow, Sloan's accrual ratio, Greenblatt's return on capital and the DuPont decomposition.
+- Piotroski F-score, Altman Z-score, Beneish M-score and owner earnings.
+- Valuation: multiples including EV/EBIT, yields including Greenblatt's, Graham number, a discounted cash flow intrinsic value and the reverse DCF.
+- Banking lines and ratios for banks, line item provenance from EDGAR, and peer comparison with rankings and the magic formula.
+- `to_json` on every object, year-over-year growth for quarters, `Financials#year`, DCF with fading growth, share classes written with a dot, and a configuration that redacts keys.
+- Any metric per share, for dividend, book value and cash flow histories.
+- Quarterly periods from EDGAR, fourth quarters derived from the annual figures, and the trailing twelve months as a period.
+- Analyst estimates from FMP, forward P/E and a PEG on expected growth.
+- The EDGAR concept map validated over the 500 largest filers with `script/coverage`, cover page share counts, and a request throttle for the SEC's rate limit.
+- Providers: SEC EDGAR (US GAAP and IFRS filers, free) and Financial Modeling Prep (annual and quarterly, quotes), behind a configurable cache.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bruno Costanzo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,297 @@
+# Fundamentalista
+
+[![Gem Version](https://badge.fury.io/rb/fundamentalista.svg)](https://rubygems.org/gems/fundamentalista) [![CI](https://github.com/bruno-costanzo/fundamentalista/actions/workflows/ci.yml/badge.svg)](https://github.com/bruno-costanzo/fundamentalista/actions/workflows/ci.yml)
+
+Fundamental analysis of listed companies, the Ruby way.
+
+Fundamentalista turns a ticker into financial statements, ratios, scores and a valuation, with one API over every data source. It reads the SEC's EDGAR XBRL API, which is free and needs no key and covers US GAAP and IFRS filers alike, or Financial Modeling Prep when you want live quotes and analyst estimates.
+
+```ruby
+company = Fundamentalista.company("AAPL")
+
+year = company.financials.latest
+year.income.revenue            # => 0.416161e12
+year.ratios.roe                # => 0.1714e1
+year.piotroski.score           # => 8
+company.financials.growth(:free_cash_flow, years: 3)
+
+valuation = company.valuation(price: 320)
+valuation.pe                   # => 0.4289e2
+valuation.fcf_yield            # => 0.0209e0
+valuation.altman_z.zone        # => :safe
+valuation.intrinsic_value(growth: 0.06, discount_rate: 0.09)
+```
+
+Every figure is a `BigDecimal`. Every derived number is `nil` when a filing lacks an input, so a ratio never raises on an incomplete company. Rates are decimals: `0.25` means 25%. Every object answers `to_h` with its figures intact and `to_json` with Floats and ISO dates, so `render json: company.financials` works in Rails.
+
+## Installation
+
+```ruby
+gem "fundamentalista"
+```
+
+## Configuration
+
+The SEC asks for a User-Agent naming your application and a contact email on every request. Financial Modeling Prep needs an API key.
+
+```ruby
+Fundamentalista.configure do |config|
+  config.edgar_user_agent = "Acme Research research@acme.com"
+  config.fmp_api_key = ENV["FMP_API_KEY"]
+  config.default_provider = :edgar        # or :fmp
+end
+```
+
+## Companies and financials
+
+`Fundamentalista.company` resolves a ticker through the default provider, or the one you name.
+
+```ruby
+apple = Fundamentalista.company("AAPL")
+apple = Fundamentalista.company("AAPL", provider: :fmp)
+apple.name   # => "Apple Inc."
+apple.cik    # => 320193
+```
+
+`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.
+
+```ruby
+financials = apple.financials(limit: 5)              # annual
+financials = apple.financials(period: :quarterly)    # quarters, newest first
+ttm = apple.ttm                                      # the trailing twelve months as one Period
+
+financials.latest.income.net_income
+financials.series(:revenue)                          # {2025 => ..., 2024 => ...}
+financials.growth(:revenue)                          # CAGR over the whole history
+financials.growth(:revenue, years: 3)
+financials.latest.growth(:revenue)                   # against the prior period
+financials.latest.yoy(:revenue)                      # against the same period a year earlier
+financials.year(2024)                                # one period by fiscal year, or year(2026, 3) for a quarter
+financials.latest.metric(:free_cash_flow)            # any line item, from whichever statement has it
+financials.series(:dividends_paid_per_share)         # any of them per share
+financials.growth(:free_cash_flow_per_share, years: 5)
+```
+
+### Quarters and the trailing twelve months
+
+Annual figures go stale for up to a year, so most analysis runs on the trailing twelve months. `financials(period: :quarterly)` returns quarters with their `quarter` number, and `ttm` adds the last four into one `Period` of type `:ttm`: flows summed, the diluted share count averaged, the latest balance sheet kept, and the four quarters before as its `prior`, so ratios on average balances, growth and the Piotroski score all work on it.
+
+```ruby
+ttm = apple.ttm                     # eight quarters: four for the period, four for its prior
+ttm.income.net_income
+ttm.ratios.roe
+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.
+
+### Statements
+
+| Statement | Reported items | Derived when missing |
+| --- | --- | --- |
+| `IncomeStatement` | revenue, cost of revenue, gross profit, SG&A, operating income, interest expense, income before tax, income tax, net income, depreciation and amortization, EBITDA, diluted EPS, diluted shares | gross profit, EBITDA, diluted EPS, tax rate |
+| `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, retained earnings, shares outstanding | total liabilities, total debt, liquid assets, net debt, working capital, net working capital |
+| `CashFlowStatement` | operating cash flow, capital expenditure, free cash flow, dividends paid, share repurchases | free cash flow, shareholder returns |
+
+Outflows are positive amounts: `capital_expenditure` is what was spent.
+
+## Banks
+
+Banks have no cost of goods, no inventory and no classified balance sheet, so the classic ratios come back `nil` for them and the lines that matter live on `period.banking`: net interest income, interest income, credit provisions, noninterest income and expense, loans, deposits, the allowance for credit losses and the Tier 1 capital ratio. `period.bank?` says whether the company reports net interest income.
+
+```ruby
+jpm = Fundamentalista.company("JPM").financials.latest
+jpm.bank?                          # => true
+jpm.banking.deposits
+jpm.ratios.net_interest_margin     # net interest income over average total assets
+jpm.ratios.efficiency_ratio        # noninterest expense over net interest plus noninterest income
+jpm.ratios.loan_to_deposit
+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.
+
+## Ratios
+
+`period.ratios` computes the classic set. Balance sheet denominators use the average of the period and the prior one when a prior is known.
+
+| Group | Ratios |
+| --- | --- |
+| Profitability | `gross_margin`, `operating_margin`, `net_margin`, `ebitda_margin`, `roe`, `roa`, `roic`, `return_on_capital` |
+| Liquidity | `current_ratio`, `quick_ratio`, `cash_ratio` |
+| Leverage | `debt_to_equity`, `debt_to_assets`, `net_debt_to_ebitda`, `interest_coverage`, `equity_multiplier` |
+| Efficiency | `asset_turnover`, `inventory_turnover`, `receivables_turnover` |
+| Working capital | `days_sales_outstanding`, `days_inventory_outstanding`, `days_payables_outstanding`, `cash_conversion_cycle` |
+| Cash | `fcf_margin`, `cash_conversion`, `capex_to_revenue`, `accrual_ratio` |
+
+`return_on_capital` is Greenblatt's, operating income over net working capital plus fixed assets; pair it with the valuation's `ebit_yield` to rank companies the magic formula way. `accrual_ratio` is Sloan's, the share of earnings not backed by operating cash flow. The working capital cycle is in days of the period.
+
+```ruby
+ratios = apple.ratios
+ratios.net_margin
+ratios.dupont     # => {net_margin:, asset_turnover:, equity_multiplier:, roe:}
+ratios.to_h
+```
+
+## Scores
+
+The Piotroski F-score counts nine signals of profitability, leverage and efficiency. Six compare the period with the prior one; without a prior they report `nil` and the score counts the rest.
+
+```ruby
+score = year.piotroski
+score.score     # => 8
+score.signals   # => {positive_income: true, cash_exceeds_income: false, ...}
+```
+
+The Beneish M-score reads eight year-over-year indices for the fingerprints of manipulated earnings: receivables outrunning sales, melting margins, softening asset quality, accruals. Above `-1.78` it flags the company.
+
+```ruby
+m = year.beneish
+m.score                 # => -0.229e1
+m.likely_manipulator?   # => false
+m.indices               # => {dsri: ..., gmi: ..., aqi: ..., sgi: ..., depi: ..., sgai: ..., tata: ..., lvgi: ...}
+year.owner_earnings     # Buffett's: net income plus depreciation minus capital expenditure
+```
+
+The Altman Z-score needs the market value of equity, so it lives on the valuation, or takes a market cap directly.
+
+```ruby
+valuation.altman_z.score            # => 0.122e2
+year.altman_z(market_cap: 4.7e12).zone   # => :safe, :grey or :distress
+```
+
+## Comparing companies
+
+`Fundamentalista.compare` puts several companies side by side. Any ratio, valuation figure, score or line item goes in a table or a ranking, and `magic_formula` orders them by Greenblatt's combined rank of earnings yield and return on capital. Pass prices for EDGAR; FMP quotes on its own.
+
+```ruby
+peers = Fundamentalista.compare("AAPL", "MSFT", "KO", prices: { "AAPL" => 320, "MSFT" => 500, "KO" => 70 })
+peers.table(:roe, :net_margin, :pe, :piotroski, :altman_z)
+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.
+
+## 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.
+
+```ruby
+year.source(:revenue)
+# => #<Fundamentalista::Source concept: "RevenueFromContractWithCustomerExcludingAssessedTax", form: "10-K", filed: 2025-10-31, derivation: :reported>
+year.source(:short_term_debt).derivation   # => :summed
+year.sources                                # every item
+```
+
+## Valuation
+
+`company.valuation` pairs the latest annual period with a market snapshot: the provider's quote, or a price you pass. EDGAR has no market data, so pass a price there.
+
+```ruby
+valuation = apple.valuation(price: 320)
+valuation.pe                    # price over diluted EPS
+valuation.forward_pe            # price over next year's consensus EPS, or forward_pe(eps: 8.8)
+valuation.pb                    # price over book value per share
+valuation.ps                    # market cap over revenue
+valuation.ev_to_ebitda
+valuation.ev_to_ebit
+valuation.peg                   # PE over expected EPS growth, in percent points
+valuation.earnings_yield
+valuation.ebit_yield            # Greenblatt's: operating income over enterprise value
+valuation.fcf_yield
+valuation.dividend_yield
+valuation.shareholder_yield     # dividends plus buybacks
+valuation.graham_number
+valuation.to_h
+```
+
+### Forward multiples and estimates
+
+Forward multiples need next year's earnings, which come from analysts, not filings. Financial Modeling Prep serves the consensus; `company.estimates` lists every year on file and `company.estimate` is the one after the latest reported period. The valuation picks it up for `forward_pe` and for `peg`, whose growth becomes the one the consensus implies. On EDGAR there are no estimates, so pass your own: `valuation.forward_pe(eps: 8.8)`.
+
+```ruby
+estimate = company.estimate         # FMP
+estimate.eps                        # consensus average
+estimate.eps_low, estimate.eps_high
+estimate.analysts                   # how many stand behind it
+estimate.eps_growth(year.income.eps_diluted)
+```
+
+### Discounted cash flow
+
+`intrinsic_value` grows the period's free cash flow at `growth` for `years`, adds a terminal value at `terminal_growth`, discounts everything at `discount_rate`, subtracts net debt, and divides by the shares outstanding. `margin_of_safety` is how far the price sits below that value.
+
+```ruby
+valuation.intrinsic_value(growth: 0.06, discount_rate: 0.09, terminal_growth: 0.025, years: 10)
+valuation.margin_of_safety(growth: 0.06, discount_rate: 0.09)
+valuation.implied_growth(discount_rate: 0.09)   # the reverse DCF: the growth the price is paying for
+```
+
+`implied_growth` runs the model backwards: it searches for the yearly free cash flow growth at which the intrinsic value equals the price, so you can judge whether the market's assumption is one you would make.
+
+Pass `fade: true` to any of them and growth declines evenly from `growth` to `terminal_growth` across the projection instead of dropping at once, which is how most analysts model a company past its high growth years.
+
+The model is also available on its own, for any cash flow stream:
+
+```ruby
+dcf = Fundamentalista::DCF.new(cash_flow: 98_767_000_000, growth: 0.06, discount_rate: 0.09)
+dcf.projection
+dcf.present_value
+dcf.terminal_value
+dcf.value
+```
+
+## Providers
+
+| | EDGAR | Financial Modeling Prep |
+| --- | --- | --- |
+| Cost | Free, no key | API key, free tier available |
+| Periods | Annual from 10-K filings, quarterly from 10-Q filings | Annual and quarterly |
+| Quotes | No, pass a price | Yes |
+| Analyst estimates | No, pass an EPS | 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.
+
+### Coverage
+
+The concept map is measured, not guessed. `script/coverage` reads the latest annual period of the largest SEC filers and reports how often each line item comes back `nil`; the map grew from what the companies missing an item actually tag. Over the 500 largest filers, the items every valuation rests on are all but complete:
+
+| Line item | Companies without it |
+| --- | --- |
+| net income, total liabilities, equity, cash, income tax, operating cash flow | under 2% |
+| revenue | 4% |
+| 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`.
+
+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.
+
+### Caching
+
+An EDGAR company document runs to several megabytes, so any long-lived process should keep responses. Set `config.cache` to any store that answers `fetch(key) { value }`, such as an Active Support cache:
+
+```ruby
+Fundamentalista.configure do |config|
+  config.cache = ActiveSupport::Cache::FileStore.new("tmp/fundamentalista", expires_in: 1.day)
+end
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rake    # specs and RuboCop
+```
+
+Specs stub every provider with recorded responses; no keys are needed.
+
+## License
+
+MIT.

data/lib/fundamentalista/balance_sheet.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Fundamentalista
+  # The balance sheet at the end of a period. +shares_outstanding+ is a
+  # share count, +ppe+ is property, plant and equipment net of
+  # depreciation; everything else is in the reporting currency.
+  class BalanceSheet < Statement
+    field :cash, :short_term_investments, :receivables, :inventory, :current_assets, :ppe, :total_assets,
+          :payables, :current_liabilities, :total_liabilities, :short_term_debt, :long_term_debt, :total_debt,
+          :equity, :retained_earnings, :shares_outstanding
+
+    # Total liabilities, derived from total assets and equity when not reported.
+    def total_liabilities
+      @total_liabilities || Decimal.subtract(total_assets, equity)
+    end
+
+    # Total debt, derived from short and long term debt when not reported.
+    # A missing short term figure counts as zero when long term debt exists.
+    def total_debt
+      @total_debt || (long_term_debt && (long_term_debt + (short_term_debt || 0)))
+    end
+
+    # Cash plus short term investments.
+    def liquid_assets
+      Decimal.sum(cash, short_term_investments || BigDecimal('0'))
+    end
+
+    # Total debt minus liquid assets; negative for a net cash position.
+    def net_debt
+      Decimal.subtract(total_debt, liquid_assets)
+    end
+
+    # Current assets minus current liabilities.
+    def working_capital
+      Decimal.subtract(current_assets, current_liabilities)
+    end
+
+    # Working capital net of cash and debt: receivables plus inventory minus
+    # payables, the operating capital Greenblatt's return on capital uses.
+    def net_working_capital
+      Decimal.subtract(Decimal.sum(receivables, inventory), payables)
+    end
+  end
+end

data/lib/fundamentalista/banking.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Fundamentalista
+  # The lines a bank reports that the three classic statements do not
+  # carry: interest and fee income and expense, credit provisions, loans,
+  # deposits and regulatory capital. Empty for companies that are not
+  # banks. +tier1_capital_ratio+ is a rate; everything else is in the
+  # reporting currency.
+  class Banking < Statement
+    field :net_interest_income, :interest_income, :provision_for_credit_losses, :noninterest_income,
+          :noninterest_expense, :loans, :deposits, :allowance_for_credit_losses, :tier1_capital_ratio
+
+    INSTANT = %i[loans deposits allowance_for_credit_losses tier1_capital_ratio].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 reports net interest income, the mark of a bank.
+    def bank?
+      !net_interest_income.nil? && !net_interest_income.zero?
+    end
+
+    # Net interest income plus noninterest income, a bank's revenue.
+    def revenue
+      Decimal.sum(net_interest_income, noninterest_income)
+    end
+  end
+end

data/lib/fundamentalista/cash_flow_statement.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Fundamentalista
+  # One period of the cash flow statement. Outflows are positive amounts:
+  # +capital_expenditure+ is what was spent, +dividends_paid+ what was paid.
+  class CashFlowStatement < Statement
+    field :operating_cash_flow, :capital_expenditure, :free_cash_flow, :dividends_paid, :share_repurchases
+
+    # Free cash flow, derived from operating cash flow and capital
+    # expenditure when not reported.
+    def free_cash_flow
+      @free_cash_flow || Decimal.subtract(operating_cash_flow, capital_expenditure)
+    end
+
+    # Cash returned to shareholders through dividends and buybacks.
+    def shareholder_returns
+      Decimal.sum(dividends_paid || BigDecimal('0'), share_repurchases || BigDecimal('0'))
+    end
+  end
+end

data/lib/fundamentalista/company.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Fundamentalista
+  # A listed company as one provider knows it. Financial statements come
+  # from #financials, the market snapshot from #quote, and #valuation puts
+  # the two together.
+  #
+  #   company = Fundamentalista.company("AAPL")
+  #   company.name                           # => "Apple Inc."
+  #   company.financials(limit: 3).latest.ratios.roe
+  #   company.ttm.ratios.net_margin
+  #   company.valuation(price: 320).pe
+  #   company.estimate.eps                   # FMP only
+  #
+  class Company
+    include Inspectable
+
+    attr_reader :ticker, :name, :cik, :currency, :provider
+
+    def initialize(ticker:, name:, provider:, cik: nil, currency: 'USD')
+      @ticker = ticker
+      @name = name
+      @cik = cik
+      @currency = currency
+      @provider = provider
+      @financials = {}
+    end
+
+    # Returns the Financials, newest first. +period+ is +:annual+ or
+    # +:quarterly+ and +limit+ the number of periods.
+    def financials(period: :annual, limit: 5)
+      @financials[[period, limit]] ||= provider.financials(self, period: period, limit: limit)
+    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)
+      financials(period: :quarterly, limit: quarters).ttm
+    end
+
+    # Returns the current Quote. Raises QuoteUnavailableError when the
+    # provider has no market data, as EDGAR does not.
+    def quote
+      @quote ||= provider.quote(self) || raise(QuoteUnavailableError, "#{provider.class.slug} has no quotes; pass a price")
+    end
+
+    # Returns the analyst Estimates the provider has, oldest first. Empty
+    # for EDGAR.
+    def estimates
+      @estimates ||= provider.estimates(self).sort_by(&:fiscal_year_end)
+    end
+
+    # Returns the Estimate for the first fiscal year ending after +after+,
+    # the latest reported period by default, or +nil+.
+    def estimate(after: latest_period.ended_on)
+      estimates.find { |candidate| candidate.fiscal_year_end > after }
+    end
+
+    # 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)
+      Valuation.new(period, price ? Quote.new(price: price) : quote, estimate: estimate(after: period.ended_on))
+    end
+
+    # The Ratios of the latest annual period.
+    def ratios
+      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.
+    def latest_period
+      financials.latest || raise(NoFinancialsError, "#{provider.class.slug} has no annual statements for #{ticker}")
+    end
+
+    def inspect_attributes # :nodoc:
+      { ticker: ticker, name: name, cik: cik, provider: provider.class.slug }
+    end
+  end
+end

data/lib/fundamentalista/comparison.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+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.
+  #
+  #   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"]
+  #
+  class Comparison
+    include Enumerable
+    include Inspectable
+
+    SCORES = { piotroski: ->(period, _) { period.piotroski.score },
+               beneish: ->(period, _) { period.beneish.score },
+               altman_z: ->(_, valuation) { valuation&.altman_z&.score } }.freeze
+
+    attr_reader :companies
+
+    def initialize(companies, prices: {})
+      @companies = companies.to_h { |company| [company.ticker, company] }
+      @prices = prices.transform_keys(&:to_s)
+    end
+
+    def each(&)
+      companies.each_value(&)
+    end
+
+    # Returns +name+ for every company, keyed by ticker. Names resolve
+    # against the latest period's ratios, valuation, scores, and line
+    # items, in that order.
+    def values(name)
+      companies.transform_values { |company| metric(company, name) }
+    end
+
+    # Returns every +names+ for every company, keyed by ticker.
+    def table(*names)
+      companies.transform_values { |company| names.to_h { |name| [name, metric(company, name)] } }
+    end
+
+    # Returns the tickers ordered by +name+, highest first unless
+    # +ascending+, with companies missing the figure last.
+    def rank(name, ascending: false)
+      known, unknown = values(name).partition { |_, value| value }
+      ordered = known.sort_by { |_, value| value }
+      (ascending ? ordered : ordered.reverse).map(&:first) + unknown.map(&:first)
+    end
+
+    # Greenblatt's magic formula: the tickers ordered by the sum of their
+    # rank on earnings yield and on return on capital, best first.
+    def magic_formula
+      yields = rank(:ebit_yield)
+      returns = rank(:return_on_capital)
+      companies.keys.sort_by { |ticker| yields.index(ticker) + returns.index(ticker) }
+    end
+
+    def inspect_attributes # :nodoc:
+      { companies: companies.keys }
+    end
+
+    private
+
+    def metric(company, name)
+      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)
+      return SCORES[name].call(period, valuation) if SCORES.key?(name)
+
+      period.metric(name)
+    end
+
+    def valuation_of(company, period)
+      price = @prices[company.ticker]
+      return company.valuation(price: price, period: period) if price
+
+      company.valuation(period: period)
+    rescue QuoteUnavailableError
+      nil
+    end
+  end
+end