README.md 2.8 KB
Newer Older
Aryan Eftekhari's avatar
Aryan Eftekhari committed
1
# SQUIC for Python
aryan eftekhari's avatar
aryan eftekhari committed
2
SQUIC is a second-order, L1-regularized maximum likelihood method for performant large-scale sparse precision matrix estimation. This repository contains the source code for the Python(v3) interface of SQUIC. 
AE's avatar
import    
AE committed
3

Aryan Eftekhari's avatar
Aryan Eftekhari committed
4
**For an interactive session using SQUIC for Python see Google Colab:**
Aryan Eftekhari's avatar
Aryan Eftekhari committed
5

Aryan Eftekhari's avatar
Aryan Eftekhari committed
6
[![SQUIC for Python](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/1iQB5hz07UMd5C1PR3w3xM3306BVcFGiO?usp=sharing)
aryan eftekhari's avatar
aryan eftekhari committed
7

AE's avatar
import    
AE committed
8
9
## Installation

Aryan Eftekhari's avatar
updzate    
Aryan Eftekhari committed
10
#### Step 1:
Aryan Eftekhari's avatar
Aryan Eftekhari committed
11
Download the shared library ``libSQUIC`` from www.gitlab.ci.inf.usi.ch/SQUIC/libSQUIC, and follow its README instructions. The default and recommended location for ``libSQUIC`` is the home directory, i.e., ``~/``. Note that precompiled versions are available.
AE's avatar
import    
AE committed
12

Aryan Eftekhari's avatar
updzate    
Aryan Eftekhari committed
13
#### Step 2:
AE's avatar
import    
AE committed
14
15
Run the following command to install the library:
```angular2
Aryan Eftekhari's avatar
Aryan Eftekhari committed
16
pip3 install squic
AE's avatar
import    
AE committed
17
```
Aryan Eftekhari's avatar
Aryan Eftekhari committed
18
_Note: The environment variable ``SQUIC_LIB_PATH`` defines the location of ``libSQUIC`` - this is by default set to the home directory of the user. If this is not the location of ``libSQUIC``, it can be changed via terminal ``bash> export SQUIC_LIB_PATH=/path/to/squic/``_
AE's avatar
import    
AE committed
19
20

## Example
Aryan Eftekhari's avatar
Aryan Eftekhari committed
21
In this example, we will use SQUIC to estimate the precision matrix of a synthetically generated dataset with correlated random variables, where the true precision matrix is tridiagonal.
AE's avatar
import    
AE committed
22
23

```angular2
Aryan Eftekhari's avatar
updzate    
Aryan Eftekhari committed
24
import squic
AE's avatar
import    
AE committed
25
26
27
import numpy as np

# generate sample from tridiagonal precision matrix
aryan eftekhari's avatar
aryan eftekhari committed
28
p = 1024
AE's avatar
import    
AE committed
29
30
31
32
33
34
35
36
37
38
39
40
n = 100
l = .4

# generate a tridiagonal matrix
a = -0.5 * np.ones(p-1)
b = 1.25 * np.ones(p)
iC_star = np.diag(a,-1) + np.diag(b,0) + np.diag(a,1)

# generate the data
L = np.linalg.cholesky(iC_star)
Y = np.linalg.solve(L.T,np.random.randn(p,n))

Aryan Eftekhari's avatar
updzate    
Aryan Eftekhari committed
41
[X,W,info_times,info_objective,info_logdetX,info_trSX] = squic.run(Y,l)
AE's avatar
import    
AE committed
42
```
Aryan Eftekhari's avatar
Aryan Eftekhari committed
43
For further details type ``help(SQUIC)``.
Aryan Eftekhari's avatar
Aryan Eftekhari committed
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59

## Publications & References
Please cite our publications if it helps your research:

```
@article{X,
 author = {X},
 title = {X}
 journal = {X}
 volume = {X}
 number = {X}
 pages = {X}
 year = {X}
 doi = {X}
}
```
Aryan Eftekhari's avatar
Aryan Eftekhari committed
60
For related research on SQUIC please see:
Aryan Eftekhari's avatar
Aryan Eftekhari committed
61

Aryan Eftekhari's avatar
Aryan Eftekhari committed
62
- [Bollhöfer, M., Eftekhari, A., Scheidegger, S. and Schenk, O., 2019. Large-Scale Sparse Inverse Covariance Matrix Estimation. SIAM Journal on Scientific Computing, 41(1), pp.A380-A401](https://doi.org/10.1137/17M1147615)
Aryan Eftekhari's avatar
Aryan Eftekhari committed
63

Aryan Eftekhari's avatar
Aryan Eftekhari committed
64
- [Eftekhari, A., Bollhöfer, M. and Schenk, O., 2018, November. Distributed Memory Sparse Inverse Covariance Matrix Estimation on High-performance Computing Architectures. In SC18: International Conference for High Performance Computing, Networking, Storage and Analysis (pp. 253-264). IEEE](https://doi.org/10.1109/SC.2018.00023)
Aryan Eftekhari's avatar
Aryan Eftekhari committed
65

Aryan Eftekhari's avatar
Aryan Eftekhari committed
66
- [Eftekhari, A., Pasadakis, D., Bollhöfer, M., Scheidegger, S. and Schenk, O., 2021. Block-Enhanced Precision Matrix Estimation for Large-Scale Datasets. Journal of Computational Science, p. 101389](https://doi.org/10.1016/j.jocs.2021.101389)