Meta Analysis Quarto NoteBook

[AritraDey-Dev]

Description

This PR implements a Quarto notebook for the meta-analysis. It uses the posterior files and trait.data.Rdata to run the Meta Analysis demo. A pecan.xml file is also included to run the workflow.

Motivation and Context

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]

Issue to open: one should be able to run the MA itself without a full settings object

[AritraDey-Dev]

<?xml version="1.0" encoding="UTF-8"?>
<pecan>
 <pfts>
  <pft>
   <name>temperate.coniferous</name>
   <posterior.files>pft/temperate.coniferous</posterior.files>
   <outdir>pft/temperate.coniferous</outdir>
  </pft>
 </pfts> 
 <meta.analysis>
    <iter>3000</iter>
    <random.effects>
      <on>FALSE</on>
      <use_ghs>TRUE</use_ghs>
    </random.effects><threshold>1.2</threshold>
  </meta.analysis>
</pecan>

This configuration alone is enough to run the meta-analysis; no additional model or run blocks are required.

[mdietze]

Cool. So I think it would be fine in the Issue I'm recommending to recommend that the MA module be refactored to take in the following as arguments:

1. trait dataframe
2. prior dataframe
3. output directory
4. list containing MA configs (iter, random.effects, use_ghs, theshold, etc.) with some sensible defaults

Here in the demo one could elect to grab those things from a settings object, but one could also build a demo based on just specifying those things.

[mdietze]

update: If this demo is updated to use the new meta_analysis_standalone function then I think we'll be able to get away from a pecan.xml and instead just have a code block that defines the inputs and configurations that the MA needs. That should make the use of the MA package more transparent.

That said, at the end of the demo you could show how to do the same thing with a pecan.xml and runModule.run.meta.analysis, which could reuse a lot of the text and code you've already written, and could point out that the "module" version is handy if you're running the MA as part of a larger modeling workflow

[AritraDey-Dev]

Updated in c40a0e0

[mdietze]

Issue to open: would be great to be able to pass data into the MA directly, rather than it having to come from a file with a very specific file name

[AritraDey-Dev]

Yes, I believe this needs a separate function to implement it. We just need to pass trait.data.Rdata and prior.distns.Rdata to make it work.

[AritraDey-Dev]

Instead, can we do this within this notebook by adding a section where the user only needs to provide the paths to trait.data.Rdata and prior.distns.Rdata ? If a user already has these two files, they can run the meta-analysis directly.

[mdietze]

follow up: I'm not requesting a change to this PR to implement what I'm suggesting. I'm instead asking that you open a new Issue to improve what we're doing in the future. Specifically, I'd recommend that the MA module take in the trait dataframe and prior dataframe as arguments to the function itself, rather than relying on the functions knowing to load those specific files from paths provided within an overly complex settings object. This will push a tiny bit of work into the demo (load the example files, look at them to see how they are formatted, pass them into the MA function) but IMHO will greatly increase the usability of the MA module as a stand-alone tool. Right now, it's functionally easy to to use the MA outside the PEcAn workflow, but its CONCEPTUALLY hard to do so because there's so much mystery in what it's doing. Right now, no one can actually run this as a stand alone module in practice without a whole lot of diving into the code to see what the module actually does and what it actually needs to work. Actually getting this working and documented might be a good place for a new GSOC student.

[AritraDey-Dev]

Done here #3718

[Mayanknishad9]

@AritraDey-Dev Thanks for creating issue #3717! I've implemented the format_try_for_ma() function in PR #3720.

This connects directly to @mdietze's suggestion about using external data. Once PR #3720 (TRY formatter) and issue #3718 (MA refactoring) are both implemented, this tutorial could show how to use TRY data with PEcAn's meta-analysis.

[mdietze]

per earlier comments, would be good to update to meta_analysis_standalone in this PR. Then #3720 could include an update to the tutorial mentioning the new TRY conversion function. This PR shouldn't wait for that -- because we don't have permissions to redistribute TRY data we can't include a fully worked example in the Demo.

[AritraDey-Dev]

@mdietze Thanks for the review and the detailed comments. I’ve tried to address and fix the suggested items in the subsequent commits.

[Mayanknishad9]

@mdietze This is a great suggestion. My format_try_for_ma() function (PR #3720 ) creates the trait_data dataframe from TRY exports that could feed directly into such a simplified MA function.

If the MA module is refactored as you suggest, users could:

1. Use format_try_for_ma() to convert TRY data to proper format
2. Pass that dataframe directly to a simplified run_meta_analysis() function
3. Bypass the complex settings object entirely

This would make PEcAn's meta-analysis much more accessible to researchers with external data sources.

[mdietze]

update: If this demo is updated to use the new meta_analysis_standalone function then I think we'll be able to get away from a pecan.xml and instead just have a code block that defines the inputs and configurations that the MA needs. That should make the use of the MA package more transparent.

That said, at the end of the demo you could show how to do the same thing with a pecan.xml and runModule.run.meta.analysis, which could reuse a lot of the text and code you've already written, and could point out that the "module" version is handy if you're running the MA as part of a larger modeling workflow

[mdietze]

If you switch to meta_analysis_standalone you might only need PEcAn.MA and could push the other library loads to the end when you show the module version.

[mdietze]

per earlier comments, would be good to update to meta_analysis_standalone in this PR. Then #3720 could include an update to the tutorial mentioning the new TRY conversion function. This PR shouldn't wait for that -- because we don't have permissions to redistribute TRY data we can't include a fully worked example in the Demo.

[mdietze]

This paragraph and the next are a bit repetitive. Recommend merging