README.md

foamgraph

foamgraph was originally developed as part of the online analysis framework EXtra-foam to provide fast display (10 Hz) and interactive data analysis for data-intensive photon science experiments at the state-of-art free-electron laser (FEL) facility - European XFEL. It was originally implemented on top of the famous Python graphics and GUI library PyQtGraph. The following features made foamgraph stand out:

• The widgets are dedicated for photon science experiments.
• The performance has been significantly improved.

As of now, foamgraph has almost evolved into its own implementation completely. It's time to decide the direction for future development. Since there are already many excellent GUI libraries around, foamgraph should and will do something different.

Getting started

Imaging you have a data producer which streams data continuously and you would like to build a GUI to visualize the data and perform interactive analysis while the data is updating. Eventually, what you need is something shown in the code snippet below: a consumer consumers the data generated by the producer and then passes the data to the GUI.

gui = PlotGalleryWindow()
consumer = Consumer(gui.queue)  # the queue is used to store data streams

gui.start()
consumer.start()

The class PlotGalleryWindow can be conveniently implemented as follows:

class PlotGalleryWindow(LiveWindow):
    def __init__(self):
        super().__init__("Plot gallery")

        # define your plots
        self._plots = [
            ShadedPlot(parent=self),
            ScatterPlot(parent=self),
            BarPlot(parent=self),
            ErrorbarPlot(parent=self),
            MultiLinePlot(parent=self),
            DoubleYPlot(parent=self),
            LinePlotWithAnnotation(parent=self),
            CandlestickPlot(parent=self),
            StemPlot(parent=self)
        ]

        # init your GUI layout and Qt signal-slot connection
        self.init()

For more details of the above use case, please check here.

In foamgraph, every plot widget should inherit from GraphView. The following code snippet shows how to create a double-y plot with a title, axis labels and a legend:

from foamgraph import FColor, GraphView


class DoubleYPlot(GraphView):
    def __init__(self, *, parent=None):
        super().__init__(parent=parent)

        self.setTitle('Double-y plot')
        self.setXYLabels("x (arb. u.)", "y (arb. u.)", y2="y2 (arg. u.)")

        self._plot = self.addCurvePlot(label="Data", pen=FColor.mkPen('w'))
        self._plot2 = self.addBarPlot(
            label="Count", y2=True, brush=FColor.mkBrush('i', alpha=150))
        self.addLegend()

    def updateF(self, data):
        """Override."""
        self._plot.setData(data['x'], data['y'])
        self._plot2.setData(data['x'], data['y2'])

Examples

• Open a terminal and start the producer:

python examples/producer.py

• Open another terminal and start the plot gallery example

python examples/plot_gallery.py

• Open another terminal and start the image analysis example

python examples/image_analysis.py

Benchmarks

The benchmark was performed on a Apple M1 Pro 16GB with the GUI geometry of 800 x 600.

Plot Type	Description	FPS
Curve	10000 points	300
Scatter	10000 points	140
Bar	500 bars	350
Image	1280 x 1024	92