Documentation: goals, examples, and working with skills

[bwengals]

ptgp needs documentation. The docs are aimed at human readers, not LLMs. The skills files (#12) are for LLMs.

What ptgp is and what it's for

A landing page that describes the goal of the library, who it's for, and how it's different from other GP libraries.

Examples

Canonical textbook problems and/or real-world examples with interesting datasets. These should be:

• Short and not exhaustive, given the fact that our attention spans have been completely ruined
• Focused on real-world problems where GPs are underused, not just toy regression on a sine wave
• Have attractive, interactive plots
• Don't go into the weeds of every utility and helper

The examples can be pedagogical, but should go beyond "What is a GP?". There are already many good places to learn that and experiment with basic GPs. The examples should be aligned with the goals of ptgp: for practitioners trying to apply GPs to tricky problems.

Ideas

• Decision theory with GP predictive distributions — Rasmussen & Williams Ch. 2.4. GPs give you a full predictive distribution, not just a point estimate. With an asymmetric loss function (e.g. overestimating is much more costly than underestimating), the optimal prediction shifts away from the mean and you need the full distribution to compute it. This comes up constantly in practice (finance, safety, inventory) and is an example I really like. It'd be cool to show how to do this with ptgp on a believable problem and should show off pytensors usefulness too.

Working with skills files

A guide for using ptgp with an LLM via the skills files (see #12). How to install them, what they cover, how to use them to plan and debug a modeling problem interactively.

Open questions

• What would be some cool ideas for docs? What are your favorite existing GP examples?
• What plotting libraries / tools for interactive plots? (Plotly, Bokeh, etc.)

[jessegrabowski]

#24 adds two galleries we can take advantage of:

• covariance gallery, patterned after preliz distribution gallery. My starting point is this example from PyMC, but with more details.
• examples gallery, patterned after pymc-examples in general

I think the thing we should avoid in the example gallery is huge, sprawling notebooks. I think something arviz does really well is that they have bite-sized examples that are basically drop-in code snippets. We can have a bigger "Case Studies" section, but as pymc-examples showed, there's a danger that everything becomes a case study and it's hard to point a user somewhere if she just wants to know how to say do a time series decomposition.

[bwengals]

I'm wondering if the bite sized code snippet examples are as useful with LLMs around and able to pretty much generate them on the fly? I do really like the arviz docs though. I'm picturing the docs being very targeted for humans, since LLMs can just read the code. So a small amount of short well made and very visual case studies, and then in the main part of the docs have stuff like plots illustrating kernels.

[jessegrabowski]

I'm wondering if the bite sized code snippet examples are as useful with LLMs around and able to pretty much generate them on the fly?

Yeah that's true. But training data has to come from somewhere. I agree that case studies are probably more interesting in general though yeah.