Sine/Cosine FPL Plot & Lorenz Generator & Processor

.github/workflows/CI.yaml

@@ -48,7 +48,7 @@ jobs:
         run: |
           brew install redis
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install dependencies
@@ -81,7 +81,7 @@ jobs:
         with:
           fetch-depth: 0
       - name: Set up Python 3.10
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: '3.10'
 

.github/workflows/docs.yaml

@@ -21,7 +21,7 @@ jobs:
 
     # Install dependencies
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python-version }}
     - name: Install dependencies

.github/workflows/pypi.yaml

@@ -5,8 +5,6 @@ on:
   push:
     tags: 
       - 'v[0-9]+.[0-9]+.[0-9]+'
-    branches:
-      - 'main'
 
 jobs:
   build:
@@ -18,7 +16,7 @@ jobs:
       with:
         fetch-depth: 0
     - name: Set up Python
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
         python-version: "3.10"
     - name: Install pypa/build

.github/workflows/test-pypi.yaml

@@ -18,7 +18,7 @@ jobs:
       with:
         fetch-depth: 0
     - name: Set up Python
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
         python-version: "3.10"
     - name: Install pypa/build

README.md

@@ -1,4 +1,9 @@
-# improv
+
+<img src="docs/improv_logo_horizontal.svg" style="width:40%"/>
+
+Adaptive experiments for neuroscience
+---------
+
 [![PyPI](https://img.shields.io/pypi/v/improv?style=flat-square?style=flat-square)](https://pypi.org/project/improv)
 [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/improv?style=flat-square)](https://pypi.org/project/improv)
 [![docs](https://github.com/project-improv/improv/actions/workflows/docs.yaml/badge.svg?style=flat-square)](https://project-improv.github.io/)
@@ -7,9 +12,8 @@
 [![PyPI - License](https://img.shields.io/pypi/l/improv?style=flat-square)](https://opensource.org/licenses/MIT)
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg?style=flat-square)](https://github.com/psf/black)
 
-A flexible software platform for real-time and adaptive neuroscience experiments.
 
-_improv_ is a streaming software platform designed to enable adaptive experiments. By analyzing data, such as 2-photon calcium images, as it comes in, we can obtain information about the current brain state in real time and use it to adaptively modify an experiment as data collection is ongoing. 
+_improv_ is a streaming software platform designed to enable adaptive experiments. By analyzing data as they arrive, we can obtain information about the current brain state in real time and use it to adaptively modify an experiment as data collection is ongoing. 
 
 ![](https://dibs.duke.edu/sites/default/files/improvGif.gif)
 
@@ -33,7 +37,8 @@ _improv_'s design is based on a streamlined version of the actor model for concu
 
 ## Installation
 
-For installation instructions, please consult the [docs](https://project-improv.github.io/improv/installation.html) on our github.
+For installation instructions, please consult the [documentation](https://project-improv.github.io/improv/installation.html).
+
 
 ### Contact
 To get in touch, feel free to reach out on Twitter <a href="http://twitter.com/annedraelos" target="_blank">@annedraelos</a> or <a href="http://twitter.com/jmxpearson" target="_blank">@jmxpearson</a>. 

demos/fastplotlib/actors/lorenz_generator.py

@@ -0,0 +1,91 @@
+from improv.actor import Actor
+import numpy as np
+import logging
+
+logger = logging.getLogger(__name__)
+logger.setLevel(logging.INFO)
+
+class Generator(Actor):
+    """
+    Generates coordinates for the Lorenz system in real time.
+    Computes the next 50 Lorenz coordinates every half second.
+    """
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.data = None
+        self.name = "Lorenz Generator"
+        self.dt = 0.01  # time step for numerical integration
+        self.frame_num = 0
+
+    def __str__(self):
+        return f"Name: {self.name}, Current Coordinates: {self.coordinates[-1] if self.coordinates else None}"
+
+    def setup(self):
+        """Generates an array that serves as an initial source of data.
+
+        Initial data is the starting point (x,y,z) for the lorenz attractor.
+        """
+        logger.info("Beginning setup for Lorenz Generator")
+
+        # initial condition
+        self.data = np.array([1.0, 1.0, 1.0]).reshape(1,3)
+
+        logger.info(f"Initialized Lorenz system with initial coordinates: {self.data}")
+
+    def stop(self):
+        """Trivial stop function."""
+        logger.info("Lorenz Generator stopping")
+        return 0
+
+    def runStep(self):
+        """Generates the next 25 points in the lorenz system.
+
+        Sends the progressively filled data as a flattened array with the frame number appended to the processor.
+        """
+        if self.frame_num >= 150:
+            return
+
+        # Add the next 10 points
+        for _ in range(25):
+            # Compute the next coordinate
+            derivative = lorenz(self.data[-1])
+            next_coordinate = self.data[-1] + derivative * self.dt
+            self.data = np.vstack((self.data, next_coordinate))
+
+        # create flattened array with xyz coordinates along with the current frame number
+        data = np.append(self.data.ravel(), self.frame_num)
+
+        # Send the flattened array with frame_num
+        try:
+            data_id = self.client.put(data)
+            if self.store_loc:
+                self.q_out.put([[data_id, str(self.frame_num)]])
+            else:
+                self.q_out.put(data_id)
+
+            # Increment frame number
+            self.frame_num += 1
+        except Exception as e:
+            logger.error(f"--------------------------------Generator Exception: {e}")
+
+
+def lorenz(xyz, s=10, r=28, b=2.667):
+    """
+    Parameters
+    ----------
+    xyz : array-like, shape (3,)
+       Point of interest in three-dimensional space.
+    s, r, b : float
+       Parameters defining the Lorenz attractor.
+
+    Returns
+    -------
+    xyz_dot : array, shape (3,)
+       Values of the Lorenz attractor's partial derivatives at *xyz*.
+    """
+    x, y, z = xyz
+    x_dot = s * (y - x)
+    y_dot = r * x - y - x * z
+    z_dot = x * y - b * z
+    return np.array([x_dot, y_dot, z_dot])

demos/fastplotlib/actors/lorenz_processor.py

@@ -0,0 +1,78 @@
+from improv.actor import Actor
+import time
+import logging
+import zmq
+import numpy as np
+
+logger = logging.getLogger(__name__)
+logger.setLevel(logging.INFO)
+
+
+class Processor(Actor):
+    """
+    Processes Lorenz data by performing custom transformations on the coordinates
+    (e.g., scaling and applying mathematical operations) and sends the processed
+    data through a ZMQ socket for visualization.
+    """
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+
+    def setup(self):
+        """
+        Sets up the ZMQ socket and initialize class variables.
+        """
+        self.name = "Processor"
+        self.frame = None
+        self.frame_num = None
+
+        # Set up ZMQ PUB socket
+        context = zmq.Context()
+        self.socket = context.socket(zmq.PUB)
+        self.socket.bind("tcp://127.0.0.1:5555")
+
+        logger.info("Processor setup completed. ZMQ PUB socket bound to tcp://127.0.0.1:5555")
+
+    def stop(self):
+        """
+        Stop function. Closes the ZMQ socket connection.
+        """
+        logger.info("Processor stopping")
+        self.socket.close()
+        return 0
+
+    def runStep(self):
+        """
+        Trivial processing step that gets the lorenz data and passes it through the
+        ZMQ socket for visualization.
+        """
+        # Delay for half a second for visualization purposes
+        time.sleep(0.5)
+
+        data_id = None
+        try:
+            data_id = self.q_in.get(timeout=0.05)
+        except Exception:
+            logger.error(f"Could not get frame!")
+            pass
+
+        if data_id is not None:
+            try:
+                if self.store_loc:
+                    # Fetch the data from the client using the ObjectID
+                    self.frame = self.client.getID(data_id[0][0])
+                else:
+                    self.frame = self.client.get(data_id)
+
+
+                # unpack the frame to get the frame number
+                data = np.array(self.frame, dtype=np.float64)
+                self.frame_num = int(data[-1])
+
+
+                # Send the processed data through the ZMQ socket
+                self.socket.send(data)
+                logger.info(f"Frame {self.frame_num}: Sent points with size {data.shape} after processing")
+
+            except Exception as e:
+                logger.error(f"Error processing frame: {e}")

demos/fastplotlib/actors/visual_processor.py

@@ -0,0 +1,93 @@
+from improv.actor import Actor
+import random
+import logging
+import zmq
+import numpy as np
+import time
+from queue import Empty
+
+logger = logging.getLogger(__name__)
+logger.setLevel(logging.INFO)
+
+
+class Processor(Actor):
+    """Sample processor used to scale a sine or cosine wave and calculate the amplitude.
+    Intended for use with sample_generator.py.
+    """
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+
+    def setup(self):
+        """Initializes all class variables. Create and bind the socket for zmq to send to fastplotlib.ipynb
+        for visualization.
+
+        self.name (string): name of the actor.
+        self.frame (ObjectID): StoreInterface object id referencing data from the store.
+        self.frame_num (int): index of current frame.
+        self.processed_data (np.array): raveled array containing the processed data appended with the current frame number
+        """
+        self.name = "Processor"
+        self.frame = None
+        self.frame_num = 0
+        self.processed_data = None
+
+        context = zmq.Context()
+        self.socket = context.socket(zmq.PUB)
+        self.socket.bind("tcp://127.0.0.1:5555")
+
+        logger.info("Completed setup for Processor")
+
+    def stop(self):
+        """Stop function that closes the zmq socket to visualization notebook."""
+        logger.info("Processor stopping")
+        self.socket.close()
+        return 0
+
+    def runStep(self):
+        """
+        Gets from the input queue, scales the data in the y-dimension by a random number between 1-10 inclusive and then
+        calculates the amplitude of the wave.
+        """
+        # delay frame unpacking for visualization purposes
+        time.sleep(0.5)
+
+        data_id = None
+        try:
+            data_id = self.q_in.get(timeout=0.05)
+        except Empty:
+            pass
+        except Exception as e:
+            logger.error(f"Could not get frame!")
+
+        if data_id is not None:
+            try:
+                if self.store_loc:
+                    # Fetch the data from the client using the ObjectID
+                    self.frame = self.client.getID(data_id[0][0])
+                else:
+                    self.frame = self.client.get(data_id)
+
+
+                # Unpack the frame to get the data and frame number
+                data = np.array(self.frame, dtype=np.float64)
+                self.frame_num = int(data[-1])
+                # reshape the data to 2D array
+                data = data[:-1].reshape(-1, 2)
+
+                # Scale the y-values of the sine or cosine wave by random factor
+                scale_factor = random.randint(1, 10)
+                data[:, 1] *= scale_factor
+
+                # calculate the amplitude
+                amplitude = np.round((data.max(axis=0)[1] - data.min(axis=0)[1]) / 2)
+                logger.info(f"Frame {self.frame_num} has amplitude {amplitude}")
+
+                # Flatten processed values and append frame number
+                self.processed_data = np.append(data.ravel(), self.frame_num)
+
+                # Send the processed data through the ZMQ socket to be visualized
+                self.socket.send(self.processed_data)
+
+            except Exception as e:
+                logger.error(f"Error processing frame: {e}")