Fix(uncertainty): allow explicit MCMC and distribution paths; avoid o…

[shbhmexe]

Title: fix(uncertainty): allow explicit MCMC and distribution paths; avoid overloading pft$outdir as an input

What was fixed or enhanced:

• get.parameter.samples() implicitly treated pft$outdir as an input source for both post.distns.Rdata and trait.mcmc.Rdata. This forced read-only calibration artifacts to be placed/mixed in output directories. The function now supports explicit, per‑PFT input paths and only falls back to pft$outdir when nothing is provided.

Why the change was necessary:

• To separate immutable input artifacts (posterior distributions and MCMC samples) from workflow outputs and to align with the intent that pft$outdir is primarily for outputs. This reduces confusion and accidental overwrites and enables using externally curated calibration results without copying them into PEcAn’s output tree.

What exact changes were made:

• Updated modules/uncertainty/R/get.parameter.samples.R to:
  • Accept posterior.files as either a vector of distribution files (backward compatible) or a list of lists per PFT with named entries distribution and/or mcmc.
  • If posterior.files[[i]]$mcmc is provided, load that MCMC directly and skip any pft$outdir/DB fallback; preserve PDA correlation handling.
  • If posterior.files[[i]]$distribution is provided, load it directly; otherwise, fall back to the most recent post.distns.Rdata in pft$outdir, then prior.distns.Rdata.
  • Added roxygen comments documenting the new accepted structure while keeping the old behavior working.

How it improves the project:

• Decouples input data locations from output directories, reducing accidental mixing of inputs/outputs and enabling cleaner workflows, especially when posteriors are generated offline.

Verification steps:

1. Provide explicit paths for a single PFT:

settings <- PEcAn.settings::read.settings('pecan.xml')
posterior.files <- list(list(
  distribution = '/path/to/post.distns.Rdata',
  mcmc         = '/path/to/trait.mcmc.Rdata'
))
PEcAn.uncertainty::get.parameter.samples(settings, ensemble.size = 3, posterior.files = posterior.files)

2. Confirm that samples.Rdata is written under settings$outdir and that no files are read from pft$outdir when explicit paths are provided.
3. Backward compatibility: call with posterior.files = NA and confirm previous fallback behavior still works.

Next steps (optional, not included in this PR):

• Consider moving MA/SA output directories to settings$meta.analysis and settings$sensitivity.analysis blocks respectively, to fully eliminate the input/output overloading risk.

Modified Files

• modules/uncertainty/R/get.parameter.samples.R ✅ push

No config or environment files were added.

[infotroph]

See #3662 for problem description and design discussion that has continued after this PR was started