.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "auto_examples/plot_velocity_embedding.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        :ref:`Go to the end <sphx_glr_download_auto_examples_plot_velocity_embedding.py>`
        to download the full example code.

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_auto_examples_plot_velocity_embedding.py:


Visualizing Dynamics: Velocity Embeddings
=========================================

This example demonstrates the "Visualizing Dynamics" pillar of the ``coco_pipe``
strategic vision. We generate a synthetic dynamical system (a noisy limit cycle)
and visualize its temporal flow using **Streamlines**.

This is conceptually similar to ``scVelo`` [1]_ but applied to generalized state
spaces like M/EEG or simulation data.

.. [1] La Manno et al. (2018). RNA velocity of single cells. Nature.

.. GENERATED FROM PYTHON SOURCE LINES 14-20

.. code-block:: Python


    import matplotlib.pyplot as plt
    import numpy as np

    from coco_pipe.viz import dim_reduction








.. GENERATED FROM PYTHON SOURCE LINES 21-27

1. Simulate Dynamical System (Limit Cycle)
------------------------------------------
We create a noisy circle where points naturally flow counter-clockwise.
System:
dx/dt = -y
dy/dt = x

.. GENERATED FROM PYTHON SOURCE LINES 27-50

.. code-block:: Python


    n_points = 500
    t = np.linspace(0, 2 * np.pi, n_points)

    # Underlying manifold (Circle)
    x = np.cos(t)
    y = np.sin(t)

    # Add noise to make it a "point cloud" rather than a perfect line
    rng = np.random.default_rng(42)
    noise_level = 0.1
    x_noisy = x + rng.normal(0, noise_level, n_points)
    y_noisy = y + rng.normal(0, noise_level, n_points)

    X_emb = np.stack([x_noisy, y_noisy], axis=1)

    # True Velocity Vectors (Tangential flow)
    # v_x = -y, v_y = x
    V_emb = np.stack([-y, x], axis=1)

    print(f"Data Shape: {X_emb.shape}")
    print(f"Velocity Shape: {V_emb.shape}")





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    Data Shape: (500, 2)
    Velocity Shape: (500, 2)




.. GENERATED FROM PYTHON SOURCE LINES 51-58

2. Visualize with Streamlines
-----------------------------
``plot_streamlines`` interpolates the velocity vectors onto a grid and
draws streamlines to visualize the flow of the system.

In a real pipeline, ``V_emb`` would be estimated from the high-dimensional
velocity projection (see Vision Document Section 4.1.1).

.. GENERATED FROM PYTHON SOURCE LINES 58-68

.. code-block:: Python


    fig = dim_reduction.plot_streamlines(
        X_emb[::2],  # Subsample for clearer scatter plot background
        V_emb[::2],
        grid_density=20,
        title="Neural State Dynamics (Simulated Limit Cycle)",
    )

    plt.show()




.. rst-class:: sphx-glr-horizontal


    *

      .. image-sg:: /auto_examples/images/sphx_glr_plot_velocity_embedding_001.png
         :alt: plot velocity embedding
         :srcset: /auto_examples/images/sphx_glr_plot_velocity_embedding_001.png
         :class: sphx-glr-multi-img

    *

      .. image-sg:: /auto_examples/images/sphx_glr_plot_velocity_embedding_002.png
         :alt: Neural State Dynamics (Simulated Limit Cycle)
         :srcset: /auto_examples/images/sphx_glr_plot_velocity_embedding_002.png
         :class: sphx-glr-multi-img





.. GENERATED FROM PYTHON SOURCE LINES 69-79

Interpretation
--------------
The streamlines clearly reveal the counter-clockwise rotation of the system
state. In real neural data, this could represent:

- **Motor Preparation**: Moving from a "Rest" state to a "Movement" state.
- **Seizure Onset**: Transitioning into a stable limit cycle (oscillation).
- **Sleep Stages**: Flowing through the sleep cycle.

This layer of information (dynamics) is completely lost in a static scatter plot.


.. rst-class:: sphx-glr-timing

   **Total running time of the script:** (0 minutes 4.906 seconds)


.. _sphx_glr_download_auto_examples_plot_velocity_embedding.py:

.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-example

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download Jupyter notebook: plot_velocity_embedding.ipynb <plot_velocity_embedding.ipynb>`

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download Python source code: plot_velocity_embedding.py <plot_velocity_embedding.py>`

    .. container:: sphx-glr-download sphx-glr-download-zip

      :download:`Download zipped: plot_velocity_embedding.zip <plot_velocity_embedding.zip>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_