チームでコード管理する際のJupytextのいい感じの設定方法

jupytextの自動変換の設定で他の人に~/.jupyter/jupyter_notebook_config.pyを編集させるの、辛いですよね。よい設定方法があるので共有します。

まず結論

以下の内容のファイルをプロジェクトのルートに配置する。

jupytext.yml

default_jupytext_formats: "ipynb,py:percent"

jupytextとは

jupytextは、.ipynbのファイルを.py, .R, .jl, .md, .Rmdなどに相互に変換するツールです。設定することでjupyter labと連携して、ファイル保存時にそれを自動変換してくれます。また、コマンドラインでも実行できるため、使いみちが豊富です。

.ipynb -> .pyへの変換には他のツールとしてnbconvertもありますが、保存時に自動的に変換するようにするには工夫がとても必要です。

.ipynb <-> .py変換

複数人で分析を行うと.ipynbのよくないところが明らかになっていきます。
いくつかありますが

• git管理するには重たい。
• json形式になっていてレビュー時に読みにくい。

などがあり、共有することが難しいです。
この解決策の一つとして、python形式などに変換するという方法があります。これによって、notebookが軽量で見やすくなり、良い感じです。
また、.py -> .ipynb変換によってnotebookの再現も問題なくできます。

環境

# Pipenv環境
python 3.8.5
jupyterlab 2.2.6

利用手順

1. jupytextのインストール

pipenvを使っていない場合はよしなに置き換えてください。

$ pipenv install jupytext

2. jupyter labのビルド

インストール後jupyter labを起動するとビルドするかどうか聞かれるので、そのままビルドしてください。
手動でビルドしたい場合はpipenv run jupyter lab buildです。

設定の方法

4種類の設定方法

設定方法は4つあります。

1. .ipynbのメタデータを編集
2. jupytext --set-formats ipynb,py notebook.ipynb
3. ~/.jupyter/jupyter_notebook_config.pyを編集
4. jupytextの設定ファイルを作成

1, 2は各ファイルごとに設定が必要で面倒です。
3はリポジトリ外のファイル操作をさせる必要があるため動作が保証できません。

今回は4番について説明します。
このやり方だと他の人がリポジトリをプルした時でもすでに設定されているので優しいです。

設定ファイルの作成

設定ファイルは以下のいずれかの名前で作成します。
.jupytext
jupytext.toml
jupytext.yml
jupytext.yaml
jupytext.json
jupytext.py
またはこれらの先頭に.を加えた形式

このファイルをプロジェクトのルートにおいておけば自動的に読み込んでくれます。
配置場所について詳細は参考リンクをご確認ください。

以下のように書くことで自動変換が効くようになります。今回はyamlで書きました。

jupytext.yml

default_jupytext_formats: "ipynb,py:percent"

VSCodeやPyCharmでの利用なども考えるとpythonファイルはpy:percent形式がおすすめです。

結果こういう感じのディレクトリ構成になると思います。

.
├── Pipfile
├── Pipfile.lock
├── notebook.ipynb  # 作成したnotebook
├── notebook.py  # 変換されて生成したpython
└── jupytext.yml  # 設定ファイル

まとめ

• .ipynb <-> .py変換を利用すればチームでのコード管理がしやすくなる。
• Jupytextはファイル保存時に自動変換することができる。
• Jupytextの設定方法は色々ある
• 設定ファイルを使えば設定を共有しやすい
• py:percentが無難

以上です！

参考

Configuration — Jupytext documentation