Type: Package
Title: General-Purpose Phase-Type Functions
Version: 1.0.4
Maintainer: Iker Rivas-González <ikerrivas96@gmail.com>
Description: General implementation of core function from phase-type theory. 'PhaseTypeR' can be used to model continuous and discrete phase-type distributions, both univariate and multivariate. The package includes functions for outputting the mean and (co)variance of phase-type distributions; their density, probability and quantile functions; functions for random draws; functions for reward-transformation; and functions for plotting the distributions as networks. For more information on these functions please refer to Bladt and Nielsen (2017, ISBN: 978-1-4939-8377-3) and Campillo Navarro (2019) https://orbit.dtu.dk/en/publications/order-statistics-and-multivariate-discrete-phase-type-distributio.
License: GPL-3
URL: https://rivasiker.github.io/PhaseTypeR/, https://github.com/rivasiker/PhaseTypeR
BugReports: https://github.com/rivasiker/PhaseTypeR/issues
Imports: expm, igraph, methods
Suggests: knitr, partitions, rmarkdown, testthat
VignetteBuilder: knitr
Encoding: UTF-8
RoxygenNote: 7.1.2
NeedsCompilation: no
Packaged: 2022-07-21 15:52:09 UTC; au595587
Author: Iker Rivas-González ORCID iD [aut, cre], Asger Hobolth [aut], Lars Nørvang Andersen [aut], Colin Guetemme [aut]
Repository: CRAN
Date/Publication: 2022-07-21 16:20:05 UTC

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

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 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

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)


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

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

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)



Checking the basic phase-type assumptions

Description

This function checks whether all the elements for building a phase-type object have the right shape.

Usage

check_phase_type(subint_mat, init_probs)

Arguments

subint_mat

Sub-intensity rate matrix.

init_probs

Initial probability vector.

Value

A list with the elements of a phase-type distribution.


Checking reward matrix

Description

This function checks whether the shape of the reward matrix is correct.

Usage

check_reward(reward_mat, init_probs)

Arguments

reward_mat

Reward matrix

init_probs

Initial probability vector.


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)


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:

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)


Moments of the multivariate continuous phase-type distribution

Description

This function calculates the moments for the multivariate phase-type distributions.

Usage

moment_mph(obj, v)

Arguments

obj

a mult_cont_phase_type.

v

a vector or an integer.

Details

The variables for which the moments are calculated can be specified in the v vector as indices in the reward matrix of the mult_cont_phase_type object.

Value

A number representing the moment of a multivariate continuous phase-type distribution.


Moments of the univariate continuous phase-type distribution

Description

This function calculates the moments for the phase-type distributions.

Usage

moment_ph(obj, m)

Arguments

obj

a mult_cont_phase_type.

m

an integer.

Details

The order of the moment can be specified by m for a cont_phase_type object.


Permutations

Description

This function calculates all possible permutations given a numeric vector.

Usage

perm(v)

Arguments

v

a numeric vector.

Value

A matrix with all possible permutations.


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:

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)