Rmd template for running workflow #3486

AritraDey-Dev · 2025-03-14T22:53:26Z

Description

This is for the issue #1866 and following up on the discussion by @mdietze in the issue #2784

This pull request introduces a new R Markdown file for the PEcAn modular workflow, which includes loading necessary packages, reading settings, and running various analyses. The key changes are summarized below:

New R Markdown file for PEcAn modular workflow:

Added file web/workflow_modular.Rmd with metadata including title, author, date, and output format.
Loaded PEcAn packages and settings files to prepare for the workflow execution.
Implemented trait analysis to fetch plant trait data and prior distributions.
Performed meta-analysis to derive probabilistic distributions for model parameters.
Generated model configuration files, executed model simulations, and retrieved results for further analysis.

Motivation and Context

This PR fixes #1866

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.

mdietze

First, I think the idea is to work with a Rmd, not a R script. Second, if code is in a Rmd code block, I don't see the advantage of also putting it in a function.

mdietze · 2025-03-15T22:06:51Z

web/workflow_modular.R

+
+run_model_execution <- function(settings_path, debug = FALSE) {
+  # Load settings
+  settings <- PEcAn.settings::read.settings(settings_path)


I don't think you want to re-load the settings object each time. Just pass the settings object, not the settings path

mdietze · 2025-03-15T22:07:41Z

web/workflow_modular.R

+  settings <- PEcAn.settings::read.settings(settings_path)
+
+  # Write configs
+  if (PEcAn.utils::status.check("CONFIG") == 0) {


status.check doesn't do much outside of the web interface, I think these bits can be dropped

You're right! PEcAn.utils::status.check() is primarily useful for the web interface, and for a standalone script, it doesn't add much value. We can safely remove those checks and simplify the script while ensuring proper execution

mdietze · 2025-03-15T22:08:04Z

web/workflow_modular.R

+  if (PEcAn.utils::status.check("CONFIG") == 0) {
+    if (debug) cat("Writing model configurations...\n")
+
+    PEcAn.utils::status.start("CONFIG")


Same with the status.start and status.end

AritraDey-Dev · 2025-03-16T17:40:40Z

thanks for reviewing ! i will make those changes in the new commits.

AritraDey-Dev · 2025-03-17T14:03:57Z

@mdietze I think we should keep this file in base/all/inst/ directory instead of keeping it in web directory?
Curious to know your thought on the changes.

robkooper · 2025-03-17T18:32:07Z

web/workflow_modular.Rmd

+output: html_document
+---
+
+```{r libraries}


Since this is a RMarkdown file, can you maybe add some text about what each section does. This will help for novice users to understand why this specific function is needed.

Maybe add a short description and a link to the documentation.

robkooper · 2025-03-17T18:33:15Z

web/workflow_modular.Rmd

+run.ensemble.analysis(plot.timeseries=TRUE) 
+```
+
+```{r finish}


Not sure this is needed. You know when it is done, when the last call returns.

The finish section isn't strictly necessary since the workflow naturally ends when the last function call completes. I included it as a simple confirmation message, especially useful when settings$debug is enabled.

Let me know if you prefer it removed!

I'd prefer to have this block removed

AritraDey-Dev · 2025-03-19T13:57:17Z

@mdietze @robkooper I am curious about your input on this PR—I’ve added descriptions for each section for clarity.Could you please review this once?

mdietze · 2025-03-19T17:34:35Z

web/workflow_modular.Rmd

+# Load PEcAn settings files.
+
+Open and read in settings file for PEcAn run.
+To create a pecan.xml, you can download one generated in the PEcAn web interface or one of the `pecan.<modelname>.xml` files in the tests/ directory of the PEcAn repository (github.com/pecanproject/pecan).


This is a good place to start, but I think in the longer term (not this PR) we'll want the Rmd to help build the settings and deprecate the web interface

There might be useful info you can pull from the tutorials (e.g. Demo 1, Demo 2, etc) to help populate the text between code blocks. Similar to (1), the long term goal (not this PR) is also to update those tutorials around the notebook-based interface

mdietze · 2025-03-19T17:39:33Z

web/workflow_modular.Rmd

+
+settings_path <- "settings.xml" 
+settings <- PEcAn.settings::read.settings(settings_path)
+settings <- PEcAn.utils::do_conversions(settings)


do.conversions 100% needs to be in a separate block.

Also, you're missing the steps that check/update the settings. e.g. PEcAn.settings::prepare.settings

mdietze · 2025-03-19T17:41:38Z

web/workflow_modular.Rmd

+}
+```
+
+# Trait Analysis


I'm not sure if we want the Trait Analysis and Meta Analysis in the default workflow. If we do they should be combined into one block since they're run together by default. If the block is retained, the text need to be expanded to describe this as OPTIONAL and what you need to provide if you elect not to run this (i.e. specify a posterior file in the settings object).

I see your point. I'll merge them into one block .

we have to make sure to clarify that if users skip the Trait & Meta Analysis step, they must manually specify a posterior file in the settings to ensure the model has the necessary input data for further analysis.

Correct. In practice, specifying a posterior file is the default way most runs are done, but it's also true that PEcAn doesn't ship with default posterior files for any models, which argues for keeping these tasks in the workflow. That said, it would be useful to add text/code to show users how to grab the posterior from this analysis so that they can re-use it in their future analyses. It's also worth noting, in the text, that this chunk is one of the few where a connection to the BETY database is currently no optional. A workflow that can run front-to-back with BETY being optional is desirable since it makes installation much simpler and also makes it possible to run in a HPC environment. One thing we could also do is to take the posterior files associated with published analyses (e.g. Fer et al 2018) and make sure they are somewhere publically archived and machine readable so that users could do a demo that doesn't require BETY.

mdietze · 2025-03-19T17:42:54Z

web/workflow_modular.Rmd

+
+```{r run-model}
+runModule.start.model.runs(settings)
+runModule.get.results(settings)


move get.results to the Model Analyses block. This function is specific to those analyses

Also, could be beyond this PR, but I think either this block, or a block after, would be a great place to show how to visualize the model outputs (e.g. a simple time series plot, a simple bivariate scatter plot). These would replace the interactive visualizations in the old web portal. I'd put this as #1 priority for the next PR.

would something simple like this work?
PEcAn.visualization::plot_netcdf(datafile, yvar, xvar, width, height, filename, year) (after taking the inputs)

Seems reasonable. Once you have a fully working workflow it would be nice if you could post a copy of the knit report so we all can see what the workflow looks like once run.

A few other things to note:

Please make sure to update changelogs

Please make sure to update the overall Documentation to reference this workflow

We should think about what sort of test need to be added to ensure this workflow continues to function (e.g., no new PRs break the workflow). My gut instinct is that this would be an integration test that runs the full workflow for any PR similar to the existing SIPNET Github Action. That said, adding an entirely new GH Action may be beyond an initial PR but is the sort of thing we should follow up on quickly.

mdietze · 2025-03-19T17:44:03Z

web/workflow_modular.Rmd

+run.sensitivity.analysis()      # Run sensitivity analysis and variance decomposition on model output
+run.ensemble.analysis()  	      # Run ensemble analysis on model output. 
+run.ensemble.analysis(plot.timeseries=TRUE) 
+```


Could be beyond this PR, but I think either this block, or a block after, would be a great place to visualize the results of these analyses.

mdietze · 2025-03-19T17:46:32Z

web/workflow_modular.Rmd

+run.ensemble.analysis(plot.timeseries=TRUE) 
+```
+
+```{r finish}


I'd prefer to have this block removed

AritraDey-Dev · 2025-03-23T15:59:43Z

@mdietze, I've been stuck on this issue for a while despite multiple debugging attempts—any insights would be really helpful !

mdietze · 2025-03-23T16:03:35Z

For that bug, have you identified what line of code is throwing the error and what the values are of the arguments being passed? If you can do that it's usually clear which argument is invalid, and then you can traceback to figure out where that input got misspecified or corrupted

AritraDey-Dev · 2025-03-23T16:18:07Z

@mdietze, I've been stuck on this issue for a while despite multiple debugging attempts—any insights would be really helpful !

yes i tried to log them.It looks something like this...

But not sure why the values are NULL.

AritraDey-Dev · 2025-03-23T18:38:13Z

test.pdf

@mdietze I am sharing the knit report for the workflow, with only the last step (running the workflow) removed.

From my investigation, the issue seems to stem from logging into RStudio with a different user, which prevents the correct configuration of the path to job.sh(As sometime it take values from pecan directory). I believe the workflow should function correctly in a properly configured environment. The changelogs and documentation i will add soon.

AritraDey-Dev · 2025-03-24T08:36:42Z

I believe this PR is ready now. @mdietze @robkooper When you have a moment, could you please take a quick look and let me know your feedback? I have also shared the knit report above.

mdietze · 2025-03-24T09:42:45Z

...e/02_demos_tutorials_workflows/02_user_demos/06_Workflow_using_Rmd_template.Rmd/workflow.Rmd

+
+This tutorial provides a step-by-step guide to running the **PEcAn Modular Workflow**. The PEcAn (Predictive Ecosystem Analyzer) system automates ecological modeling, helping researchers analyze plant functional traits, run model simulations, and perform sensitivity analyses.
+
+After setting up PEcAn locally, open **RStudio** in your browser and log in with:


These instructions are specific to the Docker stack.

yeah this should be in general.Will do the changes.

mdietze · 2025-03-24T09:47:07Z

...e/02_demos_tutorials_workflows/02_user_demos/06_Workflow_using_Rmd_template.Rmd/workflow.Rmd

+
+- Installed **PEcAn** and its dependencies.
+- An XML settings file (`settings.xml`) configured for your use case.
+- A model binary (e.g., **SIPNET** or **ED2**) specified in your settings.


A couple lines up refers to pecan.xml but here we refer to settings.xml, this will be confusing to new users

Can we add an example pecan.xml? For now it could be something configured to run specifically in the default Docker stack, but in the future we'll want to add a section to the Rmd itself to build/update the settings object.

I don't think you need an "or" in the e.g., especially if the default starting point will be SIPNET

added the steps for pecan.xml.

mdietze · 2025-03-24T09:50:35Z

...e/02_demos_tutorials_workflows/02_user_demos/06_Workflow_using_Rmd_template.Rmd/workflow.Rmd

+- An XML settings file (`settings.xml`) configured for your use case.
+- A model binary (e.g., **SIPNET** or **ED2**) specified in your settings.
+
+---


From here down appears to mostly duplicate the Rmd itself, which is unnessisary and redundant, meaning that it will also be hard to maintain as any changes there will have to be duplicated here. How to run the Rmd should be self-documenting.

...e/02_demos_tutorials_workflows/02_user_demos/06_Workflow_using_Rmd_template.Rmd/workflow.Rmd

mdietze · 2025-03-24T10:12:54Z

...e/02_demos_tutorials_workflows/02_user_demos/06_Workflow_using_Rmd_template.Rmd/workflow.Rmd

+PEcAn requires that settings be converted into the correct units before running model simulations.
+
+```{r convert-settings}
+if (!is.list(settings$host) || length(settings$host) > 1) {


This bit isn't being explained. Conceptually, it belongs in the prepare.settings block (and probably in prepare.settings itself)

This is just required for now. @infotroph already raised a Pr for this #3492 .in rstudio this is a solution for the issue described in #3492 .

In general, don't put temporary workarounds for unrelated issues into a feature PR. In cases like this where there's already a permanent fix proposed, I usually apply the fix for local testing but do not commit it into the feature branch.

For this issue specifically, this is the wrong fix as well. The issue in met.process: ensure host arg is passed on as a list #3492 wasn't the format of the host block, it was how met.process handled it internally, and it's expected for settings$host to contain other items besides name. Removing those other items will break later parts of the workflow that need to use them.

Apologies for that. As the issue is solved now, this can be safely removed.

mdietze · 2025-03-24T10:13:49Z

...e/02_demos_tutorials_workflows/02_user_demos/06_Workflow_using_Rmd_template.Rmd/workflow.Rmd

+
+# Trait and Meta Analysis
+
+PEcAn retrieves plant trait data and performs meta-analysis to derive parameter distributions for the model.


still need to explain this is optional and what the alternatives are

mdietze · 2025-03-24T10:16:02Z

...e/02_demos_tutorials_workflows/02_user_demos/06_Workflow_using_Rmd_template.Rmd/workflow.Rmd

+Model-specific configuration files are generated before running simulations.
+
+```{r run.write.configs}
+settings$model$binary <- "~/pecan/models/sipnet/"  # Update the path to your model


Updates to the settings need to be done higher up (e.g. around where you update outdir) and you need to explain what specifically you are doing in a way that a novice user would be able to update.

Also, this path is very misleading as 1. it points to a folder, not a binary and 2. no one should be installing the model binary inside the model coupler folder (or anywhere else in the PEcAn code itself)

actually this will point to model path but in setting as the name of the variable is modelbinary,on the first look it seems to be a binary,but it should be model path.I have tried to write the doc in that it will be clear.

...e/02_demos_tutorials_workflows/02_user_demos/06_Workflow_using_Rmd_template.Rmd/workflow.Rmd

mdietze · 2025-03-24T10:18:38Z

...e/02_demos_tutorials_workflows/02_user_demos/06_Workflow_using_Rmd_template.Rmd/workflow.Rmd

+
+---
+
+# Model Analyses


missing the code block that visualizes the output, which should come before the SA and EA. Also, this text should explain that it is run if those bit of the settings are configured (which they are not in a default run) and point the reader to where they would learn about how to configure them. Because this won't run by default it should also be described as optional

AritraDey-Dev · 2025-03-24T20:24:40Z

@mdietze could you review this once more?
I have made some changes in documentation and like you mention it's better not to keep entire code.I completely agree with that.I only put some small piece of code which could help user for a understandable explanation.Once this is done successfully,i can start working on the gh action for this.

dlebauer · 2025-03-25T17:14:12Z

I think the description may reference the wrong issue (#2784) could you please check?

AritraDey-Dev · 2025-03-25T17:30:45Z

I think the description may reference the wrong issue (#2784) could you please check?

The discussion regarding this with @mdietze started in the issue #2784,So it's there in the description.I will point the issue to #1866 .Thanks for the suggestion !

AritraDey-Dev · 2025-03-26T08:46:25Z

@mdietze whenever you have a moment please take a look at the changes once.

book_source/02_demos_tutorials_workflows/04_modular_workflow.Rmd

AritraDey-Dev · 2025-04-07T18:04:14Z

Hi @mdietze,
Just checking in on this PR—your review would be helpful to move things along when you have a moment.

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

…ow' into feat/modular-workflow

…r-workflow' into feat/modular-workflow" This reverts commit 7018a35, reversing changes made to cf1fb28.

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

mdietze · 2025-11-03T19:23:47Z

@AritraDey-Dev should this PR be pulled in or has it been superseded by the (already merged) Demo 1 PR (and this should be closed)

github-actions bot added the Website label Mar 14, 2025

AritraDey-Dev mentioned this pull request Mar 14, 2025

Add API endpoint to kill a workflow #2784

Open

AritraDey-Dev changed the title ~~Feat/modular workflow~~ Feat/monolithic to modular workflow Mar 14, 2025

mdietze requested changes Mar 15, 2025

View reviewed changes

AritraDey-Dev requested a review from mdietze March 16, 2025 17:53

robkooper requested changes Mar 17, 2025

View reviewed changes

AritraDey-Dev requested a review from robkooper March 17, 2025 19:21

mdietze requested changes Mar 19, 2025

View reviewed changes

AritraDey-Dev requested a review from mdietze March 19, 2025 19:07

AritraDey-Dev changed the title ~~Feat/monolithic to modular workflow~~ Rmd template for running workflow Mar 23, 2025

AritraDey-Dev mentioned this pull request Mar 23, 2025

met.process: ensure host arg is passed on as a list #3492

Merged

14 tasks

github-actions bot added the Documentation label Mar 24, 2025

mdietze reviewed Mar 24, 2025

View reviewed changes

AritraDey-Dev requested a review from mdietze March 24, 2025 18:13

divine7022 reviewed Mar 28, 2025

View reviewed changes

book_source/02_demos_tutorials_workflows/04_modular_workflow.Rmd Outdated Show resolved Hide resolved

divine7022 reviewed Mar 28, 2025

View reviewed changes

book_source/02_demos_tutorials_workflows/04_modular_workflow.Rmd Outdated Show resolved Hide resolved

AritraDey-Dev requested a review from infotroph April 1, 2025 12:06

AritraDey-Dev added 26 commits October 7, 2025 19:05

fix error in model run

8bad13a

fix: issue in multiple host for latest version of R

9ac5ad1

fix conflicts

02f77d8

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

added path of model binary

835e039

added changelog and documentation

df326fc

use correct function start_module_runs

a2f24cd

removed status.start

0191672

fixed documnrtation

7075e9b

fixed documnrtation

87c20fb

added in section 6

198e573

issue in ci

c5141b1

bookdown issue

b7a2399

added eval=FALSE

c738512

added eval=FALSE

0514322

refractor: unneccssary image

ed9dd44

refractor: anaysis doc

8296b7f

removed warning=false

71156bb

typo fix in doc

b91f72f

fix: met process

c9c635f

refractor: docs for rmd template

2b9ca2a

refractor workflow.Rmd

023ad6e

book source documentation

4f3990f

refractor changelog.md

fb29218

fix changelog

85ed48c

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

add rmarkdown to workflow pkg

cf1fb28

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

Merge remote-tracking branch 'refs/remotes/origin/feat/modular-workfl…

7018a35

…ow' into feat/modular-workflow

github-actions bot added the Base label Oct 7, 2025

AritraDey-Dev added 2 commits October 7, 2025 19:31

Revert "Merge remote-tracking branch 'refs/remotes/origin/feat/modula…

867eb2d

…r-workflow' into feat/modular-workflow" This reverts commit 7018a35, reversing changes made to cf1fb28.

remove duplicate copy of rmd file

cff2ba2

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


		This tutorial provides a step-by-step guide to running the PEcAn Modular Workflow. The PEcAn (Predictive Ecosystem Analyzer) system automates ecological modeling, helping researchers analyze plant functional traits, run model simulations, and perform sensitivity analyses.

		After setting up PEcAn locally, open RStudio in your browser and log in with:


		# Trait and Meta Analysis

		PEcAn retrieves plant trait data and performs meta-analysis to derive parameter distributions for the model.

Rmd template for running workflow #3486

Are you sure you want to change the base?

Rmd template for running workflow #3486

Conversation

AritraDey-Dev commented Mar 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Motivation and Context

Review Time Estimate

Types of changes

Checklist:

Uh oh!

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

AritraDey-Dev commented Mar 16, 2025

Uh oh!

AritraDey-Dev commented Mar 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

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!

AritraDey-Dev commented Mar 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

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!

AritraDey-Dev Mar 19, 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AritraDey-Dev commented Mar 23, 2025

Uh oh!

mdietze commented Mar 23, 2025

Uh oh!

AritraDey-Dev commented Mar 23, 2025

Uh oh!

AritraDey-Dev commented Mar 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

AritraDey-Dev commented Mar 24, 2025

Uh oh!

AritraDey-Dev commented Mar 14, 2025 •

edited

Loading

AritraDey-Dev commented Mar 17, 2025 •

edited

Loading

AritraDey-Dev commented Mar 19, 2025 •

edited

Loading

AritraDey-Dev Mar 19, 2025 •

edited

Loading

AritraDey-Dev commented Mar 23, 2025 •

edited

Loading

AritraDey-Dev Mar 26, 2025 •

edited

Loading

infotroph Mar 26, 2025 •

edited

Loading