finrb 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b167e3a39320ed5f8026b7451063d08f6eeb8e1047dc06f7688e4afc617434c2
-  data.tar.gz: 9407136f5589353ab3704f9bd7bb37b802191aa3aa51ca2bc3248cf359a276da
+  metadata.gz: 5331d4b4769cc183d279c1eb4d837d05137cb6b09dd69394addb7be0c6debfae
+  data.tar.gz: de97a959862d55711e7e6989dc8c47ffa277dcea32cc8184cc89f2158edad160
 SHA512:
-  metadata.gz: 9ec1ff7159e4d1aadd5dde4fcb168a0f1a7679e20f59c50bb26a642ccbee1e6aa65b021e67906586382e64aca23a240e566625ea359dc48e9aa2987e24a9c433
-  data.tar.gz: 671ae01b065e636c0bf8ef60e851e53866b02e09238d3a233443150a11f09851af493a2462e891a305ce174c6cb57ba492f09f6cfef48ded3693a120e448c410
+  metadata.gz: e57aeeac9a952790c895d367170596097d15fe5cbdb43bcab6a9943bfa80bff0a3a4d1e9d016e859d6f554b7a892a78ee2b3896f961b850f9ac1fafd7e064948
+  data.tar.gz: 84e26bbd5a9862c6733cbce98cebe4ebe1640751992c6fffe74d33ba31b39dc77f0f0ca5cf4ec8b6fd6bb6d0c62fa5bab1cbbacd3b0a8384d4d1eb1573b9528d

data/CHANGELOG.md

@@ -1,5 +1,30 @@
 # finrb changelog
 
+## 1.1.0
+
+### Investment returns and risk
+
+- Add compound annual growth rate (CAGR) with explicit value and period-domain validation.
+- Add modified internal rate of return (MIRR) with separate financing and reinvestment rates.
+- Add sample and population volatility, downside deviation, Sortino ratio, and maximum drawdown.
+- Add compound-return and square-root-of-time volatility annualization helpers.
+- Define the statistical conventions explicitly: volatility is sample-based by default, downside deviation includes all observations in its denominator, and maximum drawdown is returned as a non-negative loss fraction.
+
+### Loan schedules
+
+- Expose each amortization period as an immutable `Finrb::Amortization::Entry` containing its period, opening and closing balances, payment, interest, principal, additional principal, balloon settlement, and interest-only state.
+- Preserve the existing cashflow convention: payments are negative, while balances, interest, principal repaid, and additional principal are non-negative.
+- Add contractual balloon targets. Regular installments amortize toward the target and the final payment settles the residual, including cent-rounding reconciliation.
+- Add leading interest-only periods, including zero-rate periods and combinations with balloon loans. Remaining principal amortizes over the rest of the term.
+- Add upfront and financed origination fees with separate `principal`, `net_proceeds`, and `amount_financed` values. Financed fees enter the opening balance; upfront fees reduce borrower proceeds.
+- Correct schedule period numbering across rate segments and reused payment templates.
+
+### API and documentation
+
+- Add RBS declarations and API examples for all new return metrics and amortization features.
+- Refine README compatibility badges to identify tested MRI versions, x86-64/ARM64 architectures, and experimental JRuby/TruffleRuby coverage.
+- Remove redundant YARD `@api` annotations and make the internal amortization calculation methods genuinely private.
+
 ## 1.0.1
 
 ### Runtime compatibility

data/README.md

@@ -3,6 +3,9 @@
 [![CI](https://github.com/ncs1/finrb/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/ncs1/finrb/actions/workflows/ci.yml)
 [![CodeQL](https://github.com/ncs1/finrb/actions/workflows/codeql.yml/badge.svg)](https://github.com/ncs1/finrb/actions/workflows/codeql.yml)
 [![RuboCop](https://github.com/ncs1/finrb/actions/workflows/rubocop.yml/badge.svg)](https://github.com/ncs1/finrb/actions/workflows/rubocop.yml)
+[![MRI](https://img.shields.io/badge/MRI-3.3_%7C_3.4_%7C_4.0-CC342D?logo=ruby&logoColor=white)](https://github.com/ncs1/finrb/actions/workflows/ci.yml)
+[![Architectures](https://img.shields.io/badge/architectures-x86__64_%7C_arm64-4169E1)](https://github.com/ncs1/finrb/actions/workflows/ci.yml)
+[![Experimental engines](https://img.shields.io/badge/experimental-JRuby_%7C_TruffleRuby-F0AD4E)](https://github.com/ncs1/finrb/actions/workflows/ci.yml)
 
 Precision-first financial mathematics for Ruby.
 
@@ -117,6 +120,15 @@ loan = Finrb::Amortization.new(250_000, rate)
 loan.payment      # => Flt::DecNum('-1229.85')
 loan.interest.sum # => Flt::DecNum('192745.98')
 loan.balance      # => Flt::DecNum('0.00')
+
+first = loan.schedule.first
+first.opening_balance
+first.interest
+first.principal
+first.payment
+first.balloon_payment
+first.interest_only?
+first.closing_balance
 ```
 
 Pass several duration-bearing rates for an adjustable-rate schedule. A block
@@ -130,6 +142,48 @@ end
 
 Payments and interest follow the sign convention used throughout finrb:
 money received is positive and money paid is negative.
+Schedule balances, interest, principal repaid, and additional principal are
+non-negative; the schedule's payment field is negative.
+
+Set a residual principal target to create a balloon loan. Regular installments
+amortize only the non-balloon portion, and the final payment settles the stated
+balloon:
+
+```ruby
+balloon_loan = Finrb::Amortization.new(250_000, rate, balloon: 100_000)
+balloon_loan.schedule.last.balloon_payment # => Flt::DecNum('100000')
+```
+
+`balloon` is the contractual residual target. Because regular postings are
+rounded to cents, the actual `balloon_payment` in the final schedule row can
+differ from that target by a few cents.
+
+Leading interest-only periods defer scheduled principal repayment and amortize
+the balance over the remaining term:
+
+```ruby
+interest_only = Finrb::Amortization.new(250_000, rate, interest_only_periods: 24)
+interest_only.schedule.first.interest_only? # => true
+interest_only.schedule.first.principal      # => Flt::DecNum('0')
+```
+
+Origination fees can either reduce the borrower's net proceeds or be added to
+the financed balance:
+
+```ruby
+cash_fee = Finrb::Amortization.new(250_000, rate, origination_fee: 2_500)
+cash_fee.net_proceeds    # => Flt::DecNum('247500')
+cash_fee.amount_financed # => Flt::DecNum('250000')
+
+financed_fee = Finrb::Amortization.new(
+  250_000,
+  rate,
+  origination_fee: 2_500,
+  finance_origination_fee: true
+)
+financed_fee.net_proceeds    # => Flt::DecNum('250000')
+financed_fee.amount_financed # => Flt::DecNum('252500')
+```
 
 ## Configuration
 

data/lib/finrb/amortization.rb

@@ -18,20 +18,67 @@ module Finrb
   # @example Borrow $250,000 under a 30 year, fixed-rate loan with a 4.25% APR, but pay $150 extra each month
   #   rate = Rate.new(0.0425, :apr, :duration => (5 * 12))
   #   extra_payments = Finrb::Amortization.new(250000, rate){ |period| period.payment - 150 }
-  # @api public
   class Amortization
+    # Immutable breakdown of one amortization period. Payments retain finrb's
+    # cashflow sign convention and are negative; the other monetary fields are
+    # non-negative.
+    class Entry
+      ATTRIBUTES = %i[period opening_balance payment interest principal additional_payment balloon_payment interest_only closing_balance].freeze
+      MONETARY_ATTRIBUTES = ATTRIBUTES - %i[period interest_only]
+      private_constant :ATTRIBUTES, :MONETARY_ATTRIBUTES
+
+      attr_reader(*ATTRIBUTES)
+
+      def initialize(period:, opening_balance:, payment:, interest:, principal:, additional_payment:, balloon_payment:, interest_only:, closing_balance:)
+        raise(ArgumentError, 'period must be a non-negative integer.') unless period.is_a?(Integer) && !period.negative?
+        raise(ArgumentError, 'interest_only must be true or false.') unless [true, false].include?(interest_only)
+
+        @period = period
+        @interest_only = interest_only
+        MONETARY_ATTRIBUTES.each do |name|
+          value = binding.local_variable_get(name)
+          instance_variable_set("@#{name}", Validation.decimal(value, name: name.to_s))
+        end
+        freeze
+      end
+
+      def ==(other)
+        other.instance_of?(self.class) && ATTRIBUTES.all? { |name| public_send(name) == other.public_send(name) }
+      end
+      alias eql? ==
+
+      def hash
+        attributes = ATTRIBUTES.map { |name| public_send(name) }
+        attributes.hash
+      end
+
+      def to_h
+        ATTRIBUTES.to_h { |name| [name, public_send(name)] }
+      end
+
+      alias interest_only? interest_only
+    end
+
     # @return [Flt::DecNum] the balance of the loan at the end of the amortization period (usually zero)
-    # @api public
     attr_reader :balance
+    # @return [Flt::DecNum] contractual principal settled as a balloon in the final period
+    attr_reader :balloon
+    # @return [Flt::DecNum] principal balance including any financed origination fee
+    attr_reader :amount_financed
+    # @return [Flt::DecNum] cash made available to the borrower after an unfinanced fee
+    attr_reader :net_proceeds
+    # @return [Flt::DecNum] fee charged when the loan is originated
+    attr_reader :origination_fee
+    # @return [Integer] number of leading periods that pay interest but no scheduled principal
+    attr_reader :interest_only_periods
     # @return [Flt::DecNum] the required monthly payment.  For loans with more than one rate, returns nil
-    # @api public
     attr_reader :payment
     # @return [Flt::DecNum] the principal amount of the loan
-    # @api public
     attr_reader :principal
     # @return [Array] the interest rates used for calculating the amortization
-    # @api public
     attr_reader :rates
+    # @return [Array<Entry>] immutable period-by-period loan breakdown
+    attr_reader :schedule
 
     # @return [Flt::DecNum] the periodic payment due on a loan
     # @param [Flt::DecNum] principal the initial amount of the loan or investment
@@ -43,11 +90,13 @@ module Finrb
     #   rate.duration #=> 360
     #   Amortization.payment(200000, rate.monthly, rate.duration) #=> Flt::DecNum('-926.23')
     # @see https://en.wikipedia.org/wiki/Amortization_calculator
-    # @api public
-    def self.payment(principal, rate, periods)
+    def self.payment(principal, rate, periods, balloon: 0)
       principal = Validation.decimal(principal, name: 'principal')
       raise(ArgumentError, 'principal must be positive.') unless principal.positive?
 
+      balloon = Validation.decimal(balloon, name: 'balloon')
+      raise(ArgumentError, 'balloon must be non-negative and no greater than principal.') unless balloon.between?(0, principal)
+
       rate = Validation.decimal(rate, name: 'rate')
       raise(ArgumentError, 'periodic rate must be greater than -1.') if rate <= -1
 
@@ -55,9 +104,10 @@ module Finrb
 
       if rate.zero?
         # simplified formula to avoid division-by-zero when interest rate is zero
-        -Precision.money(principal / periods)
+        -Precision.money((principal - balloon) / periods)
       else
-        -Precision.money(principal * (rate + (rate / (((rate + 1)**periods) - 1))))
+        growth = (rate + 1)**periods
+        -Precision.money(((principal * growth) - balloon) * rate / (growth - 1))
       end
     end
 
@@ -66,10 +116,21 @@ module Finrb
     # @param [Flt::DecNum] principal the initial amount of the loan or investment
     # @param [Rate] rates the applicable interest rates
     # @param [Proc] block
-    # @api public
-    def initialize(principal, *rates, &block)
+    def initialize(principal, *rates, balloon: 0, interest_only_periods: 0, origination_fee: 0, finance_origination_fee: false, &block)
       @principal = Validation.decimal(principal, name: 'principal')
       raise(ArgumentError, 'principal must be positive.') unless @principal.positive?
+
+      @origination_fee = Validation.decimal(origination_fee, name: 'origination_fee')
+      raise(ArgumentError, 'origination_fee must be non-negative.') if @origination_fee.negative?
+      raise(ArgumentError, 'finance_origination_fee must be true or false.') unless [true, false].include?(finance_origination_fee)
+      raise(ArgumentError, 'an unfinanced origination_fee must be less than principal.') if !finance_origination_fee && @origination_fee >= @principal
+
+      @finance_origination_fee = finance_origination_fee
+      @amount_financed = @principal + (finance_origination_fee ? @origination_fee : 0)
+      @net_proceeds = @principal - (finance_origination_fee ? 0 : @origination_fee)
+
+      @balloon = Validation.decimal(balloon, name: 'balloon')
+      raise(ArgumentError, 'balloon must be non-negative and less than amount financed.') if @balloon.negative? || @balloon >= @amount_financed
       raise(ArgumentError, 'at least one rate is required.') if rates.empty?
       raise(ArgumentError, 'rates must be Finrb::Rate instances.') unless rates.all?(Rate)
       raise(ArgumentError, 'every rate must have a duration.') if rates.any? { |rate| rate.duration.nil? }
@@ -79,7 +140,11 @@ module Finrb
 
       # compute the total duration from all of the rates.
       @periods = rates.sum(&:duration)
-      @period  = 0
+      valid_interest_only = interest_only_periods.is_a?(Integer) && interest_only_periods.between?(0, @periods - 1)
+      raise(ArgumentError, 'interest_only_periods must be a non-negative integer shorter than the loan term.') unless valid_interest_only
+
+      @interest_only_periods = interest_only_periods
+      @period = 0
 
       compute
     end
@@ -87,17 +152,18 @@ module Finrb
     # compare two Amortization instances
     # @return [Numeric] -1, 0, or +1
     # @param [Amortization] other
-    # @api public
     def ==(other)
-      (principal == other.principal) && (rates == other.rates) && (payments == other.payments)
+      (principal == other.principal) && (origination_fee == other.origination_fee) && (finance_origination_fee? == other.finance_origination_fee?) && (balloon == other.balloon) && (interest_only_periods == other.interest_only_periods) && (rates == other.rates) && (payments == other.payments)
     end
 
+    attr_reader :finance_origination_fee
+    alias finance_origination_fee? finance_origination_fee
+
     # @return [Array] the amount of any additional payments in each period
     # @example
     #   rate = Rate.new(0.0375, :apr, :duration => (30 * 12))
     #   amt = Finrb::Amortization.new(300000, rate){ |payment| payment.amount-100}
     #   amt.additional_payments #=> [Flt::DecNum('-100.00'), Flt::DecNum('-100.00'), ... ]
-    # @api public
     def additional_payments
       @transactions.filter_map { |trans| trans.difference if trans.payment? }
     end
@@ -105,32 +171,29 @@ module Finrb
     # amortize the balance of loan with the given interest rate
     # @return none
     # @param [Rate] rate the interest rate to use in the amortization
-    # @api private
     def amortize(rate)
-      # For the purposes of calculating a payment, the relevant time
-      # period is the remaining number of periods in the loan, not
-      # necessarily the duration of the rate itself.
-      periods = @periods - @period
-      amount = Amortization.payment(@balance, rate.monthly, periods)
-
-      pmt = Payment.new(amount, period: @period)
-      pmt.modify(&@block) if @block
-      raise(ArgumentError, 'payment modification must produce a negative amount.') unless pmt.amount.negative?
+      regular_payment = nil
 
       rate.duration.to_i.times do
         # Do this first in case the balance is zero already.
         break if @balance.zero?
 
+        interest_only = @period < @interest_only_periods
+        regular_payment ||= build_regular_payment(rate) unless interest_only
+
         # Compute and record interest on the outstanding balance.
         int = Precision.money(@balance * rate.monthly)
         interest = Interest.new(int, period: @period)
         @balance += interest.amount
         @transactions << interest.dup
 
-        # Record payment.  Don't pay more than the outstanding balance.
-        pmt.amount = -@balance if pmt.amount.abs > @balance
-        @transactions << pmt.dup
-        @balance += pmt.amount
+        payment = interest_only ? build_interest_only_payment(int) : regular_payment
+        payment.period = @period
+        payment.amount = -@balance if payment.amount.abs > @balance
+        @additional_by_period << [-payment.difference, Flt::DecNum(0)].max
+        @interest_only_by_period << interest_only
+        @transactions << payment.dup
+        @balance += payment.amount
 
         @period += 1
       end
@@ -138,26 +201,35 @@ module Finrb
 
     # compute the amortization of the principal
     # @return none
-    # @api private
     def compute
-      @balance = @principal
+      @balance = @amount_financed
       @transactions = []
+      @additional_by_period = []
+      @interest_only_by_period = []
 
       @rates.each do |rate|
         amortize(rate)
       end
 
-      # Add any remaining balance due to rounding error to the last payment.
+      # Add the residual balloon and any rounding remainder to the last payment.
+      @balloon_by_period = Array.new(@additional_by_period.length, Flt::DecNum(0))
       if @balance.nonzero?
+        @balloon_by_period[-1] = [@balloon, @balance].min
         @transactions.reverse.find(&:payment?).amount -= @balance
         @balance = 0
       end
 
-      @payment = (payments.first if @rates.length == 1)
+      @payment = (payments.first if @rates.length == 1 && @interest_only_periods.zero?)
 
       @transactions.freeze
+      @additional_by_period.freeze
+      @balloon_by_period.freeze
+      @interest_only_by_period.freeze
+      @schedule = build_schedule.freeze
     end
 
+    private :amortize, :compute
+
     # @return [Integer] the time required to pay off the loan, in months
     # @example In most cases, the duration is equal to the total duration of all rates
     #   rate = Rate.new(0.0375, :apr, :duration => (30 * 12))
@@ -167,12 +239,10 @@ module Finrb
     #   rate = Rate.new(0.0375, :apr, :duration => (30 * 12))
     #   amt = Finrb::Amortization.new(300000, rate){ |payment| payment.amount-100}
     #   amt.duration #=> 319
-    # @api public
     def duration
       payments.length
     end
 
-    # @api public
     def inspect
       "Amortization.new(#{@principal})"
     end
@@ -186,7 +256,6 @@ module Finrb
     #   rate = Rate.new(0.0375, :apr, :duration => (30 * 12))
     #   amt = Finrb::Amortization.new(300000, rate)
     #   amt.interest[0,6].sum #=> Flt::DecNum('5603.74')
-    # @api public
     def interest
       @transactions.filter_map { |trans| trans.amount if trans.interest? }
     end
@@ -196,9 +265,45 @@ module Finrb
     #   rate = Rate.new(0.0375, :apr, :duration => (30 * 12))
     #   amt = Finrb::Amortization.new(300000, rate)
     #   amt.payments.sum #=> Flt::DecNum('-500163.94')
-    # @api public
     def payments
       @transactions.filter_map { |trans| trans.amount if trans.payment? }
     end
+
+    private
+
+    def build_schedule
+      opening_balance = @amount_financed
+      @transactions.each_slice(2).with_index.map do |(interest, payment), index|
+        principal = -(payment.amount + interest.amount)
+        closing_balance = opening_balance - principal
+        entry = Entry.new(period: payment.period, opening_balance:, payment: payment.amount, interest: interest.amount, principal:, additional_payment: @additional_by_period.fetch(index), balloon_payment: @balloon_by_period.fetch(index), interest_only: @interest_only_by_period.fetch(index), closing_balance:)
+        opening_balance = closing_balance
+        entry
+      end
+    end
+
+    def build_regular_payment(rate)
+      periods = @periods - @period
+      amount = Amortization.payment(@balance, rate.monthly, periods, balloon: @balloon)
+      Payment.new(amount, period: @period).tap do |payment|
+        payment.modify(&@block) if @block
+        validate_payment!(payment)
+      end
+    end
+
+    def build_interest_only_payment(interest)
+      Payment.new(-interest, period: @period).tap do |payment|
+        payment.modify(&@block) if @block
+        validate_payment!(payment, allow_zero: true)
+      end
+    end
+
+    def validate_payment!(payment, allow_zero: false)
+      valid = payment.amount.negative? || (allow_zero && payment.amount.zero?)
+      return if valid
+
+      requirement = allow_zero ? 'must not produce a positive amount' : 'must produce a negative amount'
+      raise(ArgumentError, "payment modification #{requirement}.")
+    end
   end
 end

data/lib/finrb/cashflows.rb

@@ -12,7 +12,6 @@ require 'date'
 
 module Finrb
   # Provides methods for working with cash flows (collections of transactions)
-  # @api public
   module Cashflow
     class << self
       def irr(cashflows, guess = nil)
@@ -23,6 +22,10 @@ module Finrb
         sequence(cashflows).npv(rate)
       end
 
+      def mirr(cashflows, finance_rate:, reinvestment_rate:)
+        sequence(cashflows).mirr(finance_rate:, reinvestment_rate:)
+      end
+
       def xirr(transactions, guess = nil)
         sequence(transactions).xirr(guess)
       end
@@ -55,7 +58,6 @@ module Finrb
     # @example
     #   Finrb::Cashflow.irr([-4000,1200,1410,1875,1050]) #=> 0.143
     # @see https://en.wikipedia.org/wiki/Internal_rate_of_return
-    # @api public
     def irr(guess = nil)
       validate_numeric_cashflows!
 
@@ -71,7 +73,6 @@ module Finrb
     # @example
     #   Finrb::Cashflow.npv([-100.0, 60, 60, 60], 0.1) #=> 49.211
     # @see https://en.wikipedia.org/wiki/Net_present_value
-    # @api public
     def npv(rate)
       validate_numeric_cashflows!
       cashflows = map { |entry| Validation.decimal(entry, name: 'cashflow amount') }
@@ -87,6 +88,33 @@ module Finrb
       total
     end
 
+    # Calculate the modified internal rate of return for equally spaced
+    # cashflows using separate financing and reinvestment assumptions.
+    # @return [Flt::DecNum] modified per-period internal rate of return
+    def mirr(finance_rate:, reinvestment_rate:)
+      validate_numeric_cashflows!
+      raise(InvalidCashflowError, 'MIRR requires at least two cashflows.') if size < 2
+
+      cashflows = map { |entry| Validation.decimal(entry, name: 'cashflow amount') }
+      raise(InvalidCashflowError, 'Cashflow needs at least one positive and one negative value.') if cashflows.none?(&:positive?) || cashflows.none?(&:negative?)
+
+      finance_rate = Validation.decimal(finance_rate, name: 'finance_rate')
+      reinvestment_rate = Validation.decimal(reinvestment_rate, name: 'reinvestment_rate')
+      raise(DomainError, 'Finance and reinvestment rates must be greater than -1.') if finance_rate <= -1 || reinvestment_rate <= -1
+
+      last_period = cashflows.size - 1
+      future_positive =
+        cashflows.each_with_index.sum do |amount, index|
+          amount.positive? ? amount * ((reinvestment_rate + 1)**(last_period - index)) : Flt::DecNum(0)
+        end
+      present_negative =
+        cashflows.each_with_index.sum do |amount, index|
+          amount.negative? ? amount / ((finance_rate + 1)**index) : Flt::DecNum(0)
+        end
+
+      ((future_positive / -present_negative)**(Flt::DecNum(1) / last_period)) - 1
+    end
+
     # Calculate the effective annual internal rate of return for an ordered
     # sequence of dated transactions.
     #
@@ -108,7 +136,6 @@ module Finrb
     #   @transactions << Transaction.new(  600, :date => Time.new(1990,01,01))
     #   @transactions << Transaction.new(  600, :date => Time.new(1995,01,01))
     #   Finrb::Cashflow.xirr(@transactions, 0.6) #=> Rate("0.024851", :effective, :compounds => :annually)
-    # @api public
     def xirr(guess = nil)
       validate_dated_cashflows!
 
@@ -127,7 +154,6 @@ module Finrb
     #   @transactions << Transaction.new(  600, :date => Time.new(1990,01,01))
     #   @transactions << Transaction.new(  600, :date => Time.new(1995,01,01))
     #   Finrb::Cashflow.xnpv(@transactions, 0.6).round(2) #=> -937.41
-    # @api public
     def xnpv(rate)
       validate_dated_cashflows!
       rate = Validation.decimal(rate, name: 'rate')

data/lib/finrb/rates.rb

@@ -6,7 +6,6 @@ require_relative 'validation'
 module Finrb
   # the Rate class provides an interface for working with interest rates.
   # {render:Rate#new}
-  # @api public
   class Rate
     include Comparable
 
@@ -31,7 +30,6 @@ module Finrb
     # @param [Numeric] periods the number of compounding periods per year
     # @example
     #   Rate.to_effective(0.05, 4) #=> Flt::DecNum('0.05095')
-    # @api public
     def self.to_effective(rate, periods)
       rate = Validation.decimal(rate, name: 'rate')
       periods = compounding_periods(periods)
@@ -50,7 +48,6 @@ module Finrb
     # @example
     #   Rate.to_nominal(0.06, 365) #=> Flt::DecNum('0.05827')
     # @see https://www.miniwebtool.com/nominal-interest-rate-calculator/
-    # @api public
     def self.to_nominal(rate, periods)
       rate = Validation.decimal(rate, name: 'rate')
       raise(ArgumentError, 'effective rate must be greater than -1.') if rate <= -1
@@ -75,7 +72,6 @@ module Finrb
     #   Rate.new(0.035, :apr) #=> Rate(0.035, :apr)
     # @see https://en.wikipedia.org/wiki/Effective_interest_rate
     # @see https://en.wikipedia.org/wiki/Nominal_interest_rate
-    # @api public
     def initialize(rate, type, opts = {})
       raise(ArgumentError, 'options must be a Hash.') unless opts.is_a?(Hash)
       raise(ArgumentError, 'options may only contain compounds and duration.') unless (opts.keys - %i[compounds duration]).empty?
@@ -97,13 +93,10 @@ module Finrb
     end
 
     # @return [Integer] the duration for which the rate is valid, in months
-    # @api public
     attr_reader :duration
     # @return [Flt::DecNum] the effective interest rate
-    # @api public
     attr_reader :effective
     # @return [Flt::DecNum] the nominal interest rate
-    # @api public
     attr_reader :nominal
 
     # compare two Rates, using the effective rate
@@ -113,21 +106,18 @@ module Finrb
     #   r1 = Rate.new(0.15, :nominal) #=> Rate.new(0.160755, :apr)
     #   r2 = Rate.new(0.155, :nominal, :compounds => :semiannually) #=> Rate.new(0.161006, :apr)
     #   r1 <=> r2 #=> -1
-    # @api public
     def <=>(other)
       @effective <=> other.effective
     end
 
     # Return the nominal annual percentage rate for the configured compounding frequency.
     # @return [Flt::DecNum] the nominal annual percentage rate
-    # @api public
     def apr
       nominal
     end
 
     # Return the effective annual percentage yield.
     # @return [Flt::DecNum] the effective annual percentage yield
-    # @api public
     def apy
       effective
     end
@@ -136,7 +126,6 @@ module Finrb
     # @return none
     # @param [Symbol, Numeric] input the compounding frequency
     # @raise [ArgumentError] if input is not an accepted keyword or Numeric
-    # @api private
     def compounds=(input)
       @periods =
         case input
@@ -158,7 +147,6 @@ module Finrb
     # set the effective interest rate
     # @return none
     # @param [Flt::DecNum] rate the effective interest rate
-    # @api private
     def effective=(rate)
       raise(ArgumentError, 'effective rate must be greater than -1.') if rate <= -1
 
@@ -176,7 +164,6 @@ module Finrb
     #   rate.apr.round(6) #=> Flt::DecNum('0.15')
     #   rate.apy.round(6) #=> Flt::DecNum('0.160755')
     #   rate.monthly.round(6) #=> Flt::DecNum('0.0125')
-    # @api public
     def monthly
       @monthly ||= Precision.rate(Rate.to_nominal(effective, 12) / 12)
     end
@@ -184,7 +171,6 @@ module Finrb
     # set the nominal interest rate
     # @return none
     # @param [Flt::DecNum] rate the nominal interest rate
-    # @api private
     def nominal=(rate)
       raise(ArgumentError, 'nominal rate must keep every compounded period greater than -100%.') if !@periods.infinite? && rate <= -@periods
 

data/lib/finrb/returns.rb

@@ -2,6 +2,7 @@
 
 require_relative 'decimal'
 require_relative 'errors'
+require_relative 'validation'
 
 module Finrb
   # Investment return and risk-adjusted performance calculations.
@@ -17,6 +18,107 @@ module Finrb
     end
     private_class_method :wrap_array
 
+    # Compound annual growth rate over a positive number of periods.
+    #
+    # Beginning value must be positive. Ending value may be zero, representing
+    # a total loss, but cannot be negative because a fractional growth root
+    # would not have a generally meaningful real-valued result.
+    #
+    # @param beginning_value [Numeric] value at the start of the measurement
+    # @param ending_value [Numeric] value at the end of the measurement
+    # @param periods [Integer] number of equal annual periods
+    # @return [Flt::DecNum] compound growth rate per period
+    def self.cagr(beginning_value:, ending_value:, periods:)
+      beginning_value = Validation.decimal(beginning_value, name: 'beginning_value')
+      ending_value = Validation.decimal(ending_value, name: 'ending_value')
+      periods = Validation.positive_integer(periods, name: 'periods')
+
+      raise(ArgumentError, 'beginning_value must be greater than zero.') unless beginning_value.positive?
+      raise(ArgumentError, 'ending_value must be greater than or equal to zero.') if ending_value.negative?
+
+      ((ending_value / beginning_value)**(Flt::DecNum(1) / periods)) - 1
+    end
+
+    def self.risk_values(values, name:)
+      values = wrap_array(values)
+      raise(ArgumentError, "#{name} cannot be empty.") if values.empty?
+
+      values.map { |value| Validation.decimal(value, name:) }
+    end
+    private_class_method :risk_values
+
+    # Compound a periodic return into an annual return.
+    def self.annualize_return(rate:, periods_per_year:)
+      rate = Validation.decimal(rate, name: 'rate')
+      periods_per_year = Validation.positive_integer(periods_per_year, name: 'periods_per_year')
+      raise(ArgumentError, 'rate must be greater than or equal to -1.') if rate < -1
+
+      ((rate + 1)**periods_per_year) - 1
+    end
+
+    # Scale periodic volatility by the square root of periods per year.
+    def self.annualize_volatility(volatility:, periods_per_year:)
+      volatility = Validation.decimal(volatility, name: 'volatility')
+      periods_per_year = Validation.positive_integer(periods_per_year, name: 'periods_per_year')
+      raise(ArgumentError, 'volatility must be greater than or equal to zero.') if volatility.negative?
+
+      volatility * (Flt::DecNum(periods_per_year)**Flt::DecNum('0.5'))
+    end
+
+    # Standard deviation of periodic returns. Sample volatility uses n - 1;
+    # population volatility uses n.
+    def self.volatility(returns:, sample: true)
+      raise(ArgumentError, 'sample must be true or false.') unless [true, false].include?(sample)
+
+      returns = risk_values(returns, name: 'return')
+      raise(ArgumentError, 'sample volatility requires at least two returns.') if sample && returns.size < 2
+
+      mean = returns.sum / returns.size
+      denominator = sample ? returns.size - 1 : returns.size
+      variance = returns.sum { |value| (value - mean)**2 } / denominator
+      variance**Flt::DecNum('0.5')
+    end
+
+    # Root-mean-square return shortfall below a target return. The denominator
+    # includes every observation, including returns at or above the target.
+    def self.downside_deviation(returns:, target: 0)
+      returns = risk_values(returns, name: 'return')
+      target = Validation.decimal(target, name: 'target')
+      squared_shortfalls =
+        returns.sum do |value|
+          shortfall = [value - target, Flt::DecNum(0)].min
+          shortfall**2
+        end
+
+      (squared_shortfalls / returns.size)**Flt::DecNum('0.5')
+    end
+
+    # Sortino ratio using arithmetic mean excess return and downside deviation.
+    def self.sortino_ratio(returns:, target: 0, periods_per_year: nil)
+      returns = risk_values(returns, name: 'return')
+      target = Validation.decimal(target, name: 'target')
+      downside = downside_deviation(returns:, target:)
+      raise(ArgumentError, 'downside deviation must be greater than zero.') if downside.zero?
+
+      ratio = ((returns.sum / returns.size) - target) / downside
+      return ratio if periods_per_year.nil?
+
+      periods_per_year = Validation.positive_integer(periods_per_year, name: 'periods_per_year')
+      ratio * (Flt::DecNum(periods_per_year)**Flt::DecNum('0.5'))
+    end
+
+    # Largest peak-to-trough decline as a non-negative fraction.
+    def self.max_drawdown(values:)
+      values = risk_values(values, name: 'value')
+      raise(ArgumentError, 'values must be greater than zero.') unless values.all?(&:positive?)
+
+      peak = values.first
+      values.reduce(Flt::DecNum(0)) do |maximum, value|
+        peak = value if value > peak
+        [maximum, (peak - value) / peak].max
+      end
+    end
+
     # Computing Coefficient of variation
     #
     # @param sd standard deviation

data/lib/finrb/transaction.rb

@@ -4,17 +4,13 @@ require_relative 'validation'
 
 module Finrb
   # the Transaction class provides a general interface for working with individual cash flows.
-  # @api public
   class Transaction
     # @return [Flt::DecNum] the cash value of the transaction
-    # @api public
     attr_reader :amount
     # @return [Integer] the period number of the transaction
     # @note this attribute is mainly used in the case of mortgage amortization with no dates
-    # @api public
     attr_reader :period
     # @return [Date] the date of the transaction
-    # @api public
     attr_reader :date
 
     # create a new Transaction
@@ -26,7 +22,6 @@ module Finrb
     #   t = Transaction.new(400)
     # @example a transaction with a period number
     #   t = Transaction.new(400, :period => 3)
-    # @api public
     def initialize(amount, opts = {})
       raise(ArgumentError, 'options must be a Hash.') unless opts.is_a?(Hash)
       raise(ArgumentError, 'options may only contain date and period.') unless (opts.keys - %i[date period]).empty?
@@ -47,7 +42,6 @@ module Finrb
     #   t = Transaction.new(500)
     #   t.amount = 750
     #   t.amount #=> 750
-    # @api public
     def amount=(value)
       @amount = Validation.decimal(value, name: 'amount')
     end
@@ -71,7 +65,6 @@ module Finrb
     #   t = Transaction.new(500)
     #   t.amount = 750
     #   t.difference #=> Flt::DecNum('250')
-    # @api public
     def difference
       @amount - @original
     end
@@ -82,12 +75,10 @@ module Finrb
     #   int = Interest.new(500)
     #   pmt.interest? #=> False
     #   int.interest? #=> True
-    # @api public
     def interest?
       instance_of?(Interest)
     end
 
-    # @api public
     def inspect
       "Transaction(#{@amount.round(2)}, date: #{@date})"
     end
@@ -99,7 +90,6 @@ module Finrb
     #   pmt = Payment.new(-500)
     #   pmt.modify { |t| t.amount-100 }
     #   pmt.amount #=> -600
-    # @api public
     def modify
       self.amount = yield(self)
     end
@@ -116,7 +106,6 @@ module Finrb
     #   int = Interest.new(500)
     #   pmt.payment? #=> True
     #   int.payment? #=> False
-    # @api public
     def payment?
       instance_of?(Payment)
     end

data/lib/finrb/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module Finrb
-  VERSION = '1.0.1'
+  VERSION = '1.1.0'
   public_constant :VERSION
 end

data/sig/finrb.rbs

@@ -94,14 +94,40 @@ module Finrb
   end
 
   class Amortization
-    def self.payment: (number, number, Integer) -> decimal
+    class Entry
+      def initialize: (period: Integer, opening_balance: number, payment: number, interest: number, principal: number, additional_payment: number, balloon_payment: number, interest_only: bool, closing_balance: number) -> void
+      def period: () -> Integer
+      def opening_balance: () -> decimal
+      def payment: () -> decimal
+      def interest: () -> decimal
+      def principal: () -> decimal
+      def additional_payment: () -> decimal
+      def balloon_payment: () -> decimal
+      def interest_only: () -> bool
+      def interest_only?: () -> bool
+      def closing_balance: () -> decimal
+      def ==: (untyped) -> bool
+      def eql?: (untyped) -> bool
+      def hash: () -> Integer
+      def to_h: () -> Hash[Symbol, Integer | decimal]
+    end
+
+    def self.payment: (number, number, Integer, ?balloon: number) -> decimal
 
-    def initialize: (number, *Rate) ?{ (Transaction) -> number } -> void
+    def initialize: (number, *Rate, ?balloon: number, ?interest_only_periods: Integer, ?origination_fee: number, ?finance_origination_fee: bool) ?{ (Transaction) -> number } -> void
     def ==: (untyped) -> bool
     def balance: () -> decimal
+    def balloon: () -> decimal
+    def amount_financed: () -> decimal
+    def net_proceeds: () -> decimal
+    def origination_fee: () -> decimal
+    def finance_origination_fee: () -> bool
+    def finance_origination_fee?: () -> bool
+    def interest_only_periods: () -> Integer
     def payment: () -> decimal?
     def principal: () -> decimal
     def rates: () -> Array[Rate]
+    def schedule: () -> Array[Entry]
     def additional_payments: () -> Array[decimal]
     def duration: () -> Integer
     def inspect: () -> String
@@ -111,11 +137,13 @@ module Finrb
 
   module Cashflow
     def self.irr: (Enumerable[number], ?number) -> decimal
+    def self.mirr: (Enumerable[number], finance_rate: number, reinvestment_rate: number) -> decimal
     def self.npv: (Enumerable[number], number) -> decimal
     def self.xirr: (Enumerable[Transaction], ?number) -> Rate
     def self.xnpv: (Enumerable[Transaction], number) -> decimal
 
     def irr: (?number) -> decimal
+    def mirr: (finance_rate: number, reinvestment_rate: number) -> decimal
     def npv: (number) -> decimal
     def xirr: (?number) -> Rate
     def xnpv: (number) -> decimal
@@ -163,15 +191,22 @@ module Finrb
   end
 
   module Returns
+    def self.annualize_return: (rate: number, periods_per_year: Integer) -> decimal
+    def self.annualize_volatility: (volatility: number, periods_per_year: Integer) -> decimal
+    def self.cagr: (beginning_value: number, ending_value: number, periods: Integer) -> decimal
     def self.coefficient_variation: (sd: number, avg: number) -> decimal
     def self.geometric_mean: (r: number | numbers) -> decimal
     def self.harmonic_mean: (p: number | numbers) -> decimal
     def self.hpr: (ev: number, bv: number, ?cfr: number) -> decimal
+    def self.downside_deviation: (returns: number | numbers, ?target: number) -> decimal
+    def self.max_drawdown: (values: number | numbers) -> decimal
     def self.sampling_error: (sm: number, mu: number) -> decimal
     def self.sf_ratio: (rp: number, rl: number, sd: number) -> decimal
     def self.sharpe_ratio: (rp: number, rf: number, sd: number) -> decimal
+    def self.sortino_ratio: (returns: number | numbers, ?target: number, ?periods_per_year: Integer?) -> decimal
     def self.twrr: (ev: number | numbers, bv: number | numbers, cfr: number | numbers) -> decimal
     def self.wpr: (r: number | numbers, w: number | numbers) -> decimal
+    def self.volatility: (returns: number | numbers, ?sample: bool) -> decimal
   end
 
   module Yields

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: finrb
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.1.0
 platform: ruby
 authors:
 - Nadir Cohen