mcpField
V
version-dataset

version-dataset

github.com/aperivueデータ・データベース353101 回インストール1 日前に更新
リポジトリ

version-dataset について

version-dataset は、分析実行間でデータセットのバージョンを追跡・検証する研究者向けスキルです。データを保存・変更せず、決定論的ハッシュと来歴をマニフェストに記録します。

主な機能

  1. 01データのハッシュ、シード、来歴を含むマニフェストを作成
  2. 02ファイル、表構造、列の値を検査
  3. 03分析実行前に入力を検証
  4. 04マニフェストを比較して変更を要約
  5. 05変動する列を除外可能

活用シーン

  1. 01分析入力を固定して来歴を記録
  2. 02分析再実行前にデータの差分を確認
  3. 03データセットのバージョン間の変更を確認

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/aperivue/medsci-skills --skill version-dataset

インストール後、Claude Code で/version-datasetを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

skill.yml
references/
manifest_schema.md
scripts/
version_dataset.py
tests/
test_version_dataset.sh

詳細

バージョンデータセットスキル

分析は、固定シードを使って、対象としているデータに対して実行する必要があります。このスキルは、実行間の差異を見逃さずに把握できるようにします。決定論的なフィンガープリント（ファイルの SHA-256 と、表形式ファイルの場合はスキーマおよび列ごとの値のハッシュ。明示的に指定しない限りタイムスタンプは含みません）を記録するため、後から入力が変わっていないことを証明できます。データは変更せず、マニフェストにはデータ自体ではなくハッシュを保存します。出所に関するメモは英語で記述します。

決定論的スクリプト

# Build a manifest (record the analysis seed + provenance)
python "${CLAUDE_SKILL_DIR}/scripts/version_dataset.py" manifest data.csv \
  --out manifest.json --seed 42 --provenance "KNHANES 2018 extract v1"

# Verify a later copy against it (CI / pre-analysis gate)
python "${CLAUDE_SKILL_DIR}/scripts/version_dataset.py" verify --manifest manifest.json --strict

# Compare two manifests (what changed between versions)
python "${CLAUDE_SKILL_DIR}/scripts/version_dataset.py" diff --old v1.json --new v2.json

ファイルのハッシュ計算には標準ライブラリのみを使用します。表形式ファイルのスキーマと列のハッシュ計算には、利用可能な場合は pandas を使用します。 --ignore-cols は変動する列を除外します。--base はマニフェストのキーを相対パスにします。

ワークフロー

ステップ 1：バージョンを固定する（ゲート）

データセットを分析用に凍結した時点でマニフェストを作成します。ゲート： 固定する前に、シードと出所に関するメモが正しいことをユーザーに確認してください。 マニフェストは、ユーザーが「結果の元となったデータ」として引用する記録です。 出所に関するメモはユーザーの文章です。決して創作してはいけません。

ステップ 2：各実行の前に検証する（ゲート）

分析を再実行する前（または CI で）、verify --strict を実行します。verify を実行せずに、データセットが変更されていないと言ってはいけません。ゲート： 差異が報告された場合（MANIFEST_DRIFT、終了コード 1）、停止し、計算されたとおりの差異レポートをユーザーに提示してください。変更された列のハッシュを決して軽視してはいけません。ユーザーが明示的に了承し、再固定するまでは、変更後のデータで処理を続けないでください。差異があるのに黙って再実行してしまうことを防ぐために、このスキルは存在します。

差異を解釈する前に ${CLAUDE_SKILL_DIR}/references/manifest_schema.md を読んでください。ここでは各差異カテゴリを定義しています。CSV/TSV ファイルは生のバイト列ではなく、論理的な内容（スキーマと列ごとの値のハッシュ）で比較されます。そのため、引用符の付け直し、列の並べ替え、または --ignore-cols で除外した変動列によって誤った差異が生じることはありません。バイナリ形式の表データファイル（Parquet/Stata/SAS/Excel）もバイト単位で検証されます。ラベル、メタデータ、その他のシートは列のハッシュに含まれないためです。ただし、--ignore-cols で指定した列がファイルに存在する場合は、その変更によってバイト列が変わります。

ステップ 3：バージョン間の差分を取る

データセットを意図的に更新した場合は、古いマニフェストと新しいマニフェストの diff を取り、変更内容（追加・削除・変更された列、行数の差）を提示します。これにより、ユーザーは変更点を記録して再固定できます。ゲート： 新しいバージョンに置き換える前に、ユーザーの承認を得てください。

非決定論的な成果物

PPTX/DOCX や図のバイナリファイルを、バイト単位の厳格な検証対象に含めないでください。タイムスタンプやレンダリングメタデータが埋め込まれており、ビルドのたびに変わるためです。決定論的な入力と表形式の出力（データファイル、結果の CSV）のみをマニフェストに含めるか、変動する列には --ignore-cols を使用してください。このポリシーは references/manifest_schema.md に記載されています。バンドルされている各 demo/*/ には manifest.lock.json（入力データと決定論的な結果テーブル）が含まれ、verify --strict によって検証されます。デモのコマンドはリファレンスに記載されています。

対象範囲

  • マニフェストを共有する前に /deidentify を実行してください。値の例は保存されませんが、出所に関するメモには背景情報が含まれる場合があります。
  • データのクリーニング、プロファイリング、または匿名化には → /clean-data、/generate-codebook、/deidentify を使用します。/generate-codebook はデータに「何が」含まれているかを記録し、このスキルは「どのバージョン」かを固定します。

コメント

Markdown 対応