Metadata-Version: 2.4
Name: psics
Version: 1.0.1
Summary: A sparse covariance selection example package
Author-email: Juan F Mancilla <jfmancilla@gmail.com>
License-Expression: MIT
Keywords: sics,sparse,sparse covariance,selection,inverse covariance,covariance
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: importlib.resources
Requires-Dist: matplot
Dynamic: license-file

# PSICS

## A Python toolbox for numerically solving the sparse inverse covariance selection. 

## Introduction

This Python module includes integrated access to native code for **COVSEL**, **COVPATH**, **GLASSO**, and **ALM** algorithms that were previously published. 

## PSICS description

PSICS is built using the Python programming language.  Consists of several functions that integrate the call to each of the sparse inverse covariance selection (SICS) algorithms, using the standard library **subprocess**.

This approach makes it possible to call different software scripts or programs written in **Matlab** and **R**, the two main platforms used to build original algorithms.

PSCIS installs the native code algorithms **COVSEL**, **COVPATH**, **GLASSO** and **ALM**. Originally, **COVSEL** and ALM runned in a **Matlab** environment. In this package, **Matlab** was replaced with the Octave platform. 

## PSICS general requeriments

Next are listed the software general requirements to install and use PSICS. It is important to note that this Python package was built and tested on a Debian 12 linux system.

- Rscript (R) >= 4.2.2
- GNU Octave, >=  7.3.0 
- gcc and GNU Fortran >= 12.2.0
- blas and cblas libraries (included in Octave and R installation)
- Python >= 3.10.
- pip >= 23.0.1.

An active connection to the internet is required in order to download software.

## Directions to install  and configure PSICS

### Install general requirements 

It is necessary to install the R, Octave, gcc and gFORTRAN compilers. This can be accomplished using the following commands in the terminal of a Debian-based Linux system.  

#### The gcc and gfortran compiler
```
$ sudo apt-get install gcc gfortran
```

#### R software
```
$ sudo apt-get install r-base r-base-core
```

#### Octave software
```
$ sudo apt-get install octave octave-dev

```

### Create a Python virtual environment

In order to avoid any conflict with the user software configuration, a virtual environment must be created and activated to install and test PSICS.

```
$ python3 -m venv ~/.venv
$ source ~/.venv/bin/activate
```


### PSICS installation
It is possible to install the PSICS package in two ways. The first one is an automatic installation, which only requires running an installation Python script.

If it is necessary to install the PSICS package in a manual way,  we list the steps required to proceed.

#### a) Automatic PSICS installation 

To proceed with the automatic PSICS installation, the script install.py included in the PSICS code can be used. It is necessary to include the requirements.txt file in the same directory where install.py is invoked. 

The install.py script executes the following steps:

* Download, install and configure any specific Python module required (requeriments.txt).

* Download, install and configure PSICS code.

* Install ALM, COVSEL, COVPATH algorithms code included in the PSICS packages. Optionally, the install.py script can download these algorithms code published on the following internet sites. Important: GLASSO is always installed from the CRAN site project.

* Covsel https://www.di.ens.fr/~aspremon/ZIP/COVSEL.zip
* Covpath https://cran.r-project.org/src/contrib/Archive/Covpath/Covpath_1.0.tar.gz
* Alm https://github.com/linboqiao/SICS/archive/refs/heads/master.zip
* Glasso  https://cran.r-project.org

All these  sites and the option flag to download the algorithms code are defined in the script install.py and can be edited according to possible changes. 

```
$ python3 install.py
```

#### b) Manual PSICS installation

If preferred, instead of installing PSICS automatically, it is also possible to install it in a manual way, as is shown in the following steps.

##### Install PSICS specific requirements

PSICS involves  additional software requirements related to the Python platform, defined in the requirements.txt file included in the PSICS source code. This file must be in the same directory where this command is issued.

```
$ pip install -r requirements.txt
```

##### Install PSICS

After the previous step, PSICS can be installed manually using the tar.gz package that is located in the dist directory of the PSCIS source code.

```
$ pip install psics-1.0.0.tar.gz
```

Alternatively PSICS can be installed by downloading from pypi site.

```
$ pip install psics
```


##### Configure the PSICS package

To configure the software after manual PSICS installation, the script config.py must be run to execute the following steps:

* Install ALM, COVSEL, COVPATH algorithms code included in the PSICS packages. Optionally,  install.py script can download these algorithms code published on the following internet sites. Note: GLASSO is always installed from the CRAN site project.
* Covsel https://www.di.ens.fr/~aspremon/ZIP/COVSEL.zip
* Covpath https://cran.r-project.org/src/contrib/Archive/Covpath/Covpath_1.0.tar.gz
* Alm https://github.com/linboqiao/SICS/archive/refs/heads/master.zip
* Glasso  https://cran.r-project.org

All these  sites and the option flag to download the algorithms code are defined in the script install.py and can be edited according to possible changes. 



``` 
$ python3 config.py
```


## Testing PSICS package



To verify the usability of the PSICS code, the script test.py is included in the replication code file.

In this script, the following tasks are executed:

* Create a synthetic covariance matrix with a previously known structure

* Keep the original synthetic inverse as a reference to compare the results obtained from SICS algorithms

* Call ALM, COVSEL, COVPATH, GLASSO and GLASSOPATH algorithms

* Calculate some key indicators for the results obtained in each case

* Show results resume in a text table and some graphical outputs where the real inverse covariance is compared to the inverse covariance calculated

```
$ python3 test.py
```


## Workarounds applied 



Because of some technical issues, it was required to apply some workarounds to COVPATH and COVSEL code.


1. COVPATH is not available to be installed as an R package directly from the CRAN Project site. It seems to be a version compatibility problem in the use of the useDynLib clause in NAMESPACE configuration file. Internal PSICS setup.py function corrects this problem.


2. COVSEL original code included the Quadratic program solver BoxQP compiled as a Matlab mex file. Because PSICS uses Octave instead of Matlab, setup.py function replaces the Matlab mex by compiling BoxQP in the Octave mkoctfile standard.


3. Some other minor errors in the COVSEL code source are also corrected automatically by the setup.py function.


## User's guide

Detailed guide of use can be found in file USERSGUIDE.md included in this Python package.

