transitionMatrix Package

The core module

This module provides the core transition matrix objects

• TransitionMatrix implements the functionality of a single-period transition matrix

• TransitionMatrixSet provides a container for a multi-period transition matrix collection

• TODO: EmpiricalTransitionMatrix implementing a continuously observed transition matrix

transitionMatrix Classes

TransitionMatrix

class transitionMatrix.model.TransitionMatrix(values=None, dimension=2, json_file=None, csv_file=None, states=None)

The TransitionMatrix object implements a typical (one period) transition matrix.

The class inherits from numpy matrices and implements additional properties specific to transition matrices. It forms the building block of the TransitionMatrixSet which holds a collection of matrices in increasing temporal order

Note

numpy.matrix will be deprecated at some point

static __new__(cls, values=None, dimension=2, json_file=None, csv_file=None, states=None)

Create a new transition matrix. Different options for initialization are:

• providing values as a list of list

• providing values as a numpy array

• loading from a csv file # TODO change the API to file + format

• loading from a json file # TODO change the API to file + format

Without data, a default identity matrix is generated with user specified dimension

Parameters:

• values (list of lists or numpy array) – initialization values

• dimension (int) – matrix dimensionality (default is 2)

• json_file (str) – a json file containing transition matrix data

• csv_file (str) – a csv file containing transition matrix data

• states – an optional state space object

Returns:

returns a TransitionMatrix object

Return type:

object

Note

The initialization in itself does not validate that the provided values form indeed a transition matrix

Example:

A = tm.TransitionMatrix(values=[[0.6, 0.2, 0.2], [0.2, 0.6, 0.2], [0.2, 0.2, 0.6]])

characterize()

Analyse or classify a transition matrix according to its properties

• diagonal dominance

Todo

Further characterization

fix_negativerates()

If a matrix entity is below zero, set to zero and correct the diagonal element to enforce

fix_rowsums()

If the row sum is not identically unity, correct the diagonal element to enforce

generate_random_matrix()

Todo

Implement matrix generation subject to various constraints

generator(t=1.0, fix_negative=False)

Compute the generator of a transition matrix

Parameters:

t (float) – the timescale parameter

Example:

G = A.generator()

power(n=1)

Raise a transition matrix to a desired power

Parameters:

n (int) – the desired power

Example:

B = A.power(10)

print_matrix(format_type='Standard', accuracy=2, labels=False)

Pretty print a transition matrix

Parameters:

• format_type (str) – formatting options (Standard, Percent)

• accuracy (int) – number of decimals to display

• labels (bool) – use state space labels to annotate matrix printout

remove(state, method)

Remove a transition matrix state and distribute its probability mass to other states according to a prescribed method

Parameters:

• state (int) – the state to remove

• method (str) – the method to use

Returns:

a transition matrix

Todo

Implement additional methods, for example a conservative approach where each NR is actually a default

row(i)

Return a row of matrix values

Parameters:

i (int) – row index

:return list

to_csv(file)

Write transition matrix to file in csv format

Parameters:

file – csv filename

to_json(file)

Write transition matrix to file in json format

Parameters:

file – json filename

validate(accuracy=0.001)

Validate required properties of a transition matrix. The following are checked

1. check squareness

2. check that all values are probabilities (between 0 and 1)

3. check that all rows sum to one

Parameters:

accuracy (float) – accuracy level to use for validation

Returns:

List of tuples with validation messages

TransitionMatrixSet

class transitionMatrix.model.TransitionMatrixSet(dimension=2, values=None, periods=1, temporal_type=None, method=None, json_file=None, csv_file=None)

The TransitionMatrixSet object stores a family of TransitionMatrix objects as a time ordered list. Besides storage it allows a variety of simultaneous operations on the collection of matrices

__init__(dimension=2, values=None, periods=1, temporal_type=None, method=None, json_file=None, csv_file=None)

Create a new matrix set. Different options for initialization are:

• providing values as a list of list

• providing values as a numpy array

• loading from a csv file

• loading from a json file

Without data, a default identity matrix is generated with user specified dimension

Parameters:

• values – initialization values

• dimension – matrix dimensionality (default is 2)

• method – the method to use for generating the set (Copy, Power, As-Is)

• periods – List with the timesteps of matrix observations

• temporal_type – matrix dimensionality (default is 2)

• Incremental: Each period matrix reflects transitions for that period

• Cumulative: Each period matrix reflects cumulative transitions from start to that period

Parameters:

• json_file (str) – a json file containing transition matrix data

• csv_file (str) – a csv file containing transition matrix data

Returns:

returns a TranstionMatrix Set object

Return type:

object

Note

The initialization in itself does not validate if the provided values form indeed a transition matrix set

Example:

Instantiate a transition matrix set directly using a list of matrices

C_Vals = [[[0.75, 0.25], [0.0, 1.0]],  [[0.75, 0.25], [0.0, 1.0]]]

C_Set = tm.TransitionMatrixSet(values=C_Vals, temporal_type='Incremental')

__mul__(scale)

Scale all entries of the set by a factor

cumulate()

Cumulate a transition matrix set from an incremental set

default_curve_set()

Calculate the cumulative probabilities (credit curves) for all ratings

default_curves(rating)

Calculate the incremental probability of entering an absorbing state, and the corresponding cumulative probabilities, hazard rates and survival rates

Todo

Make absorbing state an attribute of Matrix and MatrixSet

incremental()

Create an incremental transition matrix set from a cumulative set

print_matrix(format_type='Standard', accuracy=2, period=None)

Pretty print the entire Transition Matrix Set

:param format_type is the print format :param accuracy number of significant digits :param period which to print (default is all)

:type format_type str :type accuracy int :type period int

remove(state, method)

remove a transition matrix state and distribute its probability to other states according to a prescribed method. The method calls the remove method for each individual matrix of the set

to_xlsx(file=None)

Todo

Store the matrix set in an xlsx sheet

Parameters:

file

Returns:

validate()

Validate transition matrix set (validating individual entries)

Returns:

List of tuples with validation messages

EmpiricalTransitionMatrix

Todo

This is future functionality

class transitionMatrix.model.EmpiricalTransitionMatrix(dimension=2, values=None, observation_times=None, json_file=None, csv_file=None)

The EmpiricalTransitionMatrix object stores a full continuously observed Transition Matrix. Its main utility is to store matrices estimated using duration methods

Warning

not implemented / used yet

Note

The EmpiricalTransitionMatrix object is different from the TransitionMatrixSet in that it stores detailed event time of observations and the transition densities in addition to the transition probabilities

Note

An EmpiricalTransitionMatrix can be converted into a TransitionMatrixSet by sampling on a temporal grid (but not vice-versa)

__init__(dimension=2, values=None, observation_times=None, json_file=None, csv_file=None)

Create a new probability matrix. Different options for initialization are:

• providing values as a 3D numpy array of signature (S, S, T) and observation times as a list or numpy array of length T

• loading from a csv file

• loading from a json file

Without data, a default identity matrix is generated with user specified dimension

Parameters:

• values (3D numpy array) – initialization values

• dimension (int) – matrix dimensionality (default is 2)

• observation_times – List with the timesteps (support) of transition observations

• json_file (str) – a json file containing transition matrix data

• csv_file (str) – a csv file containing transition matrix data

Returns:

returns a EmpiricalTransitionMatrix object

Return type:

object

Note

The initialization in itself does not validate if the provided values form indeed a transition matrix set

Example:

Instantiate a transition probability matrix

transitionMatrix Subpackages

• Estimators SubPackage
  • transitionMatrix.estimators.simple_estimator module
    • SimpleEstimator
      • SimpleEstimator.fit()
  • transitionMatrix.estimators.cohort_estimator module
    • CohortEstimator
      • CohortEstimator.fit()
      • CohortEstimator.get_average()
  • transitionMatrix.estimators.aalen_johansen_estimator module
    • AalenJohansenEstimator
      • AalenJohansenEstimator.fit()
  • transitionMatrix.estimators.kaplan_meier_estimator module
    • KaplanMeierEstimator
• State Spaces SubPackage
  • transitionMatrix.statespaces.statespace module
    • StateSpace
      • StateSpace.cqs_map()
      • StateSpace.describe()
      • StateSpace.generic()
      • StateSpace.get_state_labels()
      • StateSpace.get_states()
      • StateSpace.validate_dataset()
• Credit Ratings SubPackage
  • transitionMatrix.creditratings.creditcurve module
    • CreditCurve
      • CreditCurve.characterize()
      • CreditCurve.hazard_curve()
      • CreditCurve.print_curve()
      • CreditCurve.to_csv()
      • CreditCurve.to_html()
      • CreditCurve.to_json()
      • CreditCurve.validate()
  • transitionMatrix.creditratings.creditsystems module
  • transitionMatrix.creditratings.predefined module
• Generators SubPackage
  • transitionMatrix.generators contents
    • deterministic()
    • exponential_transitions()
    • long_format()
    • markov_chain()
    • portfolio_labels()
• Visualization subpackage
  • transitionMatrix.visualization contents
• Utilities SubPackage
  • transitionMatrix.utils.converters module
    • datetime_to_float()
    • frame_to_array()
    • to_canonical()
    • to_compact()
  • transitionMatrix.utils.preprocessing module
    • bin_timestamps()
    • generate_cohort_bounds()
    • generate_event_dict()
    • remove_stale_events()
    • total_timestamps()
    • transitions_summary()
    • unique_entities()
    • unique_states()
    • unique_timestamps()
    • validate_absorbing_state()