Week 11 -- Documentation and user experience

[moryev]

Purpose

Implement the original Week 11 — Documentation and user experience phase so another person can install the toolkit, understand its scientific assumptions, run the main workflows, and reproduce the principal demonstrations without relying on development chat history.

This issue begins Phase 7 — Portfolio-quality release.

Goal

Turn the mature research codebase into a clear, usable, self-explanatory scientific software package.

Documentation should serve three audiences:

1. a scientist who wants to understand the physical/statistical assumptions;
2. a Python user who wants to install and run the toolkit;
3. a reviewer/employer/collaborator who wants to understand what the project demonstrates.

README / landing-page requirements

Update the README so it contains or clearly links to:

• Scientific motivation.
• Installation instructions.
• Five-minute quick start.
• Scientific assumptions and model boundaries.
• Minimal API examples.
• CLI examples.
• Benchmark/results summary table.
• Robustness/generalization findings.
• Uncertainty capabilities and semantics.
• Experimental-data workflow overview.
• Generalized IRF capabilities and limitations.
• Bayesian inference overview if Post-roadmap: Bayesian Poisson inference for TCSPC lifetime estimation #4 is included in the release.
• SQLite/SQL persistence example.
• Limitations / out-of-scope functionality.
• Roadmap / development status.
• Citation section.
• Reference to the associated article/preprint if one exists by release time.
• Screenshots or generated figures where they improve understanding.
• Reproducibility instructions.

Five-minute quick start

Provide one minimal example that demonstrates the core toolkit value with as little setup as possible.

The original roadmap example was conceptually:

import numpy as np

from tcspc_toolkit.fitting import fit_reconvolution
from tcspc_toolkit.simulation import simulate_tcspc_curve

time = np.linspace(0.0, 20.0, 512)

curve = simulate_tcspc_curve(
    time=time,
    lifetime=2.5,
    total_counts=100_000,
    background=2.0,
    irf_fwhm=0.15,
    random_seed=42,
)

result = fit_reconvolution(
    time=time,
    counts=curve.counts,
    irf=curve.irf,
)

print(result.lifetime)

Adapt this example to the stabilized public API after #2/#3 rather than preserving obsolete import/function names merely because they appeared in the original roadmap.

Acceptance for the quick start:

• Can be copied and run from a clean installation.
• Uses only public API imports.
• Runs quickly on a normal laptop.
• Produces an interpretable lifetime result.
• Uses explicit reproducible configuration/seed where randomness is involved.

Scientific assumptions

Document the main assumptions clearly and prominently, including as applicable:

• Poisson photon-counting statistics for raw histograms;
• mono-exponential model as the principal baseline model;
• IRF convolution/reconvolution assumptions;
• background treatment;
• temporal alignment/shift handling;
• distinction between synthetic ground truth and experimental reference values;
• limitations under bi-exponential/model-mismatch conditions;
• meaning and limitations of uncertainty intervals/scores;
• simulation-to-experiment distribution shift;
• limitations of leading-edge-derived IRF proxies;
• limitations of Bayesian uncertainty under model misspecification.

API documentation / examples

Provide concise examples for the major stable workflows:

• Synthetic TCSPC simulation.
• Classical reconvolution fitting.
• Preprocessing / feature extraction.
• ML prediction / benchmarking.
• Uncertainty evaluation.
• Experimental measurement import and analysis.
• Measured/generalized IRF handling.
• Bayesian inference where applicable.
• SQLite result persistence/querying.

Do not document unstable/private internals as if they were part of the public API.

CLI documentation

• Document available CLI commands and options.
• Include at least one copy-pasteable example.
• Ensure help text and README examples agree with actual CLI behavior.
• Remove or update stale CLI examples after the API/package refactor.

Benchmark and findings summary

Provide a concise table/section summarizing the principal scientific results developed through Weeks 7–10.

Include enough context that metrics are interpretable:

method
representation
regime
metric
important caveat

Do not overload the README with every experiment. Link to notebooks/docs for full detail.

Figures / screenshots

• Include a small number of high-value generated figures.
• Prefer figures that communicate TCSPC curves, estimator comparison, robustness, uncertainty, or the Week 10 sensing demonstration.
• Ensure figures can be regenerated from committed code.
• Avoid screenshots that will quickly become stale if a generated plot is more appropriate.

Reproducibility instructions

Document:

• supported Python version;
• environment/install commands;
• test command;
• notebook execution expectations;
• benchmark/config locations;
• random seed/reproducibility conventions;
• how to reproduce key benchmark tables/figures;
• how SQLite results are created/queried if included.

Citation / scholarly context

• Verify CITATION.cff is accurate.
• Provide a README citation section.
• Link the relevant associated article/preprint if available.
• Distinguish toolkit citation from citations for underlying scientific methods/dependencies where necessary.

User-experience review

Perform a fresh-user walkthrough:

1. Clone/install the repository from scratch.
2. Follow only the README.
3. Run the five-minute example.
4. Run one CLI example.
5. Locate the scientific assumptions and limitations.
6. Locate the main benchmark/sensing notebook.

• Record and fix confusing steps, missing imports, stale names, or hidden prerequisites.

Scope discipline

Week 11 is documentation and user experience, not another architecture or feature-development week.

Only make code changes required to fix genuine usability/documentation problems discovered during the fresh-user walkthrough. Larger new capabilities should be deferred to later issues/releases.

Acceptance criteria

• A new user can install the toolkit using documented instructions.
• The five-minute quick start runs unchanged from the documentation.
• Scientific assumptions and limitations are easy to find.
• Major public workflows each have a concise example or clear link.
• CLI documentation matches actual behavior.
• Key benchmark/sensing results are summarized without overstating conclusions.
• Reproducibility instructions are complete enough to regenerate the main outputs.
• Citation information is present and accurate.
• No stale roadmap-era API names are presented as current public interfaces.

Timing

Implement after the Week 10 sensing demonstration and before Week 12 CI/release work.

#13 Week 10 sensing demonstration
    ↓
#14 Week 11 documentation / UX
    ↓
#15 Week 12 CI / release