red_amber 0.4.1 → 0.5.0

data/docker/notebook/red-amber.ipynb

@@ -0,0 +1,188 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# RedAmber Examples\n",
+    "\n",
+    "This notebook walks through the [README of RedAmber](https://github.com/heronshoes/red_amber#readme)."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## `RedAmber::DataFrame`"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "tags": []
+   },
+   "outputs": [],
+   "source": [
+    "require 'red_amber'\n",
+    "include RedAmber\n",
+    "require 'datasets-arrow'\n",
+    "\n",
+    "{RedAmber: VERSION, Datasets: Datasets::VERSION}"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Example: diamonds dataset\n",
+    "\n",
+    "For the first loading of Datasets::Diamonds, it will take some time to download."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "tags": []
+   },
+   "outputs": [],
+   "source": [
+    "dataset = Datasets::Diamonds.new\n",
+    "diamonds = DataFrame.new(dataset)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "tags": []
+   },
+   "outputs": [],
+   "source": [
+    "df = diamonds\n",
+    "  .slice { carat > 1 } # or use #filter instead of #slice\n",
+    "  .group(:cut)\n",
+    "  .mean(:price) # `pick` prior to `group` is not required if `:price` is specified here.\n",
+    "  .sort('-mean(price)')"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "tags": []
+   },
+   "outputs": [],
+   "source": [
+    "usdjpy = 110.0 # when the yen was stronger\n",
+    "\n",
+    "df.rename('mean(price)': :mean_price_USD)\n",
+    "  .assign(:mean_price_JPY) { mean_price_USD * usdjpy }"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "tags": []
+   },
+   "source": [
+    "## Example: starwars dataset"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "tags": []
+   },
+   "outputs": [],
+   "source": [
+    "uri = URI('https://vincentarelbundock.github.io/Rdatasets/csv/dplyr/starwars.csv')\n",
+    "\n",
+    "starwars = DataFrame.load(uri)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "tags": []
+   },
+   "outputs": [],
+   "source": [
+    "starwars\n",
+    "  .drop(0) # delete unnecessary index column\n",
+    "  .remove { species == \"NA\" } # delete unnecessary rows\n",
+    "  .group(:species) { [count(:species), mean(:height, :mass)] }\n",
+    "  .slice { count > 1 } # or use #filter instead of slice"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## `RedAmber::Vector`"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "tags": []
+   },
+   "outputs": [],
+   "source": [
+    "penguins = DataFrame.new(Datasets::Penguins.new)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "tags": []
+   },
+   "outputs": [],
+   "source": [
+    "penguins[:bill_length_mm]"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "tags": []
+   },
+   "outputs": [],
+   "source": [
+    "penguins[:bill_length_mm] < 40"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "tags": []
+   },
+   "outputs": [],
+   "source": [
+    "penguins[:bill_length_mm].mean"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Ruby 3.0.2",
+   "language": "ruby",
+   "name": "ruby"
+  },
+  "language_info": {
+   "file_extension": ".rb",
+   "mimetype": "application/x-ruby",
+   "name": "ruby",
+   "version": "3.0.2"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}

data/docker/readme.md

@@ -0,0 +1,118 @@
+# RedAmber Minimal Notebook
+
+This is a docker image containing RedAmber created from 
+[jupyter/minimal-notebook](https://jupyter-docker-stacks.readthedocs.io/en/latest/using/selecting.html#jupyter-minimal-notebook)
+
+## Contents
+
+- From jupyter/minimal-notebook:
+  - Based on 2023-03-13 (295612d3ade4)
+  - x86-64
+  - Ubuntu-22.04
+  - python-3.10.9
+  - lab-3.6.1
+  - notebook-6.5.3
+- System ruby-dev:
+  - Ruby 3.0.2
+- Arrow 11.0.0 for Ubuntu:
+  - libarrow-dev
+  - libarrow-glib-dev
+  - libparquet-dev
+  - libparquet-glib-dev
+- Locally installed iruby:
+  - Using Ruby 3.0.2
+- Locally installed bundler and Gemfile:
+  - RedAmber 0.4.1
+  - Others (see Gemfile)
+
+## Install
+
+```
+git clone https://github.com/heronshoes/red_amber.git
+cd  docker
+```
+
+Edit ENV variable in `.env` as you like.
+
+[note] NB_USER is fixed for `jovyan`, the common user name in Jupyter,
+can not change it in this version.
+
+If TZ is not used in your host system, define it here.
+Otherwise UTC is used in the container.
+
+TOKEN will be used for token-based authentication.
+
+```
+# Example
+TZ=Asia/Tokyo
+TOKEN='something'
+```
+
+Then build `red_amber-minimal-notebook` container. It will take a while.
+
+```
+docker-compose build
+```
+
+## Start Jupyter Lab
+
+After build, start the container. Adding `-d` option will detach it in background.
+
+```
+docker-compose up
+```
+
+You can access Jupyter Lab from `http://localhost:8888/` in your browser.
+
+- `red-amber.ipynb`:
+  - Walks through the [README of RedAmber](https://github.com/heronshoes/red_amber#readme).
+- `examples_of_red_amber.ipynb`:
+  - [Examples of RedAmber](https://github.com/heronshoes/red_amber/blob/main/docker/notebook/examples_of_red_amber.ipynb) in Notebook style.
+
+## Example in REPL
+
+You can try RedAmber in irb with pre-loaded datasets.
+
+Start `terminal` in Jupyter.
+
+For the first run,
+
+```
+source ~/.bashrc
+../example
+
+```
+
+It will take a while for the first run to fetch and prepare red-datasets cache.
+
+If irb starts you can see:
+
+```ruby
+
+    69: # Welcome to RedAmber example!
+    70: # This environment will offer these pre-loaded datasets:
+    71: #   penguins, diamonds, iris, starwars, simpsons_paradox_covid,
+    72: #   mtcars, band_members, band_instruments, band_instruments2
+    73: #   (original) import_cars, comecome, dataframe, subframes
+ => 74: binding.irb
+
+irb(main):001:0> 
+```
+
+RedAmber is already loaded in this environment with some datasets shown above.
+
+```ruby
+irb(main):002:0> dataframe
+=> 
+#<RedAmber::DataFrame : 6 x 3 Vectors, 0x0000000000003818>
+        x y        z
+  <uint8> <string> <boolean>
+0       1 A        false
+1       2 A        true
+2       3 B        false
+3       4 B        (nil)
+4       5 B        true
+5       6 C        false
+```
+
+Next time you start this environment, you can simply invoke as `../example`.

data/lib/red_amber/data_frame.rb

@@ -422,12 +422,12 @@ module RedAmber
     # Create SubFrames by value grouping.
     #
     # [Experimental feature] this method may be removed or be changed in the future.
-    # @param keys [Symbol, String, Array<Symbol, String>]
+    # @param keys [List<Symbol, String>, Array<Symbol, String>]
     #   grouping keys.
     # @return [SubFrames]
     #   a created SubFrames grouped by column values on `keys`.
     # @example
-    #   df.sub_by_value(keys: :y)
+    #   df.sub_by_value(:y)
     #
     #   # =>
     #   #<RedAmber::SubFrames : 0x000000000000fc08>
@@ -454,10 +454,11 @@ module RedAmber
     #
     # @since 0.4.0
     #
-    def sub_by_value(keys: nil)
-      SubFrames.new(self, group(keys).filters)
+    def sub_by_value(*keys)
+      SubFrames.new(self, group(keys.flatten).filters)
     end
     alias_method :subframes_by_value, :sub_by_value
+    alias_method :sub_group, :sub_by_value
 
     # Create SubFrames by Windowing with `from`, `size` and `step`.
     #
@@ -697,6 +698,79 @@ module RedAmber
       end
     end
 
+    # Returns a Vector such that all elements have value `scalar`
+    #   and have same size as self.
+    #
+    # @overload propagate(scalar)
+    #   Specifies scalar as an agrument.
+    #
+    #   @param scalar [scalar]
+    #     a value to propagate in Vector.
+    #   @return [Vector]
+    #     created Vector.
+    #   @example propagate a value
+    #     df
+    #     # =>
+    #     #<RedAmber::DataFrame : 6 x 3 Vectors, 0x00000000000849a4>
+    #             x y        z
+    #       <uint8> <string> <boolean>
+    #     0       1 A        false
+    #     1       2 A        true
+    #     2       3 B        false
+    #     3       4 B        (nil)
+    #     4       5 B        true
+    #     5       6 C        false
+    #
+    #     df.assign(:sum_x) { propagate(x.sum) }
+    #     # =>
+    #     #<RedAmber::DataFrame : 6 x 4 Vectors, 0x000000000007bd04>
+    #             x y        z           sum_x
+    #       <uint8> <string> <boolean> <uint8>
+    #     0       1 A        false          21
+    #     1       2 A        true           21
+    #     2       3 B        false          21
+    #     3       4 B        (nil)          21
+    #     4       5 B        true           21
+    #     5       6 C        false          21
+    #
+    #     # Using `Vector#propagate` like below has same result as above.
+    #     df.assign(:sum_x) { x.propagate(:sum) }
+    #
+    #     # Also it is same as creating column from an Array.
+    #     df.assign(:sum_x) { [x.sum] * size }
+    #
+    # @overload propagate
+    #
+    #   @yieldparam self [DataFrame]
+    #     gives self to the block.
+    #   @yieldreturn [scalar]
+    #     a value to propagate in Vector
+    #   @return [Vector]
+    #     created Vector.
+    #   @example propagate the value from the block
+    #     df.assign(:range) { propagate { x.max - x.min } }
+    #     # =>
+    #     #<RedAmber::DataFrame : 6 x 4 Vectors, 0x00000000000e603c>
+    #             x y        z           range
+    #       <uint8> <string> <boolean> <uint8>
+    #     0       1 A        false           5
+    #     1       2 A        true            5
+    #     2       3 B        false           5
+    #     3       4 B        (nil)           5
+    #     4       5 B        true            5
+    #     5       6 C        false           5
+    #
+    # @since 0.5.0
+    #
+    def propagate(scalar = nil, &block)
+      if block
+        raise VectorArgumentError, "can't specify both function and block" if scalar
+
+        scalar = instance_eval(&block)
+      end
+      Vector.new([scalar] * size)
+    end
+
     # Catch variable (column) key as method name.
     def method_missing(name, *args, &block)
       return variables[name] if args.empty? && key?(name)