CH 0marimo のノートブックを用意する(準備)

この本のコードは、marimo のノートブックで動かす。第1章に入る前に、marimo を入れ、ノートブックを開いてセルを実行し、ノートブックのファイル(.py)の中身を読めるようにする。この章のコマンドはノートブックのセルではなく、ターミナル(Windows では PowerShell)で実行する。

0-1marimo とライブラリを入れる(仮想環境)

次にやること

コンペのフォルダーに Python の仮想環境(virtual environment)を作り、marimo と、この本で使うライブラリを入れる。道具には uv を使う。

理由

コンペごとに仮想環境を分ける:仮想環境は、そのフォルダー専用のライブラリの置き場である。コンペごとに分けると、あるコンペでライブラリを更新しても、ほかのコンペの結果は変わらない。この本の数値は Python 3.14・Polars 1.44・LightGBM 4.7 で出したものであり、版をそろえると同じ数値を再現できる。

marimo も同じ仮想環境に入れる:marimo はノートブックのエディターであり、セルを実行する Python でもある。ライブラリと同じ仮想環境に入れると、ノートブックはその環境のライブラリで動く。

uv を使う:uv は、仮想環境を作ることとライブラリを入れることを 1 つの道具で行う。入れたライブラリと版は pyproject.toml と uv.lock に記録されるので、別の PC でも uv sync で同じ環境を作り直せる。

コード

ターミナルで、コンペのフォルダーに移ってから実行する。

cd D:\kaggle\smartphone-addiction_s6e8
uv init --bare --python 3.14
uv add marimo polars pyarrow pandas numpy scikit-learn scipy lightgbm xgboost catboost optuna matplotlib seaborn
uv run marimo --version
使うコマンド
cd フォルダーターミナルの作業フォルダーを、コンペのフォルダーに移す
uv init --bare --python 3.14このフォルダーを uv のプロジェクトにし、使う Python の版を 3.14 に決める。--bare は、pyproject.toml だけを作り、サンプルのファイルを作らない指定
uv add ライブラリ …仮想環境(.venv フォルダー)を作ってライブラリを入れ、pyproject.toml と uv.lock に書く。pyarrow は、Polars の表を pandas に変える to_pandas()(第1章から使う)のために入れる
uv run コマンドこのフォルダーの仮想環境の中でコマンドを実行する。仮想環境を「有効にする」操作はいらない

結果

0.25.0

marimo の版が表示されれば、入れ終わっている。フォルダーには pyproject.toml・uv.lock・.venv ができる。この本は marimo 0.25.0 で書いたので、上の出力も 0.25.0 である。入れる時期によって版の数字は新しくなるが、本のノートブックはそのまま開ける(0-3 の __generated_with を参照)。

次の 0-2 では、marimo でノートブックを開き、セルを実行する。

0-2ノートブックを開いて、セルを実行する(marimo edit)

次にやること

0-1 で marimo が入った。次は marimo のエディターでノートブックを開き、セルを実行する。各章の実行用ノートブック(01_eda_guide.py など)も、自分で写すノートブックも、同じ方法で開く。

理由

marimo のノートブックはふつうの .py ファイルである:Jupyter の .ipynb と違い、中身は Python のコードだけである。そのまま Python として実行でき、Git で変更の差分も読める(0-3)。

セルどうしのつながりを marimo が管理する:marimo は、各セルがどの名前を定義し、どの名前を使うかを読み取る。あるセルを書き換えて実行すると、そのセルで定義した名前を使うほかのセルも、自動で実行し直される(リアクティブ実行、reactive execution)。古い結果が画面に残らない代わりに、同じ名前を 2 つのセルで定義するとエラーになる。この本で、ライブラリと定数を各章の最初のセルにまとめ、セルの中だけで使う名前に _ を付けるのはこのためである。

ターミナルから開く:marimo の拡張機能を入れたエディター(Antigravity など)でも、エディターの中で同じノートブックを開ける。ここでは、どの環境でも同じ手順で使える、ターミナルから開く方法を示す。

コード

0-1 と同じフォルダーで実行する。

uv run marimo edit 01_eda.py
使うコマンドとキー
marimo edit ファイル名.pyノートブックをエディターで開く。ファイルがなければ、新しいノートブックとして作る。ブラウザが開き、ターミナルには開く先の URL が出る
Ctrl + Enterカーソルのあるセルを実行する(Mac は Cmd + Enter)
Shift + Enterセルを実行し、その下に新しいセルを作る。本のコードを 1 枠ずつ写すときに使う
Ctrl + Sノートブックを .py ファイルに保存する。marimo は書き換えを 1 秒ほどで自動保存するので、押さなくても保存される
Ctrl + C(ターミナルで)marimo を止める

結果

        Edit 01_eda.py in your browser 📝

        ➜  URL: http://localhost:2718?access_token=…

ブラウザに marimo のエディターが開く。ファイルがなかった場合は、空のセルが 1 つあるだけのノートブックになる。URL の access_token は開くたびに変わる。ブラウザを閉じても、ターミナルで marimo を止めるまでは、この URL で開き直せる。

本の実行用ノートブックを開くときは、uv run marimo edit 01_eda_guide.py のようにファイル名を変える。最初のコードのセルにある PROJECT(データの置き場所)を自分の環境に合わせて書き換えてから、上のセルから順に実行する。ノートブックは 01 → 07 の順に、前の章で保存したファイル(folds.csv など)を読む。

次の 0-3 では、marimo が保存した .py ファイルの中身を読む。

0-3ノートブックのファイルの中身を読む(marimo の .py の形)

次にやること

0-2 でノートブックを開いた。marimo はノートブックを .py ファイルに決まった形で保存する。セルが 2 つだけのノートブックを例に、先頭の 3 行(import marimo・__generated_with・app = marimo.App(...))と、セルの書き方の意味を読む。

理由

枠は marimo が書くので、写すのはセルの中身だけでよい:エディターでセルにコードを書くと、marimo はそれを @app.cell の付いた関数に包み、受け渡す名前(関数の引数と return)を自動で書いて保存する。この本のコードの枠 1 つは、エディターのセル 1 つに当たる。@app.cell や return を自分で書く必要はない。

それでも形を知っておく:Antigravity などでファイルをそのまま開いたとき、エラーの行番号をたどるとき、Git で差分を読むときには、この形のまま目に入る。各行の意味を知っていれば、どこが自分のコードで、どこが marimo の枠かを見分けられる。

コード

sample.py(セルが 2 つのノートブックを、marimo が保存した形)

import marimo

__generated_with = "0.25.0"
app = marimo.App(width="medium")


@app.cell
def _():
    import polars as pl

    df = pl.DataFrame({"x": [1, 2, 3]})
    return (df,)


@app.cell
def _(df):
    total = df["x"].sum()
    print("合計:", total)
    return


if __name__ == "__main__":
    app.run()

このファイルは、ふつうの Python のファイルとしても実行できる。

uv run python sample.py
各行の意味
import marimomarimo のライブラリを読み込む。marimo が保存するファイルは、必ずこの行から始まる。marimo は、この行・__generated_with・app = marimo.App(...) の 3 行が並んだ形を見て、marimo のノートブックとして読み込む
__generated_with = "0.25.0"このファイルを保存した marimo の版。保存のたびに marimo が書き直すので、手で書かなくてよい。セルの実行には使われない。版が違う marimo でも開ける(この行を消しても、marimo check が警告を出すだけで動く)
app = marimo.App(width="medium")ノートブックの本体を作る。width はエディターでのセルの横幅で、"compact"(既定。狭い)・"medium"・"full"(画面いっぱい)・"columns"(セルを横に並べる)から選ぶ。エディターの設定で変えると、marimo がこの行を書き直す
@app.cell と def _(...):関数 1 つが、セル 1 つに当たる。関数名はどのセルも _ である。中身が、エディターのセルに書いたコードそのものである
def _(df): の引数ほかのセルから受け取る名前。2 つめのセルは 1 つめのセルの df を使うので、df が引数になる。marimo はこの引数から、セルを実行する順番を決める
return (df,)ほかのセルへ渡す名前。ほかのセルが使う名前だけが並び、どこからも使われない名前(2 つめのセルの total)は並ばない。marimo がコードを読んで自動で書く
@app.cell(hide_code=True)エディターでコードを隠し、出力だけを見せるセル。本の実行用ノートブックでは、見出しと説明の文章(Markdown)のセルに使っている
if __name__ == "__main__":
app.run()
python sample.py のように、ふつうの Python として実行したときに、全部のセルをつながりの順に実行する。エディターで開いたときには使われない

結果

合計: 6

1 つめのセルが作った df を 2 つめのセルが受け取り、合計の 6 を出した。各章の実行用ノートブック(01_eda_guide.py など)も、同じ形のファイルである。先頭の 3 行と最後の 2 行は marimo の枠で、その間の @app.cell の関数の中身が本のコードである。

準備はここまでである。第1章では、S6E8 のデータを読み込み、形と中身を確かめる。