API Reference

This section provides detailed API documentation for figpack.

Core Modules

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

class figpack.ExtensionRegistry[source]

Bases: object

Singleton registry for managing figpack extensions

clear() → None[source]

Clear all registered extensions (mainly for testing)

get_all_extensions() → Dict[str, FigpackExtension][source]

Get all registered extensions

Returns:

Dictionary mapping extension names to extension objects

get_extension(name: str) → FigpackExtension | None[source]

Get an extension by name

Parameters:

name – Name of the extension to retrieve

Returns:

The extension if found, None otherwise

classmethod get_instance() → ExtensionRegistry[source]

Get the singleton instance of the extension registry

classmethod register(extension: FigpackExtension) → None[source]

Register an extension with the global registry

Parameters:

extension – The extension to register

class figpack.ExtensionView(*, extension_name: str)[source]

Bases: FigpackView

Base class for views that are rendered by figpack extensions

class figpack.FigpackExtension(*, name: str, javascript_code: str, additional_files: Dict[str, str] | None = None, version: str = '1.0.0')[source]

Bases: object

Base class for figpack extensions that provide custom view components

get_additional_filenames() → Dict[str, str][source]

Get the filenames for additional JavaScript files

Returns:

Dictionary mapping original filenames to safe filenames

get_javascript_filename() → str[source]

Get the filename that should be used for this extension’s JavaScript file

Returns:

Filename for the extension JavaScript file

class figpack.FigpackView[source]

Bases: object

Base class for all figpack visualization components

save(output_path: str, *, title: str) → None[source]

Save as figure either to a folder or to a .tar.gz file :param output_path: Output path (destination folder or .tar.gz file path)

show(*, title: str, description: str | None = None, port: int | None = None, open_in_browser: bool | None = None, upload: bool | None = None, inline: bool | None = None, inline_height: int = 600, ephemeral: bool | None = None, allow_origin: str | None = None, wait_for_input: bool | None = None, _dev: bool | None = None)[source]

Display a figpack view component with intelligent environment detection and flexible display options. See https://flatironinstitute.github.io/figpack/show_function.html for complete documentation.

Automatically adapts behavior based on context (Jupyter, Colab, JupyterHub, standalone). Display modes include local browser, inline notebook, and remote upload with ephemeral options. Environment variables (FIGPACK_UPLOAD, FIGPACK_INLINE, FIGPACK_OPEN_IN_BROWSER) can control default behaviors.

Parameters:

  • title – Title for browser tab and figure (required)

  • description – Description text with markdown support (optional)

  • port – Local server port, random if None

  • open_in_browser – Auto-open in browser, auto-detects by environment

  • upload – Upload figure to figpack servers, auto-detects by environment

  • ephemeral – Use temporary figure for cloud notebooks, auto-detects

  • inline – Display inline in notebook, auto-detects by environment

  • inline_height – Height in pixels for inline display (default: 600)

  • allow_origin – CORS allow-origin header for local server

  • wait_for_input – Wait for Enter before continuing, auto-detects

  • _dev – Developer mode for figpack development

figpack.view_figure(figure_path: str, port: int | None = None) → None[source]

Extract and serve a figure archive locally

Parameters:

  • figure_path – Path to a .tar.gz archive file or a directory

  • port – Optional port number to serve on

Views

Core Views

Spike Sorting Views

Spike sorting views for figpack

class figpack.spike_sorting.views.AutocorrelogramItem(*, unit_id: str | int, bin_edges_sec: ndarray, bin_counts: ndarray)[source]

Bases: object

Represents a single autocorrelogram for a unit

class figpack.spike_sorting.views.Autocorrelograms(*, autocorrelograms: List[AutocorrelogramItem])[source]

Bases: FigpackView

A view that displays multiple autocorrelograms for spike sorting analysis

static from_sorting(sorting)[source]
static from_spikeinterface_widget(W)[source]
class figpack.spike_sorting.views.AverageWaveforms(*, average_waveforms: List[AverageWaveformItem])[source]

Bases: FigpackView

A view that displays multiple average waveforms for spike sorting analysis

static from_sorting_analyzer(sorting_analyzer)[source]
class figpack.spike_sorting.views.CrossCorrelogramItem(*, unit_id1: str | int, unit_id2: str | int, bin_edges_sec: ndarray, bin_counts: ndarray)[source]

Bases: object

Represents a single cross-correlogram between two units

class figpack.spike_sorting.views.CrossCorrelograms(*, cross_correlograms: List[CrossCorrelogramItem], hide_unit_selector: bool | None = False)[source]

Bases: FigpackView

A view that displays multiple cross-correlograms for spike sorting analysis

static from_sorting(sorting)[source]
static from_spikeinterface_widget(W)[source]
class figpack.spike_sorting.views.RasterPlot(*, start_time_sec: float, end_time_sec: float, plots: List[RasterPlotItem])[source]

Bases: FigpackView

A view that displays multiple raster plots for spike sorting analysis

static from_nwb_units_table(nwb_url_or_path_or_h5py, *, units_path: str, include_units_selector: bool = False)[source]
class figpack.spike_sorting.views.RasterPlotItem(*, unit_id: str | int, spike_times_sec: ndarray)[source]

Bases: object

Represents spike times for a single unit in a raster plot

class figpack.spike_sorting.views.SpikeAmplitudes(*, start_time_sec: float, end_time_sec: float, plots: List[SpikeAmplitudesItem])[source]

Bases: FigpackView

A view that displays spike amplitudes over time for multiple units

static from_nwb_units_table(nwb_url_or_path_or_h5py, *, units_path: str, include_units_selector: bool = False)[source]
class figpack.spike_sorting.views.SpikeAmplitudesItem(*, unit_id: str | int, spike_times_sec: ndarray, spike_amplitudes: ndarray)[source]

Bases: object

Represents spike amplitudes for a single unit

class figpack.spike_sorting.views.UnitMetricsGraph(*, units: List[UnitMetricsGraphUnit], metrics: List[UnitMetricsGraphMetric], height: int | None = None)[source]

Bases: FigpackView

A view that displays unit metrics in a graph format

class figpack.spike_sorting.views.UnitMetricsGraphMetric(*, key: str, label: str, dtype: str)[source]

Bases: object

Defines a metric with key, label, and data type

to_dict() → Dict[source]

Convert to dictionary for serialization

class figpack.spike_sorting.views.UnitMetricsGraphUnit(*, unit_id: str | int, values: Dict[str, int | float])[source]

Bases: object

Represents a unit with its metric values

to_dict() → Dict[source]

Convert to dictionary for serialization

class figpack.spike_sorting.views.UnitSimilarityScore(*, unit_id1: str | int, unit_id2: str | int, similarity: float)[source]

Bases: object

Represents a similarity score between two units

to_dict()[source]

Convert the similarity score to a dictionary representation

class figpack.spike_sorting.views.UnitsTable(*, columns: List[UnitsTableColumn], rows: List[UnitsTableRow], similarity_scores: List[UnitSimilarityScore] | None = None, height: int | None = 600)[source]

Bases: FigpackView

A view that displays a table of units with their properties and optional similarity scores

class figpack.spike_sorting.views.UnitsTableColumn(*, key: str, label: str, dtype: Literal['int', 'float', 'str', 'bool'])[source]

Bases: object

Represents a column in a units table

to_dict()[source]

Convert the column to a dictionary representation

class figpack.spike_sorting.views.UnitsTableRow(*, unit_id: str | int, values: Dict[str, Any])[source]

Bases: object

Represents a row in a units table

to_dict()[source]

Convert the row to a dictionary representation

Franklab Views

Franklab views for figpack

class figpack.franklab.views.TrackAnimation(*, bin_height: float, bin_width: float, frame_bounds: ndarray, locations: ndarray, values: ndarray, xcount: int, ycount: int, xmin: float, ymin: float, head_direction: ndarray, positions: ndarray, timestamps: ndarray, track_bin_corners: ndarray, sampling_frequency_hz: float, timestamp_start: float, total_recording_frame_length: int, track_bin_height: float, track_bin_width: float, xmax: float, ymax: float)[source]

Bases: FigpackView

A track animation visualization component for displaying animal tracking data

Core Functionality

The core functionality includes the essential show() function used to display and share visualizations. For detailed documentation of this crucial function and all its configuration options, see the show() function reference.

class figpack.core.ExtensionRegistry[source]

Bases: object

Singleton registry for managing figpack extensions

clear() → None[source]

Clear all registered extensions (mainly for testing)

get_all_extensions() → Dict[str, FigpackExtension][source]

Get all registered extensions

Returns:

Dictionary mapping extension names to extension objects

get_extension(name: str) → FigpackExtension | None[source]

Get an extension by name

Parameters:

name – Name of the extension to retrieve

Returns:

The extension if found, None otherwise

classmethod get_instance() → ExtensionRegistry[source]

Get the singleton instance of the extension registry

classmethod register(extension: FigpackExtension) → None[source]

Register an extension with the global registry

Parameters:

extension – The extension to register

class figpack.core.ExtensionView(*, extension_name: str)[source]

Bases: FigpackView

Base class for views that are rendered by figpack extensions

class figpack.core.FigpackExtension(*, name: str, javascript_code: str, additional_files: Dict[str, str] | None = None, version: str = '1.0.0')[source]

Bases: object

Base class for figpack extensions that provide custom view components

get_additional_filenames() → Dict[str, str][source]

Get the filenames for additional JavaScript files

Returns:

Dictionary mapping original filenames to safe filenames

get_javascript_filename() → str[source]

Get the filename that should be used for this extension’s JavaScript file

Returns:

Filename for the extension JavaScript file

class figpack.core.FigpackView[source]

Bases: object

Base class for all figpack visualization components

save(output_path: str, *, title: str) → None[source]

Save as figure either to a folder or to a .tar.gz file :param output_path: Output path (destination folder or .tar.gz file path)

show(*, title: str, description: str | None = None, port: int | None = None, open_in_browser: bool | None = None, upload: bool | None = None, inline: bool | None = None, inline_height: int = 600, ephemeral: bool | None = None, allow_origin: str | None = None, wait_for_input: bool | None = None, _dev: bool | None = None)[source]

Display a figpack view component with intelligent environment detection and flexible display options. See https://flatironinstitute.github.io/figpack/show_function.html for complete documentation.

Automatically adapts behavior based on context (Jupyter, Colab, JupyterHub, standalone). Display modes include local browser, inline notebook, and remote upload with ephemeral options. Environment variables (FIGPACK_UPLOAD, FIGPACK_INLINE, FIGPACK_OPEN_IN_BROWSER) can control default behaviors.

Parameters:

  • title – Title for browser tab and figure (required)

  • description – Description text with markdown support (optional)

  • port – Local server port, random if None

  • open_in_browser – Auto-open in browser, auto-detects by environment

  • upload – Upload figure to figpack servers, auto-detects by environment

  • ephemeral – Use temporary figure for cloud notebooks, auto-detects

  • inline – Display inline in notebook, auto-detects by environment

  • inline_height – Height in pixels for inline display (default: 600)

  • allow_origin – CORS allow-origin header for local server

  • wait_for_input – Wait for Enter before continuing, auto-detects

  • _dev – Developer mode for figpack development

Command Line Interface

Command-line interface for figpack

figpack.cli.download_figure(figure_url: str, dest_path: str) → None[source]

Download a figure from a figpack URL and save as tar.gz

Parameters:

  • figure_url – The figpack URL

  • dest_path – Destination path for the tar.gz file

figpack.cli.download_file(base_url: str, file_info: Dict, temp_dir: Path) → Tuple[str, bool][source]

Download a single file from the figure

Parameters:

  • base_url – The base URL for the figure

  • file_info – Dictionary with ‘path’ and ‘size’ keys

  • temp_dir – Temporary directory to download to

Returns:

Tuple of (file_path, success)

figpack.cli.get_figure_base_url(figure_url: str) → str[source]

Get the base URL from any figpack URL

Parameters:

figure_url – Any figpack URL (may or may not end with /index.html)

Returns:

The base URL for the figure directory

Return type:

str

figpack.cli.main()[source]

Main CLI entry point

Individual View Classes

For detailed documentation of specific view classes, see the source code and docstrings in the respective modules:

  • figpack.views - Core visualization components

  • figpack.spike_sorting.views - Spike sorting specific views

  • figpack.franklab.views - Franklab specific views

Usage Examples

For practical examples of using the API, see the Examples section.