condreg 0.1.3

Condition Number Regularized Covariance Estimation

CondReg: Condition-Number-Regularized Covariance Estimation

A Python package for condition-number-regularized covariance estimation, based on Won et al. (2013). This package provides high-performance implementations with cross-platform support for Windows, macOS, and Linux.

Authors

Lixing Guo, Sang Yun Oh

Installation

Quick Installation (Recommended)

pip install condreg

Platform-Specific Requirements

Windows

• Python: 3.6 or later
• Build Tools: Visual Studio 2019 or later (or Build Tools for Visual Studio)
• CMake: 3.12 or later
• Eigen3: Automatically detected or install via vcpkg

# Install via vcpkg (recommended)
vcpkg install eigen3

# Or set environment variable if manually installed
set EIGEN_INCLUDE_DIR=C:\path\to\eigen3\include

macOS

• Python: 3.6 or later
• Xcode Command Line Tools: xcode-select --install
• CMake: brew install cmake
• Eigen3: brew install eigen

# Install dependencies
brew install cmake eigen

# Install package
pip install condreg

Linux (Ubuntu/Debian)

• Python: 3.6 or later
• Build essentials: sudo apt-get install build-essential cmake
• Eigen3: sudo apt-get install libeigen3-dev

# Install dependencies
sudo apt-get update
sudo apt-get install build-essential cmake libeigen3-dev

# Install package
pip install condreg

Linux (CentOS/RHEL/Fedora)

# CentOS/RHEL
sudo yum install gcc-c++ cmake eigen3-devel

# Fedora
sudo dnf install gcc-c++ cmake eigen3-devel

# Install package
pip install condreg

Building from Source

If you need to build from source or encounter installation issues:

# Clone the repository
git clone https://github.com/dddlab/CondReg.git
cd CondReg/condreg-py-interface

# Build C++ library (cross-platform script)
python build_cpp.py

# Install Python package
pip install -e .

Environment Variables

You can set these environment variables to customize the build:

• EIGEN_INCLUDE_DIR: Path to Eigen3 headers (if not in standard location)
• CMAKE_GENERATOR: CMake generator to use (e.g., "Ninja", "Unix Makefiles")

Features

• Cross-Platform Support: Works on Windows, macOS, and Linux
• High Performance: Core algorithms implemented in C++ with Eigen for speed
• Condition Number Regularization: Implementation of the algorithm from Won et al. (2013)
• Solution Paths: Computation of regularization paths for multiple penalty parameters
• Portfolio Optimization: Tools for portfolio weight calculation and transaction cost estimation
• NumPy Integration: Seamless integration with NumPy arrays

Quickstart

import numpy as np
import condreg

# Generate synthetic data
n = 100  # samples
p = 20   # features
X = np.random.randn(n, p)

# Generate a grid of condition number bounds
k_grid = condreg.kgrid(gridmax=100.0, numpts=50)

# Estimate covariance with cross-validation
result = condreg.select_condreg(X, k_grid)

# Extract results
Sigma_hat = result['S']        # Regularized covariance matrix
Omega_hat = result['invS']     # Precision matrix estimate
k_optimal = result['kmax']     # Selected condition number bound

# Direct usage with a known condition number
direct_result = condreg.condreg(X, 10.0)
Sigma_direct = direct_result['S']
Omega_direct = direct_result['invS']

# Compute optimal portfolio weights
weights = condreg.pfweights(Sigma_hat)

Troubleshooting

Common Installation Issues

1. CMake not found: Install CMake using your system package manager
2. Eigen3 not found: Install Eigen3 or set EIGEN_INCLUDE_DIR environment variable
3. Compiler errors on Windows: Install Visual Studio Build Tools
4. Permission errors: Use pip install --user condreg for user-local installation

Platform-Specific Notes

• Windows: Requires Visual Studio 2019 or later for C++ compilation
• macOS: Requires Xcode Command Line Tools
• Linux: Requires GCC 7+ or Clang 5+ with C++14 support

API Reference

condreg.kgrid(gridmax, numpts)

Return a vector of grid of penalties for cross-validation.

• Parameters:
  • gridmax (float): Maximum value in penalty grid
  • numpts (int): Number of points in penalty grid
• Returns: Array of penalties between 1 and approximately gridmax with logarithmic spacing

condreg.select_condreg(X, k, **kwargs)

Compute the best condition number regularized based on cross-validation selected penalty parameter.

• Parameters:
  • X (numpy.ndarray): n-by-p matrix of data (will be converted to float64)
  • k (numpy.ndarray): Vector of penalties for cross-validation
  • fold (int, optional): Number of folds for cross-validation (default: min(n, 10))
• Returns: Dictionary with keys:
  • S: Condition number regularized covariance matrix
  • invS: Inverse of the regularized covariance matrix
  • kmax: Selected penalty parameter
• Notes: All input arrays are converted to numpy arrays with dtype=float64 internally

condreg.condreg(data_in, kmax)

Compute the condition number with given penalty parameter.

• Parameters:
  • data_in (numpy.ndarray): Input data matrix
  • kmax (float): Scalar regularization parameter
• Returns: Dictionary with keys:
  • S: Condition number regularized covariance matrix
  • invS: Inverse of the regularized covariance matrix

condreg.pfweights(sigma)

Compute optimal portfolio weights.

• Parameters:
  • sigma (numpy.ndarray): Covariance matrix
• Returns: Array of portfolio weights

condreg.transcost(wnew, wold, lastearnings, reltc, wealth)

Compute transaction cost.

• Parameters:
  • wnew (numpy.ndarray): New portfolio weights
  • wold (numpy.ndarray): Old portfolio weights
  • lastearnings (float): Earnings from last period
  • reltc (float): Relative transaction cost
  • wealth (float): Current wealth
• Returns: Transaction cost of rebalancing portfolio

condreg.select_kmax(X, k, fold=None)

Selection of penalty parameter based on cross-validation.

• Parameters:
  • X (numpy.ndarray): n-by-p data matrix
  • k (numpy.ndarray): Vector of penalties for cross-validation
  • fold (int, optional): Number of folds for cross-validation (default: min(n, 10))
• Returns: Dictionary with keys:
  • kmax: Selected penalty parameter
  • negL: Negative log-likelihood values

condreg.init_condreg()

Initialize the CondrReg model. This function returns an instance of the CondrReg class, which provides all the functionality directly. Most users should use the top-level functions instead.

• Returns: CondrReg model instance with methods matching the top-level functions

Citation

@article{won2013condition,
  title={Condition-number-regularized covariance estimation},
  author={Won, Joong-Ho and Lim, Johan and Kim, Seung-Jean and Rajaratnam, Bala},
  journal={Journal of the Royal Statistical Society: Series B (Statistical Methodology)},
  volume={75},
  number={3},
  pages={427--450},
  year={2013},
  publisher={Wiley Online Library},
  doi={10.1111/j.1467-9868.2012.01049.x}
}

References

• Won, J. H., Lim, J., Kim, S. J., & Rajaratnam, B. (2013). Condition-number-regularized covariance estimation. Journal of the Royal Statistical Society: Series B (Statistical Methodology), 75(3), 427–450.
• Original R implementation on GitHub

This package is developed based on the original R implementation by Professor Oh, available at dddlab/CondReg. The core algorithms follow the original work while providing extended functionalities and optimized performance through C++ reimplementation using Eigen library.

License

MIT License. See LICENSE for details.