Networks and State Spaces

A MCRoute analysis requires two key operating components: A state space, and a network. State spaces must be defined first, as they are the context under which all transition probabilities are built.

State Space

A state space consists of an ordered sequence (lists) of values and labels which represent the various possible states an object can take in a MCRoute network. These states can be relatively arbitrary, though they typically represent some sort of value-associated state such as schedule delay or travel time.

Note

Values associated with states are considered the lower bound of a given state. This arbitrary decision is required to support the construciton of transition probability matrices from probability distributions.

class mcroute.StateSpace(states)

The state space class representing a Markov chain state space.

A state space consists of a list of State objects containing two fields, a value (for numerical analysis) and a label (for reference and readability).

Note

State space names and values must be unique.

Parameters

states – A list of mcroute.States

classmethod from_csv(filepath)

Create a state space from a CSV file. The file must have two columns, the first being the name of the state, the second being the value associated with that name.

Parameters

filepath (str) – The path to the CSV file containing the states

Returns

A constructed state space

Return type

mcroute.StateSpace

classmethod from_list(name_list, value_list)

Create a state space from a list of names and a list of values.

Parameters

  • name_list (list) – The list of state labels or names

  • value_list (list) – The list of values for numerical analysis or use

Raises

DataError – mcroute.DataError

Returns

A constructed state space.

Return type

mcroute.StateSpace

classmethod from_range(low_state, high_state, interval=1)

Create a state space from a range of numbers.

This method will create a state space with matching values and labels (i.e. a value of -2 will have a label of ‘-2’). Much like Python’s own range() function, the high state is not incldued.

Parameters

  • low_state (int) – The lower bound of the state space

  • high_state (int) – The upper bound of the state space (not included)

  • interval (int, optional) – The interval between state values, defaults to 1

Returns

A constructed state space.

Return type

mcroute.StateSpace

index_at(name)

Get the index of a state with a given name.

Parameters

name (str) – The name of the state to look up.

Returns

The value of the state looked up.

Return type

numeric (float, int)

property mean

The mean state value in the state space.

Returns

The mean value of all state values.

Return type

float

property names

Get the state names in the state space.

Returns

A list of names in the state space.

Return type

list of str

property size

The number of states in the state space.

Returns

The size of the state space.

Return type

int

property states

Get the state objects in the state space.

Returns

A list of states in the state space.

Return type

list of mcroute.State

value_at(name)

Get the value of a state with a given name.

Parameters

name (str) – The name of the state to look up.

Returns

The value of the state looked up.

Return type

numeric (float, int)

property values

Get the state values in the state space.

Returns

A list of values in the state space.

Return type

list of numeric (int, float) values

Network

A network consists of a set of nodes, edges, and a state space under which to perform Markov-chain related activities. Nodes must be instantiated first, and subsequently connected by edges.

class mcroute.Network(state_space)

The base network class for MCRoute analysis.

A Network stores nodes and edges, and holds a copy of the state space for internal analysis.

Parameters

state_space (mcroute.StateSpace) – The state space under which the network is built.

add_edge(u, v, matrix, data=None)

Add an edge between u and v.

Nodes u and v must exist in the graph already. Edge attributes can be specified by passing a dictionary of key-value pairs via the data argument.

Parameters

  • u (node) – The node from which to start the edge

  • v (node) – The node to which to end the edge

  • matrix (numpy.array) – The transition probability matrix

  • data (dict, optional) – A set of data arguments to store on the edge, defaults to None

Raises

DataError – Raises an error if either node is not initialized.

add_node(name, matrix, data=None)

Add a node to the network.

Nodes can include non-matrix data, but must include a matrix.

Parameters

  • name (node) – The name of the node. Can be any Python object except none

  • matrix (numpy.array) – The matrix of transition probabilites for the node.

  • data (dict, optional) – Additional data to attach to the node, defaults to None

multi_step(path_nodes)

Return a multi-step transition probability matrix for a set of nodes.

Parameters

path_nodes (list) – A list of node names to compute multi-state transitions

Returns

A transition probability matrix representing the steps.

Return type

numpy.array

trajectories(nodes, starting_vector, n=1, smoothing=None)

Get a set of trajectories for a given path and initial probabilities.

The trajectories are sampled from the distributions resulting from the evoluation of the intial starting_vector probability distribution. Trajectories can be smoothed by limiting the total size of the jump possible from one state to another.

Parameters

  • nodes (list of node names) – A list of nodes to traverse over as a path.

  • starting_vector (numpy.array) – The initial probability distribution vector.

  • n (int, optional) – The number of trajectories to generate, defaults to 1

  • smoothing (numeric (int, float), optional) – The smoothing parameter, defaults to None

Returns

A list of state values sampled.

Return type

list

traverse(nodes, starting_vector)

Traverse a path along a prescribed set of nodes

The function evolves the starting_vector across a provided series of nodes and edges, keeping track of each probability distribution along the way.

Parameters

  • nodes (list) – A list of node names to traverse along

  • starting_vector (numpy.array) – A starting probability distribution