fundamentalista 0.1.0

data/lib/fundamentalista/valuation.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+module Fundamentalista
+  # The market's price of a Period: multiples, yields, the Graham number,
+  # the Altman Z-score and a discounted cash flow intrinsic value. Built
+  # from a Period and a Quote, plus the next year's analyst Estimate when
+  # there is one, which feeds the forward multiples.
+  #
+  #   valuation = company.valuation(price: 320)
+  #   valuation.pe                 # => 0.4289e2
+  #   valuation.forward_pe         # => 0.3625e2, with an estimate
+  #   valuation.fcf_yield          # => 0.021e-1
+  #   valuation.intrinsic_value(growth: 0.06, discount_rate: 0.09)
+  #
+  class Valuation
+    include Inspectable
+    include Serializable
+
+    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
+
+    attr_reader :period, :quote, :estimate
+
+    def initialize(period, quote, estimate: nil)
+      @period = period
+      @quote = quote
+      @estimate = estimate
+    end
+
+    def price
+      quote.price
+    end
+
+    # Shares from the quote, else the balance sheet's count, else the
+    # diluted weighted average of the period.
+    def shares_outstanding
+      quote.shares_outstanding || balance.shares_outstanding || income.diluted_shares
+    end
+
+    def market_cap
+      quote.market_cap || (shares_outstanding && (price * shares_outstanding))
+    end
+
+    # Market capitalization plus net debt.
+    def enterprise_value
+      Decimal.sum(market_cap, balance.net_debt)
+    end
+
+    def pe
+      Decimal.ratio(price, income.eps_diluted)
+    end
+
+    # Price over next year's EPS: the estimate's consensus, or the +eps+
+    # you pass. +nil+ without either.
+    def forward_pe(eps: estimate&.eps)
+      Decimal.ratio(price, Decimal.wrap(eps))
+    end
+
+    def pb
+      Decimal.ratio(price, book_value_per_share)
+    end
+
+    def ps
+      Decimal.ratio(market_cap, income.revenue)
+    end
+
+    def ev_to_ebitda
+      Decimal.ratio(enterprise_value, income.ebitda)
+    end
+
+    # Enterprise value over operating income.
+    def ev_to_ebit
+      Decimal.ratio(enterprise_value, income.operating_income)
+    end
+
+    def ev_to_sales
+      Decimal.ratio(enterprise_value, income.revenue)
+    end
+
+    # Price to earnings over expected earnings growth in percent points.
+    # The growth is the one the estimate implies over this period's EPS,
+    # else the growth of net income against the prior period, unless
+    # +growth+ is given as a rate.
+    def peg(growth: expected_growth)
+      rate = Decimal.wrap(growth)
+      Decimal.ratio(pe, rate && (rate * 100))
+    end
+
+    def earnings_yield
+      Decimal.ratio(income.eps_diluted, price)
+    end
+
+    # Greenblatt's earnings yield: operating income over enterprise value.
+    # Rank it with Ratios#return_on_capital for the magic formula.
+    def ebit_yield
+      Decimal.ratio(income.operating_income, enterprise_value)
+    end
+
+    def fcf_yield
+      Decimal.ratio(cash_flow.free_cash_flow, market_cap)
+    end
+
+    def dividend_yield
+      Decimal.ratio(cash_flow.dividends_paid, market_cap)
+    end
+
+    # Dividends plus buybacks over market capitalization.
+    def shareholder_yield
+      Decimal.ratio(cash_flow.shareholder_returns, market_cap)
+    end
+
+    def payout_ratio
+      Decimal.ratio(cash_flow.dividends_paid, income.net_income)
+    end
+
+    def book_value_per_share
+      Decimal.ratio(balance.equity, shares_outstanding)
+    end
+
+    # Graham's ceiling for a defensive investor: the square root of 22.5
+    # times earnings per share times book value per share. +nil+ when
+    # either is negative.
+    def graham_number
+      eps = income.eps_diluted
+      bvps = book_value_per_share
+      return nil if eps.nil? || bvps.nil? || eps.negative? || bvps.negative?
+
+      (BigDecimal('22.5') * eps * bvps).sqrt(16)
+    end
+
+    # The Altman Z-score at this market capitalization.
+    def altman_z
+      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
+      return nil if flow.nil? || flow <= 0 || shares_outstanding.nil?
+
+      equity = DCF.new(cash_flow: flow, **options).value - (balance.net_debt || 0)
+      equity / shares_outstanding
+    end
+
+    # How far the price sits below the intrinsic value, as a rate of that
+    # value; negative when the price is above it.
+    def margin_of_safety(**options)
+      value = intrinsic_value(**options)
+      Decimal.ratio(Decimal.subtract(value, price), value)
+    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.
+    def implied_growth(discount_rate:, **options)
+      return nil if intrinsic_value(growth: 0, discount_rate: discount_rate, **options).nil?
+
+      low = BigDecimal('-0.5')
+      high = BigDecimal('1')
+      return nil unless values_at?(low, discount_rate, options) < price && values_at?(high, discount_rate, options) > price
+
+      40.times do
+        middle = (low + high) / 2
+        values_at?(middle, discount_rate, options) < price ? low = middle : high = middle
+      end
+      (low + high) / 2
+    end
+
+    def to_h
+      ALL.to_h { |name| [name, public_send(name)] }
+    end
+
+    def inspect_attributes # :nodoc:
+      { price: price, pe: pe, forward_pe: forward_pe, pb: pb, ev_to_ebitda: ev_to_ebitda, fcf_yield: fcf_yield }
+    end
+
+    private
+
+    def expected_growth
+      estimate ? estimate.eps_growth(income.eps_diluted) : period.growth(:net_income)
+    end
+
+    def values_at?(growth, discount_rate, options)
+      intrinsic_value(growth: growth, discount_rate: discount_rate, **options)
+    end
+
+    def income
+      period.income
+    end
+
+    def balance
+      period.balance
+    end
+
+    def cash_flow
+      period.cash_flow
+    end
+  end
+end

data/lib/fundamentalista/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Fundamentalista
+  # The version of the fundamentalista gem, as a string.
+  VERSION = '0.1.0'
+end

data/lib/fundamentalista.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require 'bigdecimal'
+require 'bigdecimal/util'
+require 'date'
+require 'faraday'
+require 'faraday/retry'
+require 'json'
+require 'logger'
+require 'uri'
+require 'zeitwerk'
+require 'fundamentalista/error'
+
+loader = Zeitwerk::Loader.for_gem
+loader.inflector.inflect('dcf' => 'DCF', 'fmp' => 'FMP')
+loader.setup
+
+# Fundamental analysis of listed companies: financial statements, ratios,
+# scores and valuation, from the SEC's EDGAR or Financial Modeling Prep.
+#
+#   Fundamentalista.configure { |config| config.edgar_user_agent = "Acme research@acme.com" }
+#
+#   company = Fundamentalista.company("AAPL")
+#   year = company.financials.latest
+#   year.ratios.roe            # => 0.15e1 (BigDecimal)
+#   year.piotroski.score       # => 7
+#   company.valuation(price: 320).pe
+#   Fundamentalista.compare("AAPL", "MSFT").rank(:roe)
+#
+module Fundamentalista
+  class << self
+    # Returns the Company behind +ticker+, resolved through +provider+
+    # (+:edgar+ or +:fmp+, defaulting to the configured provider).
+    def company(ticker, provider: config.default_provider)
+      provider(provider).company(ticker)
+    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)
+      source = provider(provider)
+      companies = tickers.flatten.filter_map do |ticker|
+        source.company(ticker)
+      rescue Error => e
+        logger.warn("Skipping #{ticker}: #{e.message}")
+        nil
+      end
+      Comparison.new(companies, prices: prices)
+    end
+
+    # Returns an instance of the provider registered under +slug+.
+    def provider(slug)
+      klass = providers.fetch(slug.to_sym) do
+        raise ConfigurationError, "Unknown provider #{slug.inspect}. Known providers: #{providers.keys.join(', ')}"
+      end
+      klass.new(config)
+    end
+
+    # The registered providers, keyed by slug.
+    def providers
+      @providers ||= { edgar: Providers::Edgar, fmp: Providers::FMP }
+    end
+
+    # The global Configuration.
+    def config
+      @config ||= Configuration.new
+    end
+
+    # Yields the global Configuration.
+    #
+    #   Fundamentalista.configure do |config|
+    #     config.fmp_api_key = ENV["FMP_API_KEY"]
+    #   end
+    #
+    def configure
+      yield config
+    end
+
+    # The configured logger.
+    def logger
+      config.logger
+    end
+  end
+end

metadata

@@ -0,0 +1,136 @@
+--- !ruby/object:Gem::Specification
+name: fundamentalista
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Bruno Costanzo
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bigdecimal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-retry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.6'
+description: Financial statements, ratios, Piotroski and Altman scores, multiples
+  and discounted cash flow valuation for listed companies, from the SEC EDGAR XBRL
+  API or Financial Modeling Prep. BigDecimal throughout, nil instead of exceptions
+  on incomplete filings, one API over every provider.
+email:
+- dev.bcostanzo@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/fundamentalista.rb
+- lib/fundamentalista/balance_sheet.rb
+- lib/fundamentalista/banking.rb
+- lib/fundamentalista/cash_flow_statement.rb
+- lib/fundamentalista/company.rb
+- lib/fundamentalista/comparison.rb
+- lib/fundamentalista/configuration.rb
+- lib/fundamentalista/dcf.rb
+- lib/fundamentalista/decimal.rb
+- lib/fundamentalista/error.rb
+- lib/fundamentalista/estimate.rb
+- lib/fundamentalista/financials.rb
+- lib/fundamentalista/income_statement.rb
+- lib/fundamentalista/inspectable.rb
+- lib/fundamentalista/period.rb
+- lib/fundamentalista/provider.rb
+- lib/fundamentalista/providers/edgar.rb
+- lib/fundamentalista/providers/edgar/facts.rb
+- lib/fundamentalista/providers/edgar/tags.rb
+- lib/fundamentalista/providers/fmp.rb
+- lib/fundamentalista/quote.rb
+- lib/fundamentalista/ratios.rb
+- lib/fundamentalista/scores/altman_z.rb
+- lib/fundamentalista/scores/beneish.rb
+- lib/fundamentalista/scores/piotroski.rb
+- lib/fundamentalista/serializable.rb
+- lib/fundamentalista/source.rb
+- lib/fundamentalista/statement.rb
+- lib/fundamentalista/valuation.rb
+- lib/fundamentalista/version.rb
+homepage: https://github.com/bruno-costanzo/fundamentalista
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/bruno-costanzo/fundamentalista
+  changelog_uri: https://github.com/bruno-costanzo/fundamentalista/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/bruno-costanzo/fundamentalista/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.3
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Fundamental analysis of listed companies, the Ruby way.
+test_files: []