Updates to improve input demo documentation by abbylewis · Pull Request #4035 · PecanProject/pecan

abbylewis · 2026-06-24T16:27:41Z

Description

Updated the PEPRMT demos, including:

More text explanation, especially in the first two demos
Added year as a PEcAn standard variable (was listed as a TODO)
New visualizations in the second demo so users see that it's working
@infotroph not huge updates, but I think this should be helpful for CARB/etc to understand what's happening in the demos

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.

abbylewis · 2026-06-24T16:29:11Z

-│   ├── <runid>/           # Model-specific config copies (sometimes)
-│   └── config.*           # Generated model configs (e.g., SIPNET)
+│   ├── <runid>/           # Model-specific configs, including run job and driver data
+│   └── config.*           # Generated model configs (not used for PEPRMT)


Is this true?

It's definitely true PEPRMT doesn't use it and TBH I'm not sure what files this is talking about or what model uses them. Probably safe to delete this line.

abbylewis · 2026-06-24T16:30:06Z


 Key subdirectories include `run/` and `out/` that contain files used to configure and run the model, files generated by the underlying ecosystem model, and PEcAn standard outputs used in downstream analyses. These are described in subsequent sections.

-Additional outputs include logs, a `STATUS` file that records the steps of the workflow along with timestamps and whether each step was successful, and a copy of the `pecan.*.xml` file.


We might want to add something like this back but as is, I found it more confusing than helpful

I think these can be added to the file tree diagram -- I'll leave some suggestions to illustrate

infotroph

Thanks! I agree this is a big improvement. I left a few suggestions throughout, mostly with wording suggestions you can modify or reject freely.

infotroph · 2026-06-25T07:47:16Z

  - "Aritra Dey"
  - "David LeBauer"


At this point you've modified the source demo enough that it's probably appropriate to list yourself as the sole author and credit previous work with wording something like "This demo is patterned after PEcAn demo 1 (link here), which was written by Aritra Dey and David LeBauer". @AritraDey-Dev and @dlebauer does that make sense to y'all?

infotroph · 2026-06-25T07:52:26Z

-here::i_am("models/peprmt/demo_run/run_pecan_peprmt.qmd")
-```
-
 - A valid `pecan.xml` configuration file or use the example provided: `pecan/models/peprmt/demo_run/settings.xml`


I keep forgetting this is part of the "Before running this notebook...' list and reading it as a fragment. Would this rephrase help?

Suggested change

- A valid `pecan.xml` configuration file or use the example provided: `pecan/models/peprmt/demo_run/settings.xml`

- You will also need a valid `pecan.xml` configuration file, such as the example provided: `pecan/models/peprmt/demo_run/settings.xml`

infotroph · 2026-06-25T08:01:55Z

-│   ├── <runid>/           # Model-specific config copies (sometimes)
-│   └── config.*           # Generated model configs (e.g., SIPNET)
+│   ├── <runid>/           # Model-specific configs, including run job and driver data
+│   └── config.*           # Generated model configs (not used for PEPRMT)


It's definitely true PEPRMT doesn't use it and TBH I'm not sure what files this is talking about or what model uses them. Probably safe to delete this line.

infotroph · 2026-06-25T08:21:21Z

-```
+```         
 demo_outdir/               # Root output directory
 ├── run/                   # Configuration & execution metadata


Suggested change

├── run/ # Configuration & execution metadata

├── ensemble.samples.<ensemble_id>.Rdata # contains the selected parameter values for each ensemble member

├── run/ # Configuration & execution metadata

infotroph · 2026-06-25T08:22:48Z

+│   └── config.*           # Generated model configs (not used for PEPRMT)
 ├── out/                   # Raw model outputs by run ID
-│   └── <runid>/           # E.g., daily PEPRMT output files
+│   └── <runid>/           # E.g., PEPRMT output files


Suggested change

│ └── <runid>/ # E.g., PEPRMT output files

│ └── <runid>/ # E.g., PEPRMT output files

├── STATUS # timestamp and ok/error status of each workflow step

├── pecan.*.xml # copies of the run settings saved at different steps

├── run_manifest.csv # info about site, PFT, etc for each runid

└── samples.Rdata # draws from parameter distributions

Rephrase all of the above freely, but key point is it seems worth documenting all these files here while we're explaining it.

infotroph · 2026-06-25T08:35:25Z

-```

+model_output_marginal |>
+  mutate(site_id = sub("ENS-\\d+-", "", run_id)) |>


Suggested change

mutate(site_id = sub("ENS-\\d+-", "", run_id)) |>

mutate(

site_id = sub("ENS-\\d+-", "", run_id),

CH4_flux = PEcAn.utils::ud_convert(CH4_flux, "kg/m2/s", "mg/m2/d")

) |>

infotroph · 2026-06-25T08:35:54Z

+  select("site_id", "run_id", "posix", "CH4_flux") |>
+  ggplot() +
+  aes(x = posix, 
+      y = CH4_flux * 1E6 * 60 * 60 * 24, # Convert from kg/m2/s to mg/m2/d


Suggested change

y = CH4_flux * 1E6 * 60 * 60 * 24, # Convert from kg/m2/s to mg/m2/d

y = CH4_flux,

infotroph · 2026-06-25T08:45:44Z

 In non-demo cases, you would of course create this file by actually running an MCMC sampler and would probably want to include all the parameters in the same sampling (and therefore only pass a single `trait.mcmc.RData` into the run).

-Caution: If two or more PFTs define a parameter with the same name, `get.parameter.samples` will provide a draw from each of them and pass both as the `trait.values` argument to `write.config.PEPRMT`, which will then use whichever value appears first in `trait.values`, which is in turn determined by which PFT appears first in `settings$run$site$site.pft`.
-TODO: PEcAn should probably have a cross-model policy on how to handle duplicate parameter definitions (but one that realizes there exist models that _do_ use both of them, e.g. models that explicitly represent more than one simultaneously grown PFT).


I assume you're following a style preference here, but to mildly defend my previous formatting: Since Markdown will render adjacent lines as one paragraph, when I'm writing something that's going to be version-controlled I like to start each sentence on a new line so that future edits can have smaller diff chunks. Not a big deal, but I find it does make a difference.

infotroph · 2026-06-25T08:46:58Z

+  select("site_id", "run_id", "posix", "CH4_flux") |>
+  ggplot() +
+  aes(x = posix, 
+      y = CH4_flux * 1E6 * 60 * 60 * 24, # Convert from kg/m2/s to mg/m2/d


Same suggestion to use ud_convert here as above

infotroph · 2026-06-25T08:48:18Z

-* `data/PEPRMT_specific_inputs/`
-* `data/pfts/default_marginal/`
+We also assume you have already run `02_input_demo.qmd`. This demo uses
+these files created by in the second demp:


Suggested change

these files created by in the second demp:

these files created by the second demo:

abbylewis added 4 commits June 24, 2026 12:04

Updates to improve input demo documentation

70fceae

file names

b608907

labels

eb9d166

Tiny documentation changes for demo3

1bd390d

github-actions Bot added base models labels Jun 24, 2026

abbylewis commented Jun 24, 2026

View reviewed changes

infotroph approved these changes Jun 25, 2026

View reviewed changes


		Key subdirectories include `run/` and `out/` that contain files used to configure and run the model, files generated by the underlying ecosystem model, and PEcAn standard outputs used in downstream analyses. These are described in subsequent sections.

		Additional outputs include logs, a `STATUS` file that records the steps of the workflow along with timestamps and whether each step was successful, and a copy of the `pecan.*.xml` file.

	- A valid `pecan.xml` configuration file or use the example provided: `pecan/models/peprmt/demo_run/settings.xml`
	- You will also need a valid `pecan.xml` configuration file, such as the example provided: `pecan/models/peprmt/demo_run/settings.xml`

	├── run/ # Configuration & execution metadata
	├── ensemble.samples.<ensemble_id>.Rdata # contains the selected parameter values for each ensemble member
	├── run/ # Configuration & execution metadata

-│   └── <runid>/           # E.g., PEPRMT output files
+│   └── <runid>/           # E.g., PEPRMT output files
+├── STATUS                 # timestamp and ok/error status of each workflow step
+├── pecan.*.xml            # copies of the run settings saved at different steps
+├── run_manifest.csv       # info about site, PFT, etc for each runid
+└── samples.Rdata          # draws from parameter distributions

-  mutate(site_id = sub("ENS-\\d+-", "", run_id)) |>
+  mutate(
+    site_id = sub("ENS-\\d+-", "", run_id),
+    CH4_flux = PEcAn.utils::ud_convert(CH4_flux, "kg/m2/s", "mg/m2/d")
+  ) |>

	y = CH4_flux * 1E6 * 60 * 60 * 24, # Convert from kg/m2/s to mg/m2/d
	y = CH4_flux,

	these files created by in the second demp:
	these files created by the second demo:

Uh oh!

Conversation

abbylewis commented Jun 24, 2026

Description

Review Time Estimate

Types of changes

Checklist:

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!

infotroph 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!

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants