開発コンテナ(Development Containers)の利用

このリポジトリでは開発コンテナ(Dev Container)をサポートしています。これを使うと、ローカルの環境を汚すことなく、RedAmberに必要なツール一式を含んだ環境を準備することができます。この環境には、Ruby、Apache Arrow、RedAmberのソースツリー、GitHub CI、サンプルデータセット、IRubyカーネルを含んだJupyter Labなどが含まれていて、簡単でメンテナンスしやすく、かつ再利用性が高い構成になっています。

RedAmber用のDev Containerは、.devcontainer ディレクトリに必要な設定が書かれています。現在の実装では、Dockerfileを使用せず、Dev Containers用のUbuntuベースイメージに、Dev Container Featuresを使って、Python、GitHub CIの環境を加えて作っています。Ruby は Container ができてから走らせるスクリプトでインストールしています。

Dockerfileで作るのと比べて、- User周りの設定を自動的にやってくれる- 言語環境をFeatureとして個別に追加することができる - PythonではJupyter Labをオプションとして追加できる - Rubyはrbenvをインストールしてあって後から別のバージョンを追加できる - Quartoを動かせる環境を簡単に追加でき、Jupyter notebookのソース管理に利用できる

等の利点があります。

ここでは代表的な利用法を2つ紹介します。

1. GitHub Codespacesでクラウド上のVMをブラウザから使う

必要なもの

GitHubアカウントにサインインしている必要があります。

注意

以下の手順では、Codespacesを起動するあなたのアカウントのクォータを消費します。GitHub Freeに対しては120時間/月・コア(2コアでは60時間)、ストレージ15GB/月が無料で使用できます。使用状況については Billing and plansのCodespacesの項を参照してください。

手順

GitHubのRedAmberのリポジトリを開いてください。
開発を行う場合は、フォークしてご自身のリポジトリを作り、それを開いてください。
リポジトリ内の「<>Code」ボタン、「Codespaces」タブにある、「Create codespace on main」ボタンを押して新しいCodespacesを作成してください。
既にCodespacesがある場合は、該当するコンテナ名をクリックすると再接続できます。
Codespacesの作成には時間がかかります。「View log」をクリックしてぼーっとログを眺めるか、コーヒーを淹れに行くとよいでしょう。
今後、GitHub Container Registoryにキャッシュを保存して、速く起動できるようにする予定です。
VS Code for ブラウザでリポジトリが開きます。

動作の確認は、下の動作の確認を参照してください。

詳細

より詳しくは、(GitHub Docs)リポジトリの codespace を作成するを参照してください。

2. ローカルにクローンしたリポジトリ―からDev Containerを立ち上げ、VS Codeで使う

必要なもの

Visual Studio Code (October 2020 Release 1.51以降)

GitHub Codespaces 拡張機能をインストールして、GitHub 資格情報を使用してサインインする必要があります。GitHub Docs - GitHub Codespaces - 前提条件を参照して設定を済ませておいてください。

Docker
Windows

Windows 10 Pro/Enterprise では Docker Desktop 2.0 以降。Windows 10 Home (2004+) では、Docker Desktop 2.3 以降と WSL 2 バックエンド。
Mac

Docker Desktop 2.0 以降
Linux

Docker CE/EE 18.06 以降と Docker Compose 1.21 以降
Git

手順

ローカルに RedAmberリポジトリのクローンを作成します。
開発を行う場合は、フォークしてご自身のリポジトリを作り、それをクローンしてください。

$ git clone https://github.com/red-data-toolsまたは貴方のアカウント名/red_amber.git または、GitHub CLIで、 $ gh repo clone red-data-toolsまたは貴方のアカウント名/red_amber とします。

作成したローカルのリポジトリフォルダーをVS Codeで開きます。 $ code red_amber
コンテナーで開く

今のフォルダーをコンテナーで再度開きます。

左下隅のステータスバーのリモートホスト表示（今はローカルなので「><」の後ろに何もついていない）をクリックするとリモートウィンドウを開くオプションが表示されるので、「コンテナーで再度開く」を選択します。
コンテナーの構築が開始されます

最初の構築には、数分かかることがあります。それ以降の構築は高速になります。構築が完了すると、左下隅のステータスバーのリモートホスト表示にコンテナー名が表示されます。

動作の確認

ターミナルでインストールされているツールを確認する

ターミナルが開いていない場合は、 CTRL + ` で開いてください。

下記のコマンドを実行して、ツールがインストール済みであることを確かめてください。

“‘shell $ ruby -v –jit $ rbenv versions $ gem -v $ gem list $ bundler -v $ iruby -v

$ python –version $ pip –version $ pip list $ pipenv –version $ jupyter –version $ jupyter kenelspec list

$ git -v $ git config user.name $ gh –version “‘

ユーザーは、vscode という名前で、uid/gid はローカルのユーザーと同じになっています。

shell $ id

RedAmberのテストを走らせてみる

shell $ bundle exec rake

REPLでRedAmberを試す

プリロードされたデータセットを使って、irbの環境でRedAmberの動作を確認できます。初回はRed Datasetsのデータをロードするため少し時間がかかります。

“‘ruby $ rake example

(snip)

  81: # Welcome to RedAmber example!
  82: # This environment will offer these pre-loaded datasets:
  83: #   penguins, diamonds, iris, starwars, simpsons_paradox_covid,
  84: #   mtcars, band_members, band_instruments, band_instruments2
  85: #   import_cars, comecome, rubykaigi, dataframe, subframes

=> 86: binding.irb

irb(main):001:0> “‘

irbの動作を途中で止めているので、ここで表示されているデータセットが変数に読み込まれています。

ruby irb(main):001:0> import_cars => #<RedAmber::DataFrame : 5 x 6 Vectors, 0x0000000000010914> Year Audi BMW BMW_MINI Mercedes-Benz VW <int64> <int64> <int64> <int64> <int64> <int64> 0 2017 28336 52527 25427 68221 49040 1 2018 26473 50982 25984 67554 51961 2 2019 24222 46814 23813 66553 46794 3 2020 22304 35712 20196 57041 36576 4 2021 22535 35905 18211 51722 35215

名前空間のRedAmber はインクルードされています。 ruby irb(main):002:0> VERSION => "0.5.0" irb(main):003:0> Arrow::VERSION => "12.0.1"

@を入力すると最初のブレークポイントに戻ることができます。

exit を入力するとirbを抜けます。

Jupyter LabでRedAmberを試す

Python と IRuby カーネルを持ったJupyter Labをブラウザで起動することができます。

shell $ rake jupyter

で、ローカルの8888ポートでブラウザが立ち上がります。

Notebookフォルダーとして、doc/notebook が割り当てられていて、そこには2つの.ipynbファイルがあります。
- red_amber.ipynb : README.md で紹介している操作例。
- examples_of_red_amber.ipynb : 様々な例を集めたもの。
require 'red_amber' は lib 以下のソースを読み込んでいます。

Quarto によるドキュメント操作

Quartoはオープンソースの科学技術ドキュメントの出版システムです。

この環境では、RedAmber の動作例を活用するために Quarto CLI を使っています。

---
title: Quartoを利用したドキュメント管理
---
flowchart LR
    id1["Source management
        (.qmd)"]
    id2["Analyze and edit by JupyterLab
        (.ipynb)"]
    id3["Publish document
        (.pdf)"]

    id1 -- convert --> id2 -- convert -->  id1
    id2 -- render --> id3
    id1 -- render --> id3

Quartoのドキュメント qmd 形式でソース管理できます。
.qmdファイルを Jupyter notebook ファイル(.ipynb)に変換して、 Jupyter Lab上で編集したりデータ解析ができます。
pdf形式に変換することができます。

Quarto の動作を確認する

Quarto のバージョンと動作環境をチェックするには次のようにします。

$ quarto -v
$ quarto check

ヘルプを表示するには下記のようにします。

$ quarto --help
$ quarto render --help

ソースからJupyter Notebookを生成する

.qmdソースファイルから .ipynb を生成するには、

$ bundle exec rake quarto:convert

とします。doc/qmdフォルダー以下にあるqmdソースファイルから doc/notebookフォルダーにipynbノートブックファイルが作成されます。

より一般的には、

$ quarto convert ソースファイル.qmd
$ quarto convert ソースファイル.qmd --output 出力先ノートブック.ipynb

上の書き方では、出力ファイルはソースファイルの拡張子を .ipynbに変えて、ソースファイルと同じディレクトリに保存されます。

下記のコマンドは、Notebookを作成後、Jupyter Labを開きます。

$ bundle exec rake jupyter

Jupyter Notebookファイルを`qmd`形式で保存する

編集したJupyter Notebookをqmd形式に変換できます。

$ quarto convert ノートブック.ipynb
$ quarto convert ノートブック.ipynb --output 出力先ソースファイル.qmd

その他の活用方法

下記のコマンドはdoc/qmdフォルダー以下にあるqmdソースファイルをipynbに変換し、実行してpdfを作成します。

$ bundle exec rake quarto:test

下記はdoc/notebookフォルダーを含めたrakeの生成物を消去します。

$ rake clean

Quartoについてより詳しくは、コマンドラインヘルプ(quarto --help)、またはQuarto公式ページをご覧ください。

謝辞

Quarto の利用は、西田孝三さんの2022年度のRubyアソシエーション開発助成事業プロジェクト『RubyDataエコシステムへのQuartoの導入とその利用の促進のためのコミュニティ活動』がきっかけとなりました。この場をお借りして感謝申し上げます。

開発コンテナ(Development Containers)の利用

1. GitHub Codespacesでクラウド上のVMをブラウザから使う

必要なもの

注意

手順

詳細

2. ローカルにクローンしたリポジトリ―からDev Containerを立ち上げ、VS Codeで使う

必要なもの

手順

動作の確認

ターミナルでインストールされているツールを確認する

RedAmberのテストを走らせてみる

REPLでRedAmberを試す

Jupyter LabでRedAmberを試す

Quarto によるドキュメント操作

Quarto の動作を確認する

ソースからJupyter Notebookを生成する

Jupyter Notebookファイルをqmd形式で保存する

その他の活用方法

謝辞

Jupyter Notebookファイルを`qmd`形式で保存する