fundamentalista 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 36260d14ca8a99975cc3c9717ecd1fa5694f2e2d29144aaeb8d51e9eed3a25a5
-  data.tar.gz: 920282a4dd650e6ed172638e02b85c37b3ac6e0166af5f7a837b4e69003d1c59
+  metadata.gz: 37f787ea99f5a949329fb943c8994bc1fa3cb3b9f0ed357757926b4bb661fb57
+  data.tar.gz: f974e488c25c1b0628e9c6fbca2400b6aa86c99705d8d274d008591a0a93d52e
 SHA512:
-  metadata.gz: 698002a96de44e7c842e619fbce287758f2478f56f0e0a3c1fcbb131a635e88316b9609bfba710c7223627f6ea7ba67b5a3ad5cc5a9296cf34b061a65b76956f
-  data.tar.gz: 675e708b8b952f95aa50ef374165b37fa70f9d7d6e217ee8b14fb7a8157fec4c1402f8a0703aba8d4808fa33e0202a75eeafc43e2fd76a8bdba358b63f044763
+  metadata.gz: a8f4e210ea59fac412647858620bd23f880785fb723c902770e81b295bdfd0671884affb0b1a849e165f49f0d2dc90660c5978374f673b5038b8e5ef6002cf6b
+  data.tar.gz: 438bf83861f879aa1c4f4b47468ffdb974ab1d3700aaa5ea8ec8375a8da891e689bc21bbc7ce11b1e50b290351342da399040e185fd5c6f06d4e2392389e46b5

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.3.0
+
+- Insurance lines and ratios: premiums, claims, loss, expense and combined ratios, investment yield and the float, read from the concepts property and casualty insurers report.
+
 ## 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.

data/README.md

@@ -113,7 +113,22 @@ 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.
+The banking and insurance ratios appear in `ratios.to_h` only for banks and insurers, 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.
+
+## Insurers
+
+Insurers earn premiums and invest the float, so their lines live on `period.insurance`: premiums earned and written, claims incurred, total benefits and expenses, investment income, investments, reserves, unearned premiums, premiums receivable and reinsurance recoverables. `period.insurer?` says whether the company earns premiums, and `insurance.float` is Buffett's: reserves plus unearned premiums, less what policyholders and reinsurers still owe.
+
+```ruby
+trv = Fundamentalista.company("TRV").financials.latest
+trv.ratios.loss_ratio            # claims incurred over premiums earned
+trv.ratios.combined_ratio        # benefits, losses and expenses over premiums earned; below one, underwriting makes money
+trv.ratios.expense_ratio         # the difference between the two
+trv.ratios.investment_yield      # investment income over average investments
+trv.ratios.float_to_equity
+```
+
+These are property and casualty concepts. For life insurers, whose revenue is mostly investment income and whose reserves are future policy benefits, the combined ratio and the float mislead; read their investment yield and return on equity instead.
 
 ## Ratios
 

data/lib/fundamentalista/financials.rb

@@ -92,7 +92,8 @@ module Fundamentalista
         currency: quarters.first.currency, balance: quarters.first.balance,
         income: IncomeStatement.sum(quarters.map(&:income)),
         cash_flow: CashFlowStatement.sum(quarters.map(&:cash_flow)),
-        banking: Banking.sum(quarters.map(&:banking))
+        banking: Banking.sum(quarters.map(&:banking)),
+        insurance: Insurance.sum(quarters.map(&:insurance))
       )
     end
 

data/lib/fundamentalista/insurance.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Fundamentalista
+  # The lines an insurer reports that the three classic statements do not
+  # carry: premiums, claims, investment income, reserves and the balances
+  # behind the float. Empty for companies that are not insurers. All in
+  # the reporting currency.
+  class Insurance < Statement
+    field :premiums_earned, :premiums_written, :claims_incurred, :benefits_and_expenses, :investment_income,
+          :investments, :reserves, :unearned_premiums, :premiums_receivable, :reinsurance_recoverables
+
+    INSTANT = %i[investments reserves unearned_premiums premiums_receivable reinsurance_recoverables].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 earns premiums, the mark of an insurer.
+    def insurer?
+      !premiums_earned.nil? && !premiums_earned.zero?
+    end
+
+    # Buffett's float: reserves and unearned premiums, less what
+    # policyholders and reinsurers still owe. The money an insurer invests
+    # before it pays claims.
+    def float
+      return nil if reserves.nil?
+
+      reserves + (unearned_premiums || 0) - (premiums_receivable || 0) - (reinsurance_recoverables || 0)
+    end
+  end
+end

data/lib/fundamentalista/period.rb

@@ -27,6 +27,9 @@ module Fundamentalista
     # The Banking lines, empty for companies that are not banks.
     attr_reader :banking
 
+    # The Insurance lines, empty for companies that are not insurers.
+    attr_reader :insurance
+
     # Where each line item came from, keyed by item, as Source objects.
     # Empty when the provider does not say.
     attr_reader :sources
@@ -37,14 +40,15 @@ module Fundamentalista
     # The period before this one, or +nil+.
     attr_accessor :prior
 
-    def initialize(fiscal_year:, ended_on:, income:, balance:, cash_flow:, banking: Banking.new, sources: {},
-                   type: :annual, quarter: nil, currency: 'USD', prior: nil)
+    def initialize(fiscal_year:, ended_on:, income:, balance:, cash_flow:, banking: Banking.new, insurance: Insurance.new,
+                   sources: {}, type: :annual, quarter: nil, currency: 'USD', prior: nil)
       @fiscal_year = fiscal_year
       @ended_on = ended_on
       @income = income
       @balance = balance
       @cash_flow = cash_flow
       @banking = banking
+      @insurance = insurance
       @sources = sources
       @type = type
       @quarter = quarter
@@ -69,6 +73,11 @@ module Fundamentalista
       banking.bank?
     end
 
+    # Whether the company is an insurer, judged by premiums earned.
+    def insurer?
+      insurance.insurer?
+    end
+
     # Returns the Source of the line item +name+, or +nil+.
     def source(name)
       sources[name]
@@ -90,7 +99,8 @@ module Fundamentalista
     # Returns the period and its statements 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 }
+        income: income.to_h, balance: balance.to_h, cash_flow: cash_flow.to_h, banking: banking.to_h,
+        insurance: insurance.to_h }
     end
 
     # The days the period spans, for turning turnover into days.
@@ -136,7 +146,7 @@ module Fundamentalista
       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].find { |candidate| candidate.respond_to?(name) }
+      statement = [income, balance, cash_flow, banking, insurance].find { |candidate| candidate.respond_to?(name) }
       raise ArgumentError, "Unknown metric #{name.inspect}" unless statement
 
       statement.public_send(name)

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

@@ -111,7 +111,22 @@ module Fundamentalista
         # by fiscal year end, used when the balance sheet lacks the item.
         COVER = { shares_outstanding: 'EntityCommonStockSharesOutstanding' }.freeze
 
-        INSTANT = (BALANCE.keys + Banking::INSTANT).freeze
+        INSURANCE = {
+          premiums_earned: %w[PremiumsEarnedNet DirectPremiumsEarned],
+          premiums_written: %w[PremiumsWrittenNet DirectPremiumsWritten],
+          claims_incurred: %w[PolicyholderBenefitsAndClaimsIncurredNet
+                              LiabilityForUnpaidClaimsAndClaimsAdjustmentExpenseIncurredClaims1],
+          benefits_and_expenses: %w[BenefitsLossesAndExpenses],
+          investment_income: %w[NetInvestmentIncome GrossInvestmentIncomeOperating],
+          investments: %w[Investments],
+          reserves: %w[LiabilityForFuturePolicyBenefitsAndUnpaidClaimsAndClaimsAdjustmentExpense
+                       LiabilityForClaimsAndClaimsAdjustmentExpense LiabilityForFuturePolicyBenefits],
+          unearned_premiums: %w[UnearnedPremiums],
+          premiums_receivable: %w[PremiumsReceivableAtCarryingValue],
+          reinsurance_recoverables: %w[ReinsuranceRecoverablesOnPaidAndUnpaidLosses]
+        }.freeze
+
+        INSTANT = (BALANCE.keys + Banking::INSTANT + Insurance::INSTANT).freeze
       end
     end
   end

data/lib/fundamentalista/providers/edgar.rb

@@ -47,7 +47,8 @@ module Fundamentalista
       private
 
       STATEMENTS = { income: [IncomeStatement, Tags::INCOME], balance: [BalanceSheet, Tags::BALANCE],
-                     cash_flow: [CashFlowStatement, Tags::CASH_FLOW], banking: [Banking, Tags::BANKING] }.freeze
+                     cash_flow: [CashFlowStatement, Tags::CASH_FLOW], banking: [Banking, Tags::BANKING],
+                     insurance: [Insurance, Tags::INSURANCE] }.freeze
       private_constant :STATEMENTS
 
       def annual_period(facts, year, ended_on)

data/lib/fundamentalista/ratios.rb

@@ -24,7 +24,8 @@ module Fundamentalista
                          cash_conversion_cycle].freeze
     CASH = %i[fcf_margin cash_conversion capex_to_revenue accrual_ratio].freeze
     BANKING = %i[net_interest_margin efficiency_ratio loan_to_deposit cost_of_risk allowance_to_loans].freeze
-    ALL = (PROFITABILITY + LIQUIDITY + LEVERAGE + EFFICIENCY + WORKING_CAPITAL + CASH + BANKING).freeze
+    INSURANCE = %i[loss_ratio expense_ratio combined_ratio investment_yield float_to_equity].freeze
+    ALL = (PROFITABILITY + LIQUIDITY + LEVERAGE + EFFICIENCY + WORKING_CAPITAL + CASH + BANKING + INSURANCE).freeze
 
     attr_reader :period
 
@@ -182,15 +183,42 @@ module Fundamentalista
       Decimal.ratio(banking.allowance_for_credit_losses, banking.loans)
     end
 
+    # Claims incurred over premiums earned.
+    def loss_ratio
+      Decimal.ratio(insurance.claims_incurred, insurance.premiums_earned)
+    end
+
+    # Everything the insurer spends beyond claims, over premiums earned.
+    def expense_ratio
+      Decimal.subtract(combined_ratio, loss_ratio)
+    end
+
+    # Benefits, losses and expenses over premiums earned; below one the
+    # underwriting itself makes money.
+    def combined_ratio
+      Decimal.ratio(insurance.benefits_and_expenses, insurance.premiums_earned)
+    end
+
+    # Net investment income over average investments.
+    def investment_yield
+      Decimal.ratio(insurance.investment_income, average(:investments, of: :insurance))
+    end
+
+    # The float over equity, the leverage an insurer's investing runs on.
+    def float_to_equity
+      Decimal.ratio(insurance.float, balance.equity)
+    end
+
     # The DuPont decomposition of ROE: net margin times asset turnover times
     # the equity multiplier.
     def dupont
       { net_margin: net_margin, asset_turnover: asset_turnover, equity_multiplier: equity_multiplier, roe: roe }
     end
 
-    # Returns every ratio keyed by name; the banking ones only for banks.
+    # Returns every ratio keyed by name; the banking ones only for banks,
+    # the insurance ones only for insurers.
     def to_h
-      names = period.bank? ? ALL : ALL - BANKING
+      names = ALL - (period.bank? ? [] : BANKING) - (period.insurer? ? [] : INSURANCE)
       names.to_h { |name| [name, public_send(name)] }
     end
 
@@ -216,6 +244,10 @@ module Fundamentalista
       period.banking
     end
 
+    def insurance
+      period.insurance
+    end
+
     def average(field, of: :balance)
       current = period.public_send(of).public_send(field)
       return current unless period.prior

data/lib/fundamentalista/version.rb

@@ -2,5 +2,5 @@
 
 module Fundamentalista
   # The version of the fundamentalista gem, as a string.
-  VERSION = '0.2.0'
+  VERSION = '0.3.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fundamentalista
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Bruno Costanzo
@@ -92,6 +92,7 @@ files:
 - lib/fundamentalista/financials.rb
 - lib/fundamentalista/income_statement.rb
 - lib/fundamentalista/inspectable.rb
+- lib/fundamentalista/insurance.rb
 - lib/fundamentalista/period.rb
 - lib/fundamentalista/price_history.rb
 - lib/fundamentalista/provider.rb