dj-figpack-codecs

DataJoint codec for storing figpack visualizations in schema-addressed object storage (OAS).

Installation

pip install dj-figpack-codecs

Quick Start

import datajoint as dj
import dj_figpack_codecs  # Auto-registers <figpack> codec

# Configure a store for visualizations
dj.config['stores'] = {
    'figures': {
        'protocol': 'file',
        'location': '/data/figures',
    }
}

schema = dj.Schema('my_analysis')

@schema
class RasterPlot(dj.Computed):
    definition = """
    -> SortedUnits
    ---
    visualization : <figpack@figures>
    """

    def make(self, key):
        from figpack import views as vv
        import numpy as np

        # Fetch spike data
        spikes = (SortedUnits & key).fetch('spike_times')

        # Create figpack visualization
        fig = vv.TimeseriesGraph(
            title="Spike Raster",
            description="Unit activity over time"
        )

        for i, spike_train in enumerate(spikes):
            fig.add_line_series(
                name=f"Unit {i}",
                t=spike_train.tolist(),
                y=[i] * len(spike_train),
            )

        self.insert1({**key, 'visualization': fig})

Usage

Fetching Visualizations

Fetching returns a FigpackRef - a lazy reference that provides metadata without downloading:

# Fetch returns FigpackRef (lazy)
ref = (RasterPlot & key).fetch1('visualization')

# Access metadata without download
print(ref.title)        # "Spike Raster"
print(ref.description)  # "Unit activity over time"

# Display in browser
ref.show()

# Or load the full FigpackView
view = ref.load()

Jupyter Integration

In Jupyter notebooks, FigpackRef displays a rich HTML preview:

ref  # Shows title, description, and action hints

Storage Structure

Visualizations are stored as Zarr folders under a schema-addressed path chosen by the framework (DataJoint's build_object_path): it mirrors the schema/table structure, encodes primary keys as attr=value segments, and ends in a tokenized filename ({attribute}_{token}.zarr), subject to the store's prefix/partitioning configuration — for example:

{store_location}/demo_showcase/fluorescence_figpack/session_id=4/fig_NPhczfGY.zarr/

The layout is browsable but framework-owned — do not hand-build or rely on exact paths; the database column's metadata (path, store) is the source of truth.

API Reference

FigpackCodec

The codec for <figpack@store> attributes. Registered automatically on import.

FigpackRef

Lazy reference returned when fetching <figpack@> attributes.

Properties:

• title - Visualization title (no I/O)
• description - Visualization description (no I/O)
• path - Storage path
• store - Store name
• is_loaded - Whether data has been cached

Methods:

• load() - Download and return the FigpackView
• show(**kwargs) - Download and display in browser
• serve_under(base_dir) - Materialize a servable viewer bundle; returns its relative URL

Serving a figure in a dashboard

FigpackRef.serve_under(base_dir) materializes a self-contained, servable viewer bundle (figpack's viewer + the stored data.zarr) under base_dir/<id>/ and returns the relative URL /<id>/index.html. Dashboards (e.g. dash-datajoint-components' PlotGrid) serve base_dir over HTTP and embed the URL in an <iframe>; repeated calls are idempotent and refresh the directory mtime for TTL-based cache cleaners.

Requirements

• Python >= 3.10
• datajoint >= 2.0
• figpack >= 0.3

License

Copyright 2026 DataJoint Inc.

Licensed under the Apache License, Version 2.0. See LICENSE for details.