Tutorial Datasets

The quantem.widget.datasets module provides small, named examples for tutorials, smoke tests, and Colab notebooks. Users choose the widget/example and an explicit size; the loader handles Hugging Face paths, cache layout, and calibration details.

from quantem.widget.datasets import (
    show1d_ducky,
    show2d_gold,
    show3d_gold,
    show4dstem_gold,
    showfolder_gold,
)

All size selectors use the same language:

Size	Intended use
small	Documentation, Colab, CI smoke tests, quick first view
medium	Better visual detail for local notebooks
large	Local workstation review
full	Full available tutorial source where practical

For Show1D, the ducky ptychography example is a file-backed monitor run:

from quantem.widget import Show1D
from quantem.widget.datasets import show1d_ducky

run = show1d_ducky(size="small")
widget = Show1D.from_monitor_file(
    run / "show1d_monitor.jsonl",
    title="Real ducky joint iterative ptychography",
    x_label="frame",
    y_label="final loss",
    log_scale=False,
)
widget

Use the one-line example API when you only need the viewer:

from quantem.widget import Show1D

widget = Show1D.from_example("ducky", size="small")
widget

The public Hugging Face dataset is organized under widget-tutorials/. Reused sources live once under shared/; widget-specific monitor runs or session folders live under the widget name.

widget-tutorials/{widget-or-shared}/{example}/{size}/...

Current tutorial payloads:

widget-tutorials/show1d/ducky/small/show1d_monitor.jsonl
widget-tutorials/show1d/ducky/small/snapshots/*.npy
widget-tutorials/shared/gold-haadf/full/data.npy
widget-tutorials/show4dstem/gold-128-bin8/full/data.npy
widget-tutorials/showfolder/gold-haadf-session/small/*.emd

This keeps widget tutorial payloads grouped together instead of placing many example files at the top level of the shared dataset repository. show2d_gold and show3d_gold intentionally share widget-tutorials/shared/gold-haadf/full so the same HAADF source image is not duplicated per widget.

Reference

Friendly tutorial dataset loaders for QuantEM widget examples.

quantem.widget.datasets.show1d_ducky(*, size: str = 'small', cache_dir: str | Path | None = None, revision: str | None = None, force_download: bool = False, verbose: bool = True) → Path

Download the real ducky joint-time ptychography Show1D tutorial run.

The returned folder contains show1d_monitor.jsonl and snapshot .npy files. Use it with quantem.widget.Show1D.from_monitor_file(), or call Show1D.from_example("ducky") when a one-line widget is preferred.

Parameters:

• size – Tutorial payload size. Valid values are "small", "medium", "large", and "full". The current public upload provides the "small" payload; larger sizes are reserved for future higher resolution snapshots.

• cache_dir – Optional Hugging Face cache directory.

• revision – Optional Hugging Face dataset revision.

• force_download – If True, ask Hugging Face Hub to refresh the cached files.

• verbose – If True, print a short dataset summary.

Returns:

Local folder containing the Show1D monitor run.

Return type:

Path

quantem.widget.datasets.show2d_gold(*, size: str = 'small', cache_dir: str | Path | None = None, revision: str | None = None, force_download: bool = False, verbose: bool = True) → Dataset2d

Load the gold HAADF Show2D tutorial dataset by friendly size name.

The source image is downloaded once from widget-tutorials/shared/gold-haadf/full and the requested size controls the preview stride. The same source is reused by show3d_gold().

quantem.widget.datasets.show3d_gold(*, size: str = 'small', cache_dir: str | Path | None = None, revision: str | None = None, force_download: bool = False, verbose: bool = True) → Dataset3d

Load the gold HAADF Show3D tutorial stack by friendly size name.

The stack is built from moving crops of the shared gold HAADF tutorial source instead of storing a second copy of the image for Show3D.

quantem.widget.datasets.show4dstem_gold(*, size: str = 'small', cache_dir: str | Path | None = None, revision: str | None = None, force_download: bool = False, verbose: bool = True) → Dataset4dstem

Load the gold 4D-STEM Show4DSTEM tutorial scan by friendly size name.

The source scan is stored once under widget-tutorials/show4dstem/gold-128-bin8/full and the requested size controls the scan-axis stride.

quantem.widget.datasets.showfolder_gold(*, size: str = 'small', cache_dir: str | Path | None = None, revision: str | None = None, force_download: bool = False, verbose: bool = True, allow_fallback: bool = True) → Path

Download the compact gold HAADF ShowFolder tutorial session.

The returned folder contains the public .emd files used by the ShowFolder tutorial under widget-tutorials/showfolder/gold-haadf-session/small.