PyComplexity-ACI 0.1.0__py3-none-any.whl

PyComplexity/__init__.py

@@ -0,0 +1,3 @@
+__version__ = "0.1.0"
+
+from .aci import compute_aci

PyComplexity/aci.py

@@ -0,0 +1,195 @@
+# Version
+__author__ = 'Cyrille E. Mvomo, https://github.com/cyrillemvomo/PyComplexity'
+__version__ = "0.1.0"
+__license__ = "MIT"
+
+# Importations 
+import numpy as np
+import plotly.graph_objects as go
+from scipy.interpolate import make_interp_spline
+
+# Required function
+def makestatelocal(signal, hc, n_dim=5, delay=10):
+    """Get Delay-embedded state space.
+
+    Parameters
+    ----------
+    signal : array_like, shape (T,) (acceleration magnitude recommended, see references at https://github.com/cyrillemvomo/PyComplexity)
+        1D signal.
+    hc : array_like, shape (n_strides,)
+        Heel strike indices (samples).
+    n_dim : int, default=5 (use GFNN to determine based on your data, see https://github.com/cyrillemvomo/PyComplexity)
+        Embedding dimension.
+    delay : int, default=10 (use AMI to determine based on your data, see https://github.com/cyrillemvomo/PyComplexity)
+        Delay in samples.
+
+    Returns
+    -------
+    state : ndarray, shape ( (n_strides-1)*100 - delay*(n_dim-1), n_dim )
+        Delay-embedded state space.
+    """
+
+    signal = np.asarray(signal, dtype=np.float64).reshape(-1)
+    hc = np.asarray(hc, dtype=np.int64).reshape(-1)
+
+    # bounds check
+    if hc.min() < 0 or hc.max() >= signal.size:
+        raise ValueError(
+            f"hc indices out of bounds after conversion. "
+            f"min={hc.min()}, max={hc.max()}, len(signal)={signal.size}. "
+        )
+
+    n_strides = int(hc.size)
+    n_samples = int((n_strides - 1) * 100)
+
+    start = int(hc[0])
+    stop_inclusive = int(hc[-1])
+    signal_new = signal[start:stop_inclusive + 1]
+
+    t_new = np.arange(1, signal_new.size + 1, dtype=np.float64)
+
+    t_interp = (np.arange(1, n_samples + 1, dtype=np.float64) / n_samples) * t_new[-1]
+
+    spline = make_interp_spline(t_new, signal_new, k=3) 
+    signal_interp = spline(t_interp).astype(np.float64)
+
+    # state space
+    out_len = n_samples - delay * (n_dim - 1)
+    if out_len <= 0:
+        raise ValueError(
+            f"Requested embedding is too long: out_len={out_len}. "
+            f"Reduce n_dim and/or delay."
+        )
+
+    state = np.empty((out_len, n_dim), dtype=np.float64)
+
+    for i_dim in range(n_dim):
+        start_idx = i_dim * delay
+        end_cut = (n_dim - 1 - i_dim) * delay
+        col = signal_interp[start_idx:] if end_cut == 0 else signal_interp[start_idx:-end_cut]
+        state[:, i_dim] = col
+
+    return state
+
+
+
+# Main function
+def compute_aci(signal, hc, n_dim=5, delay=10, ws=12, fs=100, period=1, min_val= 5, plot=False):
+    """Get ACI (plot divergence curves optional).
+
+    Parameters
+    ----------
+    signal : array_like, shape (T,) (acceleration magnitude recommended, see references at https://github.com/cyrillemvomo/PyComplexity)
+        1D signal used to get delay-embedded state space.
+    hc : array_like, shape (n_strides,)
+        Heel strike indices (samples) used to get delay-embedded state space. (recommended ~70 steady state consecutive strides minimum, see references at https://github.com/cyrillemvomo/PyComplexity)
+    n_dim : int, default=5 (use GFNN to determine based on your data, see https://github.com/cyrillemvomo/PyComplexity)
+        Embedding dimension used to get delay-embedded state space.
+    delay : int, default=10 (use AMI to determine based on your data, see https://github.com/cyrillemvomo/PyComplexity)
+        Delay in samples used to get delay-embedded state space.
+    ws : int, default=12
+        Upper bound of the window size to track the divergence (gait cycles) (recommended ~5-12 see references at https://github.com/cyrillemvomo/PyComplexity)
+    fs : int, default=10 
+        Sample frequency of the resampled data (100 frames per stride to control for differences in gait speed in case of comparisons)
+    period : int, default=1 
+        Period of the resampled signal is 1 (i.e. 1 stride every 100 samples)
+    min_val : int, default=5 
+        Lower bound of the window size to track the divergence (gait cycles) (recommended ~5-12 see references at https://github.com/cyrillemvomo/PyComplexity)
+    plot : bool, default=False
+        Divergence curve with ACI fit.
+
+    Returns
+    -------
+    aci : float
+        ACI value found.
+
+    Example
+    --------
+    >>> # ACI computation and plot divergence curve fit: 
+    >>> from PyComplexity import compute_aci
+    >>> compute_aci(acc_magnitude, hc_frames, n_dim=5, delay=10, ws=12, fs=100, period=1, min_val= 5, plot=True)
+    """
+
+
+    # avoid common errors
+    if hc.size < 2:
+        raise ValueError("hc must contain at least 2 heel strikes.")
+    if n_dim < 1:
+        raise ValueError("n_dim must be >= 1")
+    if delay < 0:
+        raise ValueError("delay must be >= 0")
+    if (ws > min_val) and (ws < len(hc)+5):
+        raise ValueError("Make sure that (ws > min_val) and (ws < ~len(hc)+10)")
+    
+
+    # get divergence
+    ws_samp = int(np.round(ws * fs))
+
+    state = makestatelocal(signal, hc, n_dim, delay)
+    m, n = state.shape
+
+    state_ext = np.vstack([state, np.full((ws_samp, n), np.nan)])
+    divergence_mat = np.full((m, ws_samp), np.nan)
+    difference = np.full((m + ws_samp, n), np.nan)
+
+    for i_t in range(m):
+        for i_d in range(n):
+            difference[:, i_d] = (state_ext[:, i_d] - state_ext[i_t, i_d]) ** 2
+
+        start_index = int(np.round(max(0, i_t - np.round(0.5 * period * fs))))
+        stop_index = int(np.round(min(m - 1, i_t + np.round(0.5 * period * fs))))
+        difference[start_index:stop_index + 1, :] = np.nan
+        difference[i_t, :] = np.nan  
+
+        dist_sum = np.sum(difference, axis=1)
+        index = int(np.nanargmin(dist_sum))
+
+        diff_vec = state_ext[i_t:i_t + ws_samp, :] - state_ext[index:index + ws_samp, :]
+        divergence_mat[i_t, :] = np.sqrt(np.sum(diff_vec ** 2, axis=1))
+
+    divergence = np.nanmean(np.log(divergence_mat), axis=0)
+
+    # linear fits 
+
+    if ws_samp > min_val * period * fs:
+        L2 = int(np.round(min_val * period * fs))
+        t_long = np.arange(L2 + 1, ws_samp + 1) / fs
+        Pl = np.polyfit(t_long, divergence[L2:], 1)
+    else:
+        L2 = None
+        Pl = np.array([np.nan, np.nan])
+
+    aci = Pl[0]
+
+    # Plotly plot
+    if plot:
+        t_all = np.arange(1, ws_samp + 1) / fs
+
+        fig = go.Figure()
+
+        fig.add_trace(go.Scatter(
+            x=t_all,
+            y=divergence,
+            mode="lines",
+            name="Divergence curve"
+        ))
+
+        if not np.isnan(Pl[0]):
+            fig.add_trace(go.Scatter(
+                x=t_long,
+                y=np.polyval(Pl, t_long),
+                mode="lines",
+                name=f"Lambda L = {Pl[0]:.4f}"
+            ))
+
+        fig.update_layout(
+            title="Divergence curve",
+            xaxis_title="Stride Number",
+            yaxis_title="Ln(divergence)",
+            template="simple_white",
+            hovermode="x unified"
+        )
+
+        fig.show()
+
+    return aci

pycomplexity_aci-0.1.0.dist-info/METADATA

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: PyComplexity-ACI
+Version: 0.1.0
+Summary: A Python module for computing the Attractor Complexity Index (ACI) from lower-back accelerometer time-series during gait.
+Author-email: "Cyrille E. Mvomo" <cyrille.mvomo@mail.mcgill.ca>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/cyrillemvomo/PyComplexity
+Project-URL: Zenodo, https://doi.org/10.5281/zenodo.19324133
+Keywords: gait,biomarker,accelerometry,lyapunov exponent,non-linear dynamics,neural control of locomotion,wearable sensors
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.26.4
+Requires-Dist: scipy>=1.11.4
+Provides-Extra: viz
+Requires-Dist: plotly>=5.18; extra == "viz"
+Dynamic: license-file
+
+<p align="center">
+  <img src="src/PyComplexity/Logo.jpg" alt="PyComplexity Logo" width="1000"/>
+</p>
+
+# Python module for computing the Attractor Complexity Index (ACI), a non-linear measure of gait automaticity
+
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.19324133.svg)](https://doi.org/10.5281/zenodo.19324133) ![visitors](https://visitor-badge.laobi.icu/badge?page_id=cyrillemvomo.PyComplexity)<!-- omit in toc -->
+
+The Attractor Complexity Index (ACI) corresponds to the long-term largest Lyapunov exponent derived from gait dynamics. Initially introduced as a measure of gait stability, it is now increasingly recognized as a marker of gait automaticity across conditions of graded complexity.
+
+ACI quantifies the divergence of trajectories in the reconstructed state space, capturing deviations from stereotyped locomotor patterns. These deviations may arise from external perturbations (e.g., auditory cueing) or internal disturbances (e.g., neural dysfunction). As such, ACI provides a compact representation of how gait departs from fully automated control.
+
+This measure is highly promising in geriatrics and neurological populations, where it can serve as a behavioural proxy of alterations in underlying gait control networks.
+
+<p align="center">
+  <img src="src/PyComplexity/Description_Illustration.jpg" alt="Workflow Illustration" width="1000"/>
+</p>
+
+PyComplexity implements a suite of core functions commonly used in the estimation of Lyapunov exponents in gait analysis. The current implementation is adapted from the public MATLAB codebase (https://github.com/SjoerdBruijn/LocalDynamicStability). 
+
+This library translates these methods into Python to facilitate broader access to ACI computation in an open-source environment, particularly for researchers with limited resources or technical background.
+
+The current version provides a minimal and reproducible pipeline for deriving ACI from lower-back accelerometer time-series during gait, using fixed embedding parameters.
+
+Planned updates for Summer 2026 will extend the framework to include data-driven phase space reconstruction, with Python implementations of Global False Nearest Neighbours for optimal embedding dimension selection and Average Mutual Information for time delay estimation. These additions will be based on the following MATLAB implementation (https://github.com/danm0nster/mdembedding).
+
+
+## Installation
+
+```python
+pip install PyComplexity
+```
+
+## Example
+
+```python
+# ACI computation and plot divergence curve fit: 
+from PyComplexity import compute_aci
+compute_aci(acc_magnitude, hc_frames, n_dim=5, delay=10, ws=12, fs=100, period=1, min_val= 5, plot=True)
+```
+
+
+
+## How to cite
+
+If you use this package, please cite (mandatory):
+
+Mvomo, C. E. (2025). PyComplexity: A Python module for computing the Attractor Complexity Index (ACI) from lower-back accelerometer time-series during gait (Version v0.1.0). Zenodo. http://doi.org/10.5281/zenodo.19324133  
+
+and:
+
+Mvomo, C. E., Njiki, J. B. S., Leibovich, D., Guedes, C., Potvin-Desrochers, A., Dixon, P. C., Awai, C. E., & Paquette, C. (2026). Gait-Related Digital Mobility Outcomes in Parkinson’s Disease: New Insights into Convergent Validity? medRxiv. https://doi.org/10.64898/2026.03.07.26347847  
+
+You can also cite BibTeX (optional):
+```bibtex
+@software{cyrillemvomo_2025_19324133,
+  author       = {Cyrille E. Mvomo},
+  title        = {PyComplexity: A Python module for computing the Attractor Complexity Index (ACI) from lower-back accelerometer time-series during gait},
+  month        = July,
+  year         = 2025,
+  publisher    = {Zenodo},
+  version      = {v0.1.0},
+  doi          = {10.5281/zenodo.19324133},
+  url          = {https://doi.org/10.5281/zenodo.19324133}
+}
+```
+
+## References
+
+Mvomo, C. E., Njiki, J. B. S., Leibovich, D., Guedes, C., Potvin-Desrochers, A., Dixon, P. C., Awai, C. E., & Paquette, C. (2026). Gait-Related Digital Mobility Outcomes in Parkinson’s Disease: New Insights into Convergent Validity? medRxiv. https://doi.org/10.64898/2026.03.07.26347847  
+
+Piergiovanni, S., & Terrier, P. (2024a). Effects of metronome walking on long-term attractor divergence and correlation structure of gait. Scientific Reports, 14, 15784. https://doi.org/10.1038/s41598-024-65662-5  
+
+Piergiovanni, S., & Terrier, P. (2024b). Validity of linear and nonlinear measures of gait variability using a single lower back accelerometer. Sensors, 24(23), 7427. https://doi.org/10.3390/s24237427  
+
+Rosenstein, M. T., Collins, J. J., & De Luca, C. J. (1993). A practical method for calculating largest Lyapunov exponents from small data sets. Physica D, 65(1–2), 117–134  
+
+Terrier, P. (2019). The attractor complexity index is sensitive to gait synchronization. PeerJ, 7, e7417  
+
+Bruijn, S. M. (2023). LocalDynamicStability MATLAB implementation. Zenodo. http://doi.org/10.5281/zenodo.7593972  
+
+Wallot, S., & Mønster, D. (2018). Average mutual information and false-nearest neighbors for embedding. Frontiers in Psychology, 9, 1679  
+
+
+## Contact
+
+Cyrille E. Mvomo, PhD Candidate at McGill (Canada) and Lake Lucerne Institute (Switzerland)
+cyrille.mvomo@mail.mcgill.ca

pycomplexity_aci-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+PyComplexity/__init__.py,sha256=40ErgF_47PpY_PucoeYimeaCHh9DniQpI7wJhn1VacY,51
+PyComplexity/aci.py,sha256=KmlXVcgjEDRepVMoYfufLJqrHGqPet3jTqJturIoPOw,6893
+pycomplexity_aci-0.1.0.dist-info/licenses/LICENSE,sha256=xNk8Zf5ZBu-ftXfVeGEI6jyTHHN4ZG8fwIK06dM2Iag,1069
+pycomplexity_aci-0.1.0.dist-info/METADATA,sha256=Vzs5OqRww6lWpDmw8eqNtPT___qUD9GrxMpWMWZh7Cg,6104
+pycomplexity_aci-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+pycomplexity_aci-0.1.0.dist-info/top_level.txt,sha256=3CeL23nXzCbTWHY1_Bl0HdRorEZuT19wOc2fDH0wWLA,13
+pycomplexity_aci-0.1.0.dist-info/RECORD,,

pycomplexity_aci-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pycomplexity_aci-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 cyrillemvomo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pycomplexity_aci-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+PyComplexity