[melo-gonzo]

Base: the single-source PR #141. Merge after it. Documentation only.

Summary

Adds docs/uncertainty-quantification.md, a guide to the error bars the transient-chain example writes for the dipole center, the source position and the PSF flux. The guide covers:

• the overview: the three quantities, the quadrature sum behind <q>_err, and a three-step workflow (run, read, check)
• a quick start with launch.py, reading <q>_err and its terms from the catalog, and repeat_catalogs.py
• each term (fit, corr, kfit, kmatch, mis, and the sky astrometry reported apart): its cause and the cuphoton.xfit, cuphoton.xpois or cuphoton.xrep function that computes it, with links to the component pages
• the UQ catalog columns and how to rebuild an error bar with one term left out
• the uq configuration block, what each term needs from the survey and the earlier stages, and the uq.excluded reasons
• the variance inputs of the generic and rubin adapters
• the summary.json fields that record how the error bars were built
• a worked example that builds one PSF-flux error bar from xRep, xPois and xFit without the chain, and what each component gives on its own
• how to read the repeat test and its arms, what compare_catalogs.py reports, and coverage on injected sources
• the limits

docs/README.md links the guide under "Adapting and validating". docs/glossary.md gains Correlation factor, Coverage, Error bar, Error budget, Kernel mismatch and Repeat test.

The guide describes the code in this stack. The kernel-mismatch position step and the residual-background term are not in it yet, so the guide lists positions without a kernel-mismatch term as a limit.

Validation

• The code blocks of "Use the components on their own" ran as written on CPU against this branch, on synthetic images.
• Function and argument names, CLI flags, configuration keys and defaults, catalog columns, summary.json keys and exclusion reasons were checked against the code. A second read-only review against the code found seven inaccuracies, all fixed in this commit.
• Every relative link and anchor resolves.
• pre-commit run --files on the three files: every hook that applies to Markdown passed. The mypy hook did not run because the lockfile supports Linux only and the run was on macOS. No Python changed.

Repository hygiene

• No credentials, private paths, local datasets, notebook outputs, or generated run artifacts were added.
• Large binary artifacts are excluded or intentionally tracked through an approved storage plan.
• Security-sensitive information is not included.
• User-visible behavior changes are documented.
• New dependencies and their licenses are documented. (None added.)

Stack

PR	Base	Line
#137	main	xPOIS
#138	main	transient-chain example
#139	#138	transient-chain example
#140	#139	transient-chain example
#141	#140	transient-chain example
this PR	#141	documentation

Merge each line bottom up.

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[coderabbitai]

Important

Review skipped

Auto reviews are limited based on label configuration.

🏷️ Required labels (at least one): 1

• ai-review

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

Run configuration

• Source mode: Auto
• Repository: NVIDIA/cuPhoton
• Branch: codex/transient-uq-guide
• File: .coderabbit.yaml
• Commit: 211b10e
• Layers: Repository YAML
• Review profile: CHILL
• Plan: Enterprise
• Run ID: 51ef94a6-ee5d-407e-9cdd-aa56d7c696b2

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

_{Comment @coderabbitai help to get the list of available commands.}