Fix Smoothness examples and correct SPARC interpretation in documentation

Author: sanketsabharwal

docs/user_guide/theoretical_framework/low_level/smoothness.md

@@ -121,11 +121,11 @@ import numpy as np
 
 # Initialize analyzer
 smoothness = Smoothness(rate_hz=100.0)
-window = SlidingWindow(window_size=200)
+window = SlidingWindow(max_length=200, n_columns=1)
 
-# Add motion data (3D coordinates)
-for frame in motion_data:
-    window.add_frame(frame)
+# Add motion data (velocity values)
+for value in motion_data:
+    window.append([value])
 
     if len(window) >= 5:  # Minimum data requirement
         metrics = smoothness(window)
@@ -141,12 +141,15 @@ conditions = ['baseline', 'fatigue', 'recovery']
 smoothness_data = {}
 
 for condition in conditions:
-    data = load_condition_data(condition)
-    metrics = smoothness(data)
+    motion_data = load_condition_data(condition)
+    window = SlidingWindow(max_length=200, n_columns=1)
+    for value in motion_data:
+        window.append([value])
+    metrics = smoothness(window)
     smoothness_data[condition] = metrics['sparc']
 
-# Lower SPARC values indicate smoother movement
-print(f"Smoothest condition: {min(smoothness_data, key=smoothness_data.get)}")
+# SPARC closer to 0 indicates smoother movement
+print(f"Smoothest condition: {max(smoothness_data, key=smoothness_data.get)}")
 ```
 
 ## References

pyeyesweb/mid_level/smoothness.py

@@ -52,6 +52,11 @@ class Smoothness:
     --------
     >>> from pyeyesweb.mid_level.smoothness import Smoothness
     >>> from pyeyesweb.data_models.sliding_window import SlidingWindow
+    >>> import numpy as np
+    >>>
+    >>> # Generate sample movement data (simulated velocity profile)
+    >>> t = np.linspace(0, 2, 200)
+    >>> movement_data = np.sin(2 * np.pi * t) + 0.1 * np.random.randn(200)
     >>>
     >>> smooth = Smoothness(rate_hz=100.0, use_filter=True)
     >>> window = SlidingWindow(max_length=200, n_columns=1)
@@ -65,7 +70,7 @@ class Smoothness:
 
     Notes
     -----
-    1. SPARC: More negative values indicate smoother movement
+    1. SPARC: Values closer to 0 indicate smoother movement (less negative = smoother)
     2. Jerk RMS: Lower values indicate smoother movement
     3. Requires at least 5 samples for meaningful analysis
 
@@ -109,7 +114,7 @@ def __call__(self, sliding_window: SlidingWindow):
         -------
         dict
             Dictionary containing:
-            - 'sparc': Spectral Arc Length (more negative = smoother).
+            - 'sparc': Spectral Arc Length (closer to 0 = smoother).
                       Returns NaN if insufficient data.
             - 'jerk_rms': RMS of jerk (third derivative).
                          Returns NaN if insufficient data.