Tutorial: stats

Stats Utilities Tutorial

This tutorial provides an overview of statistical utilities available in the thalesians.adiutor.stats module, with a focus on converting correlation matrices to covariance matrices using the cor_to_cov function.

---

1. Overview

Functionality

The thalesians.adiutor.stats module provides statistical tools for quantitative and financial computations. One of its key utilities is the transformation of correlation matrices into covariance matrices.

---

2. cor_to_cov Function

Description

The cor_to_cov function converts a correlation matrix (or a compressed subdiagonal array representing it) and a set of variances into a covariance matrix.

Parameters

• cors: A correlation matrix or its compressed subdiagonal array representation.
• vars: A list or array of variances corresponding to the variables.

Returns

• covs: The resulting covariance matrix.

---

3. Usage Example

Below is an example illustrating how to use the cor_to_cov function:

import numpy as np
import thalesians.adiutor.stats as stats
import thalesians.adiutor.utils as utils

# Define the subdiagonal array representation of the correlation matrix
cors = utils.SubdiagonalArray.create((-.25, -.5, .3))

# Define the variances
vars = (4.0, 3.0, 5.0)

# Convert correlation matrix to covariance matrix
covs = stats.cor_to_cov(cors, vars)

# Display the resulting covariance matrix
print(covs)

Output

The output covariance matrix will look as follows:

[[ 4.         -0.8660254  -2.23606798]
 [-0.8660254   3.          1.161895  ]
 [-2.23606798  1.161895    5.        ]]

---

4. How It Works

The cor_to_cov function computes the covariance matrix as:

[ \text{cov}{ij} = \text{cor}{ij} \cdot \sqrt{\text{var}_i \cdot \text{var}_j} ]

where:

• (\text{cor}_{ij}) is the correlation coefficient between variables (i) and (j).
• (\text{var}_i) and (\text{var}_j) are the variances of variables (i) and (j).

---

5. Unit Test Example

Here is a minimal unit test to validate the functionality:

import unittest
import numpy as np
import numpy.testing as npt
import thalesians.adiutor.stats as stats
import thalesians.adiutor.utils as utils

class TestStats(unittest.TestCase):
    def test_cor_to_cov(self):
        cors = utils.SubdiagonalArray.create((-.25, -.5, .3))
        vars = (4.0, 3.0, 5.0)
        covs = stats.cor_to_cov(cors, vars)
        known_good_covs = np.array([
            [ 4.0, -0.8660254, -2.23606798],
            [-0.8660254, 3.0, 1.161895],
            [-2.23606798, 1.161895, 5.0]
        ])
        npt.assert_almost_equal(covs, known_good_covs)

if __name__ == '__main__':
    unittest.main()

---

6. Key Notes

• Subdiagonal Array Representation:

  • The utils.SubdiagonalArray.create function is used to represent correlation matrices efficiently by storing only the subdiagonal elements.
  • Example: (-0.25, -0.5, 0.3) represents the subdiagonal of a 3x3 correlation matrix.

• Validation: The unit test ensures the cor_to_cov function works correctly, producing results accurate to several decimal places.

---

7. Conclusion

The cor_to_cov function in thalesians.adiutor.stats is a powerful utility for converting correlation matrices to covariance matrices. This is especially useful in financial and statistical modeling where variances are given, and covariances need to be computed.