JupyterNotebook入門

JupyterNotebookの基本操作と、NIIクラウド運用チームによるプラグイン拡張の一部について解説します。

操作対象となるNotebookを準備する

新規作成

image.png

Notebook一覧表示画面の右上のプルダウンメニュー（赤丸）から、「Python3」（青丸）を選ぶことで、

image.png

新しいNotebookを作成できます。 Notebookのタイトル部分（赤丸）をクリックすると、Notebookの名前を変更できます。 保存ボタン（青丸）でNotebookをファイルとして保存できます。作成・保存したNotebookは、Notebook一覧表示画面で確認できます。 Notebookの名前に拡張子「.ipynb」が付いてファイル保存されるので、文字化けの可能性のある環境では注意してください。

Notebookのインポート・エクスポート

PC上にファイルとして持っている.ipynbファイルを、Notebook一覧表示画面のファイルリスト部分にドラッグアンドドロップすることで、 Notebookをインポートすることができます。

image.png

Notebook一覧表示画面で、エクスポートしたいNotebookのチェックボックスを付け（赤丸）、Notebookが使われている状態の場合は、実行中のセルがないか確認の上、「Shutdown」（青丸）で使用を中止し、

image.png

「Download」（赤丸）で、.ipynb形式でエクスポートできます。

基本操作

Pythonのコードを実行する

In [1]:
import math

for i in range(3) :
    print(math.sin(i))

0.0
0.8414709848078965
0.9092974268256817

セルに実行したいコードを書いて「Shift」＋「Enter」で実行できます。実行結果がセルの下に表示されます。

下のセルに「math.cos」と入力してから、「Shift」＋「Tab」を押してみてください。

In [2]:
math.cos(29)
Out[2]:
-0.7480575296890003

Docstringの参照が行えます。コードを書いている途中で調べたい場合に便利でしょう。
なお、「Shift」に続けて 「Tab」を2回押すと、より詳細な内容が表示されます。

下のセルに「math.t」まで入力してから「Tab」を押してみてください。

In [4]:
math.tan
Out[4]:
<function math.tan(x, /)>

コード補完が行えます。

Linuxコマンドを実行する

In [5]:
!ls

 000-README.ipynb
 101-VCノードの起動、削除.ipynb
 101-VCノードの起動、削除_manual.ipynb
 102-秘密情報管理サーバの利用.ipynb
 102-秘密情報管理サーバの利用_manual.ipynb
 103-Ansibleを利用したVCノードの操作.ipynb
'104-VCディスク（Amazon EBS）を利用したVCノードの起動、削除、再起動.ipynb'
 201-GPUインスタンスの利用-gpuオプション.ipynb
 201-GPUインスタンスの利用-gpuオプション_manual.ipynb
 301-AWSスポットインスタンスの利用.ipynb
 401-VCP演習.ipynb
 base
 images
 JupyterNotebook_Introduction_manual.ipynb
 old
 openpose
 scripts

「!」に続けてLinuxコマンドを書くと、そのコマンドが実行できます。

コマンドの終了コードを反転させる「!」を併せて使いたい場合は、「! ! cmd」と書くことができます。スペースの入れ方に注意してください。

マークダウンでドキュメントを書く

image.png

セルを選択した状態で、ツールバーのセルのタイプ（赤丸）を操作すると、セルのタイプを切り替えることができます。実行できる「Code」セルから、ドキュメントを書く「Markdown」セルに変更すると、そのセルにGitHubマークダウンの書式でドキュメントが書けるようになります。

下の「Code」セルを「Markdown」セルに変更して、実行（「Shift」＋「Enter」）してみてください。

引用
引用

多重引用

コードを書く場合は「```」で囲む

水平線を入れる

  • リスト1
    • リスト1_1
      • リスト1_1_1
      • リスト1_1_2
    • リスト1_2
  • リスト2
  • リスト3

マジックコマンドを使う

「%」で始まるマジックコマンドを使うことができます。有効なマジックコマンドの一覧は「%lsmagic」で確認できます。

In [6]:
%lsmagic
Out[6]:
Available line magics:
%alias  %alias_magic  %autoawait  %autocall  %automagic  %autosave  %bookmark  %cat  %cd  %clear  %colors  %conda  %config  %connect_info  %cp  %debug  %dhist  %dirs  %doctest_mode  %ed  %edit  %env  %gui  %hist  %history  %killbgscripts  %ldir  %less  %lf  %lk  %ll  %load  %load_ext  %loadpy  %logoff  %logon  %logstart  %logstate  %logstop  %ls  %lsmagic  %lx  %macro  %magic  %man  %matplotlib  %mkdir  %more  %mv  %notebook  %page  %pastebin  %pdb  %pdef  %pdoc  %pfile  %pinfo  %pinfo2  %pip  %popd  %pprint  %precision  %prun  %psearch  %psource  %pushd  %pwd  %pycat  %pylab  %qtconsole  %quickref  %recall  %rehashx  %reload_ext  %rep  %rerun  %reset  %reset_selective  %rm  %rmdir  %run  %save  %sc  %set_env  %store  %sx  %system  %tb  %time  %timeit  %unalias  %unload_ext  %who  %who_ls  %whos  %xdel  %xmode

Available cell magics:
%%!  %%HTML  %%SVG  %%bash  %%capture  %%debug  %%file  %%html  %%javascript  %%js  %%latex  %%markdown  %%perl  %%prun  %%pypy  %%python  %%python2  %%python3  %%ruby  %%script  %%sh  %%svg  %%sx  %%system  %%time  %%timeit  %%writefile

Automagic is ON, % prefix IS NOT needed for line magics.

例えば、lsコマンドでファイルの一覧を確認することができます。

In [7]:
%alias

Total number of aliases: 12
Out[7]:
[('cat', 'cat'),
 ('cp', 'cp'),
 ('ldir', 'ls -F -o --color %l | grep /$'),
 ('lf', 'ls -F -o --color %l | grep ^-'),
 ('lk', 'ls -F -o --color %l | grep ^l'),
 ('ll', 'ls -F -o --color'),
 ('ls', 'ls -F --color'),
 ('lx', 'ls -F -o --color %l | grep ^-..x'),
 ('mkdir', 'mkdir'),
 ('mv', 'mv'),
 ('rm', 'rm'),
 ('rmdir', 'rmdir')]

個々のコマンドについては、セルに入力してから「Shift」＋「Tab」で調べることができます。（Tabを2回続けると詳細情報）

目次の表示/非表示

image.png

ツールバーの目次ボタン（赤丸）を操作すると、目次の表示状態を切り替えることができます。目次が表示されていない方がセルの表示領域が広くなりますが、目次の見出しをクリックすることでジャンプすることができるので、適時、切り替えながら作業すると良いでしょう。

NII拡張について

NIIクラウド運用チームでは、JupyterNotebookを使った情報システムの構築・運用手法「Literate Computing for Reproducible Infrastructure(再構築可能なインフラのための文芸的コンピューティング、LC4RIと省略)」を提唱・実践しています。LC4RIでは、そのユースケースに合わせてJupyterNotebookを拡張して使っており、オンデマンド構築サービスで用いるJupyterNotebookにも採用されています。ここでは、NII拡張について、ハンズオンコンテンツやテンプレートの実行を行う上で知っておいた方が良いものを紹介します。

凍結

image.png

システム運用では同じ操作を複数回実施してはいけない場合が多くあります。そこで、実行したセルを誤って再実行しないように「凍結」するプラグインを開発し、使用しています。凍結されたセルを再実行したい場合には、そのセルを選択し、凍結解除を行うボタン（赤丸）を操作して、凍結を解除した後、実行が可能となります。

色による実行状態の表示

実行セルの左側に、セルの実行状態に応じて、色を付けています。

image.png

  • 青：実行中
  • 緑：実行成功
  • 赤：実行失敗

色は、Notebookをリロードしたり、一度Notebookを閉じて立ち上げなおすと消えます。

畳み込み表示とまとめ実行

image.png

見出しの左側にある△を操作することで表示を畳み込むことができます。畳み込み表示部の実行ボタン（赤丸）を押すことで、畳み込まれた範囲に含まれる実行セルを順番にまとめて実行することができます。畳み込み表示部の実行ボタンの下に並んだ□が、個々の実行セルを表しており、色や凍結マークで実行状態を表示するようになっています。

実行結果の保存

コードセルの過去の実行結果をピン止めして複数、タブ状に保存しておくことができます。通常の実行結果は、再実行により、上書きされて消えてしまいますが、この仕組みによって、過去の実行結果と今の実行結果を比較できます。「実行したら、こんな結果になるハズだよ」と、お手本として使うことができます。複数残すこともできるので、成功だけでなく、エラーの結果を得られた時にも残しておいて、「こうなったら成功だけど、こうなったら失敗しているよ。失敗の場合は……」と、マークダウンの説明と組み合わせて使うと効果的です。

  • 保存：「ピン」アイコンをクリックする度に、タブ状に保存されます
  • 比較：比較したいタブを選択して「互い違いの2本の矢印」アイコンをクリックすると、2つの結果のdiffが表示されます
In [8]:
!date

Tue 27 Sep 2022 11:08:11 PM JST

実行結果は Cell > Current Outputs > Clear もしくは Cell > All Output > Clear で消すことができます。
ただし、ピン止めしている実行結果は消えません。ピン止めしている実行結果は、タブごとに × を押して消してください。
また、フリーズしている場合は実行結果を消すことはできません。一度フリーズを解除してから消すようにしてください。

処理が実行される仕組み

カーネル

How IPython and Jupyter Notebook work

image.png

ユーザがブラウザを操作してJupyterNotebook（上の図ではNotebookServer）上でNotebookを開くと、セル内に書かれた処理を実行するための「カーネル」が生成され、ブラウザからセルの実行を指示すると、処理は全てカーネルに送られて実行され、その結果がブラウザに戻されます。カーネルは、標準として用意されているIPythonの他にも、さまざまな環境を使うことができます。

IPythonのカーネルは、Pythonの対話型環境ですので、生成されて以降に実行された変数や関数の定義を蓄積・更新していきます。「実行された」順で積み重なっていくので、Notebook上に書かれたセルの順序とは関係ありません。但し、その2つの順序が一致することも多いでしょう。

JupyterNotebookは、1つのNotebookに対しては、1つのカーネルしか生成しません。別々のPCのブラウザ上で同じNotebookを開いたとしても、全て同じカーネルを共有することになります。

異なるNotebookに対しては、異なるカーネルが生成されるので、Notebookをまたがって変数を共有することはできません。Notebookをまたがって変数を共有するためには、ファイル経由などの方法を考えなければなりません。

カーネルに関わる操作

Notebookを開くと、対応するカーネルが存在しない場合、そのNotebookに設定された種類のカーネルを自動的に生成し、セルの実行が可能な状態になりますが、明示的にカーネルを操作することもできます。

image.png

Interrupt

いわゆる「Ctrl」＋「C」です。時間のかかる処理を中断したい時などに、カーネルに対して、現在の処理実行を中断するようにリクエストします。

Restart

現在使用中のカーネルを破棄し、新しいカーネルを生成します。使っていたカーネルが保持していた変数や関数の定義は失われます。さまざまな操作によって、カーネル内の状態が把握できなくなって、イチからやり直したい場合に、使うことができます。Restart後に、続けて、セルに出力を全て消したり、先頭から全てのセルを実行（凍結済みのセルはスキップされることに注意）する操作も用意されています。

Reconnect

何らかの理由で、NotebookServerとカーネルの接続がおかしくなった場合に、明示的に再接続を指示できます。Reconnectで正常な状態に復帰できなかった場合は、Restartを使うことになるでしょう。

Shutdown

現在使用中のカーネルを停止します。Notebookのエクスポート手順にあったShutdownも同じ意味の操作です。使い終わったNotebookを再利用する可能性がある場合、大量のNotebookがあって大量のカーネルが生成される可能性がある場合は、使い終わったNotebookをShutdownする運用が良いでしょう。

image.png

Notebook一覧表示画面のRunningタブ（赤丸）で、サーバ上で実行中のプロセス一覧が表示できます。ここで、ShutdownしたいプロセスのShutdownボタン（青丸）を押して、Shutdownすることもできます。

ターミナルを使う（非推奨）

先に見たように、Notebookを使って作業を行うことで、セルでLinuxコマンドを実行でき、その結果を残しておけるので、ターミナルによるCLI操作を必要とすることは基本的にありません。むしろ、ターミナルでは、ドキュメントとして実行結果が残らないので、Notebookで作業する方が良いでしょう。

但し、パスワードなど、ドキュメントとして残ると困るものを扱うなど、例外的にターミナルが使いたい場合もあります。JupyterNotebookには、直接、ターミナルを使う機能もあります。

image.png

Notebook一覧表示画面を操作して、「New」－「Terminal」（赤丸）から、ターミナルを開くことができます。

image.png

ターミナルは、サーバ上でJupyterNotebookを実行しているユーザのシェルとして開きます。使い終わったら、exitで停止するか、先に紹介したNotebook一覧表示画面のRunningタブから停止させることができます。

その他

ファイルの移動やコピー

image.png

ファイル一覧の画面でファイルを選択し、まとめてコピーや移動ができます。
ただし、Runningの状態のNotebookを選択すると移動はできません。(Moveのボタンが表示されなくなります）。その場合は該当するNotebookをShutdownしてください。

ショートカット

image.png

Helpよりショートカットの一覧を確認できます（Keyboard Shortcuts）。また、自分用にショートカットをカスタマイズすることも可能です（Edit Keyboard Shortcuts）。
セルの状態には、入力モード（セルの左端のバーが緑色）とコマンドモード（セルの左端のバーが青色）があります。 入力モード、コマンドモードのそれぞれで使用できるショートカットが異なるので注意してください。

ツールバー

image.png

  1. Notebook の保存。File > Save and Checkpoint と同じ。File > Revert to Checkpoint で直前に保存した状態に戻せます。
  2. 現在のセルの下にセルを追加。コマンドモードで b を押す、Insert > Insert Cell Below と同じです。
  3. セルの カット（削除）。ただしフリーズした状態では削除できません。
  4. セルの コピー。
  5. セルのペースト。
  6. フォーカスがあたっているセルの上下移動。コマンドモードで 矢印の上下キーでも移動できます。
  7. セルを実行して、次のセルのフィーカスを移す。Shift + Enter と同じです。
  8. 実行中の処理を中断します。Kernel > Interrupt と同じです。
  9. カーネルを再起動します。Kernel > Restart と同じです。
  10. カーネルを再起動し、セルをすべて実行します。 Kernel > Restart & Run All と同じです。
  11. セルの種類を選択します。
    • Code コードを実行できます
    • Markdown Markdown形式で文章を入力できます
    • Raw NBConvert 入力したものがそのまま出力されます
  12. ショートカットの一覧を表示します。Help > Keyboard Shortcuts でも確認できます
  13. 選択中のセルを編集禁止にしたり、解除したりします。編集禁止にするとセルがクリーム色に色が付き、編集・削除ができなくなります。編集禁止でも実行はできます。
  14. 選択中のセルをフリーズさせます。編集・削除・実行ができなくなります。
  15. 選択中のセルのフリーズを解除します。
  16. 選択中のセル以降、そのセルがあるセクションの終わりまでをフリーズ解除します。
  17. 選択中のセル以降、Notebookの最後までのセルをすべてフリーズ解除します。
  18. 目次の表示/非表示を切り替えます。
  19. セルの実行結果をピン止めします。
  20. セルの実行結果のピン止めが複数ある場合に、最も新しいものを１つだけ残して残りを削除します。