data-cleaning

データクリーニング

クリーニングは、観測されたデータセットに対する管理された変換として扱い、見た目を整えるだけの編集とは区別します。生データを保持し、対象とする用途および粒度を明示し、情報を失う判断はすべて明確にし、クリーニング後の出力が契約を満たしていることを証明します。

モデルがデータ変換を提案する場合は、AI 境界ワークフロー を読み、対応する記録を使用してください。

タスク別の参照先

必要な内容	次に読むもの
エンドツーエンドの手法、対象範囲、停止ルール	references/methodology.md
ライブラリまたはプラットフォームの選択	references/tool-selection.md
欠損、重複、型、範囲、カテゴリ、日付、結合	references/operations.md
テキスト、識別子、Unicode、エンティティ解決	references/text-and-entity.md
スキーマ、契約、検証、ドリフト、規模	references/validation-and-scale.md
CLI、OpenRefine、モニタリング、対話型の修正	references/cli-and-interactive-tools.md
出典の主張とバージョンに依存する注意事項	references/sources.md
計画、ログ、例外、契約、レポート	templates/cleaning-plan.md、templates/transformation-log.jsonl、templates/exception-register.csv、templates/schema-contract.yml、templates/quality-report.md
簡易プロファイリングまたは照合	python3 scripts/profile_dataset.py --help または python3 scripts/reconcile_dataset.py --help を実行します

利用可能なスクリプト

スクリプト	目的	実行方法
scripts/profile_dataset.py	CSV、TSV、JSONL 入力を変更せずに行う、依存関係のない初回プロファイリングです。欠損、カーディナリティ、型の候補、重複、範囲、値の異常を確認します。クリーニングの判断を設計する前に根拠を収集する工程として、ワークフローのステップ 3（変更前のプロファイリング）で実行します。	python3 scripts/profile_dataset.py data.csv --output profile.json
scripts/reconcile_dataset.py	変換前後の区切り形式のデータセットを照合します。--key をキーとして、行数、キーの一意性／重複状況、列ごとの合計（--sum）を確認し、機械可読なレポートを出力します。粒度が維持されていることを証明し、変換による変更を正確に定量化するため、「検証を 2 回実施／レビュー」の工程で実行します。	python3 scripts/reconcile_dataset.py raw.csv cleaned.csv --key id --sum amount --output reconciliation.json
scripts/test_profile_dataset.py	代表的な入力に対するプロファイラーの動作を網羅した pytest テストスイートです。プロファイラーを変更した後、またはその出力を監査する際に実行します。CI が自動的に検出します。	python3 -m pytest scripts/test_profile_dataset.py
scripts/test_reconcile_dataset.py	キー処理、合計、レポート出力に関する照合ツールの動作を網羅した pytest テストスイートです。照合ツールを変更した後、またはその出力を監査する際に実行します。CI が自動的に検出します。	python3 -m pytest scripts/test_reconcile_dataset.py

デフォルトのワークフロー

1. 枠組みを定める： 意思決定、担当者、データソース、プライバシー上の制約、観測単位、キー、想定される粒度、期間、受け入れ基準を特定します。疑わしい値から業務ルールを暗黙に推測してはいけません。
2. 証拠を固定する： データソースのパス／URI、取得時刻、可能であればファイルサイズ／ハッシュ、エンコーディング、区切り文字、スキーマ、行数／列数、ソフトウェアのバージョンを記録します。生データは読み取り専用のまま保持し、新しい出力先に書き込みます。
3. 変更前にプロファイリングする： 欠損、センチネル値、重複、カーディナリティ、型の候補、範囲、無効な日付、空白／Unicode の異常、フィールド間の関係、ドリフトを調べます。依存関係のない初回確認には、同梱のプロファイラーを使用します。
4. 判断方針を設計する： 各調査結果を、保持、標準化、修復、補完、隔離、却下、エスカレーションのいずれかに分類します。根拠、ルール、影響を受ける行、確信度、可逆性、担当者を記録します。
5. 段階的に変換する： 名前を付けた決定論的な手順を優先します。解析 → 正規化 → 型変換／強制 → 検証 → 重複排除 → エンティティ解決 → 補完／隔離 → 形状変換の順に進めます。生データ、ステージング、却下データ、最終データセットはそれぞれ分けて保持します。
6. 二度検証する： 変換前と変換後に構造チェックを実行します。行数／粒度の保持、キーの一意性、参照整合性、許容値、単位、範囲、null のポリシー、想定される分布を検証します。テストでは失敗したレコードを特定できるようにします。
7. レビューしてリリースする： 変換前後の指標を比較し、変更されたすべての分類からサンプルを確認し、意味的な変更や情報損失を伴う変更についてドメイン担当者の承認を得て、レポートと来歴を公開し、実行を再現可能にします。

必須の管理策

• 生データを上書きしたり、行、列、カテゴリ、外れ値、照合できないエンティティを黙って削除したりしてはいけません。
• ドメインで区別されている場合は、無効、欠損、該当なし、未収集、非公開を分けます。
• 明示的なロケール、タイムゾーン、単位、エラーポリシーを指定して、日付と数値を解析します。解析に失敗した数を数え、黙って null に変換してはいけません。
• テキストの正規化は慎重に行います。照合または修復の際は、元の値と正規化した値に加え、確信度も保持します。
• 補完器、エンコーダー、正規化パラメーター、重複排除ルールは、許可された学習／参照パーティションのみを使って適合させます。時間境界や評価境界を越えたリークを避けます。
• プロファイリング結果は調査の証拠として扱い、自動修正の許可とは見なしません。異常値が実際の事象を示している場合もあります。
• 安全に修復できないレコードには隔離を使用します。「クリーン」とは、明示された契約に適合していることを意味し、「行が残っていない」ことではありません。

完了条件

クリーニングタスクが完了したと言えるのは、出力、変換／判断ログ、検証の証拠、来歴、未解決の課題がそろい、生データがそのまま保持され、受け入れチェックに合格し、レビュー担当者が結果を再現または監査できる場合に限られます。意味上の曖昧さが残る場合は、値を作り出すのではなく、隔離またはエスカレーションの段階で止めます。

使用しない場合

推測統計やモデル選択にはこのスキルを使用しないでください。これらは data-scientist の担当です。ETL のオーケストレーション、ストレージ、本番環境のデータ品質運用については data-engineering に振り分けてください。名前の付いた検証プラットフォームやデータベースプラットフォームの操作については、そのツールのスキルに振り分けてください。このスキルが提供するのは、これらのワークフローで利用するクリーニング上の判断と成果物です。

前提条件

• 同梱の両スクリプトには Python 3.9+ と標準ライブラリのみが必要です（compatibility を参照）。エコシステムツール（OpenRefine、pandas ベースのツール）は任意の高速化手段であり、references/cli-and-interactive-tools.md で説明されています。
• 読み取り専用に保てる生データ入力と、別の出力先への書き込み権限が必要です。すべてのスクリプトは入力を変更せずに読み取ります。
• 正式な成果物が必要なタスクでは、上記のテンプレートを使用します。クリーニング計画、変換ログ、例外記録、スキーマ契約、品質レポートなどが含まれます。
• 同梱のテストスイートを実行する場合に限り、pytest が必要です。

制限事項

• 同梱のプロファイラーとリコンサイラーは、初期段階のエビデンス収集ツールです。異常を明らかにし、差分を定量化しますが、保持／修復／補完／隔離の判断は行いません。これらの分類は、ワークフローの判断ステップで決定します。
• どちらのスクリプトも区切りテキストと JSONL を処理します。バイナリ形式、リレーショナルデータベース、ネストされたドキュメントストアには、別のツールが必要です。
• プロファイリングの出力は調査のためのエビデンスであり、自動修正の許可ではありません。異常は実際に発生した事象の可能性があります。
• 照合に合格しても、確認対象のキーと合計に関する構造上の保持が証明されるだけです。値の意味的な正確性については、引き続きレビューとリリースゲートでの確認が必要です。