site_analysis.transition_table

Transition table for storing labelled transition data.

Provides the TransitionTable class, which stores transition counts or probabilities as a labelled square matrix with convenient access patterns.

class TransitionTable(keys: tuple[TableKey, ...], matrix: ndarray)

Bases: Generic[TableKey]

A labelled square matrix of transition data.

Stores transition counts or probabilities with named keys for rows and columns. Provides multiple access patterns:

• .matrix — the raw (read-only) numpy.ndarray

• .get(from_key, to_key) — key-based lookup

• .to_dict() — square dict-of-dicts

• .reorder(keys) — return a new table with reordered rows/columns

• .filter(keys) — return a new table with only the specified keys

Parameters:

• keys – Row and column labels (site indices or site labels).

• matrix – A square 2-D numpy array of transition values.

Raises:

ValueError – If matrix is not 2-D and square, if len(keys) != matrix.shape[0], if keys contains duplicates, or if matrix has a non-numeric dtype.

filter(keys: Sequence[TableKey]) → TransitionTable[TableKey]

Return a new table containing only the specified keys.

Extracts the requested rows and columns without re-normalising. Rows and columns in the result follow the order given in keys.

Parameters:

keys – The keys to retain. Must be a subset of the current keys with no duplicates.

Returns:

A new TransitionTable with only the requested keys.

Raises:

ValueError – If keys contains unknown or duplicate keys.

get(from_key: TableKey, to_key: TableKey) → int | float

Look up a single transition value by key.

Parameters:

• from_key – The source key (row).

• to_key – The destination key (column).

Returns:

The transition value at (from_key, to_key).

Raises:

KeyError – If either key is not present in the table.

property keys: tuple[TableKey, ...]

Row and column labels.

property matrix: ndarray

The transition data as a read-only 2-D numpy array.

reorder(keys: Sequence[TableKey]) → TransitionTable[TableKey]

Return a new table with rows and columns reordered.

Parameters:

keys – The desired key ordering. Must contain exactly the same keys as the current table.

Returns:

A new TransitionTable with reordered rows and columns.

Raises:

ValueError – If keys does not match the current key set exactly.

to_dict() → dict[TableKey, dict[TableKey, int | float]]

Convert to a square dict-of-dicts.

Returns:

A dict {from_key: {to_key: value}} mirroring the matrix.