docs improvement

8 files changed, 120 insertions, 60 deletions

diff --git a/R/distrib.R b/R/distrib.R
index 6c588ff..edc5081 100644
--- a/R/distrib.R
+++ b/R/distrib.R
@@ -15,8 +15,8 @@
 #' \code{GHquad} computes the quadrature weights for integrating against a

 #' Gaussian distribution.

 #'

-#' if f is a function, then with(GHquad(100), crossprod(f(Z), w))

-#' will compute \eqn{\frac{1}{\sqrt{2\pi}}\int_{-\infty}^\infty f(x)e^{-\frac{x^2}{2}}\,dx}.

+#' if f is a function, then \eqn{\sum_{i=1}^n f(Z_i)w_i \approx

+#' \frac{1}{\sqrt{2\pi}} \int_{-\infty}^\infty f(x)e^{-\frac{x^2}{2}}\,dx}.

 #' @param n Integer, the number of nodes

 #' @return A list with two components:

 #'  \item{Z}{the list of nodes}

@@ -36,11 +36,11 @@ GHquad <- function(n){
 #' \code{lossdistrib} computes the probability distribution of a sum

 #' of independent Bernouilli variables with unequal probabilities.

 #'

-#' This uses the basic recursive algorithm of Andersen, Sidenius and Basu

-#' We compute the probability distribution of S = \sum_{i=1}^n X_i

-#' where X_i is Bernouilli(p_i)

+#' We compute the probability distribution of \eqn{S = \sum_{i=1}^n X_i}

+#' where \eqn{X_i} is Bernouilli(\eqn{p_i}). This uses the simple recursive

+#' algorithm of Andersen, Sidenius and Basu

 #' @param p Numeric vector, the vector of success probabilities

-#' @return A vector q such that q[k]=P(S=k)

+#' @return A vector q such that \eqn{q_k=\Pr(S=k)}

 lossdistrib <- function(p){

     ## basic recursive algorithm of Andersen, Sidenius and Basu

     n <- length(p)

@@ -58,13 +58,13 @@ lossdistrib <- function(p){
 #' \code{lossdistrib.fft} computes the probability distribution of a sum

 #' of independent Bernouilli variables with unequal probabilities.

 #'

-#' This uses the fft. Complexity is of order O(n m) + O(m\log{m})

-#' where m is the size of the grid and n, the number of probabilities.

+#' We compute the probability distribution of \eqn{S = \sum_{i=1}^n X_i}

+#' where \eqn{X_i} is Bernouilli(\eqn{p_i}).

+#' This uses the FFT, thus omplexity is of order \eqn{O(n m) + O(m\log(m))}

+#' where \eqn{m} is the size of the grid and \eqn{n}, the number of probabilities.

 #' It is slower than the recursive algorithm in practice.

-#' We compute the probability distribution of S = \sum_{i=1}^n X_i

-#' where X_i is Bernouilli(p_i)

 #' @param p Numeric vector, the vector of success probabilities

-#' @return A vector such that q[k]=P(S=k)

+#' @return A vector such that \eqn{q_k=\Pr(S=k)}

 lossdistrib.fft <- function(p){

     n <- length(p)

     theta <- 2*pi*1i*(0:n)/(n+1)

@@ -73,13 +73,20 @@ lossdistrib.fft <- function(p){
     return(1/(n+1)*Re(fft(v)))

 }

 

-#' recursive algorithm with first order correction

+#' Loss distribution of a portfolio

+#'

+#' \code{lossdistrib2} computes the probability distribution of a sum

+#' of independent Bernouilli variables with unequal probabilities.

 #'

+#' We compute the probability distribution of \eqn{L = \sum_{i=1}^n w_i S_i X_i}

+#' where \eqn{X_i} is Bernouilli(\eqn{p_i}). If \code{defaultflag} is TRUE, we

+#' compute the distribution of \eqn{D = \sum_{i=1}^n w_i X_i} instead.

+#' This a recursive algorithm with first order correction for discretization.

 #' @param p Numeric, vector of default probabilities

 #' @param w Numeric, vector of weights

 #' @param S Numeric, vector of severities

 #' @param N Integer, number of ticks in the grid

-#' @param defaultflag Boolean, if True, we compute the default distribution

+#' @param defaultflag Boolean, if TRUE, we compute the default distribution

 #' (instead of the loss distribution).

 #' @return a Numeric vector of size \code{N} computing the loss (resp.

 #' default) distribution if \code{defaultflag} is FALSE (resp. TRUE).

@@ -106,12 +113,15 @@ lossdistrib2 <- function(p, w, S, N, defaultflag=FALSE){
     return(q)

 }

 

-#' recursive algorithm with first order correction truncated version

-#' this is actually slower than lossdistrib2. But in C this is

-#' twice as fast.

-#' For high severities, M can become bigger than N, and there is

-#' some probability mass escaping.

+#' Loss distribution truncated version

+#'

+#' \code{lossdistrib2.truncated} computes the probability distribution of a sum

+#' of independent Bernouilli variables with unequal probabilities up

+#' to a cutoff N.

 #'

+#' This is actually slower than \code{lossdistrib2}, but in C this is

+#' twice as fast. For high severities, M can become bigger than the cutoff, and

+#' there is some probability mass escaping.

 #' @param p Numeric, vector of default probabilities

 #' @param w Numeric, vector of weights

 #' @param S Numeric, vector of severities

@@ -140,15 +150,26 @@ lossdistrib2.truncated <- function(p, w, S, N, cutoff=N){
     return(q)

 }

 

+#' Recovery distribution of a portfolio

+#'

+#' \code{recovdist} computes the recovery distribution of portfolio

+#' described by a vector of default probabilities, and prepay probabilities.

+#' \eqn{R=\sum_{i=1}^n w_i X_i} where \eqn{X_i=0} w.p. \eqn{1-dp_i-pp_i},

+#' \eqn{X_i=1-S_i} with probability \eqn{dp_i}, and \eqn{X_i=1} w.p. \eqn{pp_i}

+#'

+#' It is a recursive algorithm with first-order correction. For a unit of loss

+#' \eqn{lu}, each non-zero value \eqn{v} is interpolated on the grid

+#' as the pair of values

+#' \eqn{\left\lfloor\frac{v}{lu}\right\rfloor}  and

+#' \eqn{\left\lceil\frac{v}{lu}\right\rceil} so that \eqn{X_i} has

+#' four non zero values.

+#' @param dp Numeric, vector of default probabilities

+#' @param pp Numeric, vector of prepay probabilities

+#' @param w Numeric, vector of weights

+#' @param S Numeric, vector of severities

+#' @param N Integer, number of ticks in the grid

+#' @return a Numeric vector of size \code{N} computing the recovery distribution

 recovdist <- function(dp, pp, w, S, N){

-    ## computes the recovery distribution for a sum of independent variables

-    ## R=\sum_{i=1}^n w[i] X_i

-    ## where X_i = 0             w.p 1 - dp[i] - pp[i]

-    ##           = 1 - S[i]      w.p dp[i]

-    ##           = 1             w.p pp[i]

-    ## each non zero value v is interpolated on the grid as

-    ## the pair of values floor(v/lu) and ceiling(v/lu) so that

-    ## X_i has four non zero values

     n <- length(dp)

     q <- rep(0, N)

     q[1] <- 1

@@ -173,16 +194,16 @@ recovdist <- function(dp, pp, w, S, N){
     return(q)

 }

 

-#' recursive algorithm with first order correction to compute the joint

+#' Joint loss-recovery distributionrecursive algorithm with first order correction to compute the joint

 #' probability distribution of the loss and recovery.

+#'

 #' For high severities, M can become bigger than N, and there is

 #' some probability mass escaping.

-#'

 #' @param p Numeric, vector of default probabilities

 #' @param w Numeric, vector of weights

 #' @param S Numeric, vector of severities

 #' @param N Integer, number of ticks in the grid

-#' @param cutoff Integer, where to stop computing the exact probabilities

+#' @param defaultflab Logical, whether to return the loss or default distribution

 #' @return q Matrix of joint loss, recovery probability distribution

 #' colSums(q) is the recovery distribution marginal

 #' rowSums(q) is the loss distribution marginal

diff --git a/man/GHquad.Rd b/man/GHquad.Rd
index a72a1f2..1d62281 100644
--- a/man/GHquad.Rd
+++ b/man/GHquad.Rd
@@ -19,7 +19,7 @@ A list with two components:
 Gaussian distribution.
 }
 \details{
-if f is a function, then with(GHquad(100), crossprod(f(Z), w))
-will compute \eqn{\frac{1}{\sqrt{2\pi}}\int_-\infty^\infty f(x)e^{-\frac{x^2}{2}}\,dx}.
+if f is a function, then \eqn{\sum_{i=1}^n f(Z_i)w_i \approx
+\frac{1}{\sqrt{2\pi}} \int_{-\infty}^\infty f(x)e^{-\frac{x^2}{2}}\,dx}.
 }
 
diff --git a/man/lossdist.joint.Rd b/man/lossdist.joint.Rd
index c3354af..1cf7a71 100644
--- a/man/lossdist.joint.Rd
+++ b/man/lossdist.joint.Rd
@@ -2,10 +2,8 @@
 % Please edit documentation in R/distrib.R
 \name{lossdist.joint}
 \alias{lossdist.joint}
-\title{recursive algorithm with first order correction to compute the joint
-probability distribution of the loss and recovery.
-For high severities, M can become bigger than N, and there is
-some probability mass escaping.}
+\title{Joint loss-recovery distributionrecursive algorithm with first order correction to compute the joint
+probability distribution of the loss and recovery.}
 \usage{
 lossdist.joint(p, w, S, N, defaultflag = FALSE)
 }
@@ -18,7 +16,7 @@ lossdist.joint(p, w, S, N, defaultflag = FALSE)
 
 \item{N}{Integer, number of ticks in the grid}
 
-\item{cutoff}{Integer, where to stop computing the exact probabilities}
+\item{defaultflab}{Logical, whether to return the loss or default distribution}
 }
 \value{
 q Matrix of joint loss, recovery probability distribution
@@ -26,8 +24,6 @@ colSums(q) is the recovery distribution marginal
 rowSums(q) is the loss distribution marginal
 }
 \description{
-recursive algorithm with first order correction to compute the joint
-probability distribution of the loss and recovery.
 For high severities, M can become bigger than N, and there is
 some probability mass escaping.
 }
diff --git a/man/lossdistrib.Rd b/man/lossdistrib.Rd
index 3479628..7af12d4 100644
--- a/man/lossdistrib.Rd
+++ b/man/lossdistrib.Rd
@@ -10,15 +10,15 @@ lossdistrib(p)
 \item{p}{Numeric vector, the vector of success probabilities}
 }
 \value{
-A vector q such that q[k]=P(S=k)
+A vector q such that \eqn{q_k=\Pr(S=k)}
 }
 \description{
 \code{lossdistrib} computes the probability distribution of a sum
 of independent Bernouilli variables with unequal probabilities.
 }
 \details{
-This uses the basic recursive algorithm of Andersen, Sidenius and Basu
-We compute the probability distribution of S = \sum_{i=1}^n X_i
-where X_i is Bernouilli(p_i)
+We compute the probability distribution of \eqn{S = \sum_{i=1}^n X_i}
+where \eqn{X_i} is Bernouilli(\eqn{p_i}). This uses the simple recursive
+algorithm of Andersen, Sidenius and Basu
 }
 
diff --git a/man/lossdistrib.fft.Rd b/man/lossdistrib.fft.Rd
index 7f86f10..c4eae10 100644
--- a/man/lossdistrib.fft.Rd
+++ b/man/lossdistrib.fft.Rd
@@ -10,17 +10,17 @@ lossdistrib.fft(p)
 \item{p}{Numeric vector, the vector of success probabilities}
 }
 \value{
-A vector such that q[k]=P(S=k)
+A vector such that \eqn{q_k=\Pr(S=k)}
 }
 \description{
 \code{lossdistrib.fft} computes the probability distribution of a sum
 of independent Bernouilli variables with unequal probabilities.
 }
 \details{
-This uses the fft. Complexity is of order O(n m) + O(m\log{m})
-where m is the size of the grid and n, the number of probabilities.
+We compute the probability distribution of \eqn{S = \sum_{i=1}^n X_i}
+where \eqn{X_i} is Bernouilli(\eqn{p_i}).
+This uses the FFT, thus omplexity is of order \eqn{O(n m) + O(m\log(m))}
+where \eqn{m} is the size of the grid and \eqn{n}, the number of probabilities.
 It is slower than the recursive algorithm in practice.
-We compute the probability distribution of S = \sum_{i=1}^n X_i
-where X_i is Bernouilli(p_i)
 }
 
diff --git a/man/lossdistrib2.Rd b/man/lossdistrib2.Rd
index d62afb4..4d1dd9c 100644
--- a/man/lossdistrib2.Rd
+++ b/man/lossdistrib2.Rd
@@ -2,7 +2,7 @@
 % Please edit documentation in R/distrib.R
 \name{lossdistrib2}
 \alias{lossdistrib2}
-\title{recursive algorithm with first order correction}
+\title{Loss distribution of a portfolio}
 \usage{
 lossdistrib2(p, w, S, N, defaultflag = FALSE)
 }
@@ -15,7 +15,7 @@ lossdistrib2(p, w, S, N, defaultflag = FALSE)
 
 \item{N}{Integer, number of ticks in the grid}
 
-\item{defaultflag}{Boolean, if True, we compute the default distribution
+\item{defaultflag}{Boolean, if TRUE, we compute the default distribution
 (instead of the loss distribution).}
 }
 \value{
@@ -23,6 +23,13 @@ a Numeric vector of size \code{N} computing the loss (resp.
 default) distribution if \code{defaultflag} is FALSE (resp. TRUE).
 }
 \description{
-recursive algorithm with first order correction
+\code{lossdistrib2} computes the probability distribution of a sum
+of independent Bernouilli variables with unequal probabilities.
+}
+\details{
+We compute the probability distribution of \eqn{L = \sum_{i=1}^n w_i S_i X_i}
+where \eqn{X_i} is Bernouilli(\eqn{p_i}). If \code{defaultflag} is TRUE, we
+compute the distribution of \eqn{D = \sum_{i=1}^n w_i X_i} instead.
+This a recursive algorithm with first order correction for discretization.
 }
 
diff --git a/man/lossdistrib2.truncated.Rd b/man/lossdistrib2.truncated.Rd
index 2a488e9..9c4854e 100644
--- a/man/lossdistrib2.truncated.Rd
+++ b/man/lossdistrib2.truncated.Rd
@@ -2,11 +2,7 @@
 % Please edit documentation in R/distrib.R
 \name{lossdistrib2.truncated}
 \alias{lossdistrib2.truncated}
-\title{recursive algorithm with first order correction truncated version
-this is actually slower than lossdistrib2. But in C this is
-twice as fast.
-For high severities, M can become bigger than N, and there is
-some probability mass escaping.}
+\title{Loss distribution truncated version}
 \usage{
 lossdistrib2.truncated(p, w, S, N, cutoff = N)
 }
@@ -25,10 +21,13 @@ lossdistrib2.truncated(p, w, S, N, cutoff = N)
 a Numeric vector of size \code{N} computing the loss distribution
 }
 \description{
-recursive algorithm with first order correction truncated version
-this is actually slower than lossdistrib2. But in C this is
-twice as fast.
-For high severities, M can become bigger than N, and there is
-some probability mass escaping.
+\code{lossdistrib2.truncated} computes the probability distribution of a sum
+of independent Bernouilli variables with unequal probabilities up
+to a cutoff N.
+}
+\details{
+This is actually slower than \code{lossdistrib2}, but in C this is
+twice as fast. For high severities, M can become bigger than the cutoff, and
+there is some probability mass escaping.
 }
 
diff --git a/man/recovdist.Rd b/man/recovdist.Rd
new file mode 100644
index 0000000..c6da216
--- /dev/null
+++ b/man/recovdist.Rd
@@ -0,0 +1,37 @@
+% Generated by roxygen2 (4.1.1): do not edit by hand
+% Please edit documentation in R/distrib.R
+\name{recovdist}
+\alias{recovdist}
+\title{Recovery distribution of a portfolio}
+\usage{
+recovdist(dp, pp, w, S, N)
+}
+\arguments{
+\item{dp}{Numeric, vector of default probabilities}
+
+\item{pp}{Numeric, vector of prepay probabilities}
+
+\item{w}{Numeric, vector of weights}
+
+\item{S}{Numeric, vector of severities}
+
+\item{N}{Integer, number of ticks in the grid}
+}
+\value{
+a Numeric vector of size \code{N} computing the recovery distribution
+}
+\description{
+\code{recovdist} computes the recovery distribution of portfolio
+described by a vector of default probabilities, and prepay probabilities.
+\eqn{R=\sum_{i=1}^n w_i X_i} where \eqn{X_i=0} w.p. \eqn{1-dp_i-pp_i},
+\eqn{X_i=1-S_i} with probability \eqn{dp_i}, and \eqn{X_i=1} w.p. \eqn{pp_i}
+}
+\details{
+It is a recursive algorithm with first-order correction. For a unit of loss
+\eqn{lu}, each non-zero value \eqn{v} is interpolated on the grid
+as the pair of values
+\eqn{\left\lfloor\frac{v}{lu}\right\rfloor}  and
+\eqn{\left\lceil\frac{v}{lu}\right\rceil} so that \eqn{X_i} has
+four non zero values.
+}
+