ngene-fastica 0.1.2

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

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:

(n_signals, n_samples)

Rows are observed mixtures and columns are sample points.

Install locally during development

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

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:

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:

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.