Package 'PhaseTypeR'

The Univariate Discrete Phase-Type Distribution

Description

Density, distribution function, quantile function and random generation for the univariate discrete phase-type distribution.

Usage

dDPH(x, obj)

qDPH(p, obj)

pDPH(q, obj)

rDPH(n, obj)

rFullDPH(obj)

Arguments

x, q	vector of quantiles.
obj	an object of class disc_phase_type.
p	vector of probabilities.
n	number of observations. If length(n) > 1, the length is taken to be the number required.

Value

dDPH gives the density, pDPH gives the distribution function, qDPH gives the quantile function, and rDPH generates random deviates. rFullDPH returns the full path of a random draw from the distribution.

The length of the result is determined by n for rDPH, and is the maximum of the lengths of the numerical arguments for the other functions.

The numerical arguments other than n are recycled to the length of the result. Only the first elements of the logical arguments are used.

Functions

• dDPH(): Density function for the univariate continuous phase-type distribution.

• qDPH(): Quantile function for the univariate discrete phase-type distribution.

• pDPH(): Distribution function for the univariate discrete phase-type distribution.

• rDPH(): Random number generator for the univariate discrete phase-type distribution.

• rFullDPH(): Simulation of the full path for the univariate discrete phase-type distribution.

See Also

Distributions for other standard distributions.

Examples

disc_phase_type <- matrix(c(0.4, 0, 0.2,
                            0.5, 0.3, 0.2,
                            0, 0.7, 0.2), ncol = 3)
Y <- DPH(disc_phase_type)

dDPH(3:4, Y)
pDPH(5, Y)
qDPH(0.5, Y)
set.seed(0)
rDPH(6, Y)
rFullDPH(Y)

---

The phase-type distribution

Description

Generator functions for the S3 classes cont_phase_type, disc_phase_type, mult_cont_phase_type, mult_disc_phase_type, which represent the different phase-type distributions.

Usage

PH(subint_mat = NULL, init_probs = NULL)

DPH(subint_mat = NULL, init_probs = NULL)

MPH(subint_mat = NULL, init_probs = NULL,
    reward_mat = NULL)

MDPH(subint_mat = NULL, init_probs = NULL,
     reward_mat = NULL)

Arguments

subint_mat	a square matrix containing the transition rates or probabilities between transient states for continuous or discrete phase-type respectively. If the phase-type is continuous, the sub-intensity matrix diagonal should only contain negative values and the row sums should be non-positive. If the phase-type is discrete, the sub-intensity matrix should only contain values between 0 and 1.
init_probs	a vector, a one-row matrix or NULL which gives the probabilities to start in each state. If init_probs is NULL, the probability to start on the first state will be 1 and 0 otherwise.
reward_mat	a matrix NULL(default) where each row is a reward vector, and each column corresponds to a state. It should have the same number of columns as the length of the initial probabilities.

Details

PH, DPH, MPH and MDPH are the generator functions for the four types of phase-type distribution classes, this is, the continuous univariate, the discrete univariate, the continuous multivariate and the discrete multivariate respectively. The class is generated by supplying a sub-intensity matrix and an optional initial probability vector plus a reward matrix in the case of multivariate phase-type. If the initial probabilities are not specified, then the initial probability will be init_probs = c(1, 0, 0, ...) with the same length as the number of transient states.

Value

A phase-type object of class cont_phase_type for PH, disc_phase_type for DPH, mult_cont_phase_type for MPH, and mult_disc_phase_type for MDPH. All these classes inherit from list.

Examples

##===========================##
## For continuous univariate ##
##===========================##

subintensity_matrix <- matrix(c(-1.5, 1.5, 0,
                                 0,  -1,   1,
                                 0,   0,  -0.5),
                              ncol = 3,
                              byrow = TRUE)
PH(subintensity_matrix)

#---

subintensity_matrix <- matrix(c(-1.5, 1.5, 0,
                                 0,  -1,   1,
                                 0,   0,  -0.5),
                              ncol = 3,
                              byrow = TRUE)
initial_probabilities <- c(0.9, 0.1, 0)
PH(subintensity_matrix, initial_probabilities)


##=========================##
## For discrete univariate ##
##=========================##

subintensity_matrix <- matrix(c(0.4, 0.24, 0.12,
                                0,   0.4,  0.2,
                                0,   0,    0.5),
                              ncol = 3,
                              byrow = TRUE)
DPH(subintensity_matrix)

#---

subintensity_matrix <- matrix(c(0.4, 0.24, 0.12,
                                0,   0.4,  0.2,
                                0,   0,    0.5),
                              ncol = 3,
                              byrow = TRUE)
initial_probabilities <- c(0.9, 0.1, 0)
DPH(subintensity_matrix, initial_probabilities)



##=============================##
## For continuous multivariate ##
##=============================##

subintensity_matrix <- matrix(c(-3,  2,  0,
                                 0, -2,  1,
                                 0,  0, -1),
                              nrow = 3,
                              byrow = TRUE)
reward_matrix = matrix(sample(seq(0, 10, 0.1), 6), nrow = 3, ncol = 2)
initial_probabilities = c(1, 0, 0)
MPH(subintensity_matrix,
    initial_probabilities,
    reward_matrix)


##===========================##
## For discrete multivariate ##
##===========================##

subintensity_matrix <- matrix(c(0.4, 0.24, 0.12,
                                0,   0.4,  0.2,
                                0,   0,    0.5),
                              ncol = 3,
                              byrow = TRUE)
reward_matrix <- matrix(sample(seq(0, 10), 6), nrow = 3, ncol = 2)
initial_probabilities = c(1, 0, 0)
MDPH(subintensity_matrix,
     initial_probabilities,
     reward_mat = reward_matrix)

---

The Multivariate Discrete Phase-Type Distribution

Description

Density, distribution function, quantile function and random generation for the multivariate discrete phase-type distribution.

Usage

dMDPH(x, obj)

qMDPH(p, obj)

pMDPH(q, obj)

rMDPH(n, obj)

rFullMDPH(obj)

Arguments

x, q	vector of quantiles.
obj	an object of class mult_disc_phase_type.
p	vector of probabilities.
n	number of observations. If length(n) > 1, the length is taken to be the number required.

Value

dMDPH gives the density, pMDPH gives the distribution function, qMDPH gives the quantile function, and rMDPH generates random deviates. rFullMDPH returns the full path of a random draw from the distribution.

Each row of the result of For dMDPH, pMDPH, qMDPH, and rMDPH corresponds to each univariate reward transformation. For dMDPH, qMDPH and pMDPH, the inputs x, p and q can be matrices where in row i the i_th reward transformation and in col j the j_th value of x, p or q tested.

The length of the result is determined by n for rMDPH, and is the maximum of the lengths of the numerical arguments for the other functions.

The numerical arguments other than n are recycled to the length of the result. Only the first elements of the logical arguments are used.

Functions

• dMDPH(): Density function for the multivariate discrete phase-type distribution.

• qMDPH(): Quantile function for the multivariate discrete phase-type distribution.

• pMDPH(): Distribution function for the multivariate discrete phase-type distribution.

• rMDPH(): Random number generator for the multivariate discrete phase-type distribution.

• rFullMDPH(): Simulation of the full path for the multivariate discrete phase-type distribution.

See Also

Distributions for other standard distributions.

Examples

disc_phase_type <- matrix(c(0.4, 0, 0.2,
                            0.5, 0.3, 0.2,
                            0, 0.7, 0.2), ncol = 3)
R <- matrix(c(0, 1, 1,
              2, 1, 5,
              0, 1, 10,
              1, 2, 3), nrow = 3)
Y <- MDPH(disc_phase_type, reward_mat = R)

dMDPH(3:4, Y)
pMDPH(1.45, Y)
qMDPH(0.5, Y)
set.seed(0)
rMDPH(6, Y)
rFullMDPH(Y)

---

Mean of Phase-Type Distributions

Description

Calculates the mean of continuous, discrete and multivariate phase-type distributions, represented by the cont_phase_type, disc_phase_type and mult_cont_phase_type classes.

Usage

## S3 method for class 'cont_phase_type'
mean(x, ...)

## S3 method for class 'disc_phase_type'
mean(x, ...)

## S3 method for class 'mult_cont_phase_type'
mean(x, v = NULL, ...)

## S3 method for class 'mult_disc_phase_type'
mean(x, v = NULL, ...)

Arguments

x	a cont_phase_type, disc_phase_type, mult_cont_phase_type or mult_disc_phase_type object
...	other arguments passed to methods
v	NULL, integer or vector.

Details

For the univariate case (cont_phase_type and disc_phase_type), the mean of the distribution is returned.

In the case of multivariate phase-type distributions three different usages can be distinguished:

• If v = NULL (default), the means of all the variables defined by the sub-intensity matrix are returned

• If v is an integer, then the mean of the variable with the specified index in the reward matrix is returned.

• If v is a vector, then the means of the variables defined by those indices will be returned.

Value

This function returns a single value for the mean of univariate phase-type distributions, or a vector of means for each reward-transformed distribution of the multivariate phase-type distributions.

Examples

# For univariate continuous phase-type distributions
ph1 <- PH(matrix(c(-3, 0, 0, 1, -2, 0, 0, 1, -1), ncol = 3), c(0.25,0.25,0.5))
mean(ph1)

# For multivariate continuous phase-type distributions
subintensity_matrix <- matrix(c(-3, 0, 0,
                               2, -2, 0,
                               0, 1, -1), nrow = 3, ncol = 3)
reward_matrix = matrix(sample(seq(0, 10), 6), nrow = 3, ncol = 2)
ph2 <- MPH(subintensity_matrix, reward_mat = reward_matrix)
## Mean for both states in the reward matrix
mean(ph2)
## Mean for the first state in the reward matrix
mean(ph2, 1)
## Mean for the second state in the reward matrix
mean(ph2, 2)

---

The Multivariate Continuous Phase-Type Distribution

Description

Density, distribution function, quantile function and random generation for the multivariate continuous phase-type distribution.

Usage

dMPH(x, obj)

qMPH(p, obj)

pMPH(q, obj)

rMPH(n, obj)

rFullMPH(obj)

Arguments

x, q	vector of quantiles.
obj	an object of class mult_cont_phase_type.
p	vector of probabilities.
n	number of observations. If length(n) > 1, the length is taken to be the number required.

Value

dMPH gives the density, pMPH gives the distribution function, qMPH gives the quantile function, and rMPH generates random deviates. rFullMPH returns the full path of a random draw from the distribution.

Each row of the result of For dMPH, pMPH, qMPH, and rMPH corresponds to each univariate reward transformation. For dMDPH, qMDPH and pMDPH, the inputs x, p and q can be matrices where in row i the i_th reward transformation and in col j the j_th value of x, p or q tested.

The length of the result is determined by n for rMPH, and is the maximum of the lengths of the numerical arguments for the other functions.

The numerical arguments other than n are recycled to the length of the result. Only the first elements of the logical arguments are used.

Functions

• dMPH(): Density function for the multivariate continuous phase-type distribution.

• qMPH(): Quantile function for the multivariate continuous phase-type distribution.

• pMPH(): Distribution function for the multivariate continuous phase-type distribution.

• rMPH(): Random number generator for the multivariate continuous phase-type distribution.

• rFullMPH(): Simulation of the full path for the multivariate continuous phase-type distribution.

See Also

Distributions for other standard distributions.

Examples

cont_phase_type <- matrix(c(-3, 0, 1,
                            2, -3, 1,
                            1, 1, -2), ncol = 3)
R <- matrix(c(0, 1, 1,  2,
                 2, 1, 5,  2,
                 0, 1, 10, 2), nrow = 3, ncol=4, byrow=TRUE)
Y <- MPH(cont_phase_type, reward_mat = R)

dMPH(3:4, Y)
pMPH(1.45, Y)
qMPH(0.5, Y)
set.seed(0)
rMPH(6, Y)
rFullMPH(Y)

---

The Univariate Continuous Phase-Type Distribution

Description

Density, distribution function, quantile function and random generation for the univariate continuous phase-type distribution.

Usage

dPH(x, obj)

qPH(p, obj)

pPH(q, obj)

rPH(n, obj)

rFullPH(obj)

Arguments

x, q	vector of quantiles.
obj	an object of class cont_phase_type.
p	vector of probabilities.
n	number of observations. If length(n) > 1, the length is taken to be the number required.

Value

dPH gives the density, pPH gives the distribution function, qPH gives the quantile function, and rPH generates random deviates. rFullPH returns the full path of a random draw from the distribution.

The length of the result is determined by n for rPH, and is the maximum of the lengths of the numerical arguments for the other functions.

The numerical arguments other than n are recycled to the length of the result. Only the first elements of the logical arguments are used.

Functions

• dPH(): Density function for the univariate continuous phase-type distribution.

• qPH(): Quantile function for the univariate continuous phase-type distribution.

• pPH(): Distribution function for the univariate continuous phase-type distribution.

• rPH(): Random number generator for the univariate continuous phase-type distribution.

• rFullPH(): Simulation of the full path for the univariate continuous phase-type distribution.

See Also

Distributions for other standard distributions.

Examples

cont_phase_type <- matrix(c(-3, 0, 1,
                            2, -3, 1,
                            1, 1, -2), ncol = 3)
Y <- PH(cont_phase_type)

dPH(3:4, Y)
pPH(1.45, Y)
qPH(0.5, Y)
set.seed(0)
rPH(6, Y)
rFullPH(Y)

---

Phase-type distribution to network

Description

This function converts a phase-type distribution into an igraph graph object.

Usage

phase_type_to_network(phase_type, t = NULL)

Arguments

phase_type	an object of class disc_phase_type or cont_phase_type
t	NULL or numeric. Sampling time for the continuous phase-type distribution.

Value

An igraph graph object of the phase-type distribution.

Examples

## Not run: 
cont_phase_type <- matrix(c(-3, 0, 1,
                            2, -3, 1,
                            1, 1, -2), ncol = 3)
Y <- PH(cont_phase_type)
Y_network <- phase_type_to_network(Y)
set.seed(28)
plot(Y_network, layout = layout_with_fr(Y_network,  weights = rep(1, length(E(Y_network)))))

## End(Not run)

---

Print method for phase-type objects

Description

Print method for cont_phase_type, disc_phase_type, mult_cont_phase_type and mult_disc_phase_type classes.

Usage

## S3 method for class 'cont_phase_type'
print(x, ...)

## S3 method for class 'disc_phase_type'
print(x, ...)

## S3 method for class 'mult_cont_phase_type'
print(x, ...)

## S3 method for class 'mult_disc_phase_type'
print(x, ...)

Arguments

x	phase-type object
...	other arguments not used by this method

Value

Prints the phase-type object as a list.

Examples

subintensity_matrix <- matrix(c(-1.5, 1.5, 0,
                                 0,  -1,   1,
                                 0,   0,  -0.5),
                              ncol = 3,
                              byrow = TRUE)
ph1 <- PH(subintensity_matrix)

print(ph1)

---

Transformation of Phase-Type Distributions via Rewards

Description

Transform a variable following a phase-type distribution according to a non-negative reward vector.

Usage

reward_phase_type(phase_type, reward)

Arguments

phase_type	an object of class cont_phase_type or disc_phase_type.
reward	a vector of the same length as the number of states. The vector should contain non-negative values. Rewards for the discrete phase-type distribution can only be integers.

Details

For the reward transformation for continuous phase-type distribution, the transformation will be performed as presented in the book of Bladt and Nielsen (2017).

For the discrete phase_type distribution is based on the PhD of Navarro (2018) and Hobolth, Bladt and Andersen (2021).

Value

An object of class disc_phase_type or cont_phase_type.

References

Bladt, M., & Nielsen, B. F. (2017). *Matrix-exponential distributions in applied probability* (Vol. 81). New York: Springer.

Campillo Navarro, A. (2018). *Order statistics and multivariate discrete phase-type distributions*. DTU Compute. DTU Compute PHD-2018, Vol.. 492

Hobolth, A., Bladt, M. & Andersen, L.A. (2021). *Multivariate phase-type theory for the site frequency spectrum*. ArXiv.

See Also

PH, DPH

Examples

##===========================##
## For continuous phase-type ##
##===========================##

subint_mat <- matrix(c(-3, 1, 1,
                      2, -3, 0,
                      1, 1, -3), ncol = 3)
init_probs <- c(0.9, 0.1, 0)
ph <- PH(subint_mat, init_probs)
reward <- c(0.5, 0, 4)

reward_phase_type(ph, reward)

##=========================##
## For discrete phase-type ##
##=========================##

subint_mat <- matrix(c(0.4, 0, 0,
                      0.24, 0.4, 0,
                      0.12, 0.2, 0.5), ncol = 3)
init_probs <- c(0.9, 0.1, 0)
ph <- DPH(subint_mat, init_probs)

reward <- c(1, 0, 4)

reward_phase_type(ph, reward)

---

Pretty summary of the cont_phase_type class.

Description

Pretty summary of the cont_phase_type class.

Usage

## S3 method for class 'cont_phase_type'
summary(object, ...)

Arguments

object	a cont_phase_type object
...	other arguments passed to methods

Value

This function prints a nicely-formatted summary of a cont_phase_type object. The summary includes the sub-intensity matrix, the initial probabilities, the defect, the mean and the variance of the phase-type object.

Examples

ph <- PH(matrix(c(-3, 0, 1,
               2, -3, 1,
               1, 1, -2), ncol = 3))

summary(ph)

---

Pretty summary of the disc_phase_type class.

Description

Pretty summary of the disc_phase_type class.

Usage

## S3 method for class 'disc_phase_type'
summary(object, ...)

Arguments

object	a disc_phase_type object
...	other arguments passed to methods

Value

This function prints a nicely-formatted summary of a disc_phase_type object. The summary includes the sub-intensity matrix, the initial probabilities, the defect, the mean and the variance of the phase-type object.

Examples

dph <- DPH(matrix(c(0.4, 0, 0.2,
                    0.5, 0.3, 0.2,
                    0, 0.7, 0.2), ncol = 3))

summary(dph)

---

Pretty summary of the mult_cont_phase_type class.

Description

Pretty summary of the mult_cont_phase_type class.

Usage

## S3 method for class 'mult_cont_phase_type'
summary(object, ...)

Arguments

object	a mult_cont_phase_type object
...	other arguments passed to methods

Value

This function prints a nicely-formatted summary of a mult_cont_phase_type object. The summary includes the sub-intensity matrix, the initial probabilities, the defect, the reward matrix, the mean and the (co)variance of the phase-type object.

Examples

subint <- matrix(c(-3, 0, 1,
                    2, -3, 1,
                    1, 1, -2), ncol = 3)
R <- matrix(c(0, 1, 1,  2,
                 2, 1, 5,  2,
                 0, 1, 10, 2), nrow = 3, ncol=4, byrow=TRUE)
mph <- MPH(subint, reward_mat = R)

summary(mph)

---

Pretty summary of the mult_dist_phase_type class.

Description

Pretty summary of the mult_dist_phase_type class.

Usage

## S3 method for class 'mult_disc_phase_type'
summary(object, ...)

Arguments

object	a mult_dist_phase_type object
...	other arguments passed to methods

Value

This function prints a nicely-formatted summary of a mult_dist_phase_type object. The summary includes the sub-intensity matrix, the initial probabilities, the defect, the reward matrix, the mean and the (co)variance of the phase-type object.

Examples

subint <- matrix(c(0.4, 0, 0.2,
                   0.5, 0.3, 0.2,
                   0, 0.7, 0.2), ncol = 3)
R <- matrix(c(0, 1, 1,
              2, 1, 5,
              0, 1, 10,
              1, 2, 3), nrow = 3)
mdph <- MDPH(subint, reward_mat = R)

summary(mdph)

---

Variance and Covariance of Phase-Type Distributions

Description

Calculates the (co)variance of continuous, discrete and multivariate phase-type distributions generated by PH, DPH, MPH and MDPH.

Usage

var(obj, ...)

## S3 method for class 'cont_phase_type'
var(obj, ...)

## S3 method for class 'disc_phase_type'
var(obj, ...)

## S3 method for class 'mult_cont_phase_type'
var(obj, v = NULL, ...)

## S3 method for class 'mult_disc_phase_type'
var(obj, v = NULL, ...)

Arguments

obj	a cont_phase_type, disc_phase_type, mult_cont_phase_type or mult_disc_phase_type object
...	other arguments passed to methods
v	NULL, integer or vector of length 2.

Details

For the univariate case (cont_phase_type and disc_phase_type), the variance of the distribution is returned.

In the case of multivariate phase-type distributions three different usages can be distinguished:

• If v = NULL (default), then a variance-covariance matrix of all the variables specified in the reward matrix are returned, where variances are in the diagonal and covariances in the rest of the matrix element.

• If v is an integer, then the variance of the variable encoded by the v index in the reward matrix is returned.

• If v is a vector of length 2, then the covariance between the two variables encoded by the v indices in the reward matrix is returned.

Value

The value returned is either the variance (for univariate distributions) or the variance-covariance matrix (for multivariate distributions).

Examples

# For univariate continuous phase-type distributions
ph1 <- PH(matrix(c(-3, 0, 0, 1, -2, 0, 0, 1, -1), ncol = 3), c(0.25,0.25,0.5))
var(ph1)

# For multivariate continuous phase-type distributions
subintensity_matrix <- matrix(c(-3, 0, 0,
                               2, -2, 0,
                               0, 1, -1), nrow = 3, ncol = 3)
reward_matrix = matrix(sample(seq(0, 10), 6), nrow = 3, ncol = 2)
ph2 <- MPH(subintensity_matrix, reward_mat = reward_matrix)
## Variance-covariance matrix
var(ph2)
## Variance for the first state in the reward matrix
var(ph2, 1)
## Variance for the second state in the reward matrix
var(ph2, 2)

---