datalad

DataLad

概要

DataLad は、Git と git-annex の上に成り立つデータ管理レイヤーです。Git はデータセットの 構造、小さなテキストファイル、履歴を追跡します。git-annex は大きなファイルの内容を追跡し、 各ファイルをキーとして保存し、そのバイト列を必ずしもローカルリポジトリではない場所に保持します。

通常のクローンでは、Git の履歴とトップレベルのファイル一覧を取得しますが、annex 化された バイト列は取得されません。インストールされたサブデータセットはそれぞれ独自の履歴を持ち、 クローンしても自動的にそれらが取り込まれることはありません。クローンのコストは、データ量だけでなく、 Git の履歴とファイル数に依存します。annex 化されたバイト列は datalad get で選択的に取得します。

DataLad が追加する 2 つ目の要素は、来歴（provenance）です。datalad run はコマンドを実行し、 その結果を、コマンド、その入力、および出力を記録した機械可読な記録とともにコミットします。 datalad rerun はその記録を読み戻し、再実行します。これにより、「この図はどのように生成されたのか」 という問題が、考古学の問題からコマンド一つへと変わります。

プレーンな Git の代わりに DataLad を使うべき場合

次のいずれかに当てはまる場合は DataLad を使用してください:

• ファイルが Git で快適に扱うには大きすぎる、または合計がすべての共同作業者がディスク上に 置きたい量を超えている。
• データが複数の場所（ラボのサーバー、クラスターのスクラッチ、S3、スーパーコンピューター）に 存在し、どのコピーが存在するのかを知る必要がある。
• 解析が再実行可能でなければならず、単なるコミットメッセージでは証拠として不十分である。
• OpenNeuro、DANDI、または datasets.datalad.org から公開されたデータセットを利用している。 これらは DataLad データセットとして配布されています。
• プロジェクトが他のデータセットを内部にネストしており、それぞれに独自の 独立した履歴を保持させたい。

プレーンな Git を使用するのは、リポジトリがコードとテキストのみで、すべてが Git に 余裕をもって収まり、誰も部分チェックアウトを必要としない場合です。小さな純粋なコードの リポジトリの上に DataLad を重ねても、何も得られずに間接的な層が増えるだけです。

インストール

# git-annex is NOT written in Python but is available from PyPI if you already
# have git itself installed:
uv pip install git-annex
# You can also install it first from the system
# (Debian/Ubuntu: apt install git-annex; macOS: brew install git-annex;
#  conda-forge: conda install -c conda-forge git-annex)
uv pip install "datalad==1.6.5"
uv pip install "datalad-container==1.2.6"   # only for containers-run

datalad wtf --section dependencies   # confirm git-annex version is visible

PyPI の git-annex パッケージは、プラットフォーム固有のバイナリを提供します。レビュー済みの 10.20260901.post1 ホイールは、Linux glibc 2.34+（x86_64/ARM64）、macOS ARM64 14+ および x86_64 15+、ならびに Windows x86_64 をカバーしています。一致するホイールがない場合は システムパッケージを使用してください。その環境を PATH に通し、実行ファイルを検証してください。 ホイールは Git 自体を提供しません。データセットを作成または保存する前に、Git の author の 名前/メールアドレスを設定してください。

datalad wtf は解決済みの環境を出力し、挙動が不可能に見えるときに最初に実行すべき コマンドです。古い、または存在しない git-annex が、紛らわしいエラーの大部分の背後にあります。

DataLad は MIT ライセンスです。git-annex は別途 AGPL ライセンスを持ちます。いずれかのツールを 再配布する場合は、上流のライセンスを確認してください。

最初にぶつかる失敗: ポインタはデータではない

datalad clone の後、annex されたファイルは .git/annex/objects/ へのシンボリックリンクとして存在します（または、Windows や機能が制限されたファイルシステムなど、シンボリックリンクが利用できない場合は小さなポインタファイルとして存在します）。コンテンツはまだ何もダウンロードされていません。

説明的なリモートデータの例です。正確なパスについては選択したリビジョンを確認し、Python で読み取る前に NiBabel をインストールしてください。このリフレッシュでは、イメージングデータをダウンロードせずに、同等のローカルポインタ／get の動作をテストしました。

datalad clone https://github.com/OpenNeuroDatasets/ds000001.git
cd ds000001
ls sub-01/anat/            # the file is listed
python -c "import nibabel; nibabel.load('sub-01/anat/sub-01_T1w.nii.gz')"   # fails
datalad get sub-01/anat/sub-01_T1w.nii.gz                                   # now it works

認識すべき失敗モード: ツールがファイルを空、切り詰められている、破損している、「gzip ファイルではない」、または壊れたシンボリックリンクとして報告し、ディスク上のファイルサイズが数百バイトである場合です。これらの症状は、未取得の annex ポインタを示している可能性があります。破損と診断する前に annex status で確認してください。データを読み取る前に datalad get を実行し、「ファイルが存在する」ことをそのコンテンツが存在する十分な証拠として扱わないでください。

分析がディレクトリに触れる前に、明示的に取得してください:

datalad get sub-01/                  # everything under a path
datalad get -r .                     # everything, including subdatasets
datalad get -n -r .                  # subdataset structure only, no file content

datalad status --annex availability はどのコンテンツがローカルに存在するかを確認し、git annex whereis <path> は特定のファイルをどのリポジトリが保持しているかを報告します。whereis は記録された状態を読み取り、リモートに問い合わせないため、現時点で真実であることではなく、git-annex が最後に把握したことを示します。

データセットの検索、サブデータセットの動作、コンテンツの安全な削除、データセットの修復については、data-access.md を参照してください。

datalad run による来歴の記録

datalad run は、メソッドの文脈で DataLad に手を伸ばす理由です。コマンドをその効果とともに、同じコミットに保存します。

説明的な FSL の例（bet と既存の derivatives/ ディレクトリが必要です）:

datalad run -m "extract brain and mask" \
  --input "sub-01/anat/sub-01_T1w.nii.gz" \
  --output "derivatives/sub-01_brain.nii.gz" \
  --output "derivatives/sub-01_brain_mask.nii.gz" \
  "bet {inputs[0]} {outputs[0]} -m"

各部分が何をするのか、そしてそれを省略するとなぜ困るのか:

• --input は実行前にコンテンツを取得するため、コマンドがポインタで失敗しません。また依存関係を記録し、それが rerun で別のマシン上で同じ入力を取得できるようにします。
• --output は最初にターゲットのロックを解除するか削除するため、git-annex が保護しているコンテンツへの上書きを拒否しません。これがないと、同じコマンドの2回目の実行は、読み取り専用に見える annex されたファイルで権限エラーにより失敗することがよくあります。
• {inputs} と {outputs} はそれらの値に展開されます。{pwd}、{dspath}、{tmpdir} も利用可能で、{inputs[0]} は個々のエントリをインデックス指定します。
• コミットメッセージは、=== Do not change lines below === と ^^^ Do not change lines above ^^^ の間に JSON の実行記録を含みます。そのブロックを手で編集しないでください。rerun がそれを解析します。

datalad run は、データセットに保存されていない変更がある場合、開始を拒否します。クリーンでない開始状態は記録を信頼できないものにするためです。先に保存するか破棄するか、宣言された出力のみを保存する --explicit を渡してください。これは保存されていない入力の変更を捕捉しません。実行が再現可能であると主張する前に、すべての依存関係を保存してください。コマンドを確定する前に --dry-run basic または --dry-run command で確認してください。

何も変更しない実行は、datalad save とまったく同じように、コミットを生成しません。

run はコマンドとデータセットの状態を記録しますが、ホストにインストールされた任意のソフトウェアや外部サービスを凍結するものではありません。環境ロックファイルとスクリプトを宣言された入力としてバージョン管理するか、containers-run で追跡されたコンテナイメージを使用してください。乱数シードと関連するランタイム設定を記録し、計算の再現性を主張する前に、クリーンな環境から rerun をテストしてください。

再実行

datalad rerun                       # redo the run recorded at HEAD
datalad rerun --report              # show what would be done, change nothing
datalad rerun --script recompute.sh # extract the commands instead of running them
datalad rerun --since <commit> -b check <revision>   # replay a range onto a new branch

--report は計画を検査するだけで、実行や結果の検証は行いません。ブランチ（-b）は元のコミットを保持しますが、同じワークツリーを使用します。最初の実行より前から開始する --since/--onto のリプレイについてはリファレンスを参照し、科学的な出力だけでなく annex キーやコンテンツのチェックサムも比較してください。

コンテナ

datalad-container 拡張機能を使うと、イメージを一度登録するだけで、その後のすべての実行で どのイメージが出力を生成したかが記録されます:

以前にビルドしたローカル SIF イメージを使用したコンテナワークフローの例（この更新では実行 されません。ランタイムとイメージが利用可能である必要があります）:

datalad containers-add fsl --url /path/to/fsl.sif \
  --call-fmt 'apptainer exec {img} {cmd}'
datalad containers-run -n fsl -m "brain and mask in container" \
  --input "sub-01/anat/sub-01_T1w.nii.gz" \
  --output "derivatives/sub-01_brain.nii.gz" \
  --output "derivatives/sub-01_brain_mask.nii.gz" \
  "bet {inputs[0]} {outputs[0]} -m"

イメージ自体がデータセット内で追跡されるため、ソフトウェア環境はデータとともに移動し、 来歴記録の一部となります。誰かのシェル履歴に留まることはありません。コンテナが 1 つだけ 設定されている場合、-n は省略できます。

STAMPED 原則と YODA プロジェクトレイアウト、run 記録の形式、--explicit と --assume-ready のセマンティクス、および W3C PROV への来歴のエクスポートについては、 provenance.md を参照してください。

変更の保存と検査

datalad status                 # what changed, including subdataset state
datalad save -m "add QC report" path/to/file
datalad save -m "checkpoint" -r                 # recurse into subdatasets
datalad save -m "small text file" --to-git notes.md

datalad save は、データセットの .gitattributes に従って、ファイルごとにコンテンツを Git に送るか git-annex に送るかを決定します。--to-git を使うとファイルを強制的に Git に 入れることができ、これは直接読める状態を保つべきコードや小さなテキストファイルに適した 選択です。yoda プロシージャ（datalad create -c yoda）はこれを code/、README.md、 CHANGELOG.md に対して自動的に設定します。

データセットの作成

datalad create my_dataset               # plain dataset
datalad create -c yoda my_analysis      # analysis layout (code/ tracked in Git,
                                        # README.md and CHANGELOG.md preconfigured)
datalad create -d . inputs/raw          # register a new subdataset under an existing one

-c yoda は provenance.md で説明されている解析プロジェクト レイアウトを適用します。-d . は、新しいデータセットを無関係なリポジトリとして内部に 残すのではなく、親のサブデータセットとして登録するためのものです。

公開

DataLad データセットは通常、履歴用の Git ホスティングサービスと、annex されたコンテンツ用の ストレージリモートという 2 か所に同時に公開されます。

認証を伴う公開の例（リモートリソースを作成します。GitHub トークンと S3 認証情報が必要 です）。myorg/mydataset は組織の名前空間にのみ使用してください。

datalad create-sibling-github mydataset
git annex initremote store type=S3 bucket=my-bucket protocol=https \
  encryption=none autoenable=true
datalad siblings configure -s github --publish-depends store
datalad push --to github

Git シブリングとストレージシブリングは、意図的に異なるツールで作成されます。Git シブリング は Git リモートであり、datalad create-sibling-* はホスティングサービス用のものを扱います。 S3 バケット（または WebDAV、あるいは SSH ディレクトリ）は git-annex スペシャルリモート であり、Git リモートではないため、git annex initremote で作成します。datalad siblings は後からそのスペシャルリモートを認識し、他のリモートと同様に扱います。ここで datalad siblings add --url s3://... を使うことが、このセクションが防ぐために存在する 間違いです。--url は Git リモート URL ですが S3 はそうではないため、以下の push --to github は --publish-depends のホップで失敗します。

--publish-depends は、よくある壊れた公開を防ぐものです。つまり、履歴がアップロードされて いないコンテンツを参照している Git リポジトリで、共同作業者がクローンには成功するものの、 すべての datalad get が失敗するという状況です。依存関係を宣言することで、ストレージ シブリングが毎回必ず先に公開されるようになります。

datalad push は Git 履歴と、デフォルトでは（--data auto-if-wanted）ターゲットの wanted 設定によって選択された annex コンテンツの両方を送信します。wanted 設定がない場合は、選択 された現在のコンテンツをすべて転送します。--data anything は preferred-content フィル タリングを回避しますが、失われたローカルのバイトを復元したり、すべての履歴バージョンを アーカイブしたりするわけではありません。

RIA ストア、スペシャルリモート、認証情報の扱い、およびどのシブリングが何を保持するかの 設定については、publishing.md を参照してください。

ディスク容量の解放

git annex whereis sub-01/                 # inspect recorded locations first
datalad drop sub-01/                      # remove local content, keep the pointer

datalad drop はデフォルトで必要なコピーと可用性をチェックします。--nocheck は --reckless availability に取って代わられ非推奨となっており、これはそれらの保護を無効に します。--if-dirty は非推奨であり無視されます。これは可用性チェックのオプションでは ありません。--what は filecontent（デフォルト）、allkeys、datasets、all の中から 選択します。

知っておくべき障害モード

症状	原因	対処
ファイルが空、切り詰められている、または壊れたシンボリックリンクとして読み取られる	コンテンツが取得されておらず、ポインタのみが存在する	datalad get <path>
既存の出力への書き込み時に「Permission denied」	git-annex が annex されたコンテンツを書き込み保護している	--output で宣言するか、datalad unlock <path> を実行する
datalad run が開始を拒否する	データセットに未保存の変更がある	先に datalad save を実行するか、--explicit を渡す
datalad drop が拒否する	コンテンツの検証済みの第 2 コピーが存在しない	到達可能な sibling にプッシュしてから、安全性チェックを再試行する
コラボレーターがクローンしてもすべての get が失敗する	コンテンツなしで履歴が公開されている	ストレージ sibling を公開し、--publish-depends を設定する
クローンは成功するが、サブデータセットのディレクトリが空である	サブデータセットはデフォルトではインストールされない	datalad get -n -r . を実行し、その後必要なパスを get する
コマンドの動作が不可解である	git-annex が存在しないか古すぎる	datalad wtf --section dependencies

詳細リファレンス

• data-access.md: 公開データセットの検索 (registry.datalad.org、OpenNeuro、DANDI、datasets.datalad.org および /// ショートカット)、clone と get のオプション、サブデータセットの扱い、annex コンテンツの状態、ドロップ と削除、および fsck による修復。
• provenance.md: STAMPED 原則と YODA レイアウト、 run レコードの形式、run と rerun のオプションの詳細、containers-run、および DataLad の来歴を W3C PROV に向けてエクスポートする現状。
• publishing.md: sibling とそのアクション、 create-sibling-* のバリアント、RIA ストア、特殊リモート、push のセマンティクス、および 認証情報の扱い。

関連スキル

bids スキルは、DataLad を通じて配布される神経画像データセットのほとんどが整理されている Brain Imaging Data Structure を扱います。典型的なワークフローでは、DataLad で BIDS データセットをクローンし、BIDS ツールで検証してから、datalad containers-run の下で BIDS-App を実行するため、 派生データに来歴が引き継がれます。

検証範囲

2026-09-30 に、DataLad 1.6.5 および datalad-container 1.2.6 のソースと 現在の公式マニュアルに対してレビュー済みです。小規模なローカルテストでは、clone/get/drop、unlock された保存、 サブデータセットのインストール、run/rerun、デフォルトのプッシュ選択、および RIA の publish/clone/get をカバーしています。 リモートホスティング、認証情報、FSL、およびコンテナ実行の例は例示的なものであり、 認証済みのリモート公開や科学データのダウンロードは行われていません。

一次情報源

• DataLad ドキュメント: https://docs.datalad.org/en/stable/
• DataLad ハンドブック: https://handbook.datalad.org/en/latest/
• datalad run の章: https://handbook.datalad.org/en/latest/basics/101-108-run.html
• YODA 原則: https://handbook.datalad.org/en/latest/basics/101-127-yoda.html
• STAMPED 原則 (YODA から運用化): https://stamped-principles.org
• datalad-container: https://docs.datalad.org/projects/container/en/stable/
• git-annex: https://git-annex.branchable.com/
• データセットレジストリ: https://registry.datalad.org

謝辞

このスキルのトピック範囲は、@bcmcpher の MIT ライセンスの datalad-cli プラグイン (コマンドごとの 19 のスラッシュコマンドスキル) から一部情報を得ています。ここに記載された文章は 独立して書かれ、上流の DataLad ドキュメントに基づいています。どちらも DataLad を扱うため重複は避けられませんが、 構造、スタイル、および具体的な技術的主張は異なります。