feat: add ShowPDF for pair distribution function analysis

.github/workflows/widget-release.yml

@@ -133,6 +133,7 @@ jobs:
               "quantem/widget/static/show4dstem.js",
               "quantem/widget/static/showcif.js",
               "quantem/widget/static/showdiffraction.js",
+              "quantem/widget/static/showpdf.js",
               "quantem/widget/static/showptycho.js",
           }
           with zipfile.ZipFile(wheel) as zf:

CHANGELOG.md

@@ -6,6 +6,18 @@ new `rcN` heading when that rc is published to TestPyPI.
 
 ## Unreleased
 
+- Add `ShowPDF` for pair distribution function analysis of 4D-STEM data: select
+  scan regions (mask, probe, line, or line scan) and tune the background fit,
+  k window, filters, and low-r damping on top of
+  `quantem.diffraction.PairDistributionFunction`. The number density is a
+  required input for g(r) and damping; it is never estimated. Standalone HTML
+  exports recompute the curves in the browser, and saved notebooks keep a static
+  picture unless `save_state=True`. ShowPDF needs the
+  `PairDistributionFunction` of quantem pull request 248, on quantem's dev
+  branch until its next release. Its tutorial (`docs/tutorials/showpdf.ipynb`),
+  with the `datasets.showpdf_ta` loader of a simulated amorphous Ta scan, joins
+  the docs after that release.
+
 ## rc41 - 2026-10-09
 
 - Show4DSTEM opens `.qem` acquisitions in the browser with no kernel:

README.md

@@ -124,6 +124,7 @@ require a source build containing them. The guide includes setup and browser req
 | `Show4DSTEM` | Live virtual detectors, multi-dataset review, and WebGPU HTML export | [tutorial](https://electronmicroscopy.github.io/quantem.widget/tutorials/show4dstem.html) · [export guide](https://electronmicroscopy.github.io/quantem.widget/tutorials/show4dstem_export.html) · [API](https://electronmicroscopy.github.io/quantem.widget/api/show4dstem.html) |
 | `ShowPtycho` | Interactive SSB phase and aberration review | [API](https://electronmicroscopy.github.io/quantem.widget/api/showptycho.html) |
 | `ShowDiffraction` | Measure diffraction spots, rings, spacing, and angles | [tutorial](https://electronmicroscopy.github.io/quantem.widget/tutorials/showdiffraction.html) · [API](https://electronmicroscopy.github.io/quantem.widget/api/showdiffraction.html) |
+| `ShowPDF` | Pair distribution function analysis of 4D-STEM data by scan region | [API](https://electronmicroscopy.github.io/quantem.widget/api/showpdf.html) |
 | `ChooseLattice` | Select an origin and lattice vectors | [API](https://electronmicroscopy.github.io/quantem.widget/api/choose-lattice.html) |
 | `ShowCIF` | Crystal repeats, columns, tilt, and projected potential/phase previews | [tutorial](docs/tutorials/showcif.ipynb) · [API](docs/api/showcif.md) |
 

docs/_toc.yml

@@ -75,6 +75,7 @@ parts:
           - file: api/show4dstem
           - file: api/showptycho
           - file: api/showdiffraction
+          - file: api/showpdf
           - file: api/choose-lattice
           - file: api/showcif
           - file: api/html-export

docs/api/datasets.md

@@ -13,16 +13,21 @@ from quantem.widget.datasets import (
     show3d_gold,
     show4dstem_gold,
     showdiffraction_fe3o4,
+    showpdf_ta,
+    showpdf_ta_ground_truth,
 )
 ```
 
 Images and stacks come back as quantem core `Dataset2d` and `Dataset3d`
 (`show2d_gold`, `show3d_gold`, `showdiffraction_fe3o4`), and the 4D-STEM scan
 as every 4D-STEM file reads (`read_4dstem`): a `quantem.gpu.io.Dataset4dstemGPU`
 when quantem.gpu is installed and a GPU is present, else a quantem core
-`Dataset4dstem` (`show4dstem_gold`). On an Intel Mac or Windows on ARM, which
-cannot install quantem core, the widget's stand-in carries the same `array`,
-`name`, `sampling`, `units`, `metadata`, `shape`, `ndim` and `dtype`.
+`Dataset4dstem` (`show4dstem_gold`). `showpdf_ta` returns a quantem core
+`Dataset4dstem` with its detector calibrated in 1/Å, and
+`showpdf_ta_ground_truth` the `(r, g)` arrays of its atomic model's g(r). On
+an Intel Mac or Windows on ARM, which cannot install quantem core, the
+widget's stand-in carries the same `array`, `name`, `sampling`, `units`,
+`metadata`, `shape`, `ndim` and `dtype`.
 `show1d_ducky` and `gold_session` return folders.
 
 All size selectors use the same language:
@@ -83,6 +88,11 @@ 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.
 
+`showpdf_ta()` and `showpdf_ta_ground_truth()` read `4dstem/ta_amorphous_sim/`
+(`data.npy`, `meta.json` and `ground_truth_gr.npz`), in the dataset's newer
+`<modality>/<name>` layout instead of under `widget-tutorials/`, at the dataset
+commit that added that folder; pass `revision` to read another.
+
 ## Reference
 
 ```{eval-rst}

docs/api/html-export.md

@@ -4,7 +4,7 @@
 
 1. **Widget-level HTML**: `widget.export_html(...)` writes one standalone widget
    viewer. Use this when a single Show1D / Show2D / Show3D / Show3DSlices /
-   Show4DSTEM / ShowDiffraction view is the artifact.
+   Show4DSTEM / ShowDiffraction / ShowPDF view is the artifact.
 2. **Notebook-level HTML**: `jupyter nbconvert --to html notebook.ipynb`
    exports a whole notebook with its saved widget state (add `--execute` to
    rerun it first). Use this for reports and
@@ -46,6 +46,7 @@ back to the `.ipynb` or `.html` file.
 | Show3DSlices | `export_html(path=None, *, title=None, encoding="full")` |
 | Show4DSTEM | `export_html(path=None, *, title=None, dtype="uint8", det_bin=1, scan_bin=1, export_kind="interactive", dataset_scope="unhidden")` |
 | ShowDiffraction | `export_html(path=None, *, title=None)` |
+| ShowPDF | `export_html(path=None, *, title=None, mode="single", encoding="full", downsample=None)` |
 | ShowPtycho | `export(path)` writes a folder: the widget page over exact bright-field counts; the browser builds transient BF-indexed reducers in WebGPU |
 
 `encoding="uint8"` (or `quantized=True`) stores display-scaled data; `downsample`
@@ -80,6 +81,7 @@ it writes the file by calling `export_html(...)`.
 | Show3DSlices | `full`, `uint8` | none | `uint8` packs against the global range |
 | Show4DSTEM | `dtype="uint8"`, `"uint16"` | `det_bin`, `scan_bin`: `1`, `2`, `4`, `8` | mean bin; `uint8` clips counts above 255 and says how many; `export_kind="interactive"` packs the counts into the page and refuses above 2 GiB, naming the least binning that fits; `export_kind="report"` writes static PNG virtual-image pages with no raw 4D |
 | ShowDiffraction | `full` (float32) | none | exact float32 frames |
+| ShowPDF | `full`, `uint8` | none | `full` stores the float32 curves; `uint8` adds every scan position's radial profile (8 bits per k bin) so mask, probe and line selections recompute in the browser |
 
 ## Single-file exports
 

docs/api/index.md

@@ -49,6 +49,7 @@ readers and test agents.
 | [Show4DSTEM](show4dstem) | `quantem.widget.Show4DSTEM` dispatcher | state JSON, PNG, interactive WebGPU HTML; large exports use a companion data directory |
 | [ShowPtycho](showptycho) | `quantem.widget.ShowPtycho` | ptychography state JSON, WebGPU folder export with BF-indexed `G(k)` payload |
 | [ShowDiffraction](showdiffraction) | `quantem.widget.showdiffraction.ShowDiffraction` | state JSON, PNG, interactive HTML |
+| [ShowPDF](showpdf) | `quantem.widget.showpdf.ShowPDF` | state JSON, results zip (CSV), PNG/PDF/TIFF curves, interactive HTML (`encoding="full"` / `encoding="uint8"`) |
 | [ChooseLattice](choose-lattice) | `quantem.widget.choose_lattice.ChooseLattice` | state JSON (`save_state=True`) |
 | [ShowCIF](showcif) | `quantem.widget.ShowCIF` | Interactive HTML with embedded coordinates; CDN widget manager requires network |