Financial

Methods

(inner) accrInt(issue, first_interest, settlement, rate, par, frequency, basisopt) → {number}

Returns the accrued interest for a security that pays periodic interest.

Parameters:
NameTypeAttributesDescription
issuestring | number | Date

The security's issue date.

first_intereststring | number | Date

The security's first interest date.

settlementstring | number | Date

The security's settlement date. The security settlement date is the date after the issue date when the security is traded to the buyer.

ratenumber

The security's annual coupon rate.

parnumber

The security's par value. If you omit par, ACCRINT uses $1,000.

frequencynumber

The number of coupon payments per year. For annual payments, frequency = 1; for semiannual, frequency = 2; for quarterly, frequency = 4.

basisnumber<optional>

Optional. The type of day count basis to use. The default is 0.

See
Returns:

The accrued interest.

Type: 
number
Example
rosettajs.Financial.accrInt('2/2/2012', '12/4/2013', '3/30/2012', 0.1, 1000, 4, 1); // Returns 15.57377

(inner) accrIntM(issue, settlement, rate, par, basis)

Returns the accrued interest for a security that pays interest at maturity.

Category: Financial

Parameters:
NameTypeDescription
issue*

The security's issue date.

settlement*

The security's maturity date.

rate*

The security's annual coupon rate.

par*

The security's par value. If you omit par, ACCRINTM uses $1,000.

basis*

Optional. The type of day count basis to use.

To Do
  • this needs to be implemented.
Returns:

(TBD)

(inner) amorDegrc(cost, date_purchased, first_period, salvage, period, rate, basis)

Returns the depreciation for each accounting period by using a depreciation coefficient.

Category: Financial

Parameters:
NameTypeDescription
cost*

The cost of the asset.

date_purchased*

The date of the purchase of the asset.

first_period*

The date of the end of the first period.

salvage*

The salvage value at the end of the life of the asset.

period*

The period.

rate*

The rate of depreciation.

basis*

Optional. The year basis to be used.

To Do
  • this needs to be implemented.
Returns:

(TBD)

(inner) amorLinc(cost, date_purchased, first_period, salvage, period, rate, basis)

Returns the depreciation for each accounting period.

Category: Financial

Parameters:
NameTypeDescription
cost*

The cost of the asset.

date_purchased*

The date of the purchase of the asset.

first_period*

The date of the end of the first period.

salvage*

The salvage value at the end of the life of the asset.

period*

The period.

rate*

The rate of depreciation.

basis*

Optional. The year basis to be used.

To Do
  • this needs to be implemented.
Returns:

(TBD)

(inner) coupDayBS(settlement, maturity, frequency, basis)

Returns the number of days from the beginning of the coupon period to the settlement date.

Category: Financial

Parameters:
NameTypeDescription
settlement*

The security's settlement date. The security settlement date is the date after the issue date when the security is traded to the buyer.

maturity*

The security's maturity date. The maturity date is the date when the security expires.

frequency*

The number of coupon payments per year. For annual payments, frequency = 1; for semiannual, frequency = 2; for quarterly, frequency = 4.

basis*

Optional. The type of day count basis to use.

To Do
  • this needs to be implemented.
Returns:

(TBD)

(inner) coupDays(settlement, maturity, frequency, basisopt) → {number}

Returns the number of days in the coupon period that contains the settlement date.

Parameters:
NameTypeAttributesDescription
settlementstring | number | Date

The security's settlement date. The security settlement date is the date after the issue date when the security is traded to the buyer.

maturitystring | number | Date

The security's maturity date. The maturity date is the date when the security expires.

frequencynumber

The number of coupon payments per year. For annual payments, frequency = 1; for semiannual, frequency = 2; for quarterly, frequency = 4.

basisnumber<optional>

Optional. The type of day count basis to use. Default is 0.

See
Returns:

The number of days in the coupon period containing the settlement date

Type: 
number
Example
rosettajs.Financial.coupDays("01/25/2021","11/15/2021", 2, 1); // Returns 181

(inner) coupDaySnc(settlement, maturity, frequency, basis)

Returns the number of days from the settlement date to the next coupon date.

Category: Financial

Parameters:
NameTypeDescription
settlement*

The security's settlement date. The security settlement date is the date after the issue date when the security is traded to the buyer.

maturity*

The security's maturity date. The maturity date is the date when the security expires.

frequency*

The number of coupon payments per year. For annual payments, frequency = 1; for semiannual, frequency = 2; for quarterly, frequency = 4.

basis*

Optional. The type of day count basis to use.

To Do
  • this needs to be implemented.
Returns:

(TBD)

(inner) coupNCD(settlement, maturity, frequency, basis)

Returns the next coupon date after the settlement date.

Category: Financial

Parameters:
NameTypeDescription
settlement*

The security's settlement date. The security settlement date is the date after the issue date when the security is traded to the buyer.

maturity*

The security's maturity date. The maturity date is the date when the security expires.

frequency*

The number of coupon payments per year. For annual payments, frequency = 1; for semiannual, frequency = 2; for quarterly, frequency = 4.

basis*

Optional. The type of day count basis to use.

To Do
  • this needs to be implemented.
Returns:

(TBD)

(inner) coupNum(settlement, maturity, frequency, basis)

Returns the number of coupons payable between the settlement date and maturity date.

Category: Financial

Parameters:
NameTypeDescription
settlement*

The security's settlement date. The security settlement date is the date after the issue date when the security is traded to the buyer.

maturity*

The security's maturity date. The maturity date is the date when the security expires.

frequency*

The number of coupon payments per year. For annual payments, frequency = 1; for semiannual, frequency = 2; for quarterly, frequency = 4.

basis*

Optional. The type of day count basis to use.

To Do
  • this needs to be implemented
Returns:

(TBD)

(inner) coupPCD(settlement, maturity, frequency, basis)

Returns the previous coupon date before the settlement date.

Category: Financial

Parameters:
NameTypeDescription
settlement*

The security's settlement date. The security settlement date is the date after the issue date when the security is traded to the buyer.

maturity*

The security's maturity date. The maturity date is the date when the security expires.

frequency*

The number of coupon payments per year. For annual payments, frequency = 1; for semiannual, frequency = 2; for quarterly, frequency = 4.

basis*

Optional. The type of day count basis to use.

To Do
  • this needs to be implemented
Returns:

(TBD)

(inner) cumIPmt(intrate, numper, pvalue, start_period, end_period, type) → {number}

Returns the cumulative interest paid between two periods.

Category: Financial

Parameters:
NameTypeDescription
intratenumber

The interest rate.

numpernumber

The total number of payment periods.

pvaluenumber

The present value.

start_periodnumber

The first period in the calculation. Payment periods are numbered beginning with 1.

end_periodnumber

The last period in the calculation.

typenumber

The timing of the payment.

See
Returns:

the cumulative interest paid between two periods or an error if the arguments are incorrect.

Type: 
number

(inner) cumPrinc(intrate, numper, pvalue, start_period, end_period, type) → {number}

Returns the cumulative principal paid on a loan between two periods.

Category: Financial

Parameters:
NameTypeDescription
intratenumber

The interest rate.

numpernumber

The total number of payment periods.

pvaluenumber

The present value.

start_periodnumber

The first period in the calculation. Payment periods are numbered beginning with 1.

end_periodnumber

The last period in the calculation.

typenumber

The timing of the payment.

See
Returns:

returns an error if input is wrong, otherwise returns cumulative principle as a number

Type: 
number

(inner) db(initcost, salvageval, uselife, depperiod, monthsopt) → {number}

Returns the depreciation of an asset for a specified period by using the fixed-declining balance method.

Category: Financial

Parameters:
NameTypeAttributesDefaultDescription
initcostnumber

The initial cost of the asset.

salvagevalnumber

The value at the end of the depreciation (sometimes called the salvage value of the asset).

uselifenumber

The number of periods over which the asset is being depreciated (sometimes called the useful life of the asset).

depperiodnumber

The period for which you want to calculate the depreciation. Period must use the same units as life.

monthsnumber<optional>
12

Optional. The number of months in the first year. If month is omitted, it is assumed to be 12.

See
Returns:

returns the depreciation as a number or an error if the arguments are incorrect.

Type: 
number

(inner) ddb(initcost, salvageval, uselife, depperiod, decfactoropt) → {number}

Returns the depreciation of an asset for a specified period by using the double-declining balance method or some other method that you specify.

Category: Financial

Parameters:
NameTypeAttributesDescription
initcostnumber

The initial cost of the asset.

salvagevalnumber

The value at the end of the depreciation (sometimes called the salvage value of the asset). This value can be 0.

uselifenumber

The number of periods over which the asset is being depreciated (sometimes called the useful life of the asset).

depperiodnumber

The period for which you want to calculate the depreciation. Period must use the same units as life.

decfactornumber<optional>

Optional. The rate at which the balance declines. If factor is omitted, it is assumed to be 2 (the double-declining balance method).

See
Returns:

the depreciation of an asset for a specified period using fixed double declining balance or an error if the arguments are not formatted properly.

Type: 
number

(inner) disc(settlement, maturity, pr, redemption, basisopt) → {number}

Returns the discount rate for a security.

Parameters:
NameTypeAttributesDescription
settlementstring | number | Date

The security's settlement date. The security settlement date is the date after the issue date when the security is traded to the buyer.

maturitystring | number | Date

The security's maturity date. The maturity date is the date when the security expires.

prnumber

The security's price per $100 face value.

redemptionnumber

The security's redemption value per $100 face value.

basisnumber<optional>

Optional. The type of day count basis to use. Default is 0.

See
Returns:

The discount rate of the security.

Type: 
number
Example
rosettajs.Financial.disc("01/04/2023", "12/28/2023", 95.6145, 100, 2); // returns 0.0441

(inner) dollarDe(fractional_dollar, fraction) → {number}

Converts a dollar price, expressed as a fraction, into a dollar price, expressed as a decimal number.

Category: Financial

Parameters:
NameTypeDescription
fractional_dollarnumber

A number expressed as an integer part and a fraction part, separated by a decimal symbol.

fractionnumber

The integer to use in the denominator of the fraction.

See
Returns:

a decimal number that results from converting a dollar price, expressed as a fraction, into a dollar price, expressed as a decimal number. Or an error if the arguments are not formatted properly.

Type: 
number

(inner) dollarFr(decimal_dollar, fraction) → {number}

Converts a dollar price, expressed as a decimal number, into a dollar price, expressed as a fraction.

Category: Financial

Parameters:
NameTypeDescription
decimal_dollarnumber

A decimal number.

fractionnumber

The integer to use in the denominator of a fraction.

See
Returns:

a fraction that results from converting dollar price, expressed as a decimal number, into a dollar price, expressed as a fraction. Or an error if he arguments arent formatted properly.

Type: 
number

(inner) duration(settlement, maturity, coupon, yld, frequency, basis)

Returns the annual duration of a security with periodic interest payments.

Category: Financial

Parameters:
NameTypeDescription
settlement*

The security's settlement date. The security settlement date is the date after the issue date when the security is traded to the buyer.

maturity*

The security's maturity date. The maturity date is the date when the security expires.

coupon*

The security's annual coupon rate.

yld*

The security's annual yield.

frequency*

The number of coupon payments per year. For annual payments, frequency = 1; for semiannual, frequency = 2; for quarterly, frequency = 4.

basis*

Optional. The type of day count basis to use.

To Do
  • this needs to be implemented
Returns:

(TBD)

(inner) effect(nominal_intrate, nperyr) → {number}

Returns the effective annual interest rate.

Category: Financial

Parameters:
NameTypeDescription
nominal_intratenumber

The nominal interest rate.

nperyrnumber

The number of compounding periods per year.

See
Returns:

effective annual interest rate or an error if the arguments are not formated properly.

Type: 
number

(inner) fv(intrate, numper, pmt, pvopt, typeopt) → {number}

Returns the future value of an investment.

Category: Financial

Parameters:
NameTypeAttributesDefaultDescription
intratenumber

The interest rate per period.

numpernumber

The total number of payment periods in an annuity.

pmtnumber

The payment made each period; it cannot change over the life of the annuity. Typically, pmt contains principal and interest but no other fees or taxes. If pmt is omitted, you must include the pv argument.

pvnumber<optional>
0

Optional. The present value, or the lump-sum amount that a series of future payments is worth right now. If pv is omitted, it is assumed to be 0 (zero), and you must include the pmt argument.

typenumber<optional>
0

Optional. The number 0 or 1 and indicates when payments are due. If type is omitted, it is assumed to be 0.

See
Returns:

the future value of an investment or an error if the arguments are not formatted properly.

Type: 
number

(inner) fvSchedule(principal, schedule) → {number}

Returns the future value of an initial principal after applying a series of compound interest rates.

Category: Financial

Parameters:
NameTypeDescription
principalnumber

The present value.

schedulenumber

An array of interest rates to apply.

See
Returns:

the future value of an initial principal after applying a series of compound interest rates or an error if arguments are formatted improperly.

Type: 
number

(inner) intRate(settlement, maturity, investment, redemption, basis)

Returns the interest rate for a fully invested security.

Category: Financial

Parameters:
NameTypeDescription
settlement*

The security's settlement date. The security settlement date is the date after the issue date when the security is traded to the buyer.

maturity*

The security's maturity date. The maturity date is the date when the security expires.

investment*

The amount invested in the security.

redemption*

The amount to be received at maturity.

basis*

Optional. The type of day count basis to use.

To Do
  • this needs to be implemented.
Returns:

(TBD)

(inner) iPmt(intrate, period, numper, pvalue, fvalueopt, typeopt) → {number}

Returns the interest payment for an investment for a given period.

Category: Financial

Parameters:
NameTypeAttributesDefaultDescription
intratenumber

The interest rate per period.

periodnumber

The period for which you want to find the interest and must be in the range 1 to nper.

numpernumber

The total number of payment periods in an annuity.

pvaluenumber

The present value, or the lump-sum amount that a series of future payments is worth right now.

fvaluenumber<optional>
0

Optional. The future value, or a cash balance you want to attain after the last payment is made. If fv is omitted, it is assumed to be 0 (the future value of a loan, for example, is 0).

typenumber<optional>
0

Optional. The number 0 or 1 and indicates when payments are due. If type is omitted, it is assumed to be 0.

See
Returns:

the interest payment for an investment for a given period or an error if the arguments are not formatted properly.

Type: 
number

(inner) irr(values, guessopt) → {number}

Returns the internal rate of return for a series of cash flows.

Category: Financial

Parameters:
NameTypeAttributesDefaultDescription
valuesArray

An array or a reference to values that contain numbers for which you want to calculate the internal rate of return.

  • Values must contain at least one positive value and one negative value to calculate the internal rate of return.
  • IRR uses the order of values to interpret the order of cash flows. Be sure to enter your payment and income values in the sequence you want.
  • If an array or reference argument contains text, logical values, or empty values, those values are ignored.
guessnumber<optional>
0.1

Optional. A number that you guess is close to the result of IRR.

  • Microsoft Excel uses an iterative technique for calculating IRR. Starting with guess, IRR cycles through the calculation until the result is accurate within 0.00001 percent. If IRR can't find a result that works after 20 tries, the #NUM! error value is returned.
  • In most cases you do not need to provide guess for the IRR calculation. If guess is omitted, it is assumed to be 0.1 (10 percent).
  • If IRR gives the #NUM! error value, or if the result is not close to what you expected, try again with a different value for guess.
See
Returns:

the internal rate of return for a series of cash flows or an error if the arguments are incorrect.

Type: 
number

(inner) isPmt(intrate, period, numper, pvalue) → {number}

Calculates the interest paid during a specific period of an investment.

Category: Financial

Parameters:
NameTypeDescription
intratenumber

The interest rate for the investment.

periodnumber

The period for which you want to find the interest, and must be between 1 and Nper.

numpernumber

The total number of payment periods for the investment.

pvaluenumber

The present value of the investment. For a loan, Pv is the loan amount.

See
Returns:

the interest paid during a specific period of an investment or an error if the arguments are incorrect.

Type: 
number

(inner) mDuration(settlement, maturity, coupon, yld, frequency, basis)

Returns the Macauley modified duration for a security with an assumed par value of $100.

Category: Financial

Parameters:
NameTypeDescription
settlement*

The security's settlement date. The security settlement date is the date after the issue date when the security is traded to the buyer.

maturity*

The security's maturity date. The maturity date is the date when the security expires.

coupon*

The security's annual coupon rate.

yld*

The security's annual yield.

frequency*

The number of coupon payments per year. For annual payments, frequency = 1; for semiannual, frequency = 2; for quarterly, frequency = 4.

basis*

Optional. The type of day count basis to use.

To Do
  • this needs to be implemented.
Returns:

(TBD)

(inner) mirr(values, finance_intrate, reinvest_intrate) → {number}

Returns the internal rate of return where positive and negative cash flows are financed at different rates.

Category: Financial

Parameters:
NameTypeDescription
valuesArray

An array or a reference to values that contain numbers. These numbers represent a series of payments (negative values) and income (positive values) occurring at regular periods.

  • Values must contain at least one positive value and one negative value to calculate the modified internal rate of return. Otherwise, MIRR returns the #DIV/0! error value.
  • If an array or reference argument contains text, logical values, or empty values, those values are ignored; however, values with the value zero are included.
finance_intratenumber

The interest rate you pay on the money used in the cash flows.

reinvest_intratenumber

The interest rate you receive on the cash flows as you reinvest them.

See
Returns:

the internal rate of return where positive and negative cash flows are financed at different rates or an error when the arguments arent formatted properly.

Type: 
number

(inner) nominal(effect_intrate, numpery) → {number}

Returns the annual nominal interest rate.

Category: Financial

Parameters:
NameTypeDescription
effect_intratenumber

The effective interest rate.

numperynumber

The number of compounding periods per year.

See
Returns:

the annual nominal interest rate or an error if the arguments arent formatted properly

Type: 
number

(inner) nPer(intrate, payment, pvalue, fvalueopt, typeopt) → {number}

Returns the number of periods for an investment.

Category: Financial

Parameters:
NameTypeAttributesDefaultDescription
intratenumber

The interest rate per period.

paymentnumber

The payment made each period; it cannot change over the life of the annuity. Typically, pmt contains principal and interest but no other fees or taxes.

pvaluenumber

The present value, or the lump-sum amount that a series of future payments is worth right now.

fvaluenumber<optional>
0

Optional. The future value, or a cash balance you want to attain after the last payment is made. If fv is omitted, it is assumed to be 0 (the future value of a loan, for example, is 0).

typenumber<optional>
0

Optional. The number 0 or 1 and indicates when payments are due.

See
Returns:

the number of periods for an invesment or an error if the arguments are not formatted properly.

Type: 
number

(inner) npv(drate, …values) → {number}

Returns the net present value of an investment based on a series of periodic cash flows and a discount rate.

Category: Financial

Parameters:
NameTypeAttributesDescription
dratenumber

The rate of discount over the length of one period.

valuesArray.<number><repeatable>

value1, value2, ... Value1 is required, subsequent values are optional. 1 to 254 arguments representing the payments and income.

  • value1, value2, ... must be equally spaced in time and occur at the end of each period.
  • NPV uses the order of value1, value2, ... to interpret the order of cash flows. Be sure to enter your payment and income values in the correct sequence.
  • Arguments that are empty values, logical values, or text representations of numbers, error values, or text that cannot be translated into numbers are ignored.
  • If an argument is an array or reference, only numbers in that array or reference are counted. Empty values, logical values, text, or error values in the array or reference are ignored.
See
Returns:

net present value as a number or an error if the arguments dont match requirements.

Type: 
number

(inner) oddFPrice(settlement, maturity, issue, first_coupon, rate, yld, redemption, frequency, basis)

Returns the price per $100 face value of a security with an odd first period.

Category: Financial

Parameters:
NameTypeDescription
settlement*

The security's settlement date. The security settlement date is the date after the issue date when the security is traded to the buyer.

maturity*

The security's maturity date. The maturity date is the date when the security expires.

issue*

The security's issue date.

first_coupon*

The security's first coupon date.

rate*

The security's interest rate.

yld*

The security's annual yield.

redemption*

The security's redemption value per $100 face value.

frequency*

The number of coupon payments per year. For annual payments, frequency = 1; for semiannual, frequency = 2; for quarterly, frequency = 4.

basis*

Optional. The type of day count basis to use.

To Do
  • this needs to be implemented.
Returns:

(TBD)

(inner) oddFYield(settlement, maturity, issue, first_coupon, rate, pr, redemption, frequency, basis)

Returns the yield of a security with an odd first period.

Category: Financial

Parameters:
NameTypeDescription
settlement*

The security's settlement date. The security settlement date is the date after the issue date when the security is traded to the buyer.

maturity*

The security's maturity date. The maturity date is the date when the security expires.

issue*

The security's issue date.

first_coupon*

The security's first coupon date.

rate*

The security's interest rate.

pr*

The security's price.

redemption*

The security's redemption value per $100 face value.

frequency*

The number of coupon payments per year. For annual payments, frequency = 1; for semiannual, frequency = 2; for quarterly, frequency = 4.

basis*

Optional. The type of day count basis to use.

To Do
  • this needs to be implemented.
Returns:

(TBD)

(inner) oddLPrice(settlement, maturity, last_interest, rate, yld, redemption, frequency, basis)

Returns the price per $100 face value of a security with an odd last period.

Category: Financial

Parameters:
NameTypeDescription
settlement*

The security's settlement date. The security settlement date is the date after the issue date when the security is traded to the buyer.

maturity*

The security's maturity date. The maturity date is the date when the security expires.

last_interest*

The security's last coupon date.

rate*

The security's interest rate.

yld*

The security's annual yield.

redemption*

The security's redemption value per $100 face value.

frequency*

The number of coupon payments per year. For annual payments, frequency = 1; for semiannual, frequency = 2; for quarterly, frequency = 4.

basis*

Optional. The type of day count basis to use.

To Do
  • this needs to be implemented.
Returns:

(TBD)

(inner) oddLYield(settlement, maturity, last_interest, rate, pr, redemption, frequency, basis)

Returns the yield of a security with an odd last period.

Category: Financial

Parameters:
NameTypeDescription
settlement*

The security's settlement date. The security settlement date is the date after the issue date when the security is traded to the buyer.

maturity*

The security's maturity date. The maturity date is the date when the security expires.

last_interest*

The security's last coupon date.

rate*

The security's interest rate

pr*

The security's price.

redemption*

The security's redemption value per $100 face value.

frequency*

The number of coupon payments per year. For annual payments, frequency = 1; for semiannual, frequency = 2; for quarterly, frequency = 4.

basis*

Optional. The type of day count basis to use.

To Do
  • this needs to be implemented.
Returns:

(TBD)

(inner) pDuration(intrate, pvalue, fvalue) → {number}

Returns the number of periods required by an investment to reach a specified value.

Category: Financial

Parameters:
NameTypeDescription
intratenumber

Rate is the interest rate per period.

pvaluenumber

Pv is the present value of the investment.

fvaluenumber

Fv is the desired future value of the investment.

See
Returns:

the number of periods required as a number or an error if arguments are not formatted properly.

Type: 
number

(inner) pmt(intrate, numper, pvalue, fvalueopt, typeopt) → {number}

Returns the periodic payment for an annuity.

Category: Financial

Parameters:
NameTypeAttributesDefaultDescription
intratenumber

The interest rate for the loan.

numpernumber

The total number of payments for the loan.

pvaluenumber

The present value, or the total amount that a series of future payments is worth now; also known as the principal.

fvaluenumber<optional>
0

Optional. The future value, or a cash balance you want to attain after the last payment is made. If fv is omitted, it is assumed to be 0 (zero), that is, the future value of a loan is 0.

typenumber<optional>
0

Optional. The number 0 (zero) or 1 and indicates when payments are due.

See
Returns:

the periodic payment for an annuity as a number or error if the arguments are not formatted properly.

Type: 
number

(inner) pPmt(intrate, period, numper, pvalue, fvalueopt, typeopt) → {number}

Returns the payment on the principal for an investment for a given period.

Category: Financial

Parameters:
NameTypeAttributesDefaultDescription
intratenumber

The interest rate per period.

periodnumber

Specifies the period and must be in the range 1 to nper.

numpernumber

The total number of payment periods in an annuity.

pvaluenumber

The present value — the total amount that a series of future payments is worth now.

fvaluenumber<optional>
0

Optional. The future value, or a cash balance you want to attain after the last payment is made. If fv is omitted, it is assumed to be 0 (zero), that is, the future value of a loan is 0.

typenumber<optional>
0

Optional. The number 0 or 1 and indicates when payments are due.

See
Returns:

principal payment for investment over a specific period as a number, or an error if the arguments are not formated properly.

Type: 
number

(inner) price(settlement, maturity, rate, yld, redemption, frequency, basis)

Returns the price per $100 face value of a security that pays periodic interest.

Category: Financial

Parameters:
NameTypeDescription
settlement*

The security's settlement date. The security settlement date is the date after the issue date when the security is traded to the buyer.

maturity*

The security's maturity date. The maturity date is the date when the security expires.

rate*

The security's annual coupon rate.

yld*

The security's annual yield.

redemption*

The security's redemption value per $100 face value.

frequency*

The number of coupon payments per year. For annual payments, frequency = 1; for semiannual, frequency = 2; for quarterly, frequency = 4.

basis*

Optional. The type of day count basis to use.

To Do
  • this needs to be implemented.
Returns:

(TBD)

(inner) priceDisc(settlement, maturity, discount, redemption, basis) → {number}

Returns the price per $100 face value of a discounted security.

Parameters:
NameTypeDescription
settlementstring | number | Date

The security's settlement date. The security settlement date is the date after the issue date when the security is traded to the buyer.

maturitystring | number | Date

The security's maturity date. The maturity date is the date when the security expires.

discountnumber

The security's discount rate.

redemptionnumber

The security's redemption value per $100 face value.

basisnumber

Optional. The type of day count basis to use. The default is 0.

See
Returns:

Price per $100 face value of the discounted security.

Type: 
number
Example
rosettajs.Financial.priceDisc("2/16/2020","3/1/2020",0.0524,100,2); // Returns 99.80

(inner) priceMat(settlement, maturity, issue, rate, yld, basis)

Returns the price per $100 face value of a security that pays interest at maturity.

Category: Financial

Parameters:
NameTypeDescription
settlement*

The security's settlement date. The security settlement date is the date after the issue date when the security is traded to the buyer.

maturity*

The security's maturity date. The maturity date is the date when the security expires.

issue*

The security's issue date, expressed as a serial date number.

rate*

The security's interest rate at date of issue.

yld*

The security's annual yield.

basis*

Optional. The type of day count basis to use.

To Do
  • this needs to be implemented.
Returns:

(TBD)

(inner) pv(intrate, periods, payment, fvalue, typeopt) → {number}

Returns the present value of an investment.

Category: Financial

Parameters:
NameTypeAttributesDefaultDescription
intratenumber

The interest rate per period. For example, if you obtain an automobile loan at a 10 percent annual interest rate and make monthly payments, your interest rate per month is 10%/12, or 0.83%. You would enter 10%/12, or 0.83%, or 0.0083, into the formula as the rate.

periodsnumber

The total number of payment periods in an annuity. For example, if you get a four-year car loan and make monthly payments, your loan has 4*12 (or 48) periods. You would enter 48 into the formula for nper.

paymentnumber

The payment made each period and cannot change over the life of the annuity. Typically, pmt includes principal and interest but no other fees or taxes. For example, the monthly payments on a $10,000, four-year car loan at 12 percent are $263.33. You would enter -263.33 into the formula as the pmt. If pmt is omitted, you must include the fv argument.

fvaluenumber0

Optional. The future value, or a cash balance you want to attain after the last payment is made. If fv is omitted, it is assumed to be 0 (the future value of a loan, for example, is 0). For example, if you want to save $50,000 to pay for a special project in 18 years, then $50,000 is the future value. You could then make a conservative guess at an interest rate and determine how much you must save each month. If fv is omitted, you must include the pmt argument.

typenumber<optional>
0

Optional. The number 0 or 1 and indicates when payments are due.

See
Returns:

present value of an investment or an error if arguments are not formatted properly.

Type: 
number

(inner) rate(periods, payment, pvalue, fvalueopt, typeopt, guessopt) → {number}

Returns the interest rate per period of an annuity.

Category: Financial

Parameters:
NameTypeAttributesDefaultDescription
periodsnumber

The total number of payment periods in an annuity.

paymentnumber

The payment made each period and cannot change over the life of the annuity. Typically, pmt includes principal and interest but no other fees or taxes. If pmt is omitted, you must include the fv argument.

pvaluenumber

The present value — the total amount that a series of future payments is worth now.

fvaluenumber<optional>
0

Optional. The future value, or a cash balance you want to attain after the last payment is made. If fv is omitted, it is assumed to be 0 (the future value of a loan, for example, is 0). If fv is omitted, you must include the pmt argument.

typenumber<optional>

Optional. The number 0 or 1 and indicates when payments are due.

guessnumber<optional>

Optional. Your guess for what the rate will be. If you omit guess, it is assumed to be 10 percent. If RATE does not converge, try different values for guess. RATE usually converges if guess is between 0 and 1.

  • If you omit guess, it is assumed to be 10 percent.
  • If RATE does not converge, try different values for guess. RATE usually converges if guess is between 0 and 1.
See
Returns:

the interest rate per period of an annuity or an error if the arguments arent formatted properly.

Type: 
number

(inner) received(settlement, maturity, investment, discount, basis)

Returns the amount received at maturity for a fully invested security.

Category: Financial

Parameters:
NameTypeDescription
settlement*

The security's settlement date. The security settlement date is the date after the issue date when the security is traded to the buyer.

maturity*

The security's maturity date. The maturity date is the date when the security expires.

investment*

The amount invested in the security.

discount*

The security's discount rate.

basis*

Optional. The type of day count basis to use.

To Do
  • this needs to be implemented.
Returns:

(TBD)

(inner) rri(periods, pvalue, fvalue) → {number}

Returns an equivalent interest rate for the growth of an investment.

Category: Financial

Parameters:
NameTypeDescription
periodsnumber

The number of periods for the investment.

pvaluenumber

The present value of the investment.

fvaluenumber

The future value of the investment.

See
Returns:

an equivalent interestrate for growth of an investment or an error if arguments are not formatted properly.

Type: 
number

(inner) sln(initcost, salvageval, uselife) → {number}

Returns the straight-line depreciation of an asset for one period.

Category: Financial

Parameters:
NameTypeDescription
initcostnumber

The initial cost of the asset.

salvagevalnumber

The value at the end of the depreciation (sometimes called the salvage value of the asset).

uselifenumber

The number of periods over which the asset is depreciated (sometimes called the useful life of the asset).

See
Returns:

returns the straightline depreciation of an asset for 1 period or error if arguments are not formatted properly.

Type: 
number

(inner) syd(initcost, salvageval, uselife, periods) → {number}

Returns the sum-of-years' digits depreciation of an asset for a specified period.

Category: Financial

Parameters:
NameTypeDescription
initcostnumber

The initial cost of the asset.

salvagevalnumber

The value at the end of the depreciation (sometimes called the salvage value of the asset).

uselifenumber

The number of periods over which the asset is depreciated (sometimes called the useful life of the asset).

periodsnumber

The period and must use the same units as life.

See
Returns:

the sum-of-years' digits depreciation of an asset for a specified period or an error if arguments are not formatted properly.

Type: 
number

(inner) tbillEq(settlement_date, maturity_date, discount_rate) → {number}

Returns the bond-equivalent yield for a Treasury bill.

Category: Financial

Parameters:
NameTypeDescription
settlement_dateDate | number | string

The Treasury bill's settlement date. The security settlement date is the date after the issue date when the Treasury bill is traded to the buyer.

maturity_dateDate | number | string

The Treasury bill's maturity date. The maturity date is the date when the Treasury bill expires.

discount_ratenumber

The Treasury bill's discount rate.

See
Returns:

Returns the bond-equivalent yield for a Treasury bill or an error if the arguments are not formatted properly.

Type: 
number

(inner) tbillPrice(settlement_date, maturity_date, discount_rate) → {number}

Returns the price per $100 face value for a Treasury bill.

Category: Financial

Parameters:
NameTypeDescription
settlement_dateDate | number | string

The Treasury bill's settlement date. The security settlement date is the date after the issue date when the Treasury bill is traded to the buyer.

maturity_dateDate | number | string

The Treasury bill's maturity date. The maturity date is the date when the Treasury bill expires.

discount_ratenumber

The Treasury bill's discount rate.

See
Returns:

returns the price per $100 facec value for a treasury bill or an error if the arguments arent formatted properly.

Type: 
number

(inner) tbillYield(settlement_date, maturity_date, price) → {number}

Returns the yield for a Treasury bill.

Category: Financial

Parameters:
NameTypeDescription
settlement_dateDate | number | string

The Treasury bill's settlement date. The security settlement date is the date after the issue date when the Treasury bill is traded to the buyer.

maturity_dateDate | number | string

The Treasury bill's maturity date. The maturity date is the date when the Treasury bill expires.

pricenumber

The Treasury bill's price per $100 face value.

See
Returns:

the yield for a treasury bill or an error if the arguments are not formated properly

Type: 
number

(inner) vdb(cost, salvage, life, start_period, end_period, factor, no_switch)

Returns the depreciation of an asset for a specified or partial period by using a declining balance method.

Category: Financial

Parameters:
NameTypeDescription
cost*

The initial cost of the asset.

salvage*

The value at the end of the depreciation (sometimes called the salvage value of the asset). This value can be 0.

life*

The number of periods over which the asset is depreciated (sometimes called the useful life of the asset).

start_period*

The starting period for which you want to calculate the depreciation. Start_period must use the same units as life.

end_period*

The ending period for which you want to calculate the depreciation. End_period must use the same units as life.

factor*

Optional. The rate at which the balance declines. If factor is omitted, it is assumed to be 2 (the double-declining balance method). Change factor if you do not want to use the double-declining balance method. For a description of the double-declining balance method, see DDB.

no_switch*

Optional. A logical value specifying whether to switch to straight-line depreciation when depreciation is greater than the declining balance calculation.

  • If no_switch is TRUE, Microsoft Excel does not switch to straight-line depreciation even when the depreciation is greater than the declining balance calculation.
  • If no_switch is FALSE or omitted, Excel switches to straight-line depreciation when depreciation is greater than the declining balance calculation.
Returns:

(TBD)

(inner) xirr(cash_flows, paydates, guessopt) → {number}

Returns the internal rate of return for a schedule of cash flows that is not necessarily periodic.

Category: Financial

Parameters:
NameTypeAttributesDefaultDescription
cash_flowsArray.<number>

A series of cash flows that corresponds to a schedule of payments in dates. The first payment is optional and corresponds to a cost or payment that occurs at the beginning of the investment. If the first value is a cost or payment, it must be a negative value. All succeeding payments are discounted based on a 365-day year. The series of values must contain at least one positive and one negative value.

paydatesArray.<Date> | Array.<number> | Array.<string>

A schedule of payment dates that corresponds to the cash flow payments. Dates may occur in any order. Dates should be entered by using the DATE function, or as results of other formulas or functions. For example, use DATE(2008,5,23) for the 23rd day of May, 2008. Problems can occur if dates are entered as text. .

guessnumber<optional>
0.1

Optional. A number that you guess is close to the result of XIRR.

See
Returns:

internal rate of return as a number or an error if the arguments are not formatted properly.

Type: 
number

(inner) xnpv(disrate, cash_flows, paydates) → {number}

Returns the net present value for a schedule of cash flows that is not necessarily periodic.

Category: Financial

Parameters:
NameTypeDescription
disratenumber

The discount rate to apply to the cash flows.

cash_flowsArray.<number>

A series of cash flows that corresponds to a schedule of payments in dates. The first payment is optional and corresponds to a cost or payment that occurs at the beginning of the investment. If the first value is a cost or payment, it must be a negative value. All succeeding payments are discounted based on a 365-day year. The series of values must contain at least one positive value and one negative value.

paydatesArray.<Date> | Array.<number> | Array.<string>

A schedule of payment dates that corresponds to the cash flow payments. The first payment date indicates the beginning of the schedule of payments. All other dates must be later than this date, but they may occur in any order.

See
Returns:

net present value for a schedule of cash flows or an error if the arguments are not formated properly.

Type: 
number

(inner) Yield(settlement, maturity, rate, pr, redemption, frequency, basis)

Returns the yield on a security that pays periodic interest.

Category: Financial

Parameters:
NameTypeDescription
settlement*

The security's settlement date. The security settlement date is the date after the issue date when the security is traded to the buyer.

maturity*

The security's maturity date. The maturity date is the date when the security expires.

rate*

The security's annual coupon rate.

pr*

The security's price per $100 face value.

redemption*

The security's redemption value per $100 face value.

frequency*

The number of coupon payments per year. For annual payments, frequency = 1; for semiannual, frequency = 2; for quarterly, frequency = 4.

basis*

Optional. The type of day count basis to use.

To Do
  • this needs to be implemented.
Returns:

(TBD)

(inner) yieldDisc(settlement, maturity, pr, redemption, basis)

Returns the annual yield for a discounted security; for example, a Treasury bill.

Category: Financial

Parameters:
NameTypeDescription
settlement*

The security's settlement date. The security settlement date is the date after the issue date when the security is traded to the buyer.

maturity*

The security's maturity date. The maturity date is the date when the security expires.

pr*

The security's price per $100 face value.

redemption*

The security's redemption value per $100 face value.

basis*

Optional. The type of day count basis to use.

To Do
  • this needs to be implemented.
Returns:

(TBD)

(inner) yieldMat(settlement, maturity, issue, rate, pr, basis)

Returns the annual yield of a security that pays interest at maturity.

Category: Financial

Parameters:
NameTypeDescription
settlement*

The security's settlement date. The security settlement date is the date after the issue date when the security is traded to the buyer.

maturity*

The security's maturity date. The maturity date is the date when the security expires.

issue*

The security's issue date, expressed as a serial date number.

rate*

The security's interest rate at date of issue.

pr*

The security's price per $100 face value.

basis*

Optional. The type of day count basis to use.

To Do
  • this needs to be implemented.
Returns:

(TBD)