Optimize pedigree simulation codebase

[smasongarrison]

This pull request introduces significant optimizations and refactoring to the pedigree simulation codebase, focusing on improving the speed and memory usage of simulatePedigree and its helpers, especially for deeper pedigrees. It also adds more comprehensive tests and resolves an error related to insufficient single individuals. Additionally, the codebase is refactored for clarity and maintainability, with new helper functions, improved documentation, and streamlined logic for handling generations, sex assignment, couple identification, and children assignment. Some beta/optimized versions of functions are also separated for easier comparison and future development.

Performance Improvements and Bug Fixes:

• Optimized simulatePedigree and its helpers for better speed and memory usage, leading to major gains for deeper pedigrees.
• Fixed an error that occurred when there were not enough single people available during simulation.

New and Refactored Helper Functions for Pedigree Simulation:

• Documented optimized helper functions: createGenDataFrame, determineSex, assignCoupleIDs, adjustKidsPerCouple, and markPotentialChildren, each with an optional beta argument to use optimized versions.
• Moved and renamed beta/optimized helper functions to R/helpSimulatePedigree_beta.R (from R/helpPedigree.R) and updated their signatures and logic for consistency and efficiency. [1] [2] [3] [4] [5] [6]

Documentation and Usability Enhancements:

• Improved function documentation throughout, clarifying parameters, return values, and usage examples for new and existing functions. [1] [2]
• Updated NEWS file to reflect the new version (1.6) and summarize key changes.

Algorithm and Code Quality Improvements:

• Simplified and clarified logic for couple ID assignment, sex determination, and children assignment, both in standard and beta versions. [1] [2] [3] [4]
• Improved parameter validation and error handling in pedigree component building functions. [1] [2]
• Enhanced the insertEven utility function for robustness and clarity, including better handling of edge cases and improved verbose output.

Algorithmic Parameter Clarifications:

• Clarified the meaning of the max_gen parameter in pedigree component functions and improved related comments for better user understanding. [1] [2]

[codecov]

Codecov Report

❌ Patch coverage is 85.93407% with 64 lines in your changes missing coverage. Please review.
✅ Project coverage is 84.38%. Comparing base (eeadb99) to head (d999d18).

Files with missing lines	Patch %	Lines
R/helpSimulatePedigree.R	83.17%	18 Missing ⚠️
R/helpSimulatePedigree_beta.R	75.34%	18 Missing ⚠️
R/simulatePedigree.R	87.02%	17 Missing ⚠️
R/buildComponent.R	33.33%	4 Missing ⚠️
R/simulatePedigree_within.R	96.58%	4 Missing ⚠️
R/insertEven.R	85.71%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #109      +/-   ##
==========================================
- Coverage   84.42%   84.38%   -0.05%     
==========================================
  Files          25       27       +2     
  Lines        3982     4240     +258     
==========================================
+ Hits         3362     3578     +216     
- Misses        620      662      +42     

☔ View full report in Codecov by Sentry.
📢 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.

[Copilot]

Pull request overview

Refactors and optimizes simulatePedigree (and helpers) to improve speed/memory for deeper pedigrees, adds a beta switch for optimized helper paths, and updates tests/docs/vignettes accordingly.

Changes:

• Split and refactored within-/between-generation simulation logic and added a beta parameter to switch implementations.
• Added/updated helper functions and documentation/man pages for simulation internals and related parameters.
• Expanded test coverage for simulatePedigree, plus regenerated vignettes and updated NEWS.

Reviewed changes

Copilot reviewed 34 out of 35 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
vignettes/v4_validation.html	Regenerated vignette HTML output (formatting/output updates).
vignettes/v2_pedigree.html	Regenerated vignette HTML output (updated example output/figures).
vignettes/v2_pedigree.Rmd	Minor formatting update in vignette source.
vignettes/v1_modelingvariancecomponents.html	Regenerated vignette HTML output (library calls/output formatting).
vignettes/v1_modelingvariancecomponents.Rmd	Updated vignette source to use library() and improved formatting.
tests/testthat/test-simulatePedigree.R	Expanded tests to exercise beta paths and additional scenarios.
tests/testthat/test-checkSex.R	Removed stray whitespace in tests.
man/simulatePedigree.Rd	Documented new beta argument and expanded fam_shift description.
man/ped2mit.Rd	Clarified meaning of max_gen (iteration-based description).
man/ped2gen.Rd	Clarified meaning of max_gen (iteration-based description).
man/ped2com.Rd	Clarified meaning of max_gen (iteration-based description).
man/ped2cn.Rd	Clarified meaning of max_gen (iteration-based description).
man/ped2add.Rd	Clarified meaning of max_gen (iteration-based description).
man/markPotentialChildren_beta.Rd	Added documentation for beta helper.
man/markPotentialChildren.Rd	Updated documentation source reference and added beta parameter.
man/determineSex_beta.Rd	Added documentation for beta helper.
man/determineSex.Rd	Updated documentation source reference and added beta parameter.
man/createGenDataFrame_beta.Rd	Added documentation for beta helper.
man/createGenDataFrame.Rd	Updated documentation source reference and added beta/family_id_prefix.
man/buildWithinGenerations.Rd	Updated documentation source reference and added beta parameter.
man/buildBetweenGenerations.Rd	Added beta parameter to docs.
man/assignCoupleIDs_beta.Rd	Added documentation for beta helper.
man/assignCoupleIDs.Rd	Updated documentation source reference and added beta parameter.
man/adjustKidsPerCouple_beta.Rd	Added documentation for beta helper.
man/adjustKidsPerCouple.Rd	Updated documentation source reference and added beta parameter.
data-raw/optimizing.R	Added local benchmarking/profiling script for simulation performance comparisons.
R/simulatePedigree_within.R	New/refactored within-generation simulation logic with beta dispatch.
R/simulatePedigree.R	Refactored between-generation simulation logic with beta dispatch; updated simulatePedigree() signature.
R/insertEven.R	Made insertEven() more robust and clearer for edge cases.
R/helpSimulatePedigree_beta.R	Added beta implementations of simulation helper functions.
R/helpSimulatePedigree.R	Added beta-aware wrappers and updated helper implementations/documentation.
R/buildComponent.R	Improved validation and added comments related to max_gen/iteration behavior.
NEWS.md	Added release notes for 1.6 highlighting simulation optimizations and tests.

Comments suppressed due to low confidence (3)

R/helpSimulatePedigree_beta.R:196

• markPotentialChildren_beta() removes the last column with df_Ngen <- df_Ngen[, -ncol(df_Ngen)], which is brittle if column order changes. Remove coupleId by name instead (or avoid relying on it being the last column).
  R/helpSimulatePedigree_beta.R:158
• The CoupleF documentation above this function still reads like placeholder text (“IT MIGHT BE…”). Please replace with a precise definition (e.g., number of couple IDs to label as producing daughters) and any constraints so the beta helper docs are usable.
  R/helpSimulatePedigree_beta.R:21
• The example block documents createGenDataFrame_beta(), but the example calls createGenDataFrame(...). This is confusing for readers and may fail if the intent is to demonstrate the beta helper. Update the example to call the correct function name (or explicitly document why the non-beta wrapper is shown here).

[Copilot]

These newly added inline comments are hard to parse and contain multiple spelling errors, which makes the algorithm rationale unclear. Please rewrite or remove them (keeping only a concise explanation of the stopping criterion and precision tradeoff).

Suggested change

	# r is I + A + A^2 + ... = (I-A)^-1 from RAM
	# could trim, here
	## it keeps going until it explains all of the relatedness with themselves (i.e., mtSum == 0)
	# some of this precision is articifuial because we literally get to the point that the condon is eaither there or not. probabiliticy
	# how much percision do we need to get unbiased estimates
	# big matrix still happens here because the network is built. just less percise on inbreeding
	# bias-precision tradeoff. how much percision do we need to get unbiased estimates? not a lot
	# r accumulates I + A + A^2 + ... ≈ (I - A)^-1 from RAM path tracing
	# Iterate until no additional relatedness is contributed (mtSum == 0) or max_gen is reached.
	# max_gen controls the bias–precision tradeoff: larger values give more precise but more expensive estimates.

[Copilot]

buildWithinGenerations() claims to accept beta = "optimized" / "indexed", but it passes that value down to helpers that do if (beta) (e.g., createGenDataFrame()), which will error for non-logical values. Either restrict beta to a strict logical (and update error text/docs), or normalize string aliases to TRUE/FALSE before calling downstream functions.

[smasongarrison]

@copilot open a new pull request to apply changes based on this feedback normalize string aliases to TRUE/FALSE before calling downstream functions.

[Copilot]

@smasongarrison I've opened a new pull request, #111, to work on those changes. Once the pull request is ready, I'll request review from you.