Calculates hepatic function categories based on NCI-ODWG criteria

This function categorizes hepatic function impairment using the National Cancer Institute Organ Dysfunction Working Group (NCI-ODWG) criteria. It evaluates aspartate aminotransferase (AST) and bilirubin levels relative to their upper limits of normal to determine hepatic impairment severity. The function handles edge cases where bilirubin values are very close to category boundaries using floating-point tolerant comparisons.

Usage

hfc(ast, ulnast, bili, ulnbili)

Arguments

ast: Numeric vector of aspartate aminotransferase concentrations (IU/L)
ulnast: Numeric vector of upper limit of normal AST values (IU/L). Typically 33 IU/L for most laboratories
bili: Numeric vector of total bilirubin concentrations (mg/dL)
ulnbili: Numeric vector of upper limit of normal bilirubin values (mg/dL). Typically 1.2 mg/dL for most laboratories

Value

Integer vector of hepatic function categories (1-4). Returns -999 for missing values.

Details

The NCI-ODWG hepatic function categories are defined as:

1: Normal: AST ≤ ULN AND bilirubin ≤ ULN
2: Mild impairment: AST > ULN OR bilirubin > ULN but ≤ 1.5 × ULN
3: Moderate impairment: Bilirubin > 1.5 × ULN but ≤ 3 × ULN
4: Severe impairment: Bilirubin > 3 × ULN

Special handling: The function uses dplyr::near() for boundary comparisons when bilirubin values are very close to 1.5 × ULN or 3 × ULN to handle floating-point precision issues that can occur with calculated thresholds.

References

National Cancer Institute Organ Dysfunction Working Group criteria for hepatic impairment

Examples

# Single patient with normal hepatic function
hfc(ast = 15, ulnast = 33, bili = 0.6, ulnbili = 1.2)
#> [1] 1

# Multiple patients with different impairment levels
hfc(ast = c(25, 45, 30, 20),
     ulnast = c(33, 33, 33, 33),
     bili = c(0.8, 1.0, 2.5, 4.0),
     ulnbili = c(1.2, 1.2, 1.2, 1.2))
#> [1] 1 2 3 4

# Edge case: bilirubin exactly at boundary
hfc(ast = 25, ulnast = 33, bili = 1.8, ulnbili = 1.2)  # 1.8 = 1.5 * 1.2
#> [1] 2

# Pipeline example with realistic data
library(dplyr)
#> 
#> Attaching package: ‘dplyr’
#> The following objects are masked from ‘package:stats’:
#> 
#>     filter, lag
#> The following objects are masked from ‘package:base’:
#> 
#>     intersect, setdiff, setequal, union

patients <- data.frame(
  ID = 1:6,
  AST = c(15, 45, 28, 35, 22, 30),
  ULNAST = 33,
  BILI = c(0.8, 1.0, 2.2, 4.5, 1.8, 0.9),
  ULNBILI = 1.2
)

patients %>%
  mutate(BHFC = hfc(AST, ULNAST, BILI, ULNBILI))
#>   ID AST ULNAST BILI ULNBILI BHFC
#> 1  1  15     33  0.8     1.2 -999
#> 2  2  45     33  1.0     1.2    2
#> 3  3  28     33  2.2     1.2 -999
#> 4  4  35     33  4.5     1.2    2
#> 5  5  22     33  1.8     1.2    2
#> 6  6  30     33  0.9     1.2 -999