Full review of code at version 0.7.0

README.md

@@ -41,13 +41,13 @@ df = pl.DataFrame({
 })
 
 # Calculate Charlson Comorbidity Index
-result = comorbidity(df, id="id", code="code", age="age")
+result = comorbidity(df, id_col="id", code_col="code", age_col="age")
 
 # Calculate Hospital Frailty Risk Score
-frailty = hfrs(df, id="id", code="code")
+frailty = hfrs(df, id_col="id", code_col="code")
 
 # Identify disabilities
-disabilities = disability(df, id="id", code="code")
+disabilities = disability(df, id_col="id", code_col="code")
 ```
 
 ### Command Line Interface
@@ -57,7 +57,7 @@ disabilities = disability(df, id="id", code="code")
 comorbidipy charlson input.csv output.csv --age-col age
 
 # Elixhauser score
-comorbidipy elixhauser input.parquet output.parquet --weights vanwalraven
+comorbidipy elixhauser input.parquet output.parquet --weights van_walraven
 
 # Hospital Frailty Risk Score
 comorbidipy hfrs input.csv output.csv

docs/api.md

@@ -11,31 +11,31 @@ Calculate Charlson or Elixhauser comorbidity scores.
 ```python
 def comorbidity(
     df: pl.DataFrame | pl.LazyFrame,
-    id: str = "id",
-    code: str = "code",
+    id_col: str = "id",
+    code_col: str = "code",
+    age_col: str | None = None,
     score: ScoreType = ScoreType.CHARLSON,
     icd: ICDVersion = ICDVersion.ICD10,
     variant: MappingVariant = MappingVariant.QUAN,
-    weighting: WeightingVariant = WeightingVariant.CHARLSON,
+    weighting: WeightingVariant = WeightingVariant.QUAN,
     assign0: bool = True,
-    age: str | None = None,
 ) -> pl.DataFrame:
     """
     Calculate comorbidity scores from ICD diagnosis codes.
 
     Args:
         df: DataFrame with patient IDs and ICD codes.
-        id: Name of the column containing patient identifiers.
-        code: Name of the column containing ICD codes.
+        id_col: Name of the column containing patient identifiers.
+        code_col: Name of the column containing ICD codes.
+        age_col: Name of the column containing patient age (optional).
+            When provided with Charlson score and Charlson weights,
+            enables age adjustment and survival calculation.
         score: Type of comorbidity score (CHARLSON or ELIXHAUSER).
         icd: Version of ICD codes (ICD9 or ICD10).
         variant: Mapping variant for ICD code classification.
         weighting: Weighting scheme for calculating the score.
         assign0: Whether to zero out less severe conditions when
             more severe forms are present.
-        age: Name of the column containing patient age (optional).
-            When provided with Charlson score and Charlson weights,
-            enables age adjustment and survival calculation.
 
     Returns:
         DataFrame with patient IDs, binary comorbidity flags,
@@ -61,10 +61,10 @@ df = pl.DataFrame({
 
 result = comorbidity(
     df,
-    id="patient_id",
-    code="diagnosis",
+    id_col="patient_id",
+    code_col="diagnosis",
+    age_col="patient_age",
     score=ScoreType.CHARLSON,
-    age="patient_age",
 )
 ```
 
@@ -77,8 +77,8 @@ Calculate Hospital Frailty Risk Score.
 ```python
 def hfrs(
     df: pl.DataFrame | pl.LazyFrame,
-    id: str = "id",
-    code: str = "code",
+    id_col: str = "id",
+    code_col: str = "code",
 ) -> pl.DataFrame:
     """
     Calculate Hospital Frailty Risk Score from ICD-10 codes.
@@ -88,8 +88,8 @@ def hfrs(
 
     Args:
         df: DataFrame with patient IDs and ICD-10 codes.
-        id: Name of the column containing patient identifiers.
-        code: Name of the column containing ICD codes.
+        id_col: Name of the column containing patient identifiers.
+        code_col: Name of the column containing ICD codes.
 
     Returns:
         DataFrame with columns:
@@ -116,7 +116,7 @@ df = pl.DataFrame({
     "code": ["F00", "R26", "J18"],
 })
 
-result = hfrs(df, id="id", code="code")
+result = hfrs(df, id_col="id", code_col="code")
 ```
 
 ---
@@ -128,8 +128,8 @@ Identify learning disabilities and sensory impairments.
 ```python
 def disability(
     df: pl.DataFrame | pl.LazyFrame,
-    id: str = "id",
-    code: str = "code",
+    id_col: str = "id",
+    code_col: str = "code",
 ) -> pl.DataFrame:
     """
     Identify learning disabilities and sensory impairments from ICD-10 codes.
@@ -141,8 +141,8 @@ def disability(
 
     Args:
         df: DataFrame with patient IDs and ICD-10 codes.
-        id: Name of the column containing patient identifiers.
-        code: Name of the column containing ICD codes.
+        id_col: Name of the column containing patient identifiers.
+        code_col: Name of the column containing ICD codes.
 
     Returns:
         DataFrame with columns:
@@ -167,7 +167,7 @@ df = pl.DataFrame({
     "code": ["F70", "H90"],
 })
 
-result = disability(df, id="id", code="code")
+result = disability(df, id_col="id", code_col="code")
 ```
 
 ---
@@ -225,7 +225,7 @@ class WeightingVariant(StrEnum):
     QUAN = "quan"
     SHMI = "shmi"
     SHMI_MODIFIED = "shmi_modified"
-    VAN_WALRAVEN = "vanwalraven"
+    VAN_WALRAVEN = "van_walraven"
     SWISS = "swiss"
 ```
 
@@ -270,7 +270,7 @@ from comorbidipy import comorbidity
 
 # LazyFrame for memory-efficient processing
 lf = pl.scan_parquet("large_file.parquet")
-result = comorbidity(lf, id="id", code="code", age=None)
+result = comorbidity(lf, id_col="id", code_col="code")
 ```
 
 When a `LazyFrame` is passed, the function will:
@@ -290,7 +290,7 @@ import polars as pl
 df = pl.DataFrame({"wrong_col": ["P001"], "also_wrong": ["I21"]})
 
 try:
-    result = comorbidity(df, id="patient_id", code="code", age=None)
+    result = comorbidity(df, id_col="patient_id", code_col="code")
 except KeyError as e:
     print(f"Missing column: {e}")
 ```

docs/calculators/charlson.md

@@ -65,30 +65,28 @@ df = pl.DataFrame({
 # Basic calculation
 result = comorbidity(
     df,
-    id="id",
-    code="code",
+    id_col="id",
+    code_col="code",
     score=ScoreType.CHARLSON,
-    age=None,
 )
 
 # With age adjustment
 result = comorbidity(
     df,
-    id="id",
-    code="code",
-    age="age",
+    id_col="id",
+    code_col="code",
+    age_col="age",
     score=ScoreType.CHARLSON,
     weighting=WeightingVariant.CHARLSON,
 )
 
 # Using Swedish mapping
 result = comorbidity(
     df,
-    id="id",
-    code="code",
+    id_col="id",
+    code_col="code",
     score=ScoreType.CHARLSON,
     variant=MappingVariant.SWEDISH,
-    age=None,
 )
 ```
 
@@ -133,7 +131,7 @@ By default (`assign0=True`), when a more severe form of a condition is present,
 To keep both forms:
 
 ```python
-result = comorbidity(df, assign0=False, age=None)
+result = comorbidity(df, assign0=False)
 ```
 
 ## Output

docs/calculators/disability.md

@@ -59,8 +59,8 @@ df = pl.DataFrame({
 # Identify impairments
 result = disability(
     df,
-    id="patient_id",
-    code="icd_code",
+    id_col="patient_id",
+    code_col="icd_code",
 )
 
 # Result includes binary columns for each impairment type
@@ -73,7 +73,7 @@ result = disability(
 comorbidipy disability input.csv output.csv
 
 # With custom columns
-comorbidipy disability input.parquet output.parquet --id pat_id --code diagnosis
+comorbidipy disability input.parquet output.parquet --id-col pat_id --code-col diagnosis
 
 # Output as Parquet
 comorbidipy disability input.csv output.parquet
@@ -109,7 +109,7 @@ df = pl.DataFrame({
     ],
 })
 
-result = disability(df, id="id", code="code")
+result = disability(df, id_col="id", code_col="code")
 print(result)
 
 # Output:

docs/calculators/elixhauser.md

@@ -16,7 +16,7 @@ The Elixhauser index was developed in 1998 as a more comprehensive alternative t
 
 | Weighting | Description |
 |-----------|-------------|
-| `vanwalraven` | van Walraven et al. (2009) - mortality prediction |
+| `van_walraven` | van Walraven et al. (2009) - mortality prediction |
 | `swiss` | Swiss adaptation for mortality prediction |
 
 ## Comorbidity Categories
@@ -73,30 +73,27 @@ df = pl.DataFrame({
 # Basic Elixhauser calculation
 result = comorbidity(
     df,
-    id="patient_id",
-    code="icd_code",
+    id_col="patient_id",
+    code_col="icd_code",
     score=ScoreType.ELIXHAUSER,
-    age=None,
 )
 
 # With van Walraven weights
 result = comorbidity(
     df,
-    id="patient_id",
-    code="icd_code",
+    id_col="patient_id",
+    code_col="icd_code",
     score=ScoreType.ELIXHAUSER,
     weighting=WeightingVariant.VAN_WALRAVEN,
-    age=None,
 )
 
 # With Swiss weights
 result = comorbidity(
     df,
-    id="patient_id",
-    code="icd_code",
+    id_col="patient_id",
+    code_col="icd_code",
     score=ScoreType.ELIXHAUSER,
     weighting=WeightingVariant.SWISS,
-    age=None,
 )
 ```
 
@@ -107,7 +104,7 @@ result = comorbidity(
 comorbidipy elixhauser input.csv output.csv
 
 # With van Walraven weights
-comorbidipy elixhauser input.parquet output.parquet --weights vanwalraven
+comorbidipy elixhauser input.parquet output.parquet --weights van_walraven
 
 # With Swiss weights
 comorbidipy elixhauser input.csv output.csv --weights swiss
@@ -124,7 +121,7 @@ By default (`assign0=True`), when a more severe or complicated form of a conditi
 To keep both forms:
 
 ```python
-result = comorbidity(df, assign0=False, age=None)
+result = comorbidity(df, assign0=False)
 ```
 
 ## Output

docs/calculators/hfrs.md

@@ -34,8 +34,8 @@ df = pl.DataFrame({
 # Calculate HFRS
 result = hfrs(
     df,
-    id="patient_id",
-    code="icd_code",
+    id_col="patient_id",
+    code_col="icd_code",
 )
 
 # Result includes:
@@ -51,7 +51,7 @@ result = hfrs(
 comorbidipy hfrs input.csv output.csv
 
 # With custom columns
-comorbidipy hfrs input.parquet output.parquet --id pat_id --code diagnosis
+comorbidipy hfrs input.parquet output.parquet --id-col pat_id --code-col diagnosis
 
 # Output as Parquet
 comorbidipy hfrs input.csv output.parquet
@@ -111,7 +111,7 @@ df = pl.DataFrame({
     ],
 })
 
-result = hfrs(df, id="id", code="code")
+result = hfrs(df, id_col="id", code_col="code")
 print(result)
 
 # Output:

docs/cli.md

@@ -37,8 +37,8 @@ All commands support these common options:
 
 | Option | Default | Description |
 |--------|---------|-------------|
-| `--id` | `id` | Column name containing patient identifiers |
-| `--code` | `code` | Column name containing ICD codes |
+| `--id-col` / `-i` | `id` | Column name containing patient identifiers |
+| `--code-col` / `-c` | `code` | Column name containing ICD codes |
 | `--verbose` / `-v` | False | Enable verbose logging |
 
 ## Commands
@@ -90,7 +90,7 @@ comorbidipy elixhauser [OPTIONS] INPUT OUTPUT
 
 | Option | Default | Description |
 |--------|---------|-------------|
-| `--weights` | `vanwalraven` | Weighting scheme: vanwalraven, swiss |
+| `--weights` | `van_walraven` | Weighting scheme: van_walraven, swiss |
 | `--icd-version` | `10` | ICD version: 9 or 10 |
 | `--no-assign0` | False | Don't zero out less severe conditions |
 
@@ -119,7 +119,7 @@ comorbidipy hfrs [OPTIONS] INPUT OUTPUT
 comorbidipy hfrs admissions.csv frailty.csv
 
 # Custom column names
-comorbidipy hfrs data.parquet results.parquet --id patient_id --code diagnosis
+comorbidipy hfrs data.parquet results.parquet --id-col patient_id --code-col diagnosis
 ```
 
 ### disability

docs/getting-started.md

@@ -45,9 +45,9 @@ from comorbidipy import comorbidity, ScoreType, MappingVariant, WeightingVariant
 
 result = comorbidity(
     df,
-    id="id",
-    code="code",
-    age="age",  # Optional - enables age-adjusted score
+    id_col="id",
+    code_col="code",
+    age_col="age",  # Optional - enables age-adjusted score
     score=ScoreType.CHARLSON,
     variant=MappingVariant.QUAN,
     weighting=WeightingVariant.CHARLSON,
@@ -61,11 +61,10 @@ print(result)
 ```python
 result = comorbidity(
     df,
-    id="id",
-    code="code",
+    id_col="id",
+    code_col="code",
     score=ScoreType.ELIXHAUSER,
     weighting=WeightingVariant.VAN_WALRAVEN,
-    age=None,  # Elixhauser doesn't use age adjustment
 )
 ```