# GCONCORD Documentation

This directory contains documentation for the GCONCORD package.

## Contents

- **API Reference**: Complete documentation of all functions and classes
- **Tutorials**: Step-by-step guides for common tasks
- **Algorithm Details**: Mathematical background and implementation notes
- **Performance Guide**: Tips for optimal performance

## Quick Links

- [Getting Started](../examples/notebooks/getting_started.ipynb)
- [Basic Usage Examples](../examples/basic_usage.py)
- [Algorithm Comparison](../examples/algorithm_comparison.py)
- [API Reference](https://gconcord.readthedocs.io/) (when available)

## Building Documentation

To build the full documentation locally:

```bash
pip install sphinx sphinx_rtd_theme
cd docs
make html
```

The built documentation will be in `_build/html/`.

## Algorithm Overview

### CONCORD Algorithms

1. **Coordinate Descent** (`algorithm='coordinate'`)
   - Standard coordinate descent implementation
   - Best for large, sparse problems
   - Three variants: standard, high-dimensional, BLAS-optimized

2. **ISTA** (`algorithm='ista'`)
   - Iterative Shrinkage-Thresholding Algorithm
   - Matrix-level proximal gradient method
   - Best convergence for small problems

### Symmetric Lasso Algorithms

1. **Symmetric Lasso** (`symlasso()`)
   - Alternative formulation with auxiliary variables
   - Efficient diagonal updates
   - Two variants: standard and with iterate tracking

### Automatic Selection

- `algorithm='auto'` selects based on problem characteristics

## Mathematical Background

All algorithms solve variations of the sparse precision matrix problem:

```
minimize_Ω  -log det(Ω) + tr(SΩ) + λ||Ω||₁
subject to  Ω ≻ 0
```

Where:
- Ω is the precision matrix (inverse covariance)
- S is the sample covariance matrix
- λ controls sparsity
- ||·||₁ is the element-wise L1 norm

## Performance Tips

1. **Problem Size**
   - Small problems: Use ISTA
   - Medium problems: Use coordinate_blas
   - Large problems: Use coordinate descent

2. **High-Dimensional Data**
   - When n < p, use `algorithm='coordinate_high_dim'`
   - Provides efficient residual updates

3. **Memory Usage**
   - Results are returned as scipy sparse matrices
   - Use `save_iterates=False` to reduce memory usage

4. **Convergence**
   - Adjust `tolerance` for speed vs accuracy tradeoff
   - Use `verbose=True` to monitor convergence

## References

- Khare, Oh, and Rajaratnam (2015). A convex pseudo-likelihood framework for high dimensional partial correlation estimation with convergence guarantees. JRSS.
- Original CONCORD R package: https://cran.r-project.org/package=gconcord
- Original Python implementation: https://github.com/tcnlab/gconcord