28sungmin/m4-add-skills/fidelity

Fidelity

Calculates structured fidelity for clinical variables in a QUIQ-format table. Measures the average per-patient recording frequency for each clinical concept, grouped by category (Mapping_info_1).

When to Use This Skill

• After QUIQ conversion, to assess how faithfully clinical events are recorded per patient
• To identify variables with unusually high or low recording frequency
• As part of LYDUS quality management assessment

Categories and Filtering

• Event는 값 구분 없이 환자별 발생 횟수만 집계
• 나머지 3개 카테고리는 (Variable_name, Value) 조합별로 집계

Metrics

(Original_table_name, Variable_name[, Value]) 그룹별:

Weighted Fidelity = Σ(Patient_num × Mean) / Σ(Patient_num)

Output

How to Run

import os
import duckdb
skill_dir = os.path.dirname(os.path.abspath(__file__))
with open(os.path.join(skill_dir, "scripts/duckdb.sql")) as f:
    sql = f.read()
quiq_csv = "/path/to/quiq_3patients.csv"
sql = sql.replace("{quiq_csv}", quiq_csv)
df = duckdb.sql(sql).df()
total_num = df["Patient_num"].sum()
weighted_fidelity = round(
    (df["Patient_num"] * df["Mean"]).sum() / total_num, 2
)
print(f"Weighted Fidelity = {weighted_fidelity}")
save_path = "/path/to/output"
os.makedirs(save_path, exist_ok=True)
df.to_csv(f"{save_path}/fidelity_summary.csv", index=False, encoding="utf-8-sig")
with open(f"{save_path}/fidelity_total.txt", "w") as f:
    f.write(f"Weighted Fidelity = {weighted_fidelity}\n")
print(f"Saved {len(df):,} rows → {save_path}")

As a script with config

# config.yaml
quiq_path: /path/to/quiq.csv
save_path: /path/to/output

python scripts/fidelity.py --config config.yaml

Critical Notes

1. Event Value = NULL — Event 카테고리는 값 종류와 무관하게 발생 빈도만 집계하므로 Value 컬럼이 NULL.

1. Is_categorical 타입 — 원본 코드에서 df['Is_categorical'] == 1 비교 전 타입 변환 없음. 스킬 버전에서 pd.to_numeric(..., errors='coerce') 및 SQL TRY_CAST 로 수정.

1. Std = NULL — 환자가 1명인 그룹은 표준편차가 NULL (샘플 표준편차 ddof=1).

1. Weighted Fidelity 해석 — 값이 클수록 환자 1인당 평균적으로 더 많은 기록이 있음. 정상 범위는 데이터셋과 기관에 따라 다름.

References

• LYDUS 품질관리 프로그램 활용 가이드라인 (비공개 내부 문서)
• Original Python implementation: LYDUS_Fidelity.py (이성민 작성)