Metadata-Version: 2.4
Name: icalcc
Version: 0.1.3
Summary: Locally centered contrast functions for scikit-learn FastICA
Author-email: Tetsuya Saito <ted@kleinverse.io>
License-Expression: CC-BY-4.0
Project-URL: Repository, https://github.com/Kleinverse/icalcc
Project-URL: GPU Extension, https://github.com/Kleinverse/gpuicalcc
Project-URL: Research, https://github.com/Kleinverse/research
Keywords: ICA,independent component analysis,blind source separation,locally centered contrast,cumulants,higher-order statistics,Renyi entropy,FastICA,scikit-learn
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: scikit-learn>=1.3
Dynamic: license-file

# icalcc
Locally centered contrast functions for scikit-learn FastICA.
Drop-in replacement for `sklearn.decomposition.FastICA` with
bounded LCC-tanh and LCC-exp contrasts, plus polynomial LCC
contrasts of order 4, 6, and 8.
```python
from icalcc import ICALCC
ica = ICALCC(n_components=4, K='ltanh', random_state=0)
S_hat = ica.fit_transform(X)
```

## Installation
```bash
pip install icalcc
```

## Supported K Values
| K | Description |
|---|---|
| `'ltanh'` | Bounded LCC-tanh (robust to heavy tails and skewness) |
| `'lexp'` | Bounded LCC-exp (maximizes Rényi-2 entropy) |
| `4` | Polynomial LCC order 4 |
| `6` | Polynomial LCC order 6, couples m₃, m₄, m₆ |
| `8` | Polynomial LCC order 8, couples moments up to order 8 |
| `'tanh'` | Classical logcosh contrast (scikit-learn default) |
| `'exp'` | Classical Gaussian contrast |
| `'skew'` | Classical cube contrast |

## Usage
```python
from icalcc import ICALCC

# Bounded LCC-tanh (recommended for heavy-tailed or skewed sources)
ica = ICALCC(n_components=4, K='ltanh', random_state=0)
S_hat = ica.fit_transform(X)

# Bounded LCC-exp (Rényi-2 entropy interpretation)
ica = ICALCC(n_components=4, K='lexp', random_state=0)
S_hat = ica.fit_transform(X)

# Polynomial LCC order 8 (near-Gaussian sources)
ica = ICALCC(n_components=4, K=8, random_state=0)
S_hat = ica.fit_transform(X)

# Classical FastICA baseline
ica = ICALCC(n_components=4, K='tanh', random_state=0)
S_hat = ica.fit_transform(X)
```

## Convergence tracking
```python
ica.fit(X)
print(ica.converged_)  # True if all components converged
```

## See Also
- [gpuicalcc](https://github.com/Kleinverse/gpuicalcc) —
  PyTorch GPU-accelerated extension (40–48× speedup for bounded contrasts)
- [Experiment code](https://github.com/Kleinverse/research/tree/main/icalcc)

## Requirements
- Python ≥ 3.9
- numpy ≥ 1.24
- scikit-learn ≥ 1.3

## Citation

If you use this package, please cite both the software paper and
the underlying LCC kernel paper:
```bibtex
@article{saito2026icalcc,
  author  = {Saito, Tetsuya},
  title   = {{ICALCC}: Locally Centered Contrast Functions for
             {FastICA} with {GPU} Acceleration},
  journal = {TechRxiv},
  year    = {2026}
}

@article{saito2026lcc,
  author  = {Saito, Tetsuya},
  title   = {Locally Centered Cyclic Kernels for Higher-Order
             Independent Component Analysis},
  journal = {TechRxiv},
  year    = {2026}
}
```

## License
[CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)
