Add coupling tests, CI workflow, and update documentation

[siyu-hu]

This pull request introduces several improvements and updates across the project, focusing on documentation clarity, testing automation, and enhanced test coverage. The most notable changes are the addition of a GitHub Actions workflow for automated testing, significant enhancements and corrections to the README.md for better usability and accuracy, and new tests for glycome coupling logic.

Documentation improvements:

• Updated README.md to clarify Python version requirements, add virtual environment setup instructions, expand usage and simulation mode documentation, correct parameter descriptions, and include a citation section for GlycoForge. [1] [2] [3] [4] [5] [6] [7]

Continuous integration:

• Added a .github/workflows/tests.yml workflow to automatically install dependencies and run tests on pushes and pull requests to the main branch, ensuring code reliability.

Testing and benchmarking:

• Added new tests in tests/test_core_functions.py for glycome coupling, including statistical independence and coupling detectability checks, as well as norm validation for coupling directions.
  • Zero-coupling independence — uses an HSIC permutation test (300 permutations) to check that coupling_strength=0 produces no statistically detectable cross-glycome dependence (p ≥ 0.05). We can't assert exactly zero since both glycomes share the same bio/batch labels, so a permutation-based significance test is the right call here.
  • Nonzero-coupling detectability — same HSIC test with coupling_strength=1.0, asserts p < 0.05. Confirms the injected shared signal is actually detectable.
  • Unit-norm sanity check — formally asserts that all columns of the direction matrices U_A and U_B have norm = 1.0 after _build_coupling_directions.
• Updated benchmarking_batch_effect_removal.ipynb to use explicit imports from the use_cases.batch_correction submodules, create a results directory for figures, and update kernel metadata for consistency. [1] [2] [3] [4]

[Copilot]

Pull request overview

Updates documentation and CI while expanding test coverage around the new coupled-glycome simulation utilities.

Changes:

• Add HSIC-based tests for coupled-glycome injection behavior and coupling direction normalization.
• Improve README installation/usage details and add a citation block.
• Update the benchmarking notebook imports and add a GitHub Actions workflow to run pytest.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.

File	Description
tests/test_core_functions.py	Adds coupling-related tests (HSIC permutation test + unit-norm validation).
README.md	Updates install/usage text and adds citation details.
benchmarking_batch_effect_removal.ipynb	Switches to use_cases.batch_correction.* imports and creates results/figures/.
.github/workflows/tests.yml	Introduces a CI job to run the test suite on PRs/pushes to main.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.