figpack Documentation

A Python package for creating shareable, interactive visualizations in the browser.

Star this project on GitHub

Overview

figpack is a Python package for creating interactive scientific visualizations that can be displayed directly in web browsers and easily shared. Unlike traditional plotting libraries, figpack produces self-contained HTML bundles that include both the rendering logic and the underlying data. This makes figures portable, reproducible, and suitable for long-term archiving (for example, uploading to Zenodo).

At its core, figpack provides a flexible system of views (such as time series graphs, images, and domain-specific displays), organized into layouts that can compose complex dashboards. Different views within a layout are synchronized, sharing state such as the current timepoint, visible time range, or selected units, which enables coordinated exploration across multiple visualizations.

Figures can be stored either locally or in the cloud. Local figures are stored on your machine and are great for development and testing. By setting upload=True when showing a figure (or using the FIGPACK_UPLOAD=1 environment variable), you can upload the figure to the figpack cloud service, making it shareable and accessible from anywhere. Cloud storage is particularly useful for sharing results with collaborators, using figures on headless systems, or ensuring long-term archival access.

Data are stored in the efficient Zarr format, enabling interactive exploration of very large datasets through techniques like hierarchical downsampling.

Although primarily motivated by applications in neurophysiology (e.g., spike sorting), figpack is designed as a general framework for scientific applications.

Core Concepts

  • Views: The fundamental building blocks in figpack. Each view (like TimeseriesGraph, Image, or Markdown) represents a specific type of visualization or content.

  • Layouts: Composite views that organize and arrange other views (Box, Splitter, TabLayout) to create complex visualization dashboards.

  • Display System: The show() function intelligently handles visualization display across different environments (scripts, notebooks, cloud platforms).

  • Storage Format: Uses Zarr for efficient handling of numerical arrays, ensuring smooth performance even with large datasets.

  • Extensions: A system for creating custom views with specialized JavaScript visualizations, enabling integration of external libraries and custom rendering logic.

Quick Example

import numpy as np
import figpack.views as vv

# Create a timeseries graph
graph = vv.TimeseriesGraph(y_label="Signal")

# Add some data
t = np.linspace(0, 10, 1000)
y = np.sin(2 * np.pi * t)
graph.add_line_series(name="sine wave", t=t, y=y, color="blue")

# Display the visualization locally
graph.show(open_in_browser=True, title="Quick Start Example")

# Or upload to cloud to share with others
# graph.show(upload=True, title="Quick Start Example")

Documentation Structure

Development and Support

Indices and tables

Getting Started

Contents: