HTFA Hierarchical Algorithm Implementation #75
Description
Task 002: HTFA Hierarchical Algorithm Implementation
Description
Implement the Hierarchical Topographic Factor Analysis (HTFA) algorithm that extends TFA to handle multi-subject data with global template optimization and factor matching across subjects.
The HTFA class should coordinate multiple TFA instances, optimize a shared global template, and provide mechanisms for matching factors across subjects while maintaining the scikit-learn interface.
Acceptance Criteria
- HTFA class inherits from sklearn.base.BaseEstimator and TransformerMixin
- Implements fit(X) method for multi-subject factor learning
- Implements transform(X) method that projects new subjects onto global template
- Multi-subject optimization with global template convergence
- Factor matching algorithm to align factors across subjects
- Hierarchical optimization alternating between subjects and global level
- Handles variable numbers of subjects and timepoints per subject
- Validates multi-subject input data format and dimensions
- Passes comprehensive tests with synthetic multi-subject data
- Algorithm converges to stable global template and subject-specific factors
- Results are deterministic given same random seed
Technical Details
Core Components
- Global Template: Shared spatial templates optimized across all subjects
- Subject-Specific Factors: Individual temporal factors for each subject
- Factor Matching: Hungarian algorithm or correlation-based matching across subjects
- Hierarchical Optimization: Alternates between subject-level TFA and global template updates
Key Parameters
n_factors: Number of global factors (default: 10)max_iter: Maximum hierarchical iterations (default: 50)tfa_max_iter: Maximum TFA iterations per subject (default: 100)tol: Global convergence tolerance (default: 1e-6)match_method: Factor matching method ('hungarian' or 'correlation')random_state: Random seed for reproducibility
Data Format
- Input: List of 3D arrays [(voxels, timepoints)] or 4D array (subjects, voxels, timepoints)
- Output: Global templates (n_factors, n_voxels), subject factors [(n_factors, n_timepoints)]
Optimization Strategy
- Initialize with single-subject TFA on concatenated or averaged data
- Iterate: fit individual TFA models, match factors, update global template
- Use weighted averaging for global template updates
- Handle missing subjects or incomplete data gracefully
Factor Matching
- Compute correlation matrix between subject factors and global template
- Apply Hungarian algorithm for optimal factor assignment
- Handle sign flips and scaling differences between subjects
- Maintain factor ordering consistency across iterations
Dependencies
- Task 001 (Core TFA Algorithm Implementation)
- numpy for numerical computations
- scipy.optimize for optimization algorithms
- scipy.optimize.linear_sum_assignment for Hungarian matching
- sklearn.base for estimator interface
Effort Estimate
Size: XL (3-4 days)
Breakdown:
- Algorithm design and factor matching research: 1 day
- Core HTFA implementation: 2 days
- Multi-subject testing and validation: 1 day
Definition of Done
- HTFA class implemented in
htfa/core/htfa.py - Full scikit-learn estimator interface compliance
- Comprehensive unit tests in
tests/unit/core/test_htfa.py - Algorithm converges on synthetic multi-subject data
- Factor matching produces consistent assignments across subjects
- Global template stabilizes within expected iterations
- Code passes all linting and type checking
- Documentation strings follow Google style guide
- Integration tests with TFA class work correctly
- No regression in existing test suite