Matrices and Vectors¶

Markov chains require extensive manipulation and multiplication of matrices. MCRoute provdes a collection of useful methods for creating and populating transition probability matrices to attach to nodes and edges in the network, and probability vectors to use as initial conditions. These modules can be found in the mcroute.matrix and mcroute.vector libraries respectively.

Matrix¶

Matrix construction and manipulation functions for MCRoute networks.

This module contains methods that enable the constructing of matrices needed to construct a MCRoute network. Typically, these methods require a defined mcroute.StateSpace object which is used to provide context for building distributions, reading files, or validating data. Matrices produced by this module are validated and can be used for any node or edge creation. For example:

from mcroute import StateSpace
import mcroute.matrix as matrix

space = StateSpace.from_range(-2, 3)
matrix.uniform(space)

will produce a uniformly distributed matrix of dimension 5. All matrix creation methods in this module will return numpy.array objects.

mcroute.matrix.absorbing_classes(matrix)¶

Summarize the absorbing classes for a given matrix.

Absorbing classes are sets of one or more states that once entered, cannot leave. In certain cases, these absorbing classes can be indicative of data issues or design issues in the matrices.

Parameters: matrix (numpy.array) – The matrix to examine
Returns: A list of sets of absorbing classes in the matrix, by index.
Return type: list

mcroute.matrix.beta(state_space, alpha, beta)¶

Create a beta distributed transition probability matrix accross a given state space.

A reader is referred to https://en.wikipedia.org/wiki/Beta_distribution for examples of the shapes that various values of alpha and beta will produce.

The beta distribution’s support lies on the interval [0,1]. To account for this, values are first normalized based on the highest and lowest jumps possible accross the entire matrix (the magnitude of which is the last value in the state space minus the first). Then, the distribution is truncated based on the available transition space in a given row of the matrix.

See https://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.beta.html for more information on the beta distribution.

Parameters

state_space (mcroute.StateSpace) – The state space under which to build the matrix
alpha (float) – The alpha (or a) parameter. Must be strictly positive.
beta (float) – The beta (or b) parameter. Must be strictly positive.

Returns

A truncated beta matrix of transition probabilities.

Return type

numpy.array

mcroute.matrix.from_csv(state_space, filepath)¶

Create a transition probability matrix using values stored in a CSV file

Parameters

state_space (mcroute.StateSpace) – The state space under which to create the matrix
filepath (str) – The filepath to the matrix values

Raises

mcroute.DataError - An error will be thrown if the matrix size is invalid.

Returns

The created matrix.

Return type

np.Array

mcroute.matrix.from_state_delta_csv(state_space, filepath)¶

Create a matrix using a set of state transition data.

Transition data must be in the form of integers represending how many incidces a state transition shifted during the transition. Positive values shift forward on the state space, negative values shift backwards.

For example, a value of ‘-2’ indicates a transition of two state indices backwards, regardless of state values or names.

Parameters

state_space (mcroute.StateSpace) – The state space under which to construct the matrix
filepath (str) – The filepath containing the state transitions.

Raises

ZeroDivisionError - Will throw an error when a state transition row is missing data, resulting in a zero division during normalization.

Returns

The populated matrix.

Return type

np.Array

Note

This method effectively assumes that state transition values are evenly spaced. Use with caution under other conditions.

mcroute.matrix.identity(state_space)¶

Create an identity probability transition matrix.

An identity matrix has probabilities of 1.0 along the diagonal, and zero everywhere else.

Parameters: state_space (mcroute.StateSpace) – The state space under which to build the matrix.
Returns: An identity matrix of transition probabilities.
Return type: numpy.array

mcroute.matrix.shift(matrix, idx=0)¶

Update a matrix with probabilities shifted by an index amount.

Each row in the matrix will have probabilities that are shifted by the indiex provided. Probabilities that are ‘pushed off’ the edge are reassigned to the ends of the distribution (the edge states), so truncation effects are possible.

Parameters

matrix (numpy.array) – The matrix to update
idx (int, optional) – The number of indices to shift the distribution by, defaults to 0

Returns

The shifted matrix

Return type

numpy.array

mcroute.matrix.steady_state(matrix)¶

Determine the steady-state transition probability vector for a matrix.

The steady-state transition probability vector is a vector that, when multiplied by the provided matrix, returns the same vector. This represents behaviour as the number of transitions trends towards infinity.

Note

This method uses a least squares approach to solving the system of equations, which allows for the number of linearly independent rows of the matrix to be less, equal to, or greater than the number of linearly independent columns. Since some transition probability matrices can have multiple solutions (periodic ones, for example), this solution minimizes the Euclidean 2-norm. See numpy’s documentation on numpy.linalg.lstsq for further details.

Parameters: matrix (numpy.array) – The matrix to calcualte steady-state probabilities for
Returns: A steady-state transition probability vector
Return type: numpy.array (1-dimensional)

mcroute.matrix.truncate_below(state_space, matrix, treshold_state_name)¶

Truncate a probability transition matrix below a given state

Parameters

state_space (mcroute.StateSpace) – The state space under which to act on the matrix
matrix (numpy.array) – The matrix to truncate
treshold_state_name (str) – The name of the state at which to truncate

Returns

A truncated matrix of transition probabilities

Return type

numpy.array

mcroute.matrix.truncexpon(state_space, mu=1.0, sigma=1.0)¶

Create a truncated exponentially distributed probability transition matrix accross a given state space.

Note that the exponential distribution only supports state values in the positive domain. Other state values will be assigned a probabiliy of zero.

The mean and shape values used in these calculations refer to state transition values. This means that the distributions created are centered around a given state transition, and are shifted by each row.

Note that this probability distribution is truncated so that any probabilities that fall outside the possible positive transition space in each row are redistributed accross all probabilities within the allowed domain.

See https://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.truncexpon.html for more information on the truncated exponential distribution.

Parameters

state_space (mcroute.StateSpace) – The state space under which to build the matrix
mu (float, optional) – The lambda (loc) of the exponential distribution, defaults to 1
sigma (float, optional) – The scale value of the exponential distribution, defaults to 1

Returns

A truncated exponential matrix of transition probabilities.

Return type

numpy.array

mcroute.matrix.trunclognorm(state_space, mu=0, sigma=1)¶

Create a truncated log-normally distributed probability transition matrix accross a given state space.

The parameters mu and sigma follow the definition used by Wikipedia: https://en.wikipedia.org/wiki/Log-normal_distribution. For conversion to scipy’s format, sigma becomes s, mu becomes loc, and the Scipy scale parameter is held as it’s default 1.

Note: The log-normal distribution only supports state values in the positive domain. Other state values will be assigned a probabiliy of zero. This probability distribution is truncated so that any probabilities that fall outside the possible positive transition space in each row are redistributed accross all probabilities within the allowed domain.

See https://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.lognorm.html for more information on the scipy lognormal distribution.

Parameters

state_space (mcroute.StateSpace) – The state space under which to build the matrix
mu (float, optional) – The mu parameter (loc) of the log-normal distribtuion
sigma (float, optional) – The sigma value (s) of the log-normal distribution

Returns

A truncated lognormal matrix of transition probabilities.

Return type

numpy.array

mcroute.matrix.truncnorm(state_space, mean=0, std=1)¶

Create a truncated normally distributed transition matrix accross a given state space.

The mean and standard deviations used in these calculations refer to state transition values. This means that a mean of zero centers the normal distribtuion around no state change (a delta of zero). Note that this probability distribution is truncated so that any probabilities that fall outside the possible transition space in each row are redistributed accross all probabilities within the allowed domain.

Parameters

state_space (mcroute.StateSpace) – The state space under which to build the matrix
mean (int, optional) – The mean value of the distribtuion, defaults to 0
std (int, optional) – The standard deviation of the distribution, defaults to 1

Returns

A transition probability matrix

Return type

numpy.array

mcroute.matrix.uniform(state_space)¶

Create a unfiromally distributed transition probability matrix.

The resulting probability transition matrix will have equal probabilities accross all state transitions.

Parameters: state_space (mcroute.StateSpace) – The state space under which to build the matrix
Returns: A matrix of transition probabilities
Return type: numpy.array

Vector¶

Vector construction and manipulation functions for MCRoute networks.

This module contains methods that enable the constructing of vectors needed as initial conditions for traversal and probability evolution through the network. Typically, these methods require a defined mcroute.StateSpace object which is used to provide context for building the distribution. For example:

from mcroute import StateSpace
import mcroute.vector as vector

space = StateSpace.from_range(-2, 3)
vector.unit(space, '0')

will produce a unit vetor with zero probability in all rows except for the named state ‘0’, which will have probability 1.0. All vector creation methods in this module will return numpy.Array objects.

mcroute.vector.uniform(state_space)¶

Create a uniformly distributed probability vector under a state space.

Parameters: state_space (mcroute.StateSpace) – The state space under which to construct the distribution
Returns: A vector of probabilities
Return type: numpy.array

mcroute.vector.unit(state_space, state_name)¶

Create a unit probability vector at a specified state name.

This method creates a vector with all zeroes except for at the specified state name, which will have probability 1.0.

Parameters

state_space (mcroute.StateSpace) – The state space under which to construct the vector
state_name (str) – The name of the state with unit probability

Returns

A vector of probabilities

Return type

numpy.array