gaitsetpy.features

 49class GaitFeatureExtractor(BaseFeatureExtractor):
 50    """
 51    Comprehensive gait feature extractor class.
 52    
 53    This class extracts various time-domain, frequency-domain, and statistical features
 54    from gait data sliding windows.
 55    """
 56    
 57    def __init__(self, verbose: bool = True):
 58        super().__init__(
 59            name="gait_features",
 60            description="Comprehensive gait feature extractor for time-domain, frequency-domain, and statistical features"
 61        )
 62        self.verbose = verbose
 63        self.config = {
 64            'time_domain': True,
 65            'frequency_domain': True,
 66            'statistical': True,
 67            'ar_order': 3  # Order for auto-regression coefficients
 68        }
 69        
 70        if self.verbose:
 71            print("🚀 GaitFeatureExtractor initialized successfully!")
 72            print(f"📊 Default configuration: {self.config}")
 73    
 74    def extract_features(self, windows: List[Dict], fs: int, **kwargs) -> List[Dict]:
 75        """
 76        Extract gait features from sliding windows.
 77        
 78        Args:
 79            windows: List of sliding window dictionaries
 80            fs: Sampling frequency
 81            **kwargs: Additional arguments including time_domain, frequency_domain, statistical flags
 82            
 83        Returns:
 84            List of feature dictionaries for each sensor
 85        """
 86        # Update config with any passed arguments
 87        time_domain = kwargs.get('time_domain', self.config['time_domain'])
 88        frequency_domain = kwargs.get('frequency_domain', self.config['frequency_domain'])
 89        statistical = kwargs.get('statistical', self.config['statistical'])
 90        ar_order = kwargs.get('ar_order', self.config['ar_order'])
 91        
 92        if self.verbose:
 93            print("\n" + "="*60)
 94            print("🔍 STARTING GAIT FEATURE EXTRACTION")
 95            print("="*60)
 96            print(f"📈 Total sensors/windows to process: {len(windows)}")
 97            print(f"🔊 Sampling frequency: {fs} Hz")
 98            print(f"⏱️  Time domain features: {'✅' if time_domain else '❌'}")
 99            print(f"🌊 Frequency domain features: {'✅' if frequency_domain else '❌'}")
100            print(f"📊 Statistical features: {'✅' if statistical else '❌'}")
101            print(f"🔄 Auto-regression order: {ar_order}")
102            print("-"*60)
103        
104        features = []
105        
106        # Main progress bar for processing all windows
107        main_pbar = tqdm(
108            windows, 
109            desc="🔍 Processing Sensors", 
110            unit="sensor",
111            disable=not self.verbose
112        )
113        
114        for i, window_dict in enumerate(main_pbar):
115            sensor_name = window_dict['name']
116            window_data = window_dict['data']
117            
118            if self.verbose:
119                main_pbar.set_postfix({
120                    'Current': sensor_name,
121                    'Windows': len(window_data) if isinstance(window_data, list) else 1
122                })
123            
124            # Skip annotation windows
125            if sensor_name == 'annotations':
126                if self.verbose:
127                    logger.info(f"📝 Processing annotation data for {sensor_name}")
128                
129                features.append({
130                    'name': sensor_name,
131                    'features': {},
132                    'annotations': [self._extract_annotation_labels(window) for window in window_data]
133                })
134                continue
135            
136            if self.verbose:
137                logger.info(f"🎯 Processing sensor: {sensor_name}")
138                logger.info(f"📦 Number of windows: {len(window_data)}")
139            
140            sensor_features = {'name': sensor_name, 'features': {}}
141            
142            # Time domain features
143            if time_domain:
144                if self.verbose:
145                    print(f"  ⏱️  Extracting time domain features for {sensor_name}...")
146                
147                time_features = self._extract_time_domain_features(window_data)
148                sensor_features['features'].update(time_features)
149                
150                if self.verbose:
151                    feature_count = sum(len(v) if isinstance(v, list) else 1 for v in time_features.values())
152                    print(f"  ✅ Time domain: {len(time_features)} feature types, {feature_count} total features")
153            
154            # Frequency domain features
155            if frequency_domain:
156                if self.verbose:
157                    print(f"  🌊 Extracting frequency domain features for {sensor_name}...")
158                
159                freq_features = self._extract_frequency_domain_features(window_data, fs)
160                sensor_features['features'].update(freq_features)
161                
162                if self.verbose:
163                    feature_count = sum(len(v) if isinstance(v, list) else 1 for v in freq_features.values())
164                    print(f"  ✅ Frequency domain: {len(freq_features)} feature types, {feature_count} total features")
165            
166            # Statistical features
167            if statistical:
168                if self.verbose:
169                    print(f"  📊 Extracting statistical features for {sensor_name}...")
170                
171                stat_features = self._extract_statistical_features(window_data)
172                sensor_features['features'].update(stat_features)
173                
174                if self.verbose:
175                    feature_count = sum(len(v) if isinstance(v, list) else 1 for v in stat_features.values())
176                    print(f"  ✅ Statistical: {len(stat_features)} feature types, {feature_count} total features")
177            
178            # Auto-regression coefficients
179            if self.verbose:
180                print(f"  🔄 Extracting auto-regression coefficients for {sensor_name}...")
181            
182            ar_features = self._extract_ar_coefficients(window_data, ar_order)
183            sensor_features['features'].update(ar_features)
184            
185            if self.verbose:
186                feature_count = sum(len(v) if isinstance(v, list) else 1 for v in ar_features.values())
187                print(f"  ✅ Auto-regression: {len(ar_features)} feature types, {feature_count} total features")
188            
189            # Calculate total features for this sensor
190            total_features = sum(
191                len(v) if isinstance(v, list) else 1 
192                for v in sensor_features['features'].values()
193            )
194            
195            if self.verbose:
196                print(f"  🎯 Total features extracted for {sensor_name}: {total_features}")
197                print(f"  📋 Feature types: {list(sensor_features['features'].keys())}")
198                print("-"*40)
199            
200            features.append(sensor_features)
201        
202        if self.verbose:
203            print("\n" + "="*60)
204            print("🎉 FEATURE EXTRACTION COMPLETED!")
205            print("="*60)
206            print(f"📊 Total sensors processed: {len(features)}")
207            
208            # Calculate overall statistics
209            total_feature_count = 0
210            for feature_dict in features:
211                if 'features' in feature_dict:
212                    total_feature_count += sum(
213                        len(v) if isinstance(v, list) else 1 
214                        for v in feature_dict['features'].values()
215                    )
216            
217            print(f"🔢 Total features extracted: {total_feature_count}")
218            print(f"📈 Average features per sensor: {total_feature_count / len(features):.1f}")
219            print("="*60)
220        
221        return features
222    
223    def _extract_time_domain_features(self, windows: List) -> Dict[str, List]:
224        """Extract time domain features from windows."""
225        if self.verbose:
226            print("    🔍 Computing time domain features...")
227        
228        time_features = {}
229        
230        # Define time domain feature functions
231        time_domain_funcs = {
232            'mean': calculate_mean,
233            'std': calculate_standard_deviation,
234            'variance': calculate_variance,
235            'rms': calculate_root_mean_square,
236            'range': calculate_range,
237            'median': calculate_median,
238            'mode': calculate_mode,
239            'mean_absolute_value': calculate_mean_absolute_value,
240            'median_absolute_deviation': calculate_median_absolute_deviation,
241            'peak_height': calculate_peak_height,
242            'zero_crossing_rate': calculate_zero_crossing_rate,
243            'energy': calculate_energy,
244        }
245        
246        # Progress bar for time domain features
247        feature_pbar = tqdm(
248            time_domain_funcs.items(), 
249            desc="    ⏱️  Time features", 
250            unit="feature",
251            leave=False,
252            disable=not self.verbose
253        )
254        
255        for feature_name, func in feature_pbar:
256            if self.verbose:
257                feature_pbar.set_postfix({'Computing': feature_name})
258            
259            time_features[feature_name] = [
260                func(self._ensure_numpy_array(window)) for window in windows
261            ]
262        
263        return time_features
264    
265    def _ensure_numpy_array(self, signal):
266        """Convert pandas Series to numpy array if needed."""
267        if hasattr(signal, 'values'):
268            return signal.values
269        return signal
270    
271    def _extract_frequency_domain_features(self, windows: List, fs: int) -> Dict[str, List]:
272        """Extract frequency domain features from windows."""
273        if self.verbose:
274            print("    🔍 Computing frequency domain features...")
275        
276        freq_features = {}
277        
278        # Define frequency domain feature functions
279        freq_domain_funcs = {
280            'dominant_frequency': lambda w: calculate_dominant_frequency(w, fs),
281            'peak_frequency': lambda w: calculate_peak_frequency(w, fs),
282            'power_spectral_entropy': lambda w: calculate_power_spectral_entropy(w, fs),
283            'principal_harmonic_frequency': lambda w: calculate_principal_harmonic_frequency(w, fs),
284            'stride_times': lambda w: calculate_stride_times(w, fs),
285            'step_time': lambda w: calculate_step_time(w, fs),
286            'cadence': lambda w: calculate_cadence(w, fs),
287            'freezing_index': lambda w: calculate_freezing_index(w, fs),
288        }
289        
290        # Progress bar for frequency domain features
291        feature_pbar = tqdm(
292            freq_domain_funcs.items(), 
293            desc="    🌊 Freq features", 
294            unit="feature",
295            leave=False,
296            disable=not self.verbose
297        )
298        
299        for feature_name, func in feature_pbar:
300            if self.verbose:
301                feature_pbar.set_postfix({'Computing': feature_name})
302            
303            freq_features[feature_name] = [
304                func(self._ensure_numpy_array(window)) for window in windows
305            ]
306        
307        return freq_features
308    
309    def _extract_statistical_features(self, windows: List) -> Dict[str, List]:
310        """Extract statistical features from windows."""
311        if self.verbose:
312            print("    🔍 Computing statistical features...")
313        
314        stat_features = {}
315        
316        # Define statistical feature functions
317        stat_funcs = {
318            'skewness': calculate_skewness,
319            'kurtosis': calculate_kurtosis,
320            'entropy': calculate_entropy,
321            'interquartile_range': calculate_interquartile_range,
322        }
323        
324        # Progress bar for statistical features
325        feature_pbar = tqdm(
326            stat_funcs.items(), 
327            desc="    📊 Stat features", 
328            unit="feature",
329            leave=False,
330            disable=not self.verbose
331        )
332        
333        for feature_name, func in feature_pbar:
334            if self.verbose:
335                feature_pbar.set_postfix({'Computing': feature_name})
336            
337            stat_features[feature_name] = [
338                func(self._ensure_numpy_array(window)) for window in windows
339            ]
340        
341        # Handle correlation separately (needs two signals)
342        if self.verbose:
343            print("      🔗 Computing correlation features...")
344        
345        stat_features['correlation'] = [
346            calculate_correlation(
347                self._ensure_numpy_array(window)[:-1], 
348                self._ensure_numpy_array(window)[1:]
349            ) if len(window) > 1 else 0 
350            for window in windows
351        ]
352        
353        return stat_features
354    
355    def _extract_ar_coefficients(self, windows: List, order: int) -> Dict[str, List]:
356        """Extract auto-regression coefficients from windows."""
357        if self.verbose:
358            print(f"    🔍 Computing auto-regression coefficients (order={order})...")
359        
360        # Progress bar for AR coefficients
361        ar_pbar = tqdm(
362            windows, 
363            desc="    🔄 AR coeffs", 
364            unit="window",
365            leave=False,
366            disable=not self.verbose
367        )
368        
369        ar_coeffs = []
370        for window in ar_pbar:
371            coeffs = calculate_auto_regression_coefficients(
372                self._ensure_numpy_array(window), order
373            )
374            ar_coeffs.append(coeffs)
375        
376        return {'ar_coefficients': ar_coeffs}
377    
378    def _extract_annotation_labels(self, window) -> int:
379        """Extract the most common annotation label from a window."""
380        if hasattr(window, 'mode'):
381            return window.mode().iloc[0] if len(window.mode()) > 0 else 0
382        else:
383            # For numpy arrays or other types
384            unique, counts = np.unique(window, return_counts=True)
385            return unique[np.argmax(counts)]
386    
387    def get_feature_names(self) -> List[str]:
388        """
389        Get names of all features that can be extracted.
390        
391        Returns:
392            List of feature names
393        """
394        time_domain_features = [
395            'mean', 'std', 'variance', 'rms', 'range', 'median', 'mode',
396            'mean_absolute_value', 'median_absolute_deviation', 'peak_height',
397            'zero_crossing_rate', 'energy'
398        ]
399        
400        frequency_domain_features = [
401            'dominant_frequency', 'peak_frequency', 'power_spectral_entropy',
402            'principal_harmonic_frequency', 'stride_times', 'step_time',
403            'cadence', 'freezing_index'
404        ]
405        
406        statistical_features = [
407            'skewness', 'kurtosis', 'entropy', 'interquartile_range', 'correlation'
408        ]
409        
410        other_features = ['ar_coefficients']
411        
412        return time_domain_features + frequency_domain_features + statistical_features + other_features
413
414    def print_extraction_summary(self, features: List[Dict]) -> None:
415        """
416        Print a detailed summary of extracted features.
417        
418        Args:
419            features: List of feature dictionaries returned by extract_features
420        """
421        print("\n" + "="*80)
422        print("📊 FEATURE EXTRACTION SUMMARY")
423        print("="*80)
424        
425        for i, feature_dict in enumerate(features):
426            sensor_name = feature_dict['name']
427            print(f"\n🎯 Sensor {i+1}: {sensor_name}")
428            print("-" * 40)
429            
430            if 'features' in feature_dict and feature_dict['features']:
431                for feature_type, feature_values in feature_dict['features'].items():
432                    if isinstance(feature_values, list):
433                        print(f"  📈 {feature_type}: {len(feature_values)} values")
434                        if feature_values:
435                            sample_value = feature_values[0]
436                            if isinstance(sample_value, (list, np.ndarray)):
437                                print(f"    └── Shape per window: {np.array(sample_value).shape}")
438                            else:
439                                print(f"    └── Sample value: {sample_value:.4f}")
440                    else:
441                        print(f"  📈 {feature_type}: {feature_values}")
442            
443            if 'annotations' in feature_dict:
444                print(f"  📝 Annotations: {len(feature_dict['annotations'])} windows")
445        
446        print("\n" + "="*80)

 26class LBPFeatureExtractor(BaseFeatureExtractor):
 27    """
 28    Local Binary Pattern (LBP) feature extractor for VGRF data.
 29    
 30    This extractor converts time-series data into LBP codes and extracts
 31    histogram features from the LBP representation.
 32    """
 33    
 34    def __init__(self, verbose: bool = True):
 35        super().__init__(
 36            name="lbp_features",
 37            description="Local Binary Pattern feature extractor for VGRF time-series data"
 38        )
 39        self.verbose = verbose
 40        self.config = {
 41            'radius': 2,  # LBP radius (number of neighbors)
 42            'n_bins': 256,  # Number of histogram bins
 43            'normalize': True  # Normalize histogram
 44        }
 45        
 46        if self.verbose:
 47            print("🔍 LBP Feature Extractor initialized!")
 48    
 49    def lbp_1d(self, data: np.ndarray, radius: int = 2) -> str:
 50        """
 51        Compute 1D Local Binary Pattern for time-series data.
 52        
 53        Args:
 54            data: Input time-series data
 55            radius: Radius for LBP computation
 56            
 57        Returns:
 58            LBP code as binary string
 59        """
 60        n = len(data)
 61        lbp_code = ''
 62        
 63        for i in range(n):
 64            pattern = ''
 65            for j in range(i - radius, i + radius + 1):
 66                if j < 0 or j >= n:
 67                    pattern += '0'
 68                elif data[j] >= data[i]:
 69                    pattern += '1'
 70                else:
 71                    pattern += '0'
 72            lbp_code += pattern
 73        
 74        return lbp_code
 75    
 76    def lbp_to_histogram(self, lbp_code: str, n_bins: int = 256, normalize: bool = True) -> np.ndarray:
 77        """
 78        Convert LBP code to histogram features.
 79        
 80        Args:
 81            lbp_code: Binary LBP code string
 82            n_bins: Number of histogram bins
 83            normalize: Whether to normalize histogram
 84            
 85        Returns:
 86            Histogram features as numpy array
 87        """
 88        # Convert LBP code to integer values
 89        if len(lbp_code) == 0:
 90            return np.zeros(n_bins)
 91        
 92        # Process LBP code in chunks of 8 bits (or smaller)
 93        chunk_size = 8
 94        lbp_values = []
 95        
 96        for i in range(0, len(lbp_code), chunk_size):
 97            chunk = lbp_code[i:i + chunk_size]
 98            if len(chunk) > 0:
 99                # Convert binary string to integer
100                try:
101                    value = int(chunk, 2)
102                    lbp_values.append(value % n_bins)  # Ensure within bin range
103                except ValueError:
104                    continue
105        
106        if len(lbp_values) == 0:
107            return np.zeros(n_bins)
108        
109        # Create histogram
110        hist, _ = np.histogram(lbp_values, bins=n_bins, range=(0, n_bins))
111        
112        if normalize and np.sum(hist) > 0:
113            hist = hist / np.sum(hist)
114        
115        return hist
116    
117    def extract_features(self, windows: List[Dict], fs: int, **kwargs) -> List[Dict]:
118        """
119        Extract LBP features from sliding windows.
120        
121        Args:
122            windows: List of sliding window dictionaries
123            fs: Sampling frequency (unused for LBP)
124            **kwargs: Additional arguments
125            
126        Returns:
127            List of feature dictionaries
128        """
129        # Update config with any passed arguments
130        radius = kwargs.get('radius', self.config['radius'])
131        n_bins = kwargs.get('n_bins', self.config['n_bins'])
132        normalize = kwargs.get('normalize', self.config['normalize'])
133        
134        if self.verbose:
135            print(f"\n🔍 LBP Feature Extraction")
136            print(f"📊 Radius: {radius}, Bins: {n_bins}, Normalize: {normalize}")
137        
138        features = []
139        
140        for window_dict in tqdm(windows, desc="Processing LBP features", disable=not self.verbose):
141            sensor_name = window_dict['name']
142            window_data = window_dict['data']
143            
144            # Skip annotation windows
145            if sensor_name == 'annotations':
146                continue
147            
148            sensor_features = {'name': sensor_name, 'features': {}}
149            
150            # Extract LBP features for each window
151            lbp_histograms = []
152            lbp_means = []
153            lbp_stds = []
154            
155            for window in window_data:
156                # Ensure window is numpy array
157                if hasattr(window, 'values'):
158                    window = window.values
159                
160                # Compute LBP
161                lbp_code = self.lbp_1d(window, radius)
162                
163                # Convert to histogram
164                hist = self.lbp_to_histogram(lbp_code, n_bins, normalize)
165                lbp_histograms.append(hist)
166                
167                # Extract summary statistics
168                lbp_means.append(np.mean(hist))
169                lbp_stds.append(np.std(hist))
170            
171            # Store features
172            sensor_features['features'] = {
173                'lbp_histograms': lbp_histograms,
174                'lbp_mean': lbp_means,
175                'lbp_std': lbp_stds,
176                'lbp_energy': [np.sum(hist**2) for hist in lbp_histograms],
177                'lbp_entropy': [self._calculate_entropy(hist) for hist in lbp_histograms]
178            }
179            
180            features.append(sensor_features)
181        
182        return features
183    
184    def _calculate_entropy(self, hist: np.ndarray) -> float:
185        """Calculate entropy of histogram."""
186        # Avoid log(0) by adding small value
187        hist = hist + 1e-10
188        return -np.sum(hist * np.log2(hist))
189    
190    def get_feature_names(self) -> List[str]:
191        """Get names of LBP features."""
192        return [
193            'lbp_histograms', 'lbp_mean', 'lbp_std', 
194            'lbp_energy', 'lbp_entropy'
195        ]