Add EDM delay embedding infrastructure and tests

[aman-raj-srivastva]

Summary

This PR implements the initial delay embedding infrastructure for Empirical Dynamic Modeling (EDM) in FIMS as part of the GSoC 2026 project: “Add empirical dynamic model to FIMS”

This PR completes the main deliverables for:

• Weeks 1–3 of the proposal timeline
• Covers the Issue Implement Delay Embedding Generator for Time Series #1484

---

What this PR adds

Core Delay Embedding Infrastructure

Implemented a reusable delay embedding generator for univariate time series in:

inst/include/edm/functors/delay_embedding.hpp

Features include:

• configurable embedding dimension (E)
• configurable time lag (tau)
• row-major embedding matrix generation
• target-time indexing
• missing observation handling (-999 sentinel support)
• input validation and error handling
• Doxygen documentation

---

Rcpp Interface

Added EDM Rcpp integration in:

inst/include/interface/rcpp/rcpp_objects/rcpp_edm.hpp

This includes:

• DelayEmbeddingInterface
• R-accessible embedding construction
• missing-value filtering support
• module registration through RCPP_MODULE(fims)

---

FIMSFrame Integration

Extended FIMSFrame to support EDM embeddings by adding:

• edm_embeddings storage slot
• helper/accessor functions
• embedding creation utilities
• matrix conversion helpers for future EDM prediction workflows

---

Testing

C++ (GoogleTest) — tests/gtest/test_edm_delay_embedding.cpp
6 test cases covering: basic 2D/3D embeddings, configurable lag,
short-series errors, invalid E/tau, and missing-value filtering.

R — Rcpp interface — tests/testthat/test-rcpp-edm.R
3 test blocks, 18 assertions covering: construct(), construct_drop_missing(),
and element access via at().

R — FIMSFrame — tests/testthat/test-edm-fimsframe.R
6 test blocks covering: empty slot default, missing embedding error,
input validation, metadata correctness, matrix shape, and chaining.

---

Additional Work

• Added TODO(EDM) comments across key FIMS workflow files to guide future EDM and likelihood integration.
• Added "edm" support to fims_input_types.

---

Checklist

• C++ implementation with Doxygen docs
• Rcpp interface following existing FIMS patterns
• FIMSFrame slot, accessors, and constructor updated
• fims_input_types allowlist updated
• GoogleTest unit tests pass
• testthat integration tests pass
• Uncertainty propagation (deferred — pending mentor input)

---

Related Issue

Closes #1484 — Implement Delay Embedding Generator for Time Series

---

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)

[github-actions]

🎨 Chore: code formatting workflow

Our automated workflows cannot run on forks because of permission issues, and thus, we ask that you run the following code locally and push any changes that are created to your feature branch. You will only be reminded of this once per PR. Thank you!

Format C++ code

1. Install clang-format version 18.0.0
2. Run the following command from the repository root:

   clang-format -i --style="{BasedOnStyle: Google, SortIncludes: false}" $(find ./inst/include ./src ./tests/gtest -name "*.hpp" -o -name "*.cpp")

Format R code

1. Install {styler} and {roxygen2}
2. Run the following commands in R from the repository root:

styler::style_pkg() # Style R code
roxygen2::roxygenise() # Update documentation
styler::style_pkg() # Style R code again
roxygen2::roxygenise() # Update documentation again
usethis::use_tidy_description() # Style DESCRIPTION file

Push changes

1. Commit the formatting with a commit message of "Chore: format feature branch"
2. Push to your fork

[aman-raj-srivastva]

On the uncertainty propagation, my assumption for now is to propagate observational uncertainty metadata (e.g. std error / variance vectors) along with the lag-coordinate embeddings, so later prediction and likelihood components can utilize them if needed. I just wanted to confirm if this direction makes sense regarding EDM / FIMS integration, before I move ahead with anything more elaborate.

Also, I saw that my branch has merge conflicts with main, apparently due to some of the recent upstream interface and module level refactors in module registration etc. Should I just rebase my branch onto the latest upstream, or is there a desired synchronization / target branch policy for EDM development branches going forwards?

[kellijohnson-NOAA]

@aman-raj-srivastva sorry for the merge conflicts. Yes, rebasing to main is the best strategy. If you have problems, feel free to let me know and I can help out.

[aman-raj-srivastva]

Thanks! I’ll go ahead and rebase onto the latest main and work through the conflicts. I’ll definitely reach out if I run into any issues during the rebase.

[codecov]

Codecov Report

❌ Patch coverage is 87.04663% with 50 lines in your changes missing coverage. Please review.
✅ Project coverage is 87.50%. Comparing base (4a2d5f3) to head (6a5994a).

Files with missing lines	Patch %	Lines
R/fimsframe.R	79.20%	26 Missing ⚠️
...t/include/interface/rcpp/rcpp_objects/rcpp_edm.hpp	84.17%	22 Missing ⚠️
inst/include/edm/functors/delay_embedding.hpp	96.55%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1528      +/-   ##
==========================================
- Coverage   87.53%   87.50%   -0.03%     
==========================================
  Files          97      101       +4     
  Lines        8749     9134     +385     
  Branches      523      559      +36     
==========================================
+ Hits         7658     7993     +335     
- Misses       1054     1103      +49     
- Partials       37       38       +1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.