fundamentalista 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a751de0b23e903aae3241633a34846881b375b79d30cf43f123a79e85e9ef756
-  data.tar.gz: b5518a61ec6a452ea5cb13ff6c996301e2942e712c79dbac0b5d43b1dc143b2c
+  metadata.gz: 36260d14ca8a99975cc3c9717ecd1fa5694f2e2d29144aaeb8d51e9eed3a25a5
+  data.tar.gz: 920282a4dd650e6ed172638e02b85c37b3ac6e0166af5f7a837b4e69003d1c59
 SHA512:
-  metadata.gz: 5358331cec9f638346d55606350feaed1bf221567ae4f74495d045afe9c51d9297d2d45d09bc7816816cc9741046bd712f8e6f47b0338faf2a349155d704ed4b
-  data.tar.gz: ef443415389f98b381bf6d756c65cfc90358dec72c68a32de6ec8034146d2aba6a4ae87d05225394f6eeec42103e093e378b97229523b1e2689ac2628ce9cea5
+  metadata.gz: 698002a96de44e7c842e619fbce287758f2478f56f0e0a3c1fcbb131a635e88316b9609bfba710c7223627f6ea7ba67b5a3ad5cc5a9296cf34b061a65b76956f
+  data.tar.gz: 675e708b8b952f95aa50ef374165b37fa70f9d7d6e217ee8b14fb7a8157fec4c1402f8a0703aba8d4808fa33e0202a75eeafc43e2fd76a8bdba358b63f044763

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.2.0
+
+- Daily prices from FMP as a `PriceHistory` with dividend adjusted returns, the valuation of every fiscal year at its closing price, and the company beta.
+- The weighted average cost of capital as a discount rate built from the capital structure.
+
 ## 0.1.1
 
 - EBIT derived from income before tax and interest when operating income is not reported, used by interest coverage, EV/EBIT, the magic formula and the Altman Z-score.

data/README.md

@@ -222,6 +222,15 @@ estimate.analysts                   # how many stand behind it
 estimate.eps_growth(year.income.eps_diluted)
 ```
 
+### The discount rate
+
+`wacc` builds a discount rate from the capital structure at the current price: the cost of equity by CAPM from `beta`, the risk free rate and the equity premium, and the after tax cost of debt from interest expense over total debt, weighted by market value. FMP profiles carry `company.beta`; on EDGAR pass your own.
+
+```ruby
+rate = valuation.wacc(beta: company.beta, risk_free: 0.04, equity_premium: 0.05)
+valuation.intrinsic_value(growth: 0.06, discount_rate: rate)
+```
+
 ### 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.
@@ -246,6 +255,21 @@ dcf.terminal_value
 dcf.value
 ```
 
+## Prices and history
+
+FMP serves daily closes with their dividend adjusted counterparts as a `PriceHistory`; on EDGAR you build one yourself from any source. With prices, every fiscal year can be valued at the close of its last day, which is what a history of multiples is.
+
+```ruby
+prices = company.prices(from: Date.new(2020, 1, 1))          # FMP
+prices = Fundamentalista::PriceHistory.new([[Date.new(2025, 9, 26), 254.52, 254.52], ...])
+prices.at(Date.new(2025, 9, 27)).close                        # the last close on or before that day
+prices.total_return(from: Date.new(2020, 1, 1))               # dividends reinvested
+prices.annualized_return
+
+company.valuation_history(:pe, :pb, :fcf_yield)               # {2025 => {price:, pe:, pb:, fcf_yield:}, ...}
+company.valuation_history(:pe, prices: prices)                # with a history you bring
+```
+
 ## Providers
 
 | | EDGAR | Financial Modeling Prep |
@@ -254,6 +278,7 @@ dcf.value
 | 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 |
+| Prices and beta | No, bring a PriceHistory and a beta | 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

@@ -11,19 +11,25 @@ module Fundamentalista
   #   company.ttm.ratios.net_margin
   #   company.valuation(price: 320).pe
   #   company.estimate.eps                   # FMP only
+  #   company.valuation_history(:pe)         # {2025 => {price:, pe:}, ...}
   #
   class Company
     include Inspectable
 
     attr_reader :ticker, :name, :cik, :currency, :provider
 
-    def initialize(ticker:, name:, provider:, cik: nil, currency: 'USD')
+    # The stock's beta, when the provider reports one.
+    attr_reader :beta
+
+    def initialize(ticker:, name:, provider:, cik: nil, currency: 'USD', beta: nil)
       @ticker = ticker
       @name = name
       @cik = cik
       @currency = currency
+      @beta = Decimal.wrap(beta)
       @provider = provider
       @financials = {}
+      @prices = {}
     end
 
     # Returns the Financials, newest first. +period+ is +:annual+ or
@@ -32,6 +38,33 @@ module Fundamentalista
       @financials[[period, limit]] ||= provider.financials(self, period: period, limit: limit)
     end
 
+    # Returns the PriceHistory between +from+ and +to+. Raises
+    # QuoteUnavailableError when the provider has no prices, as EDGAR does
+    # not; build a PriceHistory yourself there.
+    def prices(from:, to: Date.today)
+      @prices[[from, to]] ||= provider.prices(self, from: from, to: to)
+    end
+
+    # Returns +metrics+ of the Valuation of every annual period at the
+    # close of its last day, keyed by fiscal year, newest first. Takes the
+    # provider's +prices+ unless a PriceHistory is given. Years without a
+    # price are left out.
+    #
+    #   company.valuation_history(:pe, :fcf_yield)
+    #   # => {2025 => {price: 0.25452e3, pe: 0.3412e2, fcf_yield: 0.026e-1}, ...}
+    #
+    def valuation_history(*metrics, prices: nil)
+      periods = financials.to_a
+      prices ||= self.prices(from: periods.last.ended_on)
+      periods.filter_map do |period|
+        price = prices.at(period.ended_on)
+        next unless price
+
+        valuation = Valuation.new(period, Quote.new(price: price.close))
+        [period.fiscal_year, { price: price.close, **metrics.to_h { |metric| [metric, valuation.public_send(metric)] } }]
+      end.to_h
+    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/price_history.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Fundamentalista
+  # Daily closes over a span of time, oldest first. Each Price carries the
+  # close and the dividend adjusted close, so multiples use the price of
+  # the day and returns include what was paid out.
+  #
+  #   prices = company.prices(from: Date.new(2020, 1, 1))       # FMP
+  #   prices = Fundamentalista::PriceHistory.new([[Date.new(2025, 9, 26), 254.52, 254.52], ...])
+  #   prices.at(Date.new(2025, 9, 27)).close                     # the last close on or before that day
+  #   prices.total_return(from: Date.new(2020, 1, 1))            # dividends reinvested
+  #
+  class PriceHistory
+    include Enumerable
+    include Inspectable
+    include Serializable
+
+    # One day's close and dividend adjusted close.
+    Price = Struct.new(:date, :close, :adjusted, keyword_init: true) do
+      include Serializable
+
+      def to_h
+        { date: date, close: close, adjusted: adjusted }
+      end
+    end
+
+    def initialize(points)
+      @prices = points.map { |point| wrap(point) }.sort_by(&:date)
+    end
+
+    def each(&)
+      @prices.each(&)
+    end
+
+    def size
+      @prices.size
+    end
+
+    def from
+      @prices.first&.date
+    end
+
+    def to
+      @prices.last&.date
+    end
+
+    # Returns the Price of the last trading day on or before +date+, or +nil+.
+    def at(date)
+      @prices.reverse_each.find { |price| price.date <= date }
+    end
+
+    # Returns the return with dividends reinvested between +from+ and +to+,
+    # the whole history by default, as a rate, or +nil+ when either day
+    # has no price.
+    def total_return(from: self.from, to: self.to)
+      start = at(from)
+      finish = at(to)
+      return nil unless start && finish
+
+      Decimal.ratio(finish.adjusted, start.adjusted) - 1
+    end
+
+    # Returns the total return between +from+ and +to+ annualized.
+    def annualized_return(from: self.from, to: self.to)
+      start = at(from)
+      finish = at(to)
+      return nil unless start && finish
+
+      Decimal.cagr(start.adjusted, finish.adjusted, (finish.date - start.date).to_f / 365.25)
+    end
+
+    def to_h
+      { prices: @prices.map(&:to_h) }
+    end
+
+    def inspect_attributes # :nodoc:
+      { from: from, to: to, days: size }
+    end
+
+    private
+
+    def wrap(point)
+      return point if point.is_a?(Price)
+
+      date, close, adjusted = point
+      Price.new(date: date.is_a?(Date) ? date : Date.parse(date.to_s), close: Decimal.wrap(close),
+                adjusted: Decimal.wrap(adjusted || close))
+    end
+  end
+end

data/lib/fundamentalista/provider.rb

@@ -2,8 +2,9 @@
 
 module Fundamentalista
   # The contract every data source implements: resolve a Company, return
-  # its Financials, a Quote or +nil+, and the analyst Estimates it has.
-  # Subclasses get an HTTP client with retries and error mapping.
+  # its Financials, a Quote or +nil+, the analyst Estimates it has, and
+  # its PriceHistory. Subclasses get an HTTP client with retries and error
+  # mapping.
   class Provider
     class << self
       # The symbol the provider is registered under.
@@ -34,6 +35,10 @@ module Fundamentalista
       raise NotImplementedError
     end
 
+    def prices(company, from:, to:)
+      raise NotImplementedError
+    end
+
     private
 
     def get(url, params = {}, headers: {})

data/lib/fundamentalista/providers/edgar.rb

@@ -40,6 +40,10 @@ module Fundamentalista
         []
       end
 
+      def prices(company, **)
+        raise QuoteUnavailableError, "EDGAR has no prices for #{company.ticker}; pass a PriceHistory"
+      end
+
       private
 
       STATEMENTS = { income: [IncomeStatement, Tags::INCOME], balance: [BalanceSheet, Tags::BALANCE],

data/lib/fundamentalista/providers/fmp.rb

@@ -3,8 +3,8 @@
 module Fundamentalista
   module Providers
     # Financial Modeling Prep. Needs Configuration#fmp_api_key. Serves
-    # annual and quarterly periods, company profiles, live quotes and
-    # analyst estimates.
+    # annual and quarterly periods, company profiles with beta, live
+    # quotes, analyst estimates and daily prices.
     class FMP < Provider
       BASE_URL = 'https://financialmodelingprep.com/stable/'
 
@@ -13,7 +13,7 @@ module Fundamentalista
         raise CompanyNotFoundError, "FMP lists no company under #{ticker.inspect}" unless profile
 
         Company.new(ticker: profile['symbol'], name: profile['companyName'], cik: profile['cik']&.to_i,
-                    currency: profile['currency'], provider: self)
+                    currency: profile['currency'], beta: profile['beta'], provider: self)
       end
 
       def financials(company, period: :annual, limit: 5)
@@ -32,6 +32,13 @@ module Fundamentalista
                   as_of: row['timestamp'] && Time.at(row['timestamp']))
       end
 
+      def prices(company, from:, to:)
+        params = { symbol: company.ticker, from: from.iso8601, to: to.iso8601 }
+        adjusted = fetch('historical-price-eod/dividend-adjusted', params).to_h { |row| [row['date'], row['adjClose']] }
+        points = fetch('historical-price-eod/light', params).map { |row| [row['date'], row['price'], adjusted[row['date']]] }
+        PriceHistory.new(points)
+      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/valuation.rb

@@ -151,6 +151,34 @@ module Fundamentalista
       Decimal.ratio(Decimal.subtract(value, price), value)
     end
 
+    # The cost of equity by the capital asset pricing model: the risk free
+    # rate plus +beta+ times the +equity_premium+. Rates are decimals.
+    def cost_of_equity(beta:, risk_free:, equity_premium: BigDecimal('0.05'))
+      Decimal.wrap(risk_free) + (Decimal.wrap(beta) * Decimal.wrap(equity_premium))
+    end
+
+    # The pre-tax cost of debt: interest expense over total debt, or the
+    # +cost_of_debt+ you pass.
+    def cost_of_debt(cost_of_debt: nil)
+      cost_of_debt ? Decimal.wrap(cost_of_debt) : Decimal.ratio(income.interest_expense, balance.total_debt)
+    end
+
+    # The weighted average cost of capital at this market capitalization:
+    # equity at its CAPM cost, debt at its after tax cost, weighted by
+    # market value. A ready discount rate for #intrinsic_value.
+    #
+    #   valuation.intrinsic_value(growth: 0.06, discount_rate: valuation.wacc(beta: 1.1, risk_free: 0.04))
+    #
+    def wacc(beta:, risk_free:, equity_premium: BigDecimal('0.05'), cost_of_debt: nil)
+      debt = balance.total_debt || BigDecimal('0')
+      capital = Decimal.sum(market_cap, debt)
+      return nil if capital.nil? || capital.zero?
+
+      equity_cost = cost_of_equity(beta: beta, risk_free: risk_free, equity_premium: equity_premium)
+      debt_cost = (self.cost_of_debt(cost_of_debt: cost_of_debt) || BigDecimal('0')) * (1 - (income.tax_rate || BigDecimal('0')))
+      ((market_cap * equity_cost) + (debt * debt_cost)) / capital
+    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.1.1'
+  VERSION = '0.2.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fundamentalista
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Bruno Costanzo
@@ -93,6 +93,7 @@ files:
 - lib/fundamentalista/income_statement.rb
 - lib/fundamentalista/inspectable.rb
 - lib/fundamentalista/period.rb
+- lib/fundamentalista/price_history.rb
 - lib/fundamentalista/provider.rb
 - lib/fundamentalista/providers/edgar.rb
 - lib/fundamentalista/providers/edgar/facts.rb