Example Data

Example Data#

Electron microscopists often want to try a viewer before finding, copying, or converting their own raw files. quantem.data provides a small public set of real microscopy datasets with calibration attached, so a notebook can say “load the gold HAADF example” and get a Dataset2d object ready for Show2D.

This page uses a real HAADF image of gold nanoparticles. The original array is 4096 by 4096 uint16 data; the tutorial makes a calibrated preview crop so the documentation page opens quickly while the full cached file remains available for local work.

Tip

Run this exact notebook with the Colab badge above, or View or download this notebook on GitHub. For finished results, use HTML and file export to export interactive HTML or share a trusted notebook with widget state.

import quantem.widget as qw
qw.profile()

from quantem.widget import Show2D, Show3D
from quantem.widget import datasets as widget_datasets
from quantem.widget.datasets import show2d_gold, show3d_gold

quantem.widget  0.0.1rc44.dev0
  install       editable checkout
  commit        2d009a7f61ee (dirty checkout)
quantem.gpu     0.0.1rc18.dev0
  install       local build
  commit        not recorded
quantem         0.1.10
  install       installed package
  commit        not recorded
webgpu kernels  fa4a86c (fa4a86cfee85), pinned fa4a86cfee85ea719be2dd98206d2098f0dd3344
torch           2.14.1+cu130  device=cpu
python          3.12.15

Choose a widget tutorial dataset#

Use quantem.widget.datasets when you want a ready-to-view tutorial payload with clear size names and no Hugging Face path management. These helpers reuse shared acquisitions from haadf/ and 4dstem/ at an immutable revision. Tutorial datasets records their paths and the verified widget/ collections.

[name for name in widget_datasets.__all__ if name.startswith("show")]

['show1d_ducky',
 'show2d_gold',
 'show3d_gold',
 'show4dstem_gold',
 'showpdf_ta',
 'showpdf_ta_ground_truth']

Load a calibrated HAADF image#

Load the small Show2D gold example by friendly name. The helper downloads the shared source image once, applies the documentation-sized stride, and returns a calibrated Dataset2d. Future runs reuse the local Hugging Face cache.

preview_dataset = show2d_gold(size="small", verbose=False)
preview = preview_dataset.array
pixel_size_nm = float(preview_dataset.sampling[0])

print(f"Dataset: {preview_dataset.name}")
print(f"Shape:   {preview.shape[0]} x {preview.shape[1]} pixels")
print(f"Counts:  {preview.dtype}")
print(f"Pixel:   {pixel_size_nm:.4f} {preview_dataset.units[0]}/pixel")

show2d_gold(size='small') keeps every 8th pixel of the 4096x4096 image (512x512); size='full' loads native pixels.
Dataset: Gold HAADF preview
Shape:   512 x 512 pixels
Counts:  float32
Pixel:   0.1489 nm/pixel

Show2D preview#

The preview keeps the calibrated pixel size, so the scale bar remains physically meaningful while the documentation page opens quickly.

Show2D(preview_dataset, cmap="inferno")

Show3D from the same source#

show3d_gold derives a moving-crop stack from the same shared HAADF source used by show2d_gold. The source is stored once under haadf/gold_haadf_npy; the Python helpers create the widget-specific view.

stack_dataset = show3d_gold(size="small", verbose=False)

Show3D(stack_dataset, fps=12, cmap="inferno")

show3d_gold(size='small') crops from every 8th pixel of the 4096x4096 image; size='full' crops native pixels.

Larger files#

The lower-level data APIs still work for larger raw 4D-STEM and EDS datasets. Choose those intentionally because they can be hundreds of MB or several GB.

# Example only: raw-data APIs may expose larger public folders depending on install.
# from quantem.gpu.io import discover, load
# import quantem.data as qdata
# path = qdata.download("4dstem/gold_512", revision="5925e4b49b2ca28ff82d6d5a6b9a8bfea9edfb20")
# loaded = load(discover(path)[0])  # encoded on the GPU at native detector sampling

For shareable widget tutorials, prefer the quantem.widget.datasets helpers because they pin their inputs and reuse one shared acquisition across widgets.

Widget tutorial shortcuts#

The widget tutorials use quantem.widget.datasets when the goal is to open a ready-to-view example without thinking about Hugging Face folder names, strides, or monitor-file layout:

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

These helpers use the shared size language small, medium, large, and full. Unique viewer inputs live under widget/ at the documented immutable revision. Older folder layouts require their matching software version. Reused sources are stored once, for example Show2D and Show3D both derive from haadf/gold_haadf_npy instead of keeping separate copies. To add a fixture, follow the quantem-data dataset card, then the GitHub loader steps in Contribute tutorial data.

Upload your own data#

The examples above live in the public Hugging Face repo bobleesj/quantem-data The dataset card records licensing and provenance; a repository license does not replace input-specific permission. The Hub is data-only: keep code, notebooks, checkpoints and rendered reports in their owning repositories. The GitHub loader pull request is in Contribute tutorial data.