Merge pull request #7 from PyFE/desc

Changes for package

Author: jaehyukchoi

pkg/DESCRIPTION

@@ -1,15 +1,21 @@
 Package: FER
-Title: Financial Engineering functions in R
-Version: 0.9
+Title: Financial Engineering (FE) functions in R
+Version: 0.91
 Authors@R: person("Jaehyuk", "Choi", email = "[email protected]", role = c("aut", "cre"))
-Description: What the package does (one paragraph).
+Description: R implementations of standard financial engineering codes;
+  vanilla option pricing models such as Black-Scholes, Bachelier, CEV, and
+  SABR.
+URL: https://github.com/PyFE/FE-R
+BugReports: https://github.com/PyFE/FE-R/issues
 Depends:
     R (>= 3.3.1)
+NeedsCompilation: no
 License: MIT + file LICENSE
 Encoding: UTF-8
 LazyData: true
 RoxygenNote: 7.1.1
 Imports: 
+    stats,
     statmod,
     devtools
 Suggests: 

pkg/NAMESPACE

@@ -6,4 +6,3 @@ export(BlackScholesImpvol)
 export(BlackScholesPrice)
 export(CevPrice)
 export(SabrHagan2002)
-import(stats)

pkg/R/bachelier_impvol.R

@@ -6,12 +6,14 @@
 #' @param texp (vector of) time to expiry
 #' @param intr interest rate
 #' @param divr dividend rate
-#' @param cpsign call/put sign. 1 for call, -1 for put.
+#' @param cp call/put sign. \code{1} for call, \code{-1} for put.
 #' @param forward forward price. If given, \code{forward} overrides \code{spot}
 #' @param df discount factor. If given, \code{df} overrides \code{intr}
 #' @return Bachelier implied volatility
 #'
-#' @references Choi, J., Kim, K., & Kwak, M. (2009). Numerical Approximation of the Implied Volatility Under Arithmetic Brownian Motion. Applied Mathematical Finance, 16(3), 261–268.
+#' @references Choi, J., Kim, K., & Kwak, M. (2009).
+#'   Numerical Approximation of the Implied Volatility Under Arithmetic Brownian
+#'   Motion. Applied Mathematical Finance, 16(3), 261-268.
 #'   \url{https://doi.org/10.1080/13504860802583436}
 #'
 #' @export
@@ -23,18 +25,17 @@
 #' sigma <- 20
 #' intr <- 0.05
 #' price <- 20
-#' vol <- FER::BachelierImpvol(price, strike, spot, texp, intr=intr)
+#' FER::BachelierImpvol(price, strike, spot, texp, intr=intr)
 #'
 #' @seealso \code{\link{BachelierPrice}}
 #'
 BachelierImpvol <- function(
-  price, strike = forward, spot, texp = 1,
-  intr = 0, divr = 0, cpsign = 1,
-  forward = spot*exp(-divr*texp)/df,
-  df = exp(-intr*texp)
+  price, strike=forward, spot, texp=1,
+  intr=0, divr=0, cp=1L,
+  forward=spot*exp(-divr*texp)/df, df=exp(-intr*texp)
 ){
 
-  price.straddle = 2*price/df - cpsign*(forward - strike)
+  price.straddle <- 2*price/df - cp*(forward - strike)
 
   # vectors a and b used for rational Chebyshev approximation
   a <- c(3.994961687345134e-1,

pkg/R/bachelier_price.R

@@ -6,34 +6,37 @@
 #' @param sigma (vector of) volatility
 #' @param intr interest rate
 #' @param divr dividend rate
-#' @param cpsign call/put sign. 1 for call, -1 for put.
+#' @param cp call/put sign. \code{1} for call, \code{-1} for put.
 #' @param forward forward price. If given, \code{forward} overrides \code{spot}
 #' @param df discount factor. If given, \code{df} overrides \code{intr}
 #' @return option price
-#' @import stats
 #' @export
 #'
+#' @references Choi, J., Kim, K., & Kwak, M. (2009).
+#'   Numerical Approximation of the Implied Volatility Under Arithmetic Brownian
+#'   Motion. Applied Mathematical Finance, 16(3), 261-268.
+#'   \url{https://doi.org/10.1080/13504860802583436}
+#'
 #' @examples
 #' spot <- 100
 #' strike <- seq(80,125,5)
 #' texp <- 1.2
 #' sigma <- 20
 #' intr <- 0.05
-#' price <- FER::BachelierPrice(strike, spot, texp, sigma, intr=intr)
+#' FER::BachelierPrice(strike, spot, texp, sigma, intr=intr)
 #'
 #' @seealso \code{\link{BachelierImpvol}}
 #'
 BachelierPrice <- function(
-  strike = forward, spot, texp = 1, sigma,
-  intr = 0, divr = 0, cpsign=1,
-  forward = spot*exp(-divr*texp)/df,
-  df = exp(-intr*texp)
+  strike=forward, spot, texp=1, sigma,
+  intr=0, divr=0, cp=1L,
+  forward=spot*exp(-divr*texp)/df, df=exp(-intr*texp)
 ){
   stdev <- sigma*sqrt(texp)
   stdev[stdev < 1e-32] <- 1e-32
-  dn <- cpsign*(forward-strike) / stdev
+  dn <- cp*(forward-strike)/stdev
 
   #Option Price
-  price <- df*(cpsign*(forward-strike)*pnorm(dn) + stdev*dnorm(dn))
+  price <- df * (cp*(forward-strike)*stats::pnorm(dn) + stdev*stats::dnorm(dn))
   return( price )
 }

pkg/R/blackscholes_impvol.R

@@ -6,11 +6,15 @@
 #' @param texp (vector of) time to expiry
 #' @param intr interest rate
 #' @param divr dividend rate
-#' @param cpsign call/put sign. 1 for call, -1 for put.
+#' @param cp call/put sign. \code{1} for call, \code{-1} for put.
 #' @param forward forward price. If given, \code{forward} overrides \code{spot}
 #' @param df discount factor. If given, \code{df} overrides \code{intr}
 #' @return Black-Scholes implied volatility
 #'
+#' @references Giner, G., & Smyth, G. K. (2016). statmod: Probability Calculations
+#'   for the Inverse Gaussian Distribution. The R Journal, 8(1), 339-351.
+#'   \url{https://doi.org/10.32614/RJ-2016-024}
+#'
 #' @export
 #'
 #' @examples
@@ -20,17 +24,16 @@
 #' sigma <- 0.2
 #' intr <- 0.05
 #' price <- 20
-#' vol <- FER::BlackScholesImpvol(price, strike, spot, texp, intr=intr)
+#' FER::BlackScholesImpvol(price, strike, spot, texp, intr=intr)
 #'
 #' @seealso \code{\link{BlackScholesPrice}}
 #'
 BlackScholesImpvol <- function(
-  price, strike = forward, spot, texp = 1,
-  intr = 0, divr = 0, cpsign = 1,
-  forward = spot*exp(-divr*texp)/df,
-  df = exp(-intr*texp)
+  price, strike=forward, spot, texp=1,
+  intr=0, divr=0, cp=1L,
+  forward=spot*exp(-divr*texp)/df, df=exp(-intr*texp)
 ){
-  optval = (price/df - pmax(cpsign*(forward-strike), 0))/pmin(forward, strike)
+  optval <- (price/df - pmax(cp*(forward-strike), 0))/pmin(forward, strike)
 
   # we use inverse CDF of inversegaussian distribution
   mu <- 2/abs(log(strike/forward))

pkg/R/blackscholes_price.R

@@ -6,11 +6,10 @@
 #' @param sigma (vector of) volatility
 #' @param intr interest rate
 #' @param divr dividend rate
-#' @param cpsign call/put sign. 1 for call, -1 for put.
+#' @param cp call/put sign. \code{1} for call, \code{-1} for put.
 #' @param forward forward price. If given, \code{forward} overrides \code{spot}
 #' @param df discount factor. If given, \code{df} overrides \code{intr}
 #' @return option price
-#' @import stats
 #' @export
 #'
 #' @examples
@@ -19,25 +18,23 @@
 #' texp <- 1.2
 #' sigma <- 0.2
 #' intr <- 0.05
-#' price <- FER::BlackScholesPrice(strike, spot, texp, sigma, intr=intr)
+#' FER::BlackScholesPrice(strike, spot, texp, sigma, intr=intr)
 #'
 #' @seealso \code{\link{BlackScholesImpvol}}
 #'
 BlackScholesPrice <- function(
-  strike = forward, spot, texp = 1, sigma,
-  intr = 0, divr = 0, cpsign = 1,
-  forward = spot*exp(-divr*texp)/df,
-  df = exp(-intr*texp)
+  strike=forward, spot, texp=1, sigma,
+  intr=0, divr=0, cp=1L,
+  forward=spot*exp(-divr*texp)/df, df=exp(-intr*texp)
 ){
     stdev <- sigma*sqrt(texp)
 
     # a trick to get the intrinsic value for negative or zero vol
-    # also avoid NAN in case forward = strike
+    # also avoid NAN in case forward=strike
     stdev[stdev < 1e-32] <- 1e-32
 
     d1 <- log(forward/strike)/stdev + 0.5*stdev
     d2 <- d1 - stdev
-    disc.factor <- exp(-intr*texp)
-    price <- df * cpsign*(forward*pnorm(cpsign*d1) - strike*pnorm(cpsign*d2))
+    price <- df * cp*(forward*stats::pnorm(cp*d1) - strike*stats::pnorm(cp*d2))
     return( price )
 }

pkg/R/cev_price.R

@@ -1,4 +1,4 @@
-#' Constant Elasticity Of Variance (CEV) model option price
+#' Calculate the constant elasticity of variance (CEV) model option price
 #'
 #' @param strike (vector of) strike price
 #' @param spot (vector of) spot price
@@ -7,11 +7,15 @@
 #' @param beta beta
 #' @param intr interest rate
 #' @param divr dividend rate
-#' @param cpsign call/put sign. 1 for call, -1 for put.
+#' @param cp call/put sign. \code{1} for call, \code{-1} for put.
 #' @param forward forward price. If given, \code{forward} overrides \code{spot}
 #' @param df discount factor. If given, \code{df} overrides \code{intr}
 #' @return option price
 #'
+#' @references Schroder, M. (1989). Computing the constant elasticity
+#'   of variance option pricing formula. Journal of Finance,
+#'   44(1), 211-219. https://doi.org/10.1111/j.1540-6261.1989.tb02414.x
+#'
 #' @export
 #'
 #' @examples
@@ -20,24 +24,23 @@
 #' texp <- 1.2
 #' beta <- 0.5
 #' sigma <- 2
-#' price <- FER::CevPrice(strike, spot, texp, sigma, beta)
+#' FER::CevPrice(strike, spot, texp, sigma, beta)
 #'
 CevPrice <- function(
-  strike = forward, spot, texp = 1, sigma, beta=0.5,
-  intr = 0, divr = 0, cpsign = 1,
-  forward = spot*exp(-divr*texp)/df,
-  df = exp(-intr*texp)
+  strike=forward, spot, texp=1, sigma, beta=0.5,
+  intr=0, divr=0, cp=1L,
+  forward=spot*exp(-divr*texp)/df, df=exp(-intr*texp)
 ){
   betac <- 1.0 - beta
   scale <- (betac*sigma)^2*texp
-  strike_cov = strike^(2*betac) / scale # strike change of variable
-  forward_cov = forward^(2*betac) / scale # forward change of variable
+  strike_cov <- strike^(2*betac) / scale # strike change of variable
+  forward_cov <- forward^(2*betac) / scale # forward change of variable
   deg <- 1/betac  # degree of freedom
 
-  term1 <- stats::pchisq(strike_cov, df=deg+2, ncp=forward_cov, lower.tail=(cpsign<0))
-  term2 <- stats::pchisq(forward_cov, df=deg, ncp=strike_cov, lower.tail=(cpsign>0))
+  term1 <- stats::pchisq(strike_cov, df=deg+2, ncp=forward_cov, lower.tail=(cp<0))
+  term2 <- stats::pchisq(forward_cov, df=deg, ncp=strike_cov, lower.tail=(cp>0))
 
-  price <- cpsign*df*(forward*term1 - strike*term2)
+  price <- cp*df*(forward*term1 - strike*term2)
 
   return(price)
 }

pkg/R/sabr_hagan2002.R

@@ -1,20 +1,22 @@
-#' Hagan approximation for the SABR model
+#' Calculate the equivalent BS volatility (Hagan et al. 2002) for
+#'   the Stochatic-Alpha-Beta-Rho (SABR) model
 #'
 #' @param strike (vector of) strike price
 #' @param spot (vector of) spot price
 #' @param texp (vector of) time to expiry
 #' @param sigma (vector of) volatility
-#' @param vov vol-of-vol
-#' @param rho correlation
-#' @param beta beta
+#' @param vov (vector of) vol-of-vol
+#' @param rho (vector of) correlation
+#' @param beta (vector of) beta
 #' @param intr interest rate
 #' @param divr dividend rate
-#' @param cpsign call/put sign. NULL for BS vol (default), 1 for call price, -1 for put price.
+#' @param cp call/put sign. \code{NULL} for BS vol (default), \code{1} for call price, \code{-1} for put price.
 #' @param forward forward price. If given, \code{forward} overrides \code{spot}
 #' @param df discount factor. If given, \code{df} overrides \code{intr}
-#' @return BS volatility or option price based on cpsign
+#' @return BS volatility or option price based on \code{cp}
 #'
-#' @references Hagan, P. S., Kumar, D., Lesniewski, A. S., & Woodward, D. E. (2002). Managing Smile Risk. Wilmott, September, 84–108.
+#' @references Hagan, P. S., Kumar, D., Lesniewski, A. S., & Woodward, D. E. (2002).
+#'   Managing Smile Risk. Wilmott, September, 84-108.
 #'
 #' @export
 #'
@@ -26,43 +28,46 @@
 #' texp <- 10
 #' strike <- seq(0.1, 2, 0.1)
 #' FER::SabrHagan2002(strike, 1, texp, sigma, vov, rho, beta)
+#' FER::SabrHagan2002(strike, 1, texp, sigma, vov, rho, beta, cp=1)
 #'
 SabrHagan2002 <- function(
-  strike = forward, spot, texp = 1, sigma, vov=0, rho=0, beta=1,
-  intr = 0, divr = 0, cpsign = NULL,
-  forward = spot*exp(-divr*texp)/df,
-  df = exp(-intr*texp)
+  strike=forward, spot, texp=1, sigma, vov=0, rho=0, beta=1,
+  intr=0, divr=0, cp=NULL,
+  forward=spot*exp(-divr*texp)/df, df=exp(-intr*texp)
 ){
   betac <- 1 - beta
+  betac2 <- betac*betac
+  rho2 <- rho*rho
+
   powFwdStrk <- (forward*strike)^(betac/2)
   logFwdStrk <- log(forward/strike)
   logFwdStrk2 <- logFwdStrk^2
 
-  pre1 = powFwdStrk*( 1 + betac^2/24 * logFwdStrk2*(1 + betac^2/80 * logFwdStrk2) )
+  pre1 <- powFwdStrk*( 1 + betac2/24 * logFwdStrk2*(1 + betac2/80 * logFwdStrk2) )
 
-  pre2alp0 <- (2-3*rho^2)*vov^2/24
+  pre2alp0 <- (2-3*rho2)*vov^2/24
   pre2alp1 <- vov*rho*beta/4/powFwdStrk
-  pre2alp2 <- betac^2/24/powFwdStrk^2
+  pre2alp2 <- betac2/24/powFwdStrk^2
 
   pre2 <- 1 + texp*( pre2alp0 + sigma*(pre2alp1 + pre2alp2*sigma) )
 
   zz <- powFwdStrk*logFwdStrk*vov/sigma  # need to make sure sig > 0
   yy <- sqrt(1 + zz*(zz-2*rho))
 
-  rho2 <- rho*rho
-  xx_zz = 1 + (zz/2)*(rho + zz*((rho2-1/3) + (5*rho2-3)/4*rho*zz))
+  xx_zz <- 1 + (zz/2)*(rho + zz*((rho2-1/3) + (5*rho2-3)/4*rho*zz))
 
   I <- (zz >= 1e-5)
-  xx_zz[I] = log( (yy[I] + (zz[I]-rho))/(1-rho) ) / zz[I]
+  xx_zz[I] <- log( (yy[I] + (zz[I]-rho))/(1-rho) ) / zz[I]
   I <- (zz <= -1e-5)
-  xx_zz[I] = log( (1+rho)/(yy[I] - (zz[I]-rho)) ) / zz[I]
+  xx_zz[I] <- log( (1+rho)/(yy[I] - (zz[I]-rho)) ) / zz[I]
 
-  vol.bs = sigma*pre2/(pre1*xx_zz) # blks vol
+  vol.bs <- sigma*pre2/(pre1*xx_zz) # BS volatility
 
-  if(is.null(cpsign)){
+  if(is.null(cp)){
     return(vol.bs)
   } else {
-    p <- BlackScholesPrice(strike, forward, texp, vol.bs, cpsign=cpsign)
-    return(df*p)
+    # if cp is specified, calculate option price
+    p <- df * BlackScholesPrice(strike, forward, texp, sigma=vol.bs, cp=cp)
+    return(p)
   }
 }