kamila

Imported from ahfoss/kamila (AGENTS.md). Install upstream with npx skills add ahfoss/kamila. Copyright stays with the author.

AGENTS.md - Developer Guide for AI Assistants

This repository contains kamila, an R package implementing methods for clustering mixed-type (continuous and categorical) data, specifically KAMILA (KA-means for MIXed LArge data sets) and Modha-Spangler clustering.

This guide provides context, architecture guidelines, and operational instructions for AI agents modifying or maintaining this codebase.

1. Repository Architecture

kamila/
├── R/                      # Core R functions & roxygen2 documentation
│   ├── kamila.R            # Main KAMILA clustering algorithm
│   ├── modha_spangler.R    # Modha-Spangler clustering algorithm
│   ├── gen_mixed_data.R    # Mixed-type data generation utilities
│   ├── misc_functions.R    # Internal helper functions
│   └── RcppExports.R       # Auto-generated Rcpp function bindings
├── src/                    # C++ acceleration layer (Rcpp)
│   ├── cppfunctions.cpp    # C++ implementations of distance/cluster routines
│   └── RcppExports.cpp    # Auto-generated Rcpp bindings
├── tests/
│   └── testthat/           # Unit test suite (testthat v3)
│       ├── test_kamila.R   # KAMILA algorithm unit tests
│       └── test_gmsClust.R # Modha-Spangler unit tests
├── man/                    # Rd documentation files (auto-generated by roxygen2)
├── .github/workflows/      # CI/CD GitHub Actions pipelines
│   ├── R-CMD-check.yaml    # Multi-OS & R-version validation
│   ├── rhub.yaml           # R-hub v2 multi-platform & sanitizer checks
│   ├── test-coverage.yaml # Code coverage reporting via covr/Codecov
│   └── lint.yaml          # Code quality & delinting check via lintr
├── DESCRIPTION             # R package metadata & dependencies
├── NAMESPACE               # Auto-generated package exports/imports
└── .Rbuildignore           # Non-package files ignored during R CMD check

2. Key Development Commands

Run all commands from the repository root directory using Rscript or an interactive R session:

3. Coding & Maintenance Standards

R Code Guidelines

• Roxygen2 Documentation: All exported functions must have roxygen2 header comments (#'). Do NOT edit .Rd files in man/ directly; always edit R/*.R source files and run devtools::document().
• Imports: Declare external package dependencies in DESCRIPTION (Imports: or Suggests:) and add @importFrom tags in R source comments.
• Input Validation: Use explicit input checks (is.matrix(), is.data.frame(), stop()) to provide clear error messages for invalid parameter types.

C++ / Rcpp Guidelines

• Exporting: Annotate exported C++ functions with // [[Rcpp::export]].
• Rebuilding Bindings: Whenever C++ function signatures change, run Rcpp::compileAttributes() before testing or committing.
• Memory Safety: Use Rcpp structures (Rcpp::NumericMatrix, Rcpp::IntegerVector, Rcpp::NumericVector) and avoid unmanaged raw pointers.

News & Release Notes Maintenance

• Mandatory News Updates: Any changes, enhancements, bug fixes, deprecations, or version updates MUST be logged in NEWS.md following CRAN package news standards.

Pre-Commit Verification & Testing

Before committing any changes, you MUST run and pass all verification checks:

1. Unit Tests: Run devtools::test(). All tests must pass with 0 failures and 0 errors.
2. Linter: Run lintr::lint_package(). There must be 0 linter warnings or violations.
3. Code Coverage: Run covr::package_coverage(). Code coverage MUST NOT decrease below 100% from any commit. Every new function, branch, edge case, and error condition must be accompanied by corresponding unit tests.
4. Package Check: Run devtools::check(cran = TRUE). Ensure the package builds with 0 errors, 0 warnings, and 0 notes.

CI/CD & Ignored Files

• Ignore Rules: Never commit build artifacts (*.o, *.so, *.dll, *.Rcheck/, 00check.log, .RData).
• CRAN Compliance: Ensure all non-package root files (AGENTS.md, CONTRIBUTING.md, .lintr, .github/, codecov.yml) are listed in .Rbuildignore.

4. Git Commit & Branching Conventions

• Branch Management: NEVER commit or push directly to master unless explicitly requested by the user. Always perform development and commits on feature or bugfix branches (fix/*, feature/*).
• Pre-Commit Checks: Do NOT commit without passing unit tests, lintr checks, and verifying 100% code coverage.
• Commit Format: Use concise Conventional Commit messages:
  • feat: New feature or parameter addition
  • fix: Bug fix or error resolution
  • docs: Documentation updates (roxygen2 / README / AGENTS.md / NEWS.md)
  • ci: Pipeline changes (.github/workflows)
  • test: Adding or updating testthat specs
  • refactor: Code reorganization without behavior change