mikecroucher / nearest_correlation

Python versions of nearest correlation matrix algorithms

Python versions of nearest correlation matrix algorithms.

This module will eventually contain several algorithms for solving nearest correlation matrix problems.

The only algorithm currently implemented is Nick Higham's. The code in this module is a port of the MATLAB original at http://nickhigham.wordpress.com/2013/02/13/the-nearest-correlation-matrix/

Run the test suite as follows:

python nearest_correlation_unittests.py

An example computation that finds the nearest correlation matrix to the input matrix:

In [1]: from nearest_correlation import nearcorr

In [2]: import numpy as np

In [3]: A = np.array([[2, -1, 0, 0], 
   ...:               [-1, 2, -1, 0],
   ...:               [0, -1, 2, -1], 
   ...:               [0, 0, -1, 2]])

In [4]: X = nearcorr(A)

In [5]: X
Out[5]: 
array([[ 1.        , -0.8084125 ,  0.1915875 ,  0.10677505],
       [-0.8084125 ,  1.        , -0.65623269,  0.1915875 ],
       [ 0.1915875 , -0.65623269,  1.        , -0.8084125 ],
       [ 0.10677505,  0.1915875 , -0.8084125 ,  1.        ]])

Here's an example using the weights parameter. weights is a vector defining a diagonal weight matrix diag(W):.

In [1]: from nearest_correlation import nearcorr

In [2]: import numpy as np

In [3]: A = np.array([[1, 1, 0],
   ...:               [1, 1, 1],
   ...:               [0, 1, 1]])

In [4]: weights = np.array([1,2,3])

In [5]: X = nearcorr(A, weights = weights)

In [6]: X
Out[6]: 
array([[ 1.        ,  0.66774961,  0.16723692],
       [ 0.66774961,  1.        ,  0.84557496],
       [ 0.16723692,  0.84557496,  1.        ]])

By default, the maximum number of iterations allowed before the algorithm gives up is 100. This can be changed using the max_iterations parameter. When the number of iterations exceeds max_iterations an exception is raised unless except_on_too_many_iterations = False

In [7]: A = np.array([[1, 1, 0],
   ...:               [1, 1, 1],
   ...:               [0, 1, 1]])

In [8]: nearcorr(A,max_iterations=10)
---------------------------------------------------------------------------
ExceededMaxIterationsError                Traceback (most recent call last)
<ipython-input-8-a79bc46a3452> in <module>()
----> 1 nearcorr(A,max_iterations=10)

/Users/walkingrandomly/Dropbox/nearest_correlation/nearest_correlation.py in nearcorr(A, tol, flag, max_iterations, n_pos_eig, weights, verbose, except_on_too_many_iterations)
    106                     message = "No solution found in "\
    107                               + str(max_iterations) + " iterations"
--> 108                 raise ExceededMaxIterationsError(message, X, iteration, ds)
    109             else:
    110                 # exceptOnTooManyIterations is false so just silently

ExceededMaxIterationsError: 'No solution found in 10 iterations'

If except_on_too_many_iterations=False, the best matrix found so far is quiety returned.

In [10]: nearcorr(A,max_iterations=10,except_on_too_many_iterations=False)
Out[10]: 
array([[ 1.        ,  0.76073699,  0.15727601],
       [ 0.76073699,  1.        ,  0.76073699],
       [ 0.15727601,  0.76073699,  1.        ]])

Continuing failed computations

If a computation failed because the the number of iterations exceeded max_iterations, it is possible to continue by passing the exception obejct to nearcorr:

from nearest_correlation import nearcorr, ExceededMaxIterationsError
import numpy as np

A = np.array([[1, 1, 0],
              [1, 1, 1],
              [0, 1, 1]])

# Is one iteration enough?
try:
    X = nearcorr(A, max_iterations=1)
except ExceededMaxIterationsError as e:
    restart = e # capture the Exception object
    print("1 iteration wasn't enough")

# start from where we left off using the default number of `max_iterations`
X = nearcorr(restart)

# This will give the correct result
print(X)

nearest_correlation's Issues

Handling a "too many iterations" case

Currently, the code prints an info message if the number of iterations is too high, which is generally not a desired behaviour. I propose two changes.

First, moving the whole thing to the beginning of the while-loop and just returning the result, like this:

iter = 1
while max(rel_diffX, rel_diffY, rel_diffXY) > tol[0]:
    iter = iter + 1
    if iter > maxits: return X, iter
    # The rest of the computation goes here

This way, there would be no printing and a user would still be able to check if the number of iterations is too high. However, the resulting X would still be computed by maxiter iterations (instead of the current maxiter + 1). This also guarantees that iter > maxits means "X is not good enough". Currently, that final X might still be good (if the desired precision was met exactly in the (maxits+1)-th iterations).

Second, it might be a good idea to make an exception for this case. Essentially, "too many iterations" is a kind of an error, so raising an exception (with X added to the exception object) would make sense. Since this is not always a desirable behaviour, an additional function parameter exceptOnTooManyIterations (or a better name) with a default value True can be added.

`iter` variable name

Maybe change iter to it, to avoid confusion with the built-in function iter, and also to conform the name of the maxits variable (it's not called not maxiters).