|
| 1 | +#Copilot Instructions for BGmisc |
| 2 | + |
| 3 | +##Project Overview |
| 4 | + |
| 5 | +BGmisc is an R package for extended behavior genetics analysis. It provides functions for: |
| 6 | +- Variance component model identification |
| 7 | +- Calculation of relatedness coefficients using path-tracing methods |
| 8 | +- Inference of relatedness |
| 9 | +- Pedigree conversion and manipulation |
| 10 | +- Simulation of multi-generational family data |
| 11 | + |
| 12 | +This package is published on CRAN and follows strict R package development standards. |
| 13 | + |
| 14 | +##Repository Structure |
| 15 | + |
| 16 | +-**R/**: Contains all R source code for package functions |
| 17 | +-**tests/testthat/**: Contains unit tests using the testthat framework |
| 18 | +-**man/**: Documentation files generated by roxygen2 |
| 19 | +-**vignettes/**: Package vignettes and articles |
| 20 | +-**data/**: Package datasets |
| 21 | +-**data-raw/**: Scripts for generating package data |
| 22 | +-**.github/workflows/**: CI/CD workflows for R CMD check, test coverage, and pkgdown |
| 23 | + |
| 24 | +##Development Standards |
| 25 | + |
| 26 | +###Code Style |
| 27 | +- Follow the[Tidyverse Style Guide](https://style.tidyverse.org/) |
| 28 | +- Use meaningful variable and function names |
| 29 | +- Keep functions focused and modular |
| 30 | +- Avoid unnecessary dependencies |
| 31 | + |
| 32 | +###Documentation |
| 33 | +- All functions must have roxygen2 documentation with: |
| 34 | +- Title and description |
| 35 | +-`@param` for all parameters |
| 36 | +-`@return` for return values |
| 37 | +-`@examples` with working examples |
| 38 | +-`@export` for user-facing functions |
| 39 | +- Update README.Rmd (not README.md directly) for user-facing documentation |
| 40 | +- Include references to relevant papers and methods where applicable |
| 41 | + |
| 42 | +###Testing |
| 43 | +- Use the testthat package (edition 3) for all tests |
| 44 | +- Place test files in`tests/testthat/` with prefix`test-` |
| 45 | +- Test file names should match the source file:`test-functionName.R` for`functionName.R` |
| 46 | +- Aim for high test coverage of new code |
| 47 | +- Include tests for: |
| 48 | +- Expected behavior with valid inputs |
| 49 | +- Error handling with invalid inputs |
| 50 | +- Edge cases and boundary conditions |
| 51 | +- Regression tests for bugs |
| 52 | + |
| 53 | +###Dependencies |
| 54 | +- Minimize new dependencies |
| 55 | +- Use only CRAN packages for dependencies |
| 56 | +- Imports: data.table, igraph, Matrix, stats, stringr, methods |
| 57 | +- Suggests packages are for testing, vignettes, or optional features |
| 58 | + |
| 59 | +###Building and Testing |
| 60 | +- Use`devtools::check()` or`R CMD check` before submitting changes |
| 61 | +- Run`devtools::test()` to run all tests |
| 62 | +- Ensure no warnings or errors in R CMD check |
| 63 | +- Test coverage is tracked via Codecov |
| 64 | + |
| 65 | +##Branching Strategy |
| 66 | + |
| 67 | +This project follows a GitFlow branching strategy: |
| 68 | +-**main**: Stable, mirrors CRAN version |
| 69 | +-**dev_main**: Pre-release integration branch, stable |
| 70 | +-**dev**: Active development, less stable |
| 71 | +-**feature branches**: Created from dev_main for new features |
| 72 | + |
| 73 | +When contributing: |
| 74 | +1. Create feature branches from dev_main |
| 75 | +2. Make focused, atomic commits |
| 76 | +3. Ensure all tests pass |
| 77 | +4. Submit PR to dev_main branch |
| 78 | + |
| 79 | +##Common Tasks |
| 80 | + |
| 81 | +###Adding a New Function |
| 82 | +1. Create the function in the appropriate R file in`R/` |
| 83 | +2. Add roxygen2 documentation |
| 84 | +3. Add corresponding tests in`tests/testthat/` |
| 85 | +4. Run`devtools::document()` to update documentation |
| 86 | +5. Run`devtools::check()` to verify the package builds |
| 87 | +6. Update NEWS.md with the change |
| 88 | + |
| 89 | +###Modifying Existing Functions |
| 90 | +1. Make minimal changes to achieve the goal |
| 91 | +2. Update roxygen2 documentation if the interface changes |
| 92 | +3. Add or update tests to cover the changes |
| 93 | +4. Ensure all existing tests still pass |
| 94 | +5. Update NEWS.md with the change |
| 95 | + |
| 96 | +###Working with Pedigrees |
| 97 | +- Pedigree data structures typically include: ID, dadID, momID, sex |
| 98 | +- Use data.table for efficient pedigree operations |
| 99 | +- Validate pedigree structures using checkPedigree functions |
| 100 | +- Consider both nuclear families and extended pedigrees |
| 101 | + |
| 102 | +###Performance Considerations |
| 103 | +- BGmisc handles large pedigrees, so performance matters |
| 104 | +- Use vectorized operations when possible |
| 105 | +- Consider memory efficiency for large datasets |
| 106 | +- Profile code if adding potentially slow operations |
| 107 | + |
| 108 | +##Package-Specific Guidelines |
| 109 | + |
| 110 | +###Relatedness Calculations |
| 111 | +- Use path-tracing methods as described in Wright (1922) and McArdle & McDonald (1984) |
| 112 | +- Ensure consistency with kinship2 package where applicable |
| 113 | +- Handle inbreeding loops correctly |
| 114 | + |
| 115 | +###Pedigree Operations |
| 116 | +- Maintain data integrity when modifying pedigrees |
| 117 | +- Preserve relationships and structure |
| 118 | +- Validate inputs and outputs |
| 119 | +- Handle edge cases (founder individuals, complex families) |
| 120 | + |
| 121 | +###Simulation Functions |
| 122 | +- Ensure reproducibility with set.seed() |
| 123 | +- Document simulation parameters clearly |
| 124 | +- Validate generated pedigrees |
| 125 | + |
| 126 | +##References |
| 127 | + |
| 128 | +Key papers to understand when working on this package: |
| 129 | +- Hunter et al. (2021) - Variance component model identification |
| 130 | +- Wright (1922) - Path coefficients and correlation |
| 131 | +- McArdle & McDonald (1984) - Path analysis |
| 132 | +- Garrison et al. (2024) - BGmisc package paper (JOSS) |
| 133 | + |
| 134 | +##Getting Help |
| 135 | + |
| 136 | +- Check existing issues:https://github.com/R-Computing-Lab/BGmisc/issues |
| 137 | +- Review the CONTRIBUTING.md file |
| 138 | +- See package documentation:https://r-computing-lab.github.io/BGmisc/ |
| 139 | +- Contact maintainer:garrissm@wfu.edu |
| 140 | + |
| 141 | +##Quality Standards |
| 142 | + |
| 143 | +Before submitting code: |
| 144 | +-[ ] All tests pass |
| 145 | +-[ ] R CMD check produces no errors, warnings, or notes |
| 146 | +-[ ] Code follows Tidyverse style guide |
| 147 | +-[ ] Documentation is complete and accurate |
| 148 | +-[ ] NEWS.md is updated |
| 149 | +-[ ] Changes are minimal and focused on the issue |