Demo 2 Quarto notebook tutorial for PEcAn uncertainty analysis #3570

AritraDey-Dev · 2025-07-13T04:31:38Z

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.

Signed-off-by: Aritra Dey <[email protected]>

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 · 2025-08-05T21:43:00Z

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

AritraDey-Dev · 2025-08-26T20:28:10Z

@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.

documentation/tutorials/Demo_02_Uncertainty_Analysis/uncertainty.qmd

dlebauer · 2025-09-01T20:01:52Z

documentation/tutorials/Demo_02_Uncertainty_Analysis/uncertainty.qmd

Signed-off-by: Aritra Dey <[email protected]>

AritraDey-Dev · 2025-10-21T17:34:53Z

documentation/tutorials/Demo_02_Uncertainty_Analysis/uncertainty.qmd

+legend("topright", legend = c("LAI", "Above Ground Wood"), col = c("darkgreen", "brown"), lty = 1)
+```
+
+# 18. PEcAn Outputs


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 ?

I will remove this part and push the changes.

I've created #3661 to track future re-implementation of a meta-analysis tutorial.

And have implemented the requested revisions in AritraDey-Dev#10

mdietze · 2025-11-03T19:26:10Z

@AritraDey-Dev @dlebauer anything left to do or is this ready to merge?

AritraDey-Dev · 2025-11-04T14:45:11Z

Most of the core work for this PR is done; just waiting for @dlebauer’s review to get it merged.

….qmd demo - Enable auto-numbered and cross-referenced sections

dlebauer

I've consolidated sections 9&18, move some content to Demo 1, and automated section numbering 🤞🏻.

Please review AritraDey-Dev#10 and make or request any additional changes. Once that is complete, this should be ready to merge!

dlebauer · 2025-10-15T18:15:28Z

documentation/tutorials/Demo_02_Uncertainty_Analysis/uncertainty.qmd

+
+Editing the more interesting settings to change the PFT (`settings$pfts`) or extend the run (`settings$run$end.date`) is an optional exercise for the user. For example, you could change the pft or the end date, but this requires additional parameter files and meteorological inputs. This includes files containing parameters for that PFT (`settings$pfts$pft$posterior.files`), or a climate file (`settings$run$met$path$path1`) that extends to the desired simulation period.
+
+# 7. Create Output Directory


@AritraDey-Dev I think that this is automated by the prepare.settings() function, so the section can be removed. Please confirm.

yes indeed this is not needed.

dlebauer · 2025-11-10T23:33:17Z

documentation/tutorials/Demo_02_Uncertainty_Analysis/uncertainty.qmd

+legend("topright", legend = c("LAI", "Above Ground Wood"), col = c("darkgreen", "brown"), lty = 1)
+```
+
+# 18. PEcAn Outputs


I will remove this part and push the changes.

I've created #3661 to track future re-implementation of a meta-analysis tutorial.

dlebauer · 2025-11-11T00:41:44Z

documentation/tutorials/Demo_02_Uncertainty_Analysis/uncertainty.qmd

+legend("topright", legend = c("LAI", "Above Ground Wood"), col = c("darkgreen", "brown"), lty = 1)
+```
+
+# 18. PEcAn Outputs


And have implemented the requested revisions in AritraDey-Dev#10

documentation/tutorials/Demo_02_Uncertainty_Analysis/pecan.xml

CHANGELOG.md

documentation/tutorials/Demo_02_Uncertainty_Analysis/uncertainty.qmd

infotroph · 2025-11-10T22:59:00Z

documentation/tutorials/Demo_02_Uncertainty_Analysis/uncertainty.qmd

+
+1. Disabling database write operations because we are not using a database
+    ```{r disable-db-write}
+   settings$database <- NULL # Disable database operations for this demo


As we discussed for demo 1, I don't see why this is needed -- setting a list entry to NULL is the same as removing it, so why not just delete it from the XML in the first place?) -- and I'm really quite sure the user should not need to do it. If deleting this line makes the demo work wrong, please file an issue with a reprex so that we can fix whatever makes this distracting hack necessary.

Yes, for now deleting this line will not make the demo work. I agree that this line is unrelated to the demo. This is probably an issue with the PEcAn DB package.

documentation/tutorials/Demo_02_Uncertainty_Analysis/uncertainty.qmd

infotroph · 2025-11-11T07:12:17Z

documentation/tutorials/Demo_02_Uncertainty_Analysis/uncertainty.qmd

+├── run/                   # Configuration & execution metadata
+│   ├── runs.txt           # List of run IDs (one per model realization)
+│   ├── <runid>/           # Model-specific config copies (sometimes)
+│   └── config.*           # Generated model configs (e.g., SIPNET)


I have never seen config.* in the rundir! What module generates them?

Yes,A lot of refactoring need to be done in this part.i will fix this.

documentation/tutorials/Demo_02_Uncertainty_Analysis/uncertainty.qmd

infotroph · 2025-11-11T07:17:42Z

documentation/tutorials/Demo_02_Uncertainty_Analysis/uncertainty.qmd

+├── sensitivity.analysis/  # Sensitivity raw outputs &amp; figures
+│   ├── sensitivity.output.*.Rdata
+│   └── sensitivity.analysis.*.pdf
+├── ensemble.analysis/     # Ensemble summaries &amp; figures
+│   ├── ensemble.Rdata
+│   ├── ensemble.analysis.*.pdf
+│   └── ensemble.ts.*.pdf
+├── variance.decomposition/  # Created when variance decomposition runs
+│   └── variance.decomposition.*.pdf


I'm used to seeing all of these saved directly in outdir without their own subdirectories -- what process creates these?

fixed in 97c15b9

Minor changes to Demo 2

Signed-off-by: Aritra Dey <[email protected]>

Co-authored-by: Chris Black <[email protected]>

…ty.qmd Co-authored-by: Chris Black <[email protected]>

Signed-off-by: Aritra Dey <[email protected]>

CHANGELOG.md

Co-authored-by: Chris Black <[email protected]>

Signed-off-by: Aritra Dey <[email protected]>

dlebauer

Looks great, thanks for your persistence addressing all of the feedback!

github-actions bot added the Documentation label Jul 13, 2025

AritraDey-Dev changed the title ~~Quarto ensemble sensivity~~ Quarto notebook tutorial for PEcAn uncertainty analysis Jul 13, 2025

AritraDey-Dev requested review from dlebauer and mdietze July 15, 2025 11:40

AritraDey-Dev added 7 commits July 15, 2025 17:11

feat: uncertainty analysis quarto notebook

0300aeb

Signed-off-by: Aritra Dey <[email protected]>

correct pecan.xml path

3f84625

Signed-off-by: Aritra Dey <[email protected]>

fix: setings path

5f53a2e

Signed-off-by: Aritra Dey <[email protected]>

add additional instructions on ensemble analysis

e75b1f4

Signed-off-by: Aritra Dey <[email protected]>

set ensemble run no to 50 for customization

e836f28

Signed-off-by: Aritra Dey <[email protected]>

added pecan.xml for example

b94022e

Signed-off-by: Aritra Dey <[email protected]>

updated changelog.md

122ef77

Signed-off-by: Aritra Dey <[email protected]>

AritraDey-Dev force-pushed the quarto-ensemble-sensivity branch from 7033438 to 122ef77 Compare July 15, 2025 11:45

Merge branch 'develop' into quarto-ensemble-sensivity

846dd5a

dlebauer requested changes Aug 5, 2025

View reviewed changes

AritraDey-Dev force-pushed the quarto-ensemble-sensivity branch from 12f7e60 to b9cb3bf Compare August 26, 2025 13:58

AritraDey-Dev requested a review from dlebauer August 26, 2025 20:29

dlebauer changed the title ~~Quarto notebook tutorial for PEcAn uncertainty analysis~~ Demo 2 Quarto notebook tutorial for PEcAn uncertainty analysis Aug 27, 2025

dlebauer reviewed Aug 27, 2025

View reviewed changes

documentation/tutorials/Demo_02_Uncertainty_Analysis/uncertainty.qmd Show resolved Hide resolved

dlebauer reviewed Aug 27, 2025

View reviewed changes

documentation/tutorials/Demo_02_Uncertainty_Analysis/uncertainty.qmd Outdated Show resolved Hide resolved

dlebauer reviewed Sep 1, 2025

View reviewed changes

documentation/tutorials/Demo_02_Uncertainty_Analysis/uncertainty.qmd Outdated Show resolved Hide resolved

AritraDey-Dev force-pushed the quarto-ensemble-sensivity branch 2 times, most recently from 8d965d1 to cfface8 Compare September 30, 2025 17:23

AritraDey-Dev added 5 commits October 4, 2025 21:40

feat: uncertainty analysis quarto notebook

ad8ee17

Signed-off-by: Aritra Dey <[email protected]>

correct pecan.xml path

e9559ad

Signed-off-by: Aritra Dey <[email protected]>

fix: setings path

30c1d3d

Signed-off-by: Aritra Dey <[email protected]>

add additional instructions on ensemble analysis

9c775c6

Signed-off-by: Aritra Dey <[email protected]>

set ensemble run no to 50 for customization

70eb78b

Signed-off-by: Aritra Dey <[email protected]>

AritraDey-Dev commented Oct 21, 2025

View reviewed changes

dlebauer mentioned this pull request Nov 11, 2025

Update / expand meta-analysis demo #3661

Open

- Remove description of trait data and meta-analysis from uncertainty…

123c628

….qmd demo - Enable auto-numbered and cross-referenced sections

dlebauer mentioned this pull request Nov 11, 2025

Minor changes to Demo 2 AritraDey-Dev/pecan#10

Merged

dlebauer requested changes Nov 11, 2025

View reviewed changes

add self as co-author

0e54cb2

infotroph reviewed Nov 11, 2025

View reviewed changes

AritraDey-Dev and others added 9 commits November 15, 2025 22:37

Merge pull request #10 from dlebauer/uncertainty_demo_update

4193a99

Minor changes to Demo 2

fix pft outdir path

b6a06c7

Signed-off-by: Aritra Dey <[email protected]>

Update CHANGELOG.md

cf80986

Co-authored-by: Chris Black <[email protected]>

Update documentation/tutorials/Demo_02_Uncertainty_Analysis/uncertain…

7ac3aa5

…ty.qmd Co-authored-by: Chris Black <[email protected]>

Update documentation/tutorials/Demo_02_Uncertainty_Analysis/uncertain…

e3b2834

…ty.qmd Co-authored-by: Chris Black <[email protected]>

Update documentation/tutorials/Demo_02_Uncertainty_Analysis/uncertain…

2d6c85a

…ty.qmd Co-authored-by: Chris Black <[email protected]>

Update documentation/tutorials/Demo_02_Uncertainty_Analysis/uncertain…

fbf778b

…ty.qmd Co-authored-by: Chris Black <[email protected]>

Update documentation/tutorials/Demo_02_Uncertainty_Analysis/uncertain…

22f5069

…ty.qmd Co-authored-by: Chris Black <[email protected]>

fix: output directory structure

97c15b9

Signed-off-by: Aritra Dey <[email protected]>

AritraDey-Dev added the Type: Enhancement label Nov 20, 2025

AritraDey-Dev requested review from dlebauer and infotroph November 21, 2025 13:00

infotroph reviewed Nov 21, 2025

View reviewed changes

CHANGELOG.md Outdated Show resolved Hide resolved

AritraDey-Dev and others added 3 commits November 22, 2025 13:36

Update CHANGELOG.md

52e8db3

Co-authored-by: Chris Black <[email protected]>

allow multi variable outputs for ensemble analysis

628f626

Signed-off-by: Aritra Dey <[email protected]>

change naming for outputs

45553d2

Signed-off-by: Aritra Dey <[email protected]>

dlebauer approved these changes Nov 25, 2025

View reviewed changes

dlebauer added this pull request to the merge queue Nov 25, 2025

Merged via the queue into PecanProject:develop with commit 579b9d9 Nov 25, 2025
19 of 26 checks passed

AritraDey-Dev deleted the quarto-ensemble-sensivity branch November 25, 2025 07:49


		Editing the more interesting settings to change the PFT (`settings$pfts`) or extend the run (`settings$run$end.date`) is an optional exercise for the user. For example, you could change the pft or the end date, but this requires additional parameter files and meteorological inputs. This includes files containing parameters for that PFT (`settings$pfts$pft$posterior.files`), or a climate file (`settings$run$met$path$path1`) that extends to the desired simulation period.

		# 7. Create Output Directory

Demo 2 Quarto notebook tutorial for PEcAn uncertainty analysis #3570

Demo 2 Quarto notebook tutorial for PEcAn uncertainty analysis #3570

Conversation

AritraDey-Dev commented Jul 13, 2025

Description

Motivation and Context

Review Time Estimate

Types of changes

Checklist:

Uh oh!

dlebauer left a comment

Choose a reason for hiding this comment

Uh oh!

AritraDey-Dev commented Aug 5, 2025

Uh oh!

AritraDey-Dev commented Aug 26, 2025

Uh oh!

Uh oh!

Uh oh!

dlebauer commented Sep 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mdietze commented Nov 3, 2025

Uh oh!

AritraDey-Dev commented Nov 4, 2025

Uh oh!

dlebauer left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

infotroph Nov 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

dlebauer left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

dlebauer commented Sep 1, 2025 •

edited

Loading

infotroph Nov 11, 2025 •

edited

Loading