研究成果を再実行できるパッケージにまとめる
データ、コード、README、環境の記録、期待結果をまとめ、空のフォルダから実行して引き渡しを確かめます。日本語の説明書付きサンプルも使えます。
再現可能な成果パッケージに必要なもの
成果パッケージは、報告した分析をもう一度実行するためのファイルと説明をひとまとめにしたものです。README、入力データまたは取得方法、データ辞書、分析コード、確認済みの環境、照合用の期待結果をそろえます。ファイルを集めただけで完成ではありません。他の人が開始場所と実行方法を判断できるか確かめます。
この章では、これまで使ってきた 4 件の架空の学習時間データを引き渡します。期待する平均は background-noise が 20.0 分、quiet が 25.0 分です。これは計算を練習するための値で、音の効果について結論を出すデータではありません。
| ファイル | 役割 | 確認すること |
|---|---|---|
README.ja.md | 目的、開始場所、コマンド、期待結果 | 記載どおりに実行できるか |
data/sessions.csv | 元の入力 | 使用した版と値が分かるか |
data/data-dictionary.ja.md | 列、単位、欠測値の説明 | 条件名と数値を解釈できるか |
analysis/analyze.py | 分析手順 | 入力を読み、指定の出力を作るか |
expected/means.csv | 照合用の参照表 | 新しい出力と一致するか |
入力、分析、出力を分ける理由は、結果を作り直すときに元データを誤って書き換えないためです。整理方法はデータ辞書の章でも確認できます。
空のフォルダからサンプルを実行する
- 学習時間の成果パッケージ(ZIP)を、新しい空のフォルダに展開します。
- 展開した
study-sessions/に移動し、README.ja.mdを読みます。 - Python 3 の環境で、下のコマンドを実行します。外部パッケージは不要です。
- 生成された
results/means.csvとexpected/means.csvを照合します。
python --version
python analysis/analyze.py
環境によっては python を python3 または py -3 に置き換えてください。新しい結果表の内容は次のとおりです。
condition,mean_minutes
background-noise,20.0
quiet,25.0
再実行すると生成済みの結果表は置き換えられます。入力と期待結果を書き換えて合わせるのではなく、同じ入力と手順から一致するかを確かめましょう。失敗したら、作業フォルダ、入力ファイル、Python の版、コードの変更を順に確認します。環境の説明は前の章を参照してください。
公開できるものと、申請が必要なものを分ける
データ、コード、説明文、図について、それぞれの利用条件を確認します。ある教材を読めることと、その教材に含まれる全素材を自由に再配布できることは同じではありません。第三者の図やフォントにも個別の条件があります。
アクセス制限のある研究データを、再現可能性のために無理に公開する必要はありません。利用申請の窓口、条件、取得後の配置場所を記し、一般の読者には架空データで試せる範囲を示します。公開用の例と実研究で異なる入力や出力も明示します。
共有前に認証情報、参加者を特定できる情報、私的なメモを取り除きます。Git リポジトリ全体を渡すなら過去の履歴も共有対象です。現在のファイルを削除しただけで履歴から消えるわけではありません。
他の人が推測した箇所を直す
可能なら共同研究者に新しいコピーを渡し、「README だけでこの表を再作成できますか」と頼みます。自分で検証する場合も、いつもの作業フォルダや記憶に頼らず、配布用の ZIP を展開した状態から始めてください。
- 入力データの版と取得方法を確認する。
- 説明された環境とコマンドで分析する。
- 新しい出力を期待結果と比較する。
- 確認したコードのリビジョン、環境、日付を記録する。
- 最初に推測が必要だった説明を直し、もう一度試す。
「最新版」だけでは後日どの版を使ったか分かりません。共有時には検証したコミットやリリースを示し、元データを変えた場合は期待結果と説明も意図して更新します。履歴の残し方はGit の章で復習できます。
練習:5 分の引き渡し点検
サンプルまたは自分の小さな研究プロジェクトについて、次の 5 点を確かめてください。
- README に目的、開始場所、実行コマンドがある。
- 入力の由来、版、各列の意味、必要な申請方法が分かる。
- コードと環境の確認済みの版が記録されている。
- 期待結果があり、新しく作った出力と比較できる。
- 公開範囲と各素材の利用条件が分かる。
点検結果の書き方を見る
例:「新しいフォルダに展開し、README.ja.md のコマンドで分析した。外部パッケージは不要。結果は background-noise が 20.0 分、quiet が 25.0 分で参照表と一致した。自分の Python の版と OS を記録した。」これは記録の例です。自分が確認していない実行環境や結果を写して済ませないでください。
これで日本語の 5 章は完了です。次は自分の表や図をひとつ選び、入力から出力までの小さなパッケージに置き換えてみましょう。
引き渡す手順をフロー図で伝える
工程がいくつもある場合は、入力データ、分析スクリプト、結果表、独立した照合の 4 つの箱で関係を整理しましょう。図は説明の補助です。実行コマンドと期待結果も README に残します。
参考資料とライセンス
本章は The Turing Way Community の著作物(Copyright © The Turing Way Community、CC BY 4.0)を基に構成しています。Miss Formula が英語版を編集基準として日本語で説明を再構成し、計算例と練習問題を追加しました。原典の図やデータは転載していません。