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,
    showdiffraction_fe3o4,
    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 (bobleesj/quantem-data) is organized under widget-tutorials/. Reused sources live once under shared/; widget-specific monitor runs or session folders live under the widget name. Upload and download commands are on that dataset card. The GitHub loader pull request is in Contribute tutorial data.

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/show4dstem/gold-512-bin4/full/data.npy
widget-tutorials/show4dstem/gold-512-bin8/full/data.npy
widget-tutorials/showfolder/gold-haadf-session/small/*.emd

showdiffraction_fe3o4() expects widget-tutorials/showdiffraction/fe3o4-saed/small/data.npy. That folder is not in the current hub snapshot.

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.showdiffraction_fe3o4(*, size: str = 'small', cache_dir: str | Path | None = None, revision: str | None = None, force_download: bool = False, verbose: bool = True, allow_fallback: bool = True) → ndarray

Load the real Fe3O4 nanoparticle SAED pattern used by the ShowDiffraction tutorial.

The pattern is downloaded from widget-tutorials/showdiffraction/fe3o4-saed and falls back to a packaged copy when the download is unavailable. It is uncalibrated by design; the tutorial calibrates it against the Fe3O4 phase.

Parameters:

• size – Tutorial payload size. Valid values are "small", "medium", "large", and "full". The public upload provides the "small" payload.

• 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.

• allow_fallback – If True, use the packaged pattern when the download is unavailable.

Returns:

512 by 512 float32 diffraction pattern.

Return type:

np.ndarray

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.