red_amber 0.5.0 → 0.5.1

data/README.md

@@ -4,10 +4,10 @@
 [![CI](https://github.com/heronshoes/red_amber/actions/workflows/ci.yml/badge.svg)](https://github.com/red-data-tools/red_amber/actions/workflows/ci.yml)
 [![Maintainability](https://api.codeclimate.com/v1/badges/b8a745047045d2f49daa/maintainability)](https://codeclimate.com/github/heronshoes/red_amber/maintainability)
 [![Test coverage](https://api.codeclimate.com/v1/badges/b8a745047045d2f49daa/test_coverage)](https://codeclimate.com/github/heronshoes/red_amber/test_coverage)
-[![Doc](https://img.shields.io/badge/docs-latest-blue)](https://heronshoes.github.io/red_amber/)
+[![Doc](https://img.shields.io/badge/docs-latest-blue)](https://red-data-tools.github.io/red_amber/)
 [![Discussions](https://img.shields.io/github/discussions/heronshoes/red_amber)](https://github.com/red-data-tools/red_amber/discussions)
 
-A simple dataframe library for Ruby.
+A dataframe library for Rubyists.
 
 - Powered by [Red Arrow](https://github.com/apache/arrow/tree/master/ruby/red-arrow)
 [![Red Data Tools Chat (en)](https://badges.gitter.im/red-data-tools/en.svg)](https://app.element.io/#/room/#red-data-tools_en:gitter.im) [![Gem Version](https://img.shields.io/gem/v/red-arrow?color=brightgreen)](https://rubygems.org/gems/red-arrow)
@@ -17,18 +17,25 @@ A simple dataframe library for Ruby.
 
 ![screenshot from jupyterlab](https://raw.githubusercontent.com/red-data-tools/red_amber/main/doc/image/screenshot.png)
 
+## Overview
+* RedAmber is a dataframe library written in ruby. It uses columnar memory format based on [Apache Arrow](https://arrow.apache.org/).
+* Our goal is to manipulate data frames in a Ruby-like writing style using blocks and collections.
+* You can easily try RedAmber with [Dev Container](https://containers.dev/). See [RedAmber Dev Container](doc/Dev_Containers.md).
+* We have [rich document with many examples](https://red-data-tools.github.io/red_amber/) and Jupyter Notebook with 127 operation examples. See [RedAmber Dev Container](doc/Dev_Containers.md).
+
 ## Requirements
 ### Ruby
-Supported Ruby version is >= 3.0 (since RedAmber 0.3.0).
+Supported Ruby version is >= 3.0.
 
 ### Required libraries
 ```ruby
-gem 'red-arrow',   '~> 12.0.0' # Requires Apache Arrow (see installation below)
-gem 'red-parquet', '~> 12.0.0' # Optional, if you use IO from/to parquet
-gem 'red-datasets-arrow'       # Optional, if you use Red Datasets or random sampling feature
-gem 'red-arrow-numo-narray'    # Optional, recommended if you use inputs from Numo::NArray
-gem 'red-arrow-activerecord'   # Optional, if you use Active Record
-gem 'rover-df',    '~> 0.3.0'  # Optional, if you use IO from/to Rover::DataFrame
+gem 'red-arrow',   '~> 12.0.0' # Requires Apache Arrow (see installation below).
+gem 'red-arrow-numo-narray'    # Optional, recommended if you use inputs from Numo::NArray,
+                               # or use random sampling feature.
+gem 'red-parquet', '~> 12.0.0' # Optional, if you use IO from/to parquet.
+gem 'red-datasets-arrow'       # Optional, if you use Red Datasets.
+gem 'red-arrow-activerecord'   # Optional, if you use Active Record.
+gem 'rover-df',                # Optional, if you use IO from/to Rover::DataFrame.
 ```
 
 ## Installation
@@ -40,7 +47,7 @@ Install requirements before you install RedAmber.
 - Apache Parquet GLib (~> 12.0.0)  # If you use IO from/to parquet
 
 See [Apache Arrow install document](https://arrow.apache.org/install/).
-  
+
   - Minimum installation example for the latest Ubuntu:
 
       ```
@@ -49,8 +56,7 @@ See [Apache Arrow install document](https://arrow.apache.org/install/).
       wget https://apache.jfrog.io/artifactory/arrow/$(lsb_release --id --short | tr 'A-Z' 'a-z')/apache-arrow-apt-source-latest-$(lsb_release --codename --short).deb
       sudo apt install -y -V ./apache-arrow-apt-source-latest-$(lsb_release --codename --short).deb
       sudo apt update
-      sudo apt install -y -V libarrow-dev
-      sudo apt install -y -V libarrow-glib-dev
+      sudo apt install -y -V libarrow-dev libarrow-glib-dev
       ```
 
   - On Fedora 39 (Rawhide):
@@ -63,8 +69,7 @@ See [Apache Arrow install document](https://arrow.apache.org/install/).
   - On macOS, using Homebrew:
 
       ```
-      brew install apache-arrow
-      brew install apache-arrow-glib
+      brew install apache-arrow apache-arrow-glib
       ```
 
 If you prepared Apache Arrow, add these lines to your Gemfile:
@@ -72,27 +77,37 @@ If you prepared Apache Arrow, add these lines to your Gemfile:
 ```ruby
 gem 'red-arrow',   '~> 12.0.0'
 gem 'red_amber'
+gem 'red-arrow-numo-narray'    # Optional, recommended if you use inputs from Numo::NArray
+                               # or use random sampling feature.
 gem 'red-parquet', '~> 12.0.0' # Optional, if you use IO from/to parquet
 gem 'red-datasets-arrow'       # Optional, recommended if you use Red Datasets
-gem 'red-arrow-numo-narray'    # Optional, recommended if you use inputs from Numo::NArray
 gem 'red-arrow-activerecord'   # Optional, if you use Active Record
-gem 'rover-df',    '~> 0.3.0'  # Optional, if you use IO from/to Rover::DataFrame
+gem 'rover-df',                # Optional, if you use IO from/to Rover::DataFrame.
 ```
 
 And then execute `bundle install` or install them yourself such as `gem install red_amber`.
 
+## Development Containers
+
+This repository supports [Dev Containers](https://containers.dev/). You can create a container as a full-featured development environment for RedAmber. The environment includes Ruby, Apache Arrow, RedAmber with source tree, GitHub CLI, sample datasets and Jupyter Lab with IRuby kernel. And 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.
+Please refer [How to use Dev Containers in RedAmber](doc/Dev_Containers.md) to use it.
+
 ## Docker image and Jupyter Notebook
 
+(Notice: This feature may be removed in the future. Try Dev Container above.)
+
 Docker image is available from `docker` folder. See [readme](docker/readme.md) for instruction. Integrated Jypyter notebook is in docker/notebook folder.
 
-You can try the contents of this README interactively by [Binder](https://mybinder.org/v2/gh/heronshoes/docker-stacks/RedAmber-binder?filepath=red-amber.ipynb). 
+You can try the contents of this README interactively by [Binder](https://mybinder.org/v2/gh/heronshoes/docker-stacks/RedAmber-binder?filepath=red-amber.ipynb).
 [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/heronshoes/docker-stacks/RedAmber-binder?filepath=red-amber.ipynb)
 
 [RubyData Docker Stacks](https://github.com/RubyData/docker-stacks) is available as a ready-to-run Docker image containing Jupyter and useful data tools as well as RedAmber (Thanks to Kenta Murata).
 
 ## Comparison of DataFrames
 
-Comparison of  basic features of RedAmber with Python 
+Comparison of  basic features of RedAmber with Python
 [pandas](https://pandas.pydata.org/),
 R [Tidyverse](https://www.tidyverse.org/) and
 Julia [Dataframes](https://dataframes.juliadata.org/stable/) is in [DataFrame_Comparison.md](doc/DataFrame_Comparison.md) (Thanks to Benson Muite).
@@ -100,7 +115,7 @@ Julia [Dataframes](https://dataframes.juliadata.org/stable/) is in [DataFrame_Co
 ## Data frame in `RedAmber`
 
 Class `RedAmber::DataFrame` represents a set of data in 2D-shape.
-Its entity is a Red Arrow's Table object. 
+Its entity is a Red Arrow's Table object.
 
 ![dataframe model of RedAmber](https://raw.githubusercontent.com/red-data-tools/red_amber/main/doc/image/dataframe_model.png)
 
@@ -219,14 +234,13 @@ See [Vector.md](doc/Vector.md) for details.
 
 ## Jupyter notebook
 
-[Examples of Red Amber](https://github.com/heronshoes/docker-stacks/blob/RedAmber-binder/binder/examples_of_red_amber.ipynb)
-([raw file](https://raw.githubusercontent.com/heronshoes/docker-stacks/RedAmber-binder/binder/examples_of_red_amber.ipynb)) shows more examples in jupyter notebook.
+We are managing the source of Jupyter Notebook in qmd format by Quarto. You can easily create Notebooks and try it with Jupyter Lab in [Dev Container](doc/Dev_Containers.md).
 
-You can try this notebook on [Binder](https://mybinder.org/v2/gh/heronshoes/docker-stacks/RedAmber-binder?filepath=examples_of_red_amber.ipynb). 
-[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/heronshoes/docker-stacks/RedAmber-binder?filepath=examples_of_red_amber.ipynb)
+## Development
 
+The recommended way to develop RedAmber is to use Dev Container. Please refer [How to use Dev Containers in RedAmber](doc/Dev_Containers.md) to use it.
 
-## Development
+Otherwise run below commands after install required libraries in your local system.
 
 ```shell
 git clone https://github.com/red-data-tools/red_amber.git
@@ -235,6 +249,8 @@ bundle install
 bundle exec rake test
 ```
 
+We need to pass `rake test` in development of RedAmber, but not require to pass `rake rubocop` when you make a contribution. In this project we respect your preferences in code style. However, we may unify the style during merging.
+
 ## Community
 
 I will appreciate if you could help to improve this project. Here are a few ways you can help:

data/Rakefile

@@ -2,6 +2,7 @@
 
 require 'bundler/gem_tasks'
 require 'rake/testtask'
+require 'rake/clean'
 
 Rake::TestTask.new(:test) do |t|
   t.libs << 'test'
@@ -15,3 +16,57 @@ require 'rubocop/rake_task'
 RuboCop::RakeTask.new
 
 task default: %i[test rubocop]
+
+def install_gems_for_examples
+  sh 'cd bin; bundle install; cd -'
+end
+
+# Example
+desc 'Start example environment'
+task :example do
+  install_gems_for_examples
+  sh 'bundle exec --gemfile=bin/Gemfile bin/example'
+end
+
+# Quarto
+namespace :quarto do
+  qmd_dir = 'doc/qmd'
+  notebook_dir = 'doc/notebook'
+
+  directory notebook_dir
+
+  qmd_files = FileList["#{qmd_dir}/*.qmd"]
+  qmd_files.exclude('~*.qmd')
+  notebooks = qmd_files.pathmap('%{qmd,notebook}p').ext('.ipynb')
+
+  qmd_files.zip(notebooks).each do |qmd, notebook|
+    file notebook => notebook_dir
+    file notebook => qmd do
+      sh "quarto convert #{qmd} -o #{notebook}"
+    end
+  end
+
+  desc 'Convert qmd to ipynb files'
+  task convert: notebooks
+  file notebooks => notebook_dir
+
+  desc 'test to execute notebooks'
+  task test: notebooks do
+    install_gems_for_examples
+    notebooks.each do |notebook|
+      quarto_options = '--execute-daemon-restart --execute'
+      sh "bundle exec --gemfile=bin/Gemfile quarto render #{notebook} #{quarto_options}"
+    end
+  end
+end
+
+desc 'Start jupyter lab'
+task jupyter: 'quarto:convert' do
+  install_gems_for_examples
+
+  jupyter_options =
+    "--notebook-dir='doc/notebook' --NotebookApp.token=''"
+  sh "bundle exec --gemfile=bin/Gemfile jupyter lab #{jupyter_options}"
+end
+
+CLEAN << 'doc/notebook'

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の導入とその利用の促進のためのコミュニティ活動』 がきっかけとなりました。この場をお借りして感謝申し上げます。