[WIP] feat(edm): implement EDM model families, R-level user workflows, and documentation

[aman-raj-srivastva]

Summary

Building upon the previously merged delay embedding infrastructure (#1528), prediction framework (#1561), and FIMS/TMB integration (#1620), this PR focuses on delivering high-level R interfaces, EDM model family abstractions, expanded R test coverage, and user documentation for Empirical Dynamic Modeling (EDM) within FIMS.

---

Goals

This PR focuses on:

• Providing high-level R interfaces for fitting and forecasting with EDM.
• Introducing user-friendly EDM model family abstractions.
• Building reusable workflows for univariate and multivariate EDM models.
• Expanding R-level testing.
• Improving documentation for end users.

---

Planned Changes

High-Level R Interface

Introduce user-facing wrapper functions that simplify running EDM models without directly interacting with low-level C++ interface objects.

Proposed API

fit_edm(data, method = c("simplex", "smap", "gp"), embedding_name = NULL,
        E = 3L, tau = 1L, theta = 1.0, n_neighbors = 0L, forecast_horizon = 1L)

edm_forecast(fit, n_ahead = 1L)

These wrappers will build upon the existing EDM prediction framework while providing a simpler interface for fisheries scientists.

---

EDM Model Families

Implement reusable abstractions for:

• Univariate EDM models
• Multivariate EDM models
• Environmental and biological covariates
• Future fisheries-specific EDM workflows

These abstractions will reuse the prediction framework implemented in #1561 and the FIMS integration introduced in #1620.

---

Integration with FIMS

Provide higher-level workflows demonstrating how EDM predictions can be used within existing FIMS stock assessment pipelines.

Example use cases include:

• Recruitment forecasting
• Biomass forecasting
• Hybrid EDM + stock assessment workflows

---

Testing

Expand testthat coverage for:

• High-level R wrapper functions
• EDM model construction
• Forecast generation
• Delay embedding extraction utilities
• Model output reshaping and validation

---

Documentation

This PR will include:

• Complete roxygen2 documentation for exported R functions.
• Doxygen documentation for newly added C++ components.
• User documentation for the high-level EDM workflow.

The complete end-to-end EDM vignette (vignettes/edm-user-guide.Rmd) will be delivered in a follow-up PR once the R interfaces are finalized and reviewed.

---

Expected Outcome

After this work is complete, users will be able to:

• Fit EDM models directly from R.
• Generate empirical forecasts using high-level interfaces.
• Build univariate and multivariate EDM workflows.
• Integrate EDM with traditional FIMS stock assessment models.
• Follow documented examples demonstrating complete EDM workflows.

---

Checklist

• High-level R wrapper functions (fit_edm(), edm_forecast())
• Univariate EDM model family
• Multivariate EDM model family
• Support for environmental and biological covariates
• Integration with existing FIMS EDM infrastructure
• Expanded testthat coverage
• roxygen2 documentation
• Doxygen documentation
• User guide vignette

---

Related

• Builds on Add EDM delay embedding infrastructure and tests #1528
• Builds on feat(edm): implement EDM prediction framework (Simplex, S-Map, GP-EDM) #1561
• Builds on feat(edm): integrate EDM prediction framework into FIMS #1620
• Closes Implement EDM Model Families, R User Workflows, and Vignette Documentation #1677

---

Instructions for code reviewer

👋Hello reviewer👋, thank you for taking the time to review this PR!

• Please use this checklist during your review, checking off items that you have verified are complete but feel free to skip over items that are not relevant!
• See the GitHub documentation for how to comment on a PR to indicate where you have questions or changes are needed before approving the PR.
• Please use standard conventional messages for both commit messages and comments
• PR reviews are a great way to learn so feel free to share your tips and tricks. However, when suggesting changes to the PR that are optional please include nit: (for nitpicking) as the comment type. For example, nit: I prefer using a data.frame() instead of a matrix because ...
• Engage with the developer. Make it clear when the PR is approved by selecting the approved status, and potentially commenting on the PR with something like This PR is now ready to be merged.

Checklist

• The code is well-designed
• The code is designed well for both users and developers
• Code coverage remains high- [ ] Comments are clear, useful, and explain why instead of what
• Code is appropriately documented (doxygen and roxygen)