Implement CLI and fix Polars compatibility for comorbidipy

[Copilot]

The library had broken imports and no command-line interface. This implements a Typer-based CLI and updates the codebase for Polars 1.37+ compatibility.

Import fixes

• hfrs.py and learning_disability.py: corrected import paths to ..codemaps.mapping
• __init__.py: exported public API (comorbidity, hfrs, disability, enums)

CLI implementation

Three commands via Typer, each supporting CSV/Parquet I/O:

• comorbidity: Charlson/Elixhauser scores with configurable mapping and weighting variants
• hfrs: Hospital Frailty Risk Score
• disability: ICD-10 disability/sensory impairment identification

comorbidipy comorbidity input.csv output.csv --score charlson --icd icd10 --variant quan

Polars API updates

• map_dict() → replace_strict() with explicit default and return_dtype parameters
• pl.max(expr) → expr.max() (method call on expression)
• df[col] * weight → pl.col(col) * weight (expression-based column access)
• Added return_dtype=pl.Utf8 to map_elements() in hfrs to prevent null-type column inference

Documentation

• README updated with CLI and Python API examples
• Added clarifying comments to pivot expressions

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• astral.sh
  • Triggering command: /usr/bin/curl curl -LsSf REDACTED (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

Start implementation

The user has attached the following file paths as relevant context:

• .github/copilot-instructions.md

[Chronological Review: The conversation began with the user requesting a rewrite of the file `comorbidity.py` to suit the project. The user then provided context about the Comorbidipy library, its purpose, and its relation to an R library. Following this, the user requested the creation of a GitHub issue outlining a plan for the GitHub Copilot Agent to modernize the library, emphasizing performance improvements, data handling, and documentation. The user then instructed to start the implementation of these changes.]

[Intent Mapping:

1. "Rewrite this file to suit this project" - User wants to modify comorbidity.py.
2. "Create a github issue with a clear plan for GitHub Copilot Agent to address" - User seeks to document a comprehensive plan for modernization.
3. "Start implementation" - User is ready to begin coding based on the outlined plan.]

[Technical Inventory:

• Core Technology: Python
• Frameworks/Libraries: Polars (for dataframe operations), Typer (for CLI), Mkdocs (for documentation)
• Architectural Decisions: Modernization of the library for performance and scalability, support for various data formats (CSV, Parquet, Avro), and robust logging and exception management.]

[Code Archaeology:

• File Name: comorbidity.py
• Purpose: To calculate clinical comorbidity scores.
• Current State: The user has indicated that this file needs a complete rewrite to align with the new project goals.]

[Progress Assessment:

• Completed Tasks: User has outlined the requirements for the library rewrite and modernization.
• Partially Complete Work: The actual implementation of the changes has just begun.]

[Context Validation: All necessary context for continuing the work on the library rewrite is captured, including user goals and technical requirements.]

[Recent Commands Analysis:

• Last Agent Commands: User requested to "Start implementation."
• Tool Results Summary: No specific tool results were generated as the command was a directive to begin coding.
• Pre-Summary State: The agent was preparing to implement the changes outlined in the GitHub issue and user requests.
• Operation Context: The commands executed were directly related to the user's goal of modernizing the Comorbidipy library for better performance and usability.]

1. Conversation Overview: - Primary Objectives: - "Rewrite this file to suit this project" - Modify `comorbidity.py`. - "Create a github issue with a clear plan for GitHub Copilot Agent to address" - Document modernization plan. - "Start implementation" - Begin coding based on the outlined plan. - Session Context: The conversation has focused on the modernization of the Comorbidipy library, detailing performance improvements, data handling capabilities, and documentation requirements. - User Intent Evolution: The user transitioned from outlining requirements to initiating the implementation phase.

2. Technical Foundation:

• Python: Core programming language for the library.
• Polars: For efficient dataframe operations.
• Typer: For creating a user-friendly CLI.
• Mkdocs: For generating detailed documentation.

3. Codebase Status:

• File Name: comorbidity.py
  • Purpose: Calculate clinical comorbidity scores.
  • Current State: Needs a complete rewrite to meet new project specifications.
  • Key Code Segments: Not yet defined as implementation has just started.
  • Dependencies: Will integrate with Polars for data handling.

4. Problem Resolution:

• Issues Encountered: None documented yet as the implementation phase has just begun.
• Solutions Implemented: Not applicable at this stage.
• Debugging Context: No ongoing troubleshooting efforts reported.
• Lessons Learned: Insights will emerge as implementation progresses.

5. Progress Tracking:

• Completed Tasks: User has defined the scope and requirements for the library rewrite.
• Partially Complete Work: Implementation has just started.
• Validated Outcomes: None yet, as testing will follow implementation.

6. Active Work State:

• Current Focus: Starting the implementation of the modernization plan for comorbidity.py.
• Recent Context: User has provided a detailed plan for the library's rewrite and is ready to begin coding.
• Working Code: No specific code snippets have been modified yet.
• Immediate Context: User is focused on implementing the changes outlined in the GitHub issue.

7. Recent Operations:

• Last Agent Commands: User requested to "Start implementation."
• Tool Results Summary: No specific tool results were generated as the command was a directive to begin coding.
• Pre-Summary State: The agent was preparing to implement the changes outlined in the GitHub issue and user requests.
• Operation Context: The commands executed were directly related to the user's goal of modernizing the Comorbidipy library for better performance and usability.

8. Cont...

Created from VS Code.

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[Copilot]

Pull request overview

This PR implements a command-line interface using Typer and updates the codebase for Polars 1.37+ API compatibility, addressing broken imports that prevented the library from functioning.

Changes:

• Implemented Typer-based CLI with three commands (comorbidity, hfrs, disability) supporting CSV/Parquet I/O
• Updated Polars API calls from deprecated methods to modern equivalents (map_dict → replace_strict, pl.max(expr) → expr.max(), df[col] → pl.col(col))
• Fixed import paths in calculator modules to correctly reference codemaps.mapping
• Exported public API and enums in init.py for convenient imports
• Added comprehensive CLI and Python API examples to README with installation and usage instructions

Reviewed changes

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

Show a summary per file

File	Description
src/comorbidipy/cli.py	New CLI module with three commands (comorbidity, hfrs, disability) using Typer, includes file I/O helpers for CSV/Parquet formats
src/comorbidipy/calculators/comorbidity.py	Updated Polars API calls: map_dict → replace_strict, pl.max → expr.max(), df[col] → pl.col(col); added clarifying comments for pivot logic
src/comorbidipy/calculators/hfrs.py	Fixed import path and updated Polars API calls: map_dict → replace_strict with return_dtype, added return_dtype to map_elements
src/comorbidipy/calculators/learning_disability.py	Fixed import path, updated Polars API calls: map_dict → replace_strict, pl.max → expr.max(); added clarifying comments for pivot logic
src/comorbidipy/init.py	Exported public API functions (comorbidity, hfrs, disability) and enums (ICDVersion, ScoreType, MappingVariant, WeightingVariant)
README.md	Added installation instructions, CLI usage examples, Python API examples, and input data format documentation

[Copilot]

The docstring for _read_file function should follow the custom guideline format with an Args section and Returns section. Currently, it only has a brief one-liner. It should document the input_file parameter, what the function returns, and any exceptions that might be raised.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated no new comments.