Example Notebooks

[briochh]

Keen to start adding some more example Jupyter notebooks, to help shed light on the what and hows for using the various functionalities in pyEMU.

Would be great to get input (and volunteers) for putting some examples together. Ideally, I was thinking of many streamlined examples, addressing one or two methods (or variations of methods) each, this mean duplication but also opportunity to highlight different options for how to do things. Not sure the best way to compile the wishlist but we can start the conversation. My list so far of things to cover (some could def be grouped) :

• Example setting up PEST interface for a simple analytical model using PstFrom()
• Example for wrangling model inputs or outputs into forms supported by PstFrom()
• Example setting up uncorrelated list type multiplier style pars
• Example setting up uncorrelated array type multiplier style pars
• Example setting up multi-scale pars
• Example setting up direct style pars
• Example building covariance matrix for uncorrelated pars (and drawing parameter realisations)
• Example defining parameter correlations, building covariance matrix (and drawing).
• Example with non MODFLOW type model
• Example performing linear analyses (e.g. Schur)

+more

[jtwhite79]

Im keen B! All of those you list would be great additions. There have been several requests to demo how to setup pilot points so maybe some more examples of pilot points? I think @mnfienen has unstructured mf6 and a nested mf6 freyberg variants - would be nice to show how unstructured and nested models can be used with PstFrom (there is already a mf-usg pstfrom autotest). Also agree on a non-modflow example - what about swat? Ive done some pest-swat action before and I remember liking the swat input format. Maybe @MJKnowling could get us a cool smart-ag example? I would also like to get an example or add to an example of adding cycle numbers to get into the sequential data assimilation stuff.

[wkitlasten]

I always find it helpful to digest when the examples are small and self-contained (low cognitive capacity requires low cognitive load). So breaking them out into short, streamlined, standalone examples (obs, pars, pilot points, etc) sounds great!

I know using the usual Freyberg model is easy enough, but for the simple streamlined examples it might be worth creating the files in the notebook, esp with "model independence" in mind. A couple lines to make and write a generic "observations.csv" file or 5x5 array where the user immediately sees where each value is coming from (and can easily experiment/break stuff) might get more traction than using the freyberg example with 130 files of various types in the dir... which was copied from another dir... which is one of 7 dirs with "freyberg" in it (did I mention low cognitive capacity?). The "forward_run" can be stoopidly silly (e.g. multiply by 2) for the purposes of showing how to load/make stuff in pyemu.

With that said, a "full workflow" final example would also be nice, in which case freyberg is an obvious choice.

While you are at it, I find the 1-5 line "example" (stand alone if possible) at the end of the doc strings to be a super helpful starting point for those of us with low bandwidth:

Example::

        v = pyemu.utils.geostats.ExpVario(a=1000,contribution=1.0)
        gs = pyemu.utils.geostats.GeoStruct(variograms=v,nugget=0.5)

[langevin-usgs]

Forgive me if I'm stating the obvious, but from the flopy side (and also the mf6 side) we have been having some lucks with rtd rendering notebooks and/or python scripts, and this is done through github actions. See here for example. https://flopy.readthedocs.io/en/latest/_notebooks/tutorial02_mf6.html. I see pyemu uses RTD, but not for the examples as far as I can tell.

Rather than having monolithic notebooks, we are trying to move toward crisp little self-contained examples that describe bite-sized bits of information. Along those lines, that example linked to above is currently being rewritten into smaller individual sections. It's a lot of thankless work, but hopefully worthwhile in the long run.

If you decide to go this route (which introduces yet another failure point!), one of things we've found to be useful is running sphinx locally to preview these things before feeling around in the dark on github actions and waiting for it to show up in RTD. My unsolicited 2 cents!

[mnfienen]

@wkitlasten and @langevin-usgs I totally agree that bite-size chunks can be really useful for deeper understanding. Also some more involved cases can help people make the jump from synthetic to real-world. So, I see a mix of both.

Great idea to get going on this @briochh! I'm keen to help

[briochh]

Sweet, Thanks all. I am pretty slammed for the moment but hoping to carve out some time in the (relatively near) future. Good to have a collection of brains on board. In the meantime, if anyone has any more tidy topic suggestion dump them in here.

[aleaf]

Totally agree with what @langevin-usgs is saying re: rendering Notebooks using Sphinx (and nbsphinx). I think it makes the content of the notebooks much more accessible. No waiting time or issues with GitHub having to render the notebook, and the comment headers in the notebook are linked to in the documentation table of contents. And you don't even need RTD- using the github pages deploy action, they can be rendered straight to github pages as part of a github actions workflow. This can be done as part of a test workflow, by having a test module that executes the Notebooks you want to include and outputs the results to your docs folder. That way, you can guarantee that what is being shown in the docs is tested and consistent with the current state of the code. And the latest version of the docs can be refreshed with every commit. This workflow should be pretty easy to set up for pyemu; I'd be happy to help if you're interested.

[jtwhite79]

That would be a huge contribution @aleaf! We are running the notebooks as part of GH actions currently so hopefully it wont too terrible get to this next level. Lemme know how I can help.

@briochh - thinking about some geostats notebooks too, for things like variogram-to-covariance matrix, pilot points and factors, and spectral sim.