@u-dev/unison-calculators

unison-calculators

This is a set of calculation classes used for building front-end deal calculators. This is the math component.

NPM module here

Explanation of basic deal math (to be continued.)

Sharing percentage - How much Unison shares in a home's appreciation
Investment percentage - How much Unison invested in a deal, expressed as a percentage of the asset value
Leverage - For every percent Unison has invested in an asset, how many percentage points do they share in the asset's appreciation. Leverage can vary based on an asset's risk profile.

Example Formulas:

S = Sharing percentage
s = Sharing amount
I = Investment percentage
i = Investment amount
L = Leverage
A = Appreciation

// Sharing percentage (S) equals the investment percentage (I) times the leverage (L)

S = I * L
// ex. .35 = .1 * 3.5

// Sharing amount(s) equals sharing percentage(S) times apprciation (A)
s = S * A
// ex. 35,000 = .35 * 100,000

Utility Calculator

UtilCalculator

The util calculator can be used to do basic math for Unison deals.

For instance, I could run:

let calculator = new UtilCalculator('HomeOwner')
calculator.minSharingPercentage(3.5) // => 0.175
calculator.minInvestmentAmount(500000) // => 25000
calculator.maxInvestmentAmount(500000) // => 100000
calculator.sharingPercentage(.2, 3.5) // => .7
calculator.investmentPercentage(500000,100000) // => .2
calculator.unisonShare(100000,.35) // => 35000
calculator.leverage() // => 4
calculator.leverage({qualifiesForNewPricing: true}) // => 3.5

let calculator = new UtilCalculator('HomeBuyer')
calculator.minSharingPercentage(3.5) // => 0.175
calculator.minInvestmentAmount(500000) // => 25000
calculator.maxInvestmentAmount(500000) // => 100000
calculator.sharingPercentage(.2, 3.5) // => .7
calculator.investmentPercentage(500000,100000) // => .2
calculator.unisonShare(100000,.35) // => 35000
calculator.leverage() // => 3.5
calculator.leverage({isNewConstruction: true}) // => 4.5

API documentation:

// .initialize
// @param {string} product - The product we are calculating for
new UtilCalculator('HomeOwner')

// #minSharingPercentage()
// Given a deal's leverage, what is the minimum sharing percentage Unison could do for the deal?
// @param {number} leverage - The leverage in a unison deal
calculator.minSharingPercentage(3.5)

// #minInvestmentAmount()
// Given a home value, what is the minimum amount of money that Unison could invest?
// @param {number} homeValue - The home value
calculator.minInvestmentAmount(500000)

// #maxInvestmentAmount()
// Given a home value, what is the maximum amount of money that Unison could invest?
// @param {number} homeValue - The home value
calculator.maxInvestmentAmount(500000)

// #sharingPercentage()
// Given an investment percentage and a deal's leverage,
// what percent does Unison share in the appreciation?
// @param {number} investmentPercentage - The amount unison invested in a deal
// @param {number} leverage - The leverage on a deal
calculator.sharingPercentage(.2, 3.5)

// #investmentPercentage()
// Given an asset's value and an investment amount, what percent did Unison invest in the deal?
// @param {number} homeValue - The amount that the asset appreciated
// @param {number} investmentAmount - The percentage share unison has given a deal
calculator.investmentPercentage(500000, 100000)

// #unisonShare()
// Given an appreciation amount and a sharing percentage, how much is Unison's share?
// @param {number} appreciationAmount - The amount an asset has change over the course of a deal (can be negative)
// @param {number} unisonSharingPercentage - The percentage that Unison shares in appreciation
calculator.unisonShare(100000, .35)

// #leverage()
// Given a set of optional modifiers, what is the projected leverage for a deal?
// @param {object} options  
// @param {string} [options.qualifiesForNewPricing] - This acts as a leverage modifier on HomeOwner deals
// @param {string} [options.isNewConstruction] - This acts as a leverage modifier on HomeBuyer deals
calculator.leverage({qualifiesForNewPricing: true})

Scenario Calculators

HomeBuyerScenarioCalculator

The HomeBuyer scenario calculator can be used to calculate the outcome of a homebuyer deal.

To get started initialize a HomeBuyerCalculator instance and run the #calculate function.

#calculate takes four arguments 1) initialHomeValue, 2) unisonInvestment, 3) finalPriceChange, 4) and optional configuration object

For instance, I could run:

let calculator = new HomeBuyerScenarioCalculator()
calculator.calculate(500000,50000,100000,{
  isNewConstruction: false
})

And expect

{
  finalPriceChange: 100000,
  initialHomeValue: 500000,
  unisonInvestment: 50000,
  unisonLeverage: 4,
  unisonSharingPercentage: 0.4,
  unisonInvestmentPercentage: 0.1,
  futureSalePrice: 600000,
  unisonPayment: 90000,
  unisonShareInChange: 40000
}

API documentation:

// .initialize
new HomeBuyerScenarioCalculator()

// #calculate()
// Given an initial value, investment amount, and final value,
// along with a set of optional deal modifiers, what is the outcome of a Unison deal?
// @param {number} initialHomeValue - The initial home value
// @param {number} unisonInvestment - The amount unison has invested
// @param {number} finalPriceChange - The change in value you want to calculate for
// @param {object} [options={}] - optional modifiers for calculations
// @param {boolean} [options.isNewConstruction=false] - toggles pricing (non-new construction homes have better pricing)
calculator.calculate(500000, 50000, 100000, {
  isNewConstruction: false
})

HomeOwnerScenarioCalculator

The HomeOwner scenario calculator can be used to calculate the outcome of a homebuyer deal.

To get started initialize a HomeBuyerCalculator instance and run the #calculate function.

#calculate takes four arguments 1) initialHomeValue, 2) unisonInvestment, 3) finalPriceChange, 4) and optional configuration object

For instance, I could run:

let calculator = new HomeOwnerScenarioCalculator()
calculator.calculate(500000, 50000, 100000, {
  qualifiesForNewPricing: false
})

And expect

{
  finalPriceChange: 100000,
  initialHomeValue: 500000,
  unisonInvestment: 50000,
  unisonLeverage: 4,
  unisonSharingPercentage: 0.4,
  unisonInvestmentPercentage: 0.1,
  futureSalePrice: 600000,
  unisonPayment: 90000,
  unisonShareInChange: 40000
}

API documentation:

// .initialize
new HomeOwnerScenarioCalculator()

// #calculate()
// Given an initial value, investment amount, and final value,
// along with a set of optional deal modifiers, what is the outcome of a Unison deal?
// @param {number} initialHomeValue - The initial home value
// @param {number} unisonInvestment - The amount unison has invested
// @param {number} finalPriceChange - The change in value you want to calculate for
// @param {object} [options={}] - optional modifiers for calculations
// @param {boolean} [options.qualifiesForNewPricing=false] - toggles pricing (this is new pricing A.K.A. purchased in last year, which has better pricing)
calculator.calculate(500000, 50000, 100000, {
  qualifiesForNewPricing: false
})

Mortgage Calculators

HomeBuyerMortgageCalculator

The homebuyer mortgage calculator can be used to calculate mortgage payments with and without Unison.

To get started, initialize a new calculator with (optionally) an object containing any assumptions you want to overwrite.

You can then use the #calculate function to see payment outcomes for various combinations.

#calculate takes three arguments 1) homePrice, 2) clientDownPaymentPercentage, and 3) unisonDownPaymentPercentage

For instance, I could run:

var calculator = new HomeBuyerMortgageCalculator({assumptions: {mortgageYears: 30}})
calculator.calculate(500000,.1,.1)

And expect:

{
  assumptions: {
    mortgageYears: 30,
    annualMortgageInsurancePremium: 0.0074,
    annualMortgageInterestRate: 0.04,
    annualPropertyInsuranceRate: 0.003,
    annualPropertyTaxRate: 0.0125,
  },
  monthlyMortgagePayment: -1910,
  monthlyPMIPayment: 0,
  monthlyPropertyTaxPayment: -521,
  monthlyPropertyInsurancePayment: -125,
  totalMonthlyPayments: -2556,
  clientDownPaymentAmount: 50000,
  unisonDownPaymentAmount: 50000,
  downPaymentAmount: 100000,
  hasPMI: false,
}

Here are the default assumptions for any new calculator:

const DEFAULT_ASSUMPTIONS = {
  mortgageYears: 30,
  annualMortgageInterestRate: .04,
  annualPropertyTaxRate: .0125,
  annualPropertyInsuranceRate: .003,
  annualMortgageInsurancePremium: .0074,
}

API documentation:

// .initialize
// @param {object} [options={assumptions={}}] - The default set of options
// @param {number} [options.assumptions.mortgageYears] - Length of mortgage in years
// @param {number} [options.assumptions.annualMortgageInterestRate] - Annual loan interest rate
// @param {number} [options.assumptions.annualPropertyTaxRate] - Annual property tax rate
// @param {number} [options.assumptions.annualPropertyInsuranceRate] - Annual property insurance rate
// @param {number} [options.assumptions.annualMortgageInsurancePremium] - PMI rate
new HomeBuyerMortgageCalculator(options)

// #calculate()
// Given a home price, client down payment percentage (decimal percentage of total)
// and a unison down payment percentage (decimal percentage of total),
// what are the client's costs?
// @param {number} homePrice - The initial home value
// @param {number} clientDownPaymentPercentage - The percent of the loan, expressed as a decimal, that the client paid down
// @param {number} unisonDownPaymentPercentage - The percent of the loan, expressed as a decimal, that unison paid down
calculator.calculate(500000,.1,.1)