clean-data

データのプロファイリングとクリーニングのスキル

3段階で臨床データセットのプロファイリングとフラグ付けを行い、クリーニング用コードを生成します。各段階はユーザーの承認を得るゲートで終了します。コードとレポートを生成しますが、データの自動クリーニングは行いません。臨床データのクリーニングには専門知識が必要なため、すべてのクリーニング判断について、研究者の明示的な確認が必要です。

まず PHI を確認してください。 データセットに PHI または PII が含まれる場合は、作業を進める前に /deidentify を実行し、作業ディレクトリに *_deidentified.* ファイルがある場合は、それらを使用してください。それ以外の場合は、データ辞書／コードブックのみを使用するか、ネットワークに接続しないローカル環境で作業してください。このスキルはデータに対して実行するコードを作成するものであり、コード作成のために生の行データを見る必要はありません。

3段階のワークフロー

Stage 1：プロファイリング

入力：CSV／Excel ファイルのパス、またはデータ辞書／コードブック

1. ${CLAUDE_SKILL_DIR}/references/profiling_template.py（pandas）をデータセットに合わせて調整します。変数と行の数、データ型、変数ごとの欠損数と割合、カテゴリ変数のユニーク数、数値変数の最小値／最大値／平均値／中央値／標準偏差、ヒストグラム、棒グラフを出力します。
2. ユーザーからコードブックが提供された場合は、変数名、想定される型、想定される範囲を照合します。列名やコーディングを推測してはいけません。対応関係が不確かな場合は [VERIFY: variable_name] と記載し、データ辞書で確認するようユーザーに尋ねてください。
3. 要約を提示します（出力形式を参照）。すべての件数と統計値は、実行したスクリプトの出力に基づくものとします。

ゲート：ユーザーにプロファイルを確認してもらいます。Stage 2（フラグ付け）に進むか、また対象から除外する変数や重点的に確認する変数があるかを尋ねてください。

ステージ 2：フラグ付け

欠損データのメカニズム、外れ値の判断基準、重複の検出、日付の処理、臨床上の注意点（不等号が付いた検査値、単位の混在、センチネル値）について、${CLAUDE_SKILL_DIR}/references/cleaning_patterns.md を読んでください。次のカテゴリの問題にフラグを付けてください。

1. 欠損値：欠損率が 5% を超える変数。パターン分析（MCAR/MAR/MNAR のヒューリスティック）。
2. 統計的外れ値：IQR 法（Q1 - 1.5IQR、Q3 + 1.5IQR）および Z スコア（|z| > 3）。
3. 重複：行が完全に一致する重複、および準重複（患者 ID が同じで日付が異なる）。
4. 型の不一致：数値が文字列として格納されている、日付の形式が統一されていない。
5. 非現実的な値：コードブックの有効範囲と照合してください。コードブックに記載がない場合は、references/implausible_value_rules.md §1 にある領域のデフォルトの生理学的上限・下限と照合してください。非現実的な値は、入力ミス、単位の誤り、センチネル値の誤りである可能性が高いため、修正するか欠損値に設定します。統計的外れ値（#2）は生物学的にあり得る値なので、保持して感度分析を行います。上限・下限違反を誤りと判断する前に、単位を確認してください。自動修正は絶対に行わないでください。 5b. フィールド間の不整合：references/implausible_value_rules.md §2 に記載された論理的矛盾（時間的順序（出生 ≤ イベント ≤ 死亡、入院 ≤ 退院）、派生値と元データの整合性（BMI／年齢の再計算、部分集合 ≤ 全体集合、合計 = 各項目の合計）、性別・状態ごとのフィールド、最小値 ≤ 最大値、および拡張期血圧 < 収縮期血圧の組み合わせ）にフラグを付けてください。どのルールに違反したかを明記してください。重大な矛盾は重大度「高」です。
6. カテゴリの不整合：カテゴリ値の誤字や表記揺れ（「Male」、「male」、「M」、「MALE」）。
7. カテゴリ値から推定されるゼロ：カテゴリによって、投与量／期間の変数が自然にゼロとなる場合（smoking_status == 'never' は pack_years == 0 を意味する、alcohol_use == 'never' は grams_per_week == 0 を意味するなど）、推定されるゼロが NULL として格納されたレコードにフラグを付けてください。これは欠損データのパターンではなく矛盾です。完全ケースモデルでは、喫煙経験のない人が気づかれないまま除外され、MICE ではゼロ以外の投与量が代入されるため、曝露の対比が損なわれます。推奨アクション：「カテゴリが参照レベルの場合は投与量 = 0 に設定し、曝露ありの対象に残る欠損値のみを代入する」。カテゴリと投与量の対応関係を指定して scripts/check_structural_zero.py で検出します。/analyze-stats の「共変量の落とし穴：構造的ゼロと投与量／期間変数」と組み合わせて使用します。
8. 逆転項目：肯定的な表現と否定的な表現が混在する複数項目のリッカート尺度では、尺度の合計値または Cronbach のアルファを計算する前に、すべての逆転項目を (min+max) - x で再コード化する必要があります。再コード化していない逆転項目は他の項目と負の相関を示し、アルファを低下させ、多くの場合負の値にします。負のアルファは「多次元構造」ではなく、逆転項目の再コード化に関するバグです。推奨アクション：「逆転表現の項目を再コード化してから、信頼性を再計算する」。尺度項目の列を指定して scripts/check_reverse_coding.py で検出します（項目とそれ以外の項目との負の相関、および負の未調整アルファ）。再コード化自体は、下流処理で /analyze-stats の likert_summary.py --reverse-items によって適用されます。

フラグ付けレポートは次の表で提示してください。

変数	問題の種類	件数	重大度	推奨アクション
age	外れ値（IQR）	3	中	確認：値は 150、200、-5
pack_years	カテゴリ値から推定されるゼロ	12421	高	smoking_status=='never' の場合は 0 に設定（構造的ゼロであり、欠損ではない）

重大度のレベル：

• 高：分析に影響する可能性が高いデータエラー（型の不一致、あり得ない値）
• 中：専門家による確認が必要な可能性のある問題（統計的外れ値、中程度の欠損）
• 低：簡単に修正できる軽微な不整合（カテゴリラベル、末尾の空白）

承認ゲート：ユーザーは各行について、推奨アクションを（A）承認、（R）却下して現状維持、または（M）アクションを変更します。承認されたアクションのみ、クリーニングコードが生成されます。

ステージ 3：コード生成

ユーザーが承認した操作のみを対象に、Python（またはリクエストされた場合は R）のコードを生成します。

• 欠損値の処理：リストワイズ削除、平均値／中央値による補完、または MICE の設定（コードのみを提供し、変数と方法の選択および実行はユーザーが行います）
• 外れ値の処理：ウィンザー化、削除、または保持してフラグを付与
• 重複の削除：ログを記録しながら完全一致の重複を削除
• 型変換：日付の標準化、数値の解析
• カテゴリの統一：不統一なラベルに対応するマッピングテーブル

生成するコードには、以下を必ず含めてください。

• 変更前後の行数をコンソールに出力
• すべての変更をクリーニングログ DataFrame に記録
• 再現性の確保：該当する場合は np.random.seed(42) と random.seed(42) を設定
• 出力：クリーニング済み CSV（新しいファイル。入力ファイルは上書きしません）と cleaning_log.csv
• 各クリーニング手順を説明する明確なコメント

生成するスクリプトの最後に、次の注意書きを記載してください。

「このコードは、承認されたクリーニングルールのみを実装します。分析に進む前に、出力された cleaning_log.csv を確認し、すべての変更を検証してください。」

対象外：臨床記録の自由記述からの情報抽出、および画像データや DICOM メタデータ。クリーニング後は /analyze-stats に引き継いでください。引用は /search-lit から取得し、記憶に頼らないでください。

出力形式

すべてのレポートを、次のテンプレートに従って構成してください。

## Data Profiling Report

### Dataset Overview
- Rows: [N]
- Columns: [N]
- File size: [size]
- Date range: [if applicable]

### Variable Summary
| Variable | Type | Missing N (%) | Unique | Min | Max | Mean | SD |
|----------|------|---------------|--------|-----|-----|------|-----|
| ...      | ...  | ...           | ...    | ... | ... | ...  | ... |

### Flags
| Variable | Issue | Count | Severity | Suggested Action |
|----------|-------|-------|----------|-----------------|
| ...      | ...   | ...   | ...      | ...             |

### Cleaning Code
[Python/R script -- only for approved actions]

### Cleaning Log
[What was changed, how many rows affected, before/after counts]