Demo 2 Quarto notebook tutorial for PEcAn uncertainty analysis

[AritraDey-Dev]

Description

Added a Quarto notebook tutorial for PEcAn uncertainty analysis (uncertainty.qmd) that demonstrates ensemble and sensitivity analysis workflows. The tutorial includes:

• Complete workflow from loading settings to running ensemble/sensitivity analyses
• Parameter customization sections for ensemble size, sampling methods, and sensitivity quantiles
• Comprehensive output interpretation guide explaining variance decomposition and parameter prioritization
• Model result visualization with run ID identification
• Session information for reproducibility

Motivation and Context

This change introduces Demo2 for the Quarto notebook focused on uncertainty analysis. It serves as a continuation and enhancement of the work initiated in Demo1. The goal is to extend the functionality and provide a more comprehensive demonstration of uncertainty analysis within the PEcAn framework.

Review Time Estimate

• Immediately
• Within one week
• When possible

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

• My change requires a change to the documentation.
• My name is in the list of CITATION.cff
• I agree that PEcAn Project may distribute my contribution under any or all of
  • the same license as the existing code,
  • and/or the BSD 3-clause license.
• I have updated the CHANGELOG.md.
• I have updated the documentation accordingly.
• I have read the CONTRIBUTING document.
• I have added tests to cover my changes.
• All new and existing tests passed.

[dlebauer]

Thank you for this PR, it is off to a great start and it is clear that you have a good understanding of how these analyses work.

I've started reviewing the notebook and have a few suggestions for how and what information is presented - I think it will be most effective if I flesh out some of the more technical details, and determine what information can be provided as cross references to publications vs what should be explained here.

But I'd also like to request some changes from the workflow side. Many of these are changes to Demo 1 that I suggested (AritraDey-Dev#6), and I think these should be reflected in this repository.

Some specific changes that come to mind:

• eliminate hard coded paths like /pecan and /data
• use R's file.copy() function in place of system('cp ...)
• don't assume user will be running in Docker with local binaries and absolute paths pre-installed
• the only difference between the pecan.xml files should be related to uncertainty / ensemble / sensitivity analysis. File paths and other settings should be the same. This helps clarify and identify the meaningful changes that are necessary.
• Make directory naming consistent - not clear why there is 01_Demo_basic_run, 02_Demo_Uncertainty_Analysis, and Demo_02_Uncertainty_Analysis.

These changes should help keep the tutorial easier to understand and maintain. Let me know if you’d like help implementing them—happy to pair on a walkthrough or review the follow-up PR. Thanks!

[AritraDey-Dev]

Yes, once the Demo 1 PR gets merged, I’ll add the changes you mentioned above here.

[AritraDey-Dev]

@dlebauer I have incorporated the changes from demo1, based on your feedback here.This PR is now ready for review. Could you please take a look.

[dlebauer]

Great work getting Demo 1 in #3531 merged 🎉 — that’s a big milestone!

Now that that one is merged, there is still a fair bit of cleanup to do here, and it will require updating Demo 1 as well. It’s all very doable, and I think the payoff will be a much more polished and user-friendly Demo 2.

Here are some steps:

• Merge branches and resolve conflicts. This branch is out of sync with the develop branch (which includes Demo 1. Some conflicts are trivial - e.g., Changelog, News) and should be straightforward to resolve. Some like standard_vars.csv and download_sipnet.R may not be as simple. I think you want standard_vars from the develop branch and download_sipnet from this branch.
• Remove / consolidate Background material:
  • All explanation of setup that is generic to PEcAn (PEcAn intro, scenario description, installing PEcAn + SIPNET, etc.) belongs in Demo 1.
  • We should assume users have completed Demo 1 already, and reference Demo 1 for more details.
  • Demo 2 can still include code snippets to ensure standalone execution, but the narrative should “jump right in,” mirroring the flow of the web-based Demo 2.
• Make sure that Pedagogical content from Web Demo 2 is included
  • Right now, a lot of the educational/explanatory scaffolding is missing. We’ll need to bring over:
    • Normal quantile explanation for sensitivity (pnorm(-2:2))
    • File/output map (what’s in /run, /out, /pft, etc.)
    • Plot interpretation guide (sensitivity curves, variance decomposition)
    • Reflective exercises on prioritizing constraints
    • Links to support/docs
  • These can be integrated as callouts, subsections, or short exercises so the Quarto tutorial keeps its runnable focus but doesn’t lose the teaching value.
• use plot_sensitivities and plot_variance_decomposition functions to show the results.

This is very close! While this is still a bit of work, it’s mostly structural and editorial / pedagogical. Once you have successfully merged the branches, consolidated the background, and made sure that all information from the original Demo 2 is in the new version, I can take a final pass at the writing.

[dlebauer]

Hi @AritraDey-Dev thank you for this!

I've made some major edits in AritraDey-Dev#7. Please review and let me know if I have changed the intent. The goal was to make it more clear and remove some explanations that had been covered in Demo 1.

I'll approve this one once that is merged.

[AritraDey-Dev]

@dlebauer are there any changes needed from your side, or is this PR ready to be merged?

[dlebauer]

Please cross reference with the original demo2 to make sure that the new one has all of the pedagogical content. Or, I can do that Monday.

[AritraDey-Dev]

This part is almost same as section 9 which tells about pecan outputs,also in this part as it mentions trait and meta analysis which we are not doing in this notebook,so can we remove this part @dlebauer ?