red_amber 0.4.2 → 0.5.1

data/doc/Dev_Containers.ja.md

@@ -0,0 +1,290 @@
+# 開発コンテナ(Development Containers)の利用
+
+このリポジトリでは [開発コンテナ(Dev Container)](https://containers.dev/)をサポートしています。
+これを使うと、ローカルの環境を汚すことなく、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](https://github.com/settings/billing)のCodespacesの項を参照してください。
+
+### 手順
+- GitHubの[RedAmberのリポジトリ](https://github.com/red-data-tools/red_amber)を開いてください。
+  - 開発を行う場合は、フォークしてご自身のリポジトリを作り、それを開いてください。
+
+- リポジトリ内の「<>Code」ボタン、「Codespaces」タブにある、「Create codespace on main」ボタンを押して新しいCodespacesを作成してください。
+  * 既にCodespacesがある場合は、該当するコンテナ名をクリックすると再接続できます。
+- Codespacesの作成には時間がかかります。「View log」をクリックしてぼーっとログを眺めるか、コーヒーを淹れに行くとよいでしょう。
+  * 今後、GitHub Container Registoryにキャッシュを保存して、速く起動できるようにする予定です。
+- VS Code for ブラウザでリポジトリが開きます。
+
+  動作の確認は、下の[動作の確認](#動作の確認)を参照してください。
+
+### 詳細
+より詳しくは、[(GitHub Docs)リポジトリの codespace を作成する](https://docs.github.com/ja/codespaces/developing-in-codespaces/creating-a-codespace-for-a-repository)を参照してください。
+
+## 2. ローカルにクローンしたリポジトリ―からDev Containerを立ち上げ、VS Codeで使う
+
+### 必要なもの
+- Visual Studio Code (October 2020 Release 1.51以降)
+
+  GitHub Codespaces 拡張機能をインストールして、GitHub 資格情報を使用してサインインする必要があります。[GitHub Docs - GitHub Codespaces - 前提条件](https://docs.github.com/ja/codespaces/developing-in-codespaces/using-github-codespaces-in-visual-studio-code#prerequisites)を参照して設定を済ませておいてください。
+
+- 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](https://quarto.org/)はオープンソースの科学技術ドキュメントの出版システムです。
+
+この環境では、RedAmber の動作例を活用するために Quarto CLI を使っています。
+
+```mermaid
+---
+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 のバージョンと動作環境をチェックするには次のようにします。
+
+```shell
+$ quarto -v
+$ quarto check
+```
+
+ヘルプを表示するには下記のようにします。
+
+```shell
+$ quarto --help
+$ quarto render --help
+```
+
+### ソースからJupyter Notebookを生成する
+`.qmd`ソースファイルから `.ipynb` を生成するには、
+
+```shell
+$ bundle exec rake quarto:convert
+```
+とします。`doc/qmd`フォルダー以下にあるqmdソースファイルから `doc/notebook`フォルダーに`ipynb`ノートブックファイルが作成されます。
+
+より一般的には、
+
+```shell
+$ quarto convert ソースファイル.qmd
+$ quarto convert ソースファイル.qmd --output 出力先ノートブック.ipynb
+```
+上の書き方では、出力ファイルはソースファイルの拡張子を `.ipynb`に変えて、ソースファイルと同じディレクトリに保存されます。
+
+下記のコマンドは、Notebookを作成後、Jupyter Labを開きます。
+
+```shell
+$ bundle exec rake jupyter
+```
+
+### Jupyter Notebookファイルを`qmd`形式で保存する
+
+編集したJupyter Notebookをqmd形式に変換できます。
+
+```shell
+$ quarto convert ノートブック.ipynb
+$ quarto convert ノートブック.ipynb --output 出力先ソースファイル.qmd
+```
+
+### その他の活用方法
+
+下記のコマンドは`doc/qmd`フォルダー以下にあるqmdソースファイルを`ipynb`に変換し、実行してpdfを作成します。
+
+```shell
+$ bundle exec rake quarto:test
+```
+
+下記は`doc/notebook`フォルダーを含めたrakeの生成物を消去します。
+
+```shell
+$ rake clean
+```
+
+Quartoについてより詳しくは、コマンドラインヘルプ(`quarto --help`)、または[Quarto](https://quarto.org/)公式ページをご覧ください。
+
+### 謝辞
+
+Quarto の利用は、西田孝三さんの2022年度のRubyアソシエーション開発助成事業プロジェクト『RubyDataエコシステムへのQuartoの導入とその利用の促進のためのコミュニティ活動』 がきっかけとなりました。この場をお借りして感謝申し上げます。

data/doc/Dev_Containers.md

@@ -0,0 +1,292 @@
+# How to use Development Containers in RedAmber
+
+We support [Development Container](https://containers.dev/) in this repository.
+You can prepare a container as a full-featured development environment for RedAmber. Dev Containers allow you to encapsulate Ruby, Apache Arrow, RedAmber with source tree, GitHub CLI, sample datasets and Jupyter Lab with IRuby kernel. You don't need to worry about the change of your local environment.
+
+`.devcontainer` directory in this repository includes settings of Dev Container for RedAmber. We don't use Dockerfile here, based on Ubuntu image for Dev Container, Python and GitHub CLI tools using Dev Container Features. I think this style has simplicity, maintainability, and reusability. Ruby is added after the container is created by script.
+
+It has some benefits below compared to make dev environment by Dockerfile;
+
+1) It automatically makes user setting with same UID/GID as local user.
+2) Additional tools can be introduced by `Dev Container Features`.
+3) Ruby Feature includes `rbenv` and it is easy to add another version afterwards.
+4) Python Feature includes Jupyter Lab as an option.
+5) Quarto is introduced. It converts Jupyter notebook from/to qmd file and it is useful to manage notebook in the source tree.
+
+We will show 2 examples here.
+
+## 1. GitHub Codespace in cloud from browser
+
+### Prerequisite
+
+You need to sign in GitHub Account.
+
+### Notice
+
+You will consume your Codespace quota of your account in the step below. For GitHub Free, you can use 120 hours per month per core (it means 60 hours per month for 2 cores VM) and have a storage with 15 GB per month for free. You can check your usage from `Codespaces` section in [Billing and plans](https://github.com/settings/billing).
+
+### Procedures
+- Open the [repository of RedAmber](https://github.com/red-data-tools/red_amber) in GitHub.
+  - If you are going to develop RedAmber, you should fork it and open your forked repository to push PR later.
+
+- Push `<>Code` button, select `Codespaces` tab, push `Create codespace on main` button to create new Codespace.
+  * You can re-connect existing Codespace if you already have there.
+- Creating Codespace takes time. You can click `View log` to browse log running or have a coffee to wait.
+  * I am planning to improve building process to save cache in GitHub Container Registory.
+
+- VS Code for browser will open the repository in the remote container.
+
+  Please refer [Operations](#operations) to use the environment.
+
+### Details
+Please see [(GitHub Docs)Creating a codespace for a repository](https://docs.github.com/en/codespaces/developing-in-codespaces/creating-a-codespace-for-a-repository) for detail.
+
+## 2. Start Dev Container from the local repository, and use it from VS Code
+
+### Prerequisites
+- Visual Studio Code (October 2020 Release 1.51+)
+
+  You need to install GitHub Codespaces extention, and sign into GitHub Codespaces  with your GitHub credentials. Please see [GitHub Docs - GitHub Codespaces - Prerequisites](https://docs.github.com/en/codespaces/developing-in-codespaces/using-github-codespaces-in-visual-studio-code#prerequisites) and prepare settings.
+
+- Docker
+  - Windows
+
+    In Windows 10 Pro/Enterprise, Docker Desktop 2.0+
+    In Windows 10 Home (2004+), Docker Desktop 2.3+ and WSL 2 backend.
+
+  - Mac
+
+    Docker Desktop 2.0+
+
+  - Linux
+
+    Docker CE/EE 18.06+ and Docker Compose 1.21+
+
+- Git
+
+### Procedures
+
+- Create a local clone of RedAmber repository.
+
+  - If you are going to develop RedAmber, make a fork and clone it.
+
+  ```
+  $ git clone https://github.com/(red-data-tools or your account name)/red_amber.git
+  ```
+
+  Alternatively using GitHub CLI,
+
+  ```
+  $ gh repo clone (red-data-tools or your account name)/red_amber
+  ```
+
+- Open local repo folder by VS Code.
+
+  ```
+  $ code red_amber
+  ```
+
+- Re-open by container
+
+  Re-open current folder by container.
+
+  - Click remote host indicator in the left bottom corner, then options to open remote windows will open. Choose 'reopen by container'.
+
+- Building of container will start.
+
+  It takes time for first building. If it is finished, container name will be displayed on the remote host indicator.
+
+## Operations
+
+### Check installed tools by terminal
+
+  If you don't have the terminal open, open it with ``CTRL + ` ``.
+
+  Run these command to check these tools are installed.
+
+  ```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
+  ```
+
+  The user name is `vscode` in this environment. `uid` and `gid` are the same as local user.
+
+  ```shell
+  $ id
+  ```
+
+### Run tests of RedAmber
+
+  ```shell
+  $ bundle exec rake
+  ```
+
+### Try RedAmber in REPL
+
+  You can try RedAmber in `irb` using pre loaded datasets. It takes time in the first run to load the datasets from 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>
+  ```
+
+  This code stops in the code by `binding.irb`, you have some datasets in local variables.
+
+  ```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
+  ```
+
+  The namespace `RedAmber` is included.
+
+  ```ruby
+  irb(main):002:0> VERSION
+  => "0.5.0"
+  irb(main):003:0> Arrow::VERSION
+  => "12.0.1"
+  ```
+
+  You can return to the first breakinng point by hitting `@`.
+
+  You can exit irb by `exit`.
+
+### Try RedAmber in Jupyter Lab
+
+  You can try Jupyter Lab with Python and IRuby kernels in your browser.
+
+  ```shell
+  $ rake jupyter
+  ```
+
+  - `doc/notebook` is allocated as notebook folder. There are 2 files in it.
+    - `red_amber.ipynb` : Examples in `README.md`.
+    - `examples_of_red_amber.ipynb` : Hundreds examples of RedAmber.
+  - `require 'red_amber'` will load from source directory `lib`.
+
+## Document authoring by Quarto
+
+[Quarto](https://quarto.org/) is an open-source scientific and technical publishing system.
+We use Quarto CLI to show usage examples of RedAmber.
+
+```mermaid
+---
+title: Document management with 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
+```
+
+* We can manage the source of the Jupyter notebook by Quarto's markdown format `qmd`.
+* We can convert a `.qmd` file to a Jupyter notebook file (`.ipynb`) and will be able to edit it or make analysis on Jupyter Lab.
+* We can render `.qmd` or `.ipynb` files to `.pdf`.
+
+### To show the information of Quarto
+
+Try below to show version and verify correct functioning of Quarto installation.
+
+```shell
+$ quarto -v
+$ quarto check
+```
+
+To show help,
+
+```shell
+$ quarto --help
+$ quarto render --help
+```
+
+### Convert qmd file to Jupyter Notebook
+
+To convert `.qmd` source file to `.ipynb`,
+
+```shell
+$ bundle exec rake quarto:convert
+```
+
+This command will create `ipynb` notebooks from `doc/qmd` and save them to `doc/notebook`.
+
+In more general,
+
+```shell
+$ quarto convert source_file.qmd
+$ quarto convert source_file.qmd --output Notebook.ipynb
+```
+
+The first one will output `source_file.ipynb` file in the same directory.
+
+Command below will convert qmd_document files in `doc/qmd` to `.ipynb` files and save them to `doc/notebook` . Then open `doc/notebook` with Jupyter Lab.
+
+```shell
+$ bin/jupyter
+```
+
+### Convert Jupyter Notebook to `qmd`
+
+You can convert Notebook file to qmd file.
+
+```shell
+$ quarto convert notebook.ipynb
+$ quarto convert notebook.ipynb --output output_source_file.qmd
+```
+
+### Others
+
+To render Notebook files in `doc/qmd` to pdf,
+
+```shell
+$ bundle exec rake quarto:test
+```
+To clear `doc/notebook` (and all the generated artifacts by rake),
+
+```shell
+$ rake clean
+```
+
+To know more about Quarto, see command line help by `quarto --help`, or visit [Quarto](https://quarto.org/) web.
+
+### Thanks
+
+ As for the use of Quarto, I started to try after the Kozo Nishida's work with Ruby Association Grant 2022 "Introducing Quarto into the RubyData ecosystem and promoting the combination to the Ruby community". I would like to take this opportunity to thank him.