Metadata-Version: 2.4
Name: ngene-fastica
Version: 0.1.2
Summary: A lightweight, heavily annotated FastICA implementation for educational and local waveform separation demos.
Author-email: Hyunsuk Frank Roh <frank@ngene.org>
Project-URL: Homepage, https://ngene.org/waveform.html
Project-URL: Demo, https://ngene.org/waveform.html
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering
Classifier: Intended Audience :: Education
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.22
Dynamic: license-file

# nGene FastICA

A lightweight, heavily annotated FastICA implementation for educational signal separation and local waveform separation demos.

This package keeps the FastICA engine simple and local. Version `0.1.2` restores and expands the human-readable explanatory comments around the core algorithm so that the code can be studied as an educational implementation, not only used as a black-box function.

## What this package does

Fast Independent Component Analysis (FastICA) separates observed mixed signals into estimated independent source components. Typical examples include synthetic waveform separation, auditory signal demos, and educational blind-source-separation experiments.

Input shape convention:

```text
(n_signals, n_samples)
```

Rows are observed mixtures and columns are sample points.

## Install locally during development

```bash
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
python -m pip install --upgrade pip
python -m pip install -e .
```

## Basic usage

```python
import numpy as np
from ngene_fastica import FastICA

# Shape convention: rows are observed mixtures, columns are samples.
X = np.random.randn(3, 10000)
S = FastICA(n_components=3, random_state=42).fit_transform(X)
print(S.shape)
```

## Backward-compatible usage

The original educational script used `num_sources`, `max_iterations`, `tolerance`, and `decompose_mixtures()`. These names are supported as aliases:

```python
from ngene_fastica import FastICA

ica = FastICA(num_sources=3, max_iterations=500, tolerance=1e-5, random_state=42)
source_signals = ica.decompose_mixtures(signal_mixtures)
```

## Local waveform separation demo

After local installation:

```bash
ngene-fastica-demo
```

The demo writes WAV files for generated sources, mixed signals, and separated signals. ICA recovers sources up to permutation and sign, so the separated files may not match the original source order exactly.

## Educational notes in the source code

The core implementation in `src/ngene_fastica/fastica.py` now includes step-by-step explanatory comments for:

- input shape convention;
- centering;
- covariance estimation;
- eigenvalue decomposition;
- whitening;
- random unmixing-matrix initialization;
- fixed-point FastICA iteration;
- `tanh` non-linearity and derivative;
- symmetric decorrelation by SVD;
- sign-invariant convergence;
- final source extraction through `components_`.

## Notes

- Input shape is `(n_signals, n_samples)`.
- The implementation uses NumPy only; SciPy is not required.
- This is intended as a lightweight educational/demo package, not a replacement for mature scientific packages.
- ICA output has sign and permutation ambiguity by design.
