Skip to main content

Scientific Workspace Browser

Scientific Workspace Browser turns a file-backed scientific script into a local browser application, served by Python or running Python entirely in the browser on a static site. The Python package and command-line interface are named sigvue. It does not impose separate processing and presentation stages.

If you can read and display your data, you already have the application:

def view(data, ui):
    products = analyze(data)
    with ui.tab("Results"):
        ui.plot(lambda: plot(products), key="results")

The author returns one Workspace. A reusable Reader handles discovery and exact buffering; one unrestricted view(data, ui) callback does everything after that.

Sigvue is intended to make signal viewing and repeatable batch processing simple to start and straightforward to extend. The same domain reader, processing functions, and plots work headlessly; the workspace adds discovery, buffer controls, lazy views, and optional durable batch actions without forcing the scientific pipeline into framework-specific stages.

Two standalone applications show the same core serving very different signal workflows:

  • NOAA NEXRAD Viewer discovers Level III radar sequences, provides segmented scan playback, and renders full-resolution GIFs as durable batch results.
  • SigMF Viewer discovers recordings and collections, reads exact moving windows, presents progressive waterfalls, and renders high-resolution per-channel PNGs in batch mode.

Install and run

python -m pip install sigvue
sigvue

Open http://127.0.0.1:8000. Run sigvue --config /path/to/browser.toml to open an existing profile directly.

For the same application in a native desktop window, install Sigvue's desktop extra and run the core desktop host:

python -m pip install "sigvue[desktop]"
sigvue-desktop --config /path/to/browser.toml

From a Sigvue source checkout, the equivalent editable installation is:

python -m pip install -e ".[desktop]"
sigvue-desktop --config examples/browser.toml

sigvue-desktop accepts the same workspace profile as the browser server. It owns the local server and pywebview window, including native fullscreen and the workspace wizard's folder picker. Workspace packages only provide readers, views, and batch actions; they do not need their own desktop launcher.

Static hosting: GitHub Pages and GitLab Pages

The static build runs the same Python workspaces and request handlers in a Pyodide Web Worker. It includes NumPy, SciPy, Matplotlib, Pillow, Plotly, and the complete generated LTE and communications recordings. Analysis, controls, window navigation, plot interaction, annotations, and JSON/MAT exports run on the visitor's device; this is not a collection of pre-rendered demo screenshots. The server and desktop commands above are unchanged.

The Static demos on GitHub Pages workflow builds and tests the actual browser application on pull requests and deploys main. In repository Settings → Pages → Build and deployment, select GitHub Actions. The project URL is https://briday1.github.io/sigvue/. No Python server, API service, credentials, CDN, or cross-origin-isolation headers are needed by the published application.

To build the same site yourself, from this checkout:

python -m pip install -e ".[examples]"
python -m examples.scripts.generate_all
curl --fail --location --retry 3 \
  https://github.com/pyodide/pyodide/releases/download/314.0.6/pyodide-314.0.6.tar.bz2 \
  --output /tmp/pyodide.tar.bz2
echo "fd25b21567f83f83b0b8bb1780a5458c6d4dd10bb07a22004424194022037f00  /tmp/pyodide.tar.bz2" | sha256sum --check
tar -xjf /tmp/pyodide.tar.bz2 -C /tmp
sigvue-static --root "$PWD" --config examples/browser.toml \
  --include examples --pyodide /tmp/pyodide --output _site
python -m http.server --directory _site 8000

Open http://localhost:8000. Publish the contents of _site to any HTTPS static host, including a GitLab Pages public/ artifact. Hash-based links work at a project subpath and survive refresh without a server rewrite or custom 404 page. The output must be absent or empty when building again.

For your own project, provide its root, profile, and explicit --include files/directories; repeat --include as needed. Paths in the profile must be relative and remain inside that root. Only selected files are published; review them before deployment because every bundled file is public. Hidden files, symlinks, caches, and tests are excluded. Extra native dependencies must have a compatible Pyodide build; arbitrary installed desktop extensions cannot be copied into WebAssembly.

Storage is local to the visitor. Writable files and annotations live in IndexedDB, isolated by site path. Nothing is uploaded to GitHub, GitLab, or a Sigvue backend. Use Local files to import files or folders, or download a ZIP backup; exports download through the browser as ordinary files. Workspace paths inside Python start at /project. Browser storage is not the host's filesystem: changing the hosted source files or another person's annotations is neither necessary nor possible. Clearing site data removes local changes; private browsing and storage quotas follow browser policy. Storage failures are reported rather than silently switching to nonpersistent storage. Local profiles and data are preserved when a new version of the site is deployed; deployed Python modules are refreshed.

To create a workspace using your own recordings:

  1. Open Local files, choose a destination such as my-recordings, and import your files (or import a folder, preserving its folder name).
  2. Open + Workspace, choose the LTE or communications workspace type, and set Data directory to /project/my-recordings.
  3. Choose a name and identifier. Enable Save to a profile to retain the workspace after reload; the default profile is also browser-local.

Custom Python workspace repositories can be imported the same way. Include their browser.toml or pyproject.toml workspace declarations, then select the imported /project/... repository in + Workspace → Discover. The normal Python installation continues to discover and read files on its server; these browser file controls are specific to the static build.

Static mode requires a current browser with WebAssembly, workers, IndexedDB, and service workers, served over HTTPS (or localhost for development). The initial download includes Python and scientific libraries. Browser memory limits still apply. A Python callback runs to completion on its worker: the UI remains responsive, but native threads, subprocesses, direct device access, and interruption of a running synchronous batch callback are not provided by Pyodide. Workspaces needing those OS facilities should continue using the local server. Bundled image processing uses Pillow to encode generated arrays; do not deploy custom decoders for untrusted files without checking security updates for the selected Pyodide package set.

The API

The API diagram

There is one application object:

Workspace(
    identifier="my-data",
    name="My Data",
    description="Inspect recordings.",
    reader=reader,
    view=view,
)

Inside view, the author decides what is shared, what is deferred, and whether processing and plotting are separate at all.

Minimal file-backed workspace

from pathlib import Path

import plotly.graph_objects as go

from sigvue import Files, Workspace


def open_samples(path: Path) -> tuple[float, ...]:
    return tuple(float(value) for value in path.read_text().split(","))


def view(samples, ui):
    gain = float(ui.number("gain", default=2.0, minimum=0.0))
    values = tuple(value * gain for value in samples)

    ui.stat("Samples", len(samples))
    with ui.tab("Values"):
        ui.plot(
            lambda: go.Figure(go.Scatter(y=values)),
            key="values",
        )


def create_workspace(config=None):
    return Workspace(
        identifier="values",
        name="Values",
        description="Inspect sample files.",
        reader=Files("data", "*.samples", open_samples),
        view=view,
    )

There is no framework boundary between multiplication and plotting. The callback can call one combined function just as easily:

def view(samples, ui):
    with ui.tab("Values"):
        ui.plot(lambda: process_and_plot(samples), key="values")

That lambda is lazy. Hidden tabs and switcher choices are not executed.

Headless data access

Reader.discover() returns native author-owned references. Paths stay Path objects; grouped collections and database keys stay domain objects.

reader = Files("data", "*.samples", open_samples)
path = reader.discover()[0]
samples = reader.load(path)
figure = process_and_plot(samples)

The same reader used by the browser is useful in scripts, notebooks, tests, and batch jobs.

Windowed data

reader = Files(root, "*.bin", open_recording).windowed(
    read_window,  # read_window(recording, start, stop)
    duration=lambda recording: recording.duration_seconds,
    default=0.100,
    minimum=0.010,
    step=0.010,
    overview=power_overview,
    overview_heatmap=low_resolution_waterfall,
    overview_colormap_control="colormap",
    overview_limits_control="dbfs_limits",
    overview_label="Median power",
)

Headlessly:

window = reader.load(path, start=2.0, stop=2.1)

Opened recordings, recent exact buffers, and overviews are revision-aware cached for repeated browser requests. Reader buffering never approximates scientific data. overview remains the lightweight line drawn across the window bar; overview_heatmap optionally adds a rectangular numeric raster behind it without changing the bar's geometry. Heatmap columns run left-to-right in recording-time order and rows run bottom-to-top, so a conventional frequency-x/time-y waterfall should be transposed before it is supplied. The bar's expand icon selects the complete recording extent on demand. The optional control bindings make the compact heatmap follow an existing ui.colormap() picker and ui.limits() dBFS range; changing either redraws the bar and the main plot together.

Segmented data

from sigvue import Segment

reader = Files(root, "*.json", open_collection).segmented(
    read_segment,  # read_segment(collection, selected_segment)
    duration=lambda collection: collection.duration,
    segments=lambda collection: tuple(
        Segment(event.id, event.start, event.duration, event.label)
        for event in collection.events
    ),
)

The callback receives the selected Segment, so irregular events and scans retain their identity.

Plot interaction and commit workflows

Plot selections and viewports are public request state. Bind either event directly to a paired ui.limits() control, or read the selection in presentation code:

bounds = ui.limits(
    "frequency_bounds",
    default=(0.0, 100.0),
    minimum=0.0,
    maximum=500.0,
    commit="explicit",  # preview locally until an action is clicked
    resettable=True,
)
apply_bounds = ui.action("apply_bounds", label="Apply bounds")
selection = ui.plot_selection("spectrum")

with ui.tab("Spectrum"):
    ui.plot(
        make_spectrum(bounds, apply_bounds),
        key="spectrum",
        selection_controls={"xaxis": "frequency_bounds"},
        drag_mode="select",
        modebar_add=("select2d",),
    )

A string binding targets one ui.limits() control; a two-name tuple targets separate scalar controls. viewport_controls has the same binding forms for pan/zoom ranges. New plot events update the bound control, while a later manual edit clears stale selection ownership. With commit="change" (the default), updates refresh immediately. With commit="explicit", handles and overlays can be previewed without rerunning analysis; clicking any ui.action() sends all current control values and a momentary action flag in one request.

A resettable limits control resets to the default and bounds declared by the current render, so authors can derive them from the active data window. Per-plot modebar_add, modebar_remove, and drag_mode customize Plotly tools without reaching into browser internals.

Seek and live playback

reader = Files(root, "*.bin", open_recording).playback(
    read_window,
    duration=lambda recording: recording.duration_seconds,
    default=0.020,
    minimum=0.001,
    maximum=0.100,
    buffer_step=0.001,
    mode="live",
    seek_step=0.010,
    refresh_interval=1.0,
)

This supplies an exact moving buffer. When maximum is given, the browser also exposes its width.

Application-specific buffering

If a domain needs coupled controls that do not fit the regular helpers, the reader boundary stays open:

reader = Files(root, "*.collection", open_collection).buffered(
    read_buffer,       # ordinary headless read(opened, ...)
    select_buffer,     # select_buffer(opened, ui)
)

reader.load(reference, ...) calls read_buffer directly. The browser calls select_buffer, which may declare buffer controls and then use that same exact read. This does not introduce another processing or presentation stage.

Processing, caching, and lazy work

Sigvue does not decide how the callback is divided.

Direct processing is ordinary Python:

def view(data, ui):
    threshold = float(ui.number("threshold", default=3.0))
    events = detect_events(data, threshold)
    with ui.tab("Events"):
        ui.plot(lambda: plot_events(data, events), key="events")

For shared expensive work, ui.compute is an optional generic cache:

def view(data, ui):
    threshold = float(ui.number("threshold", default=3.0))
    events = ui.compute(
        "event-detection",
        lambda: detect_events(data, threshold),
    )
    with ui.tab("Events"):
        ui.plot(lambda: plot_events(data, events), key="events")
    with ui.tab("Table"):
        ui.table(lambda: event_rows(events), key="event-table")

By default, the cache key includes:

  • the reader/source revision;
  • the selected window, segment, or playback position;
  • every control declared before ui.compute.

The author may specify depends_on=(...) to narrow control dependencies, or ignore ui.compute entirely.

Slow work needed by only one view belongs inside that view:

def view(data, ui):
    with ui.tab("Overview"):
        ui.plot(lambda: plot_overview(data), key="overview")

    with ui.tab("Slow diagnostics"):
        ui.plot(
            lambda: analyze_and_plot_diagnostics(data),
            key="diagnostics",
        )

Opening Overview does not run the diagnostics.

Exact complex layouts

The same callback supports all current layouts without another abstraction:

def view(data, ui):
    reference = str(ui.select(
        "phase_reference",
        default="Channel 1",
        options=channel_names(data),
    ))
    calibrated = ui.compute(
        "calibrated-radar",
        lambda: calibrate(data, phase_reference=reference),
    )

    ui.stat("Channels", calibrated.channel_count)

    with ui.tab("Waterfall"):
        ui.view_switcher(
            ("Domain", "Channel"),
            waterfall_views(calibrated, ui),
            key="waterfall-domain",
            selector=("buttons", "dropdown"),
            axis_navigation="bounded",
        )

    with ui.tab("Calibration", columns=(1, 1)):
        ui.plot(lambda: phase_plot(calibrated), key="phase")
        ui.table(calibrated.calibration_rows, key="calibration")

Tabs, weighted grids, nested groups, multidimensional switchers, display controls, inline processing controls, tables, text, and deferred plots all stay in the one nested ui API.

Exact complex layouts diagram

Custom discovery metadata

Paths receive useful defaults. Custom references may provide describe:

from sigvue import DataResource, Reader

reader = Reader(
    discover=discover_sequences,
    open=open_sequence,
    describe=lambda sequence: DataResource(
        identifier=sequence.id,
        title=sequence.title,
        source=sequence,
        timestamp=sequence.timestamp,
        tags=("radar", sequence.station),
        summary={"scan_count": sequence.scan_count},
    ),
)

Optional DiscoveryColumn values on Workspace define typed catalog columns. Recursive readers preserve their relative directories as browser folders by default. Set flatten_discovery=True on Workspace to show every discovered item at the workspace root without changing its identifier, source, or reader.

Optional capabilities

Annotation, export, and batch support remain independent:

Workspace(
    ...,
    reader=reader,
    view=view,
    annotator=MyAnnotator(),
    exporter=MyExporter(),
    batch=MyBatchActions(),
    discovery_columns=MY_COLUMNS,
)

These contracts are imported directly from sigvue. Format-specific readers and capabilities belong with the application or examples, not in Sigvue core. Batch actions run independently of the current browser route. The notification bell shows queued and running actions, follows them while the user browses other workspaces or views, and retains their completed outputs for opening or path copying. Reloading the page reconnects to jobs still owned by the server.

Workspace actions should use request.each(resources, render_one) when they apply the same operation to discovered items. Sigvue then reports aggregate progress, isolates an item failure so later items still run, and returns the successful results. Long-running render functions can call request.raise_if_cancelled() at safe boundaries; the same cancellation hook is available to item actions.

BatchResult.assets can list nested support files for a primary HTML result, such as image tiles. Sigvue serves those files to the report without adding thousands of support paths to the notification UI.

Top-level BatchResult.files entries may also be directories. Sigvue opens those results in a viewport-sized searchable file/image browser with independent scrollback and expandable nested folders. The tree updates as a running batch finishes files without resizing the image preview. PNG and GIF previews scale to fit that pane in both dimensions without internal scrolling. Sigvue opens individual images and HTML reports directly, and offers other file types as downloads alongside their local copyable paths.

The persistent Browse menu can open all declared outputs for that workspace or item, or narrow the result browser to one batch action type. It is not limited to the most recently run action. A particular notification still links to its individual job, while All batch results shows finished outputs from every action sharing the same destination directory.

Optional capabilities diagram

Configuration

A package exposes create_workspace(config):

[project.entry-points."sigvue.workspaces"]
my-analysis = "my_package.sigvue:create_workspace"

browser.toml chooses instances:

[browser]
title = "My data browser"

[[workspaces]]
use = "my-analysis"
id = "recordings"
name = "Recordings"
flatten_discovery = false

[workspaces.config]
data_root = "./data"

The profile is optional. Running sigvue without --config opens an empty catalog with an Add workspace wizard. The wizard first discovers workspace factories owned by the current project (including its browser.toml, examples/browser.toml, and project entry points), falling back to installed entry points only when the project has none. Selecting a different source repository scopes discovery to that repository. The wizard pairs a factory with a data directory and lets the user set the instance name, identifier, description, category, tags, and additional factory configuration. Flatten discovery can present all discovered items in one list instead of retaining the reader's folder hierarchy. The new workspace exists only in the running server unless Save to a profile is selected; saving atomically creates or appends to the chosen TOML file.

Applications can use the same profile-shaped spec without creating a file:

from pathlib import Path

from sigvue import create_app, workspace_launch_spec

workspace = workspace_launch_spec(
    {
        "use": "my-analysis",
        "id": "recordings",
        "name": "Recordings",
        "config": {"data_root": "./data"},
    },
    Path.cwd(),
)
app = create_app(workspace_specs=(workspace,))

app.configure_workspace(...) adds another instance later and optionally accepts persist_path= to promote that session workspace to TOML. Profile reloads preserve all other session-only workspaces.

The factory reads that location with WorkspaceConfig(config).path("data_root"). The bundled examples deliberately provide no code-level fallback, so browser.toml is their single source of truth for data locations. The same factory may still be reused in several TOML entries with different roots and metadata.

When a profile contains exactly one enabled workspace, the browser opens that workspace's item discovery directly at /. Profiles with multiple workspaces retain the searchable workspace catalog. Workspace code and configuration are identical in both cases.

Runnable examples

Small examples live in the examples/ directory. The standalone examples distribution covers communications, LTE waterfalls, calibrated multi-channel radar, annotated ECG, weather radar, passive acoustics, seismology, stored events, and native planetary data.

python -m pip install -e ".[examples]"
python -m examples.scripts.generate_all
sigvue --config examples/browser.toml

PyPI documentation

PyPI does not render Mermaid. The release workflow renders the diagrams:

python scripts/build_pypi_readme.py --ref "v$VERSION"

scripts/puppeteer-ci.json supplies Chromium's CI sandbox arguments.

Development

python -m pip install -e ".[test,release,examples]"
python -m pytest -q tests examples/tests
python -m build
python -m twine check dist/*

Metadata

Release files for sigvue 2026.80

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for sigvue 2026.80
File Size Uploaded Provenance Actions
sigvue-2026.80.tar.gz 193.7 kB Without provenance Details for sigvue-2026.80.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for sigvue 2026.80
File Interpreter ABI Platform Actions
sigvue-2026.80-py3-none-any.whl Python 3 none any Details for sigvue-2026.80-py3-none-any.whl

Total release size: 340.2 kB

Release files / sigvue-2026.80.tar.gz

Download URL sigvue-2026.80.tar.gz
Size 193.7 kB
Tags Source
SHA-256 checksum
How to use checksums
62a16d74f0f82e0e132b9b619f8fab1125c4e2f20ff5024c640f2b4bc8f9e49e
BLAKE2b-256 checksum
How to use checksums
4d8522713c52825569767fa566c449fb4b2fe6fe0b182f4e0e41f5848b477606
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.14

Release files / sigvue-2026.80-py3-none-any.whl

Download URL sigvue-2026.80-py3-none-any.whl
Size 146.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ef90ba95958f2c4675364ffdc9c22fac6aeeda001b3130aab2c5b54399e17449
BLAKE2b-256 checksum
How to use checksums
8a6849d7439e541dd4fb0d9bb2cc5445600408163c3a3114b395c3ef8903752b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.14

Security for sigvue 2026.80

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

2026.80 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page