v0.2.8

* How to show sub-coomand help

README.md

@@ -9,15 +9,15 @@ Create ASCII charts on the terminal with data from standard streams in the pipel
 
 :bar_chart: Powered by [UnicodePlot](https://github.com/red-data-tools/unicode_plot.rb)
 
-:construction: Under development! :construction:
-
 ## Installation
 
 ```
 gem install u-plot
 ```
 
-## Usage
+Note: The name of the Gem is `u-plot` (not uplot).
+
+## Screenshots
 
 **histogram**
 
@@ -26,22 +26,125 @@ ruby -r numo/narray -e "puts Numo::DFloat.new(1000).rand_norm.to_a" \
   | uplot hist --nbins 15
 ```
 
-<img src="https://i.imgur.com/wpsoGJq.png" width="75%" height="75%"></img>
+<img src="https://i.imgur.com/wpsoGJq.png" width="75%" height="75%">
+
+```sh
+echo -e "from numpy import random;" \
+        "n = random.randn(10000);"  \
+        "print('\\\n'.join(str(i) for i in n))" \
+| python \
+| uplot hist --nbins 20
+```
+
+<img src="https://i.imgur.com/97R2MQx.png" width="75%" height="75%">
 
 **scatter**
 
 ```sh
-wget https://raw.githubusercontent.com/uiuc-cse/data-fa14/gh-pages/data/iris.csv -qO - \
- | cut -f1-4 -d, \
- | uplot scatter -H -d, -t IRIS -m 10
+curl -s https://raw.githubusercontent.com/uiuc-cse/data-fa14/gh-pages/data/iris.csv \
+| cut -f1-4 -d, \
+| uplot scatter -H -d, -t IRIS
+```
+
+<img src="https://i.imgur.com/STX7bFT.png" width="75%" height="75%">
+
+**line**
+
+```sh
+curl -s https://www.mhlw.go.jp/content/pcr_positive_daily.csv \
+| cut -f2 -d, \
+| uplot line -w 50 -h 15 -t 'PCR positive tests' --xlabel Date --ylabel number
+```
+
+<img src="https://i.imgur.com/PVl5dsa.png" width="75%" height="75%">
+
+**box**
+
+```sh
+curl -s https://raw.githubusercontent.com/uiuc-cse/data-fa14/gh-pages/data/iris.csv \
+| cut -f1-4 -d, \
+| uplot box -H -d, -t IRIS
+```
+
+<img src="https://i.imgur.com/sNI4SmN.png" width="75%" height="75%">
+
+**colors**
+
+```sh
+uplot colors
+```
+
+<img src="https://i.imgur.com/LxyHQsz.png">
+
+## Usage
+
+`uplot --help`
+
+```
+Program: uplot (Tools for plotting on the terminal)
+Version: 0.2.7 (using UnicodePlot 0.0.4)
+Source:  https://github.com/kojix2/uplot
+
+Usage:   uplot <command> [options] <in.tsv>
+
+Commands:
+    barplot    bar
+    histogram  hist
+    lineplot   line
+    lineplots  lines
+    scatter    s
+    density    d
+    boxplot    box
+    colors                   show the list of available colors
+
+    count      c             baplot based on the number of occurrences
+                             (slower than `sort | uniq -c | sort -n -k1`)
+
+Options:
+    -O, --pass [VAL]         file to output standard input data to [stdout]
+                             for inserting uplot in the middle of Unix pipes
+    -o, --output VAL         file to output results to [stderr]
+    -d, --delimiter VAL      use DELIM instead of TAB for field delimiter
+    -H, --headers            specify that the input has header row
+    -T, --transpose          transpose the axes of the input data
+    -t, --title VAL          print string on the top of plot
+    -x, --xlabel VAL         print string on the bottom of the plot
+    -y, --ylabel VAL         print string on the far left of the plot
+    -w, --width VAL          number of characters per row
+    -h, --height VAL         number of rows
+    -b, --border VAL         specify the style of the bounding box
+    -m, --margin VAL         number of spaces to the left of the plot
+    -p, --padding VAL        space of the left and right of the plot
+    -c, --color VAL          color of the drawing
+        --[no-]labels        hide the labels
+        --fmt VAL            xyxy : header is like x1, y1, x2, y2, x3, y3...
+                             xyy  : header is like x, y1, y2, y2, y3...
+```
+
+Use `--help` to print command-specific options.
+
+`uplot hist --help`
+
+```
+Usage: uplot histogram [options] <in.tsv>
+
+Options for histogram:
+        --symbol VAL         character to be used to plot the bars
+        --closed VAL
+    -n, --nbins VAL          approximate number of bins
+
+Options:
+...
 ```
 
 ## Development
 
+Let's keep it simple.
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at [https://github.com/kojix2/uplot](https://github.com/kojix2/uplot).
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+[MIT License](https://opensource.org/licenses/MIT).

lib/uplot/command.rb

@@ -8,13 +8,10 @@ module Uplot
 
   class Command
     attr_accessor :params
-    attr_reader :raw_inputs, :data, :fmt, :parser
+    attr_reader :data, :fmt, :parser
 
     def initialize
       @params = Params.new
-
-      @raw_inputs = []
-
       @parser = Parser.new
     end
 
@@ -31,14 +28,13 @@ module Uplot
       @debug    = parser.debug
 
       if command == :colors
-        Plot.colors
+        Plot.colors(parser.color_names)
         exit
       end
 
       # Sometimes the input file does not end with a newline code.
       while (input = Kernel.gets(nil))
         input.freeze
-        @raw_inputs << input
         @data = Preprocessing.input(input, delimiter, headers, transpose)
         pp @data if @debug
         plot = case command

lib/uplot/command/params.rb

@@ -2,6 +2,11 @@
 
 module Uplot
   class Command
+    # UnicodePlot parameters.
+    # * Normally in a Ruby program, you might use hash for the parameter object.
+    # * Here, I use Struct for 2 safety reason.
+    # * The keys are static in Struct.
+    # * Struct does not conflict with keyword arguments. Hash dose.
     Params = Struct.new(
       # Sort me!
       :title,

lib/uplot/command/parser.rb

@@ -7,26 +7,33 @@ module Uplot
   class Command
     class Parser
       attr_reader :command, :params,
-                  :delimiter, :transpose, :headers, :pass, :output, :fmt, :debug
+                  :delimiter, :transpose, :headers, :pass, :output, :fmt,
+                  :color_names, :debug
 
       def initialize
-        @command = nil
-        @params = Params.new
+        @command     = nil
+        @params      = Params.new
 
-        @delimiter  = "\t"
-        @transpose  = false
-        @headers    = nil
-        @pass       = false
-        @output     = $stderr
-        @fmt        = 'xyy'
-        @debug      = false
+        @delimiter   = "\t"
+        @transpose   = false
+        @headers     = nil
+        @pass        = false
+        @output      = $stderr
+        @fmt         = 'xyy'
+        @debug       = false
+        @color_names = false
       end
 
       def create_default_parser
         OptionParser.new do |opt|
-          opt.program_name = 'uplot'
-          opt.version = Uplot::VERSION
-          opt.on('-O', '--pass [VAL]', 'file to output standard input data to [stdout]') do |v|
+          opt.program_name  = 'uplot'
+          opt.version       = Uplot::VERSION
+          opt.summary_width = 24
+          opt.on_tail('') # Add a blank line at the end
+          opt.separator('')
+          opt.on('Common options:')
+          opt.on('-O', '--pass [VAL]', 'file to output standard input data to [stdout]',
+                 'for inserting uplot in the middle of Unix pipes') do |v|
             @pass = v || $stdout
           end
           opt.on('-o', '--output VAL', 'file to output results to [stderr]') do |v|
@@ -38,7 +45,7 @@ module Uplot
           opt.on('-H', '--headers', TrueClass, 'specify that the input has header row') do |v|
             @headers = v
           end
-          opt.on('-T', '--transpose', TrueClass) do |v|
+          opt.on('-T', '--transpose', TrueClass, 'transpose the axes of the input data') do |v|
             @transpose = v
           end
           opt.on('-t', '--title VAL', String, 'print string on the top of plot') do |v|
@@ -74,7 +81,13 @@ module Uplot
           opt.on('--fmt VAL', String, 'xyxy : header is like x1, y1, x2, y2, x3, y3...', 'xyy  : header is like x, y1, y2, y2, y3...') do |v|
             @fmt = v
           end
-          opt.on('--debug', TrueClass) do |v|
+          # Optparse adds the help option, but it doesn't show up in usage.
+          # This is why you need the code below.
+          opt.on('--help', 'print sub-command help menu') do
+            puts opt.help
+            exit
+          end
+          opt.on('--debug', TrueClass, 'print preprocessed data') do |v|
             @debug = v
           end
           yield opt if block_given?
@@ -83,115 +96,139 @@ module Uplot
 
       def main_parser
         @main_parser ||= create_default_parser do |main_parser|
-          # Usage and help messages
+          # Here, help message is stored in the banner.
+          # Because help of main_parser may be referred by `sub_parser`.
+          
           main_parser.banner = \
             <<~MSG
+              
               Program: uplot (Tools for plotting on the terminal)
-              Version: #{Uplot::VERSION} (using unicode_plot #{UnicodePlot::VERSION})
+              Version: #{Uplot::VERSION} (using UnicodePlot #{UnicodePlot::VERSION})
+              Source:  https://github.com/kojix2/uplot
 
-              Usage:   uplot <command> [options]
+              Usage:   uplot <command> [options] <in.tsv>
 
-              Command: barplot    bar
-                       histogram  hist
-                       lineplot   line
-                       scatter    s
-                       density    d
-                       boxplot    box
-                       colors
+              Commands:
+                  barplot    bar           draw a horizontal barplot
+                  histogram  hist          draw a horizontal histogram
+                  lineplot   line          draw a line chart
+                  lineplots  lines         draw a line chart with multiple series
+                  scatter    s             draw a scatter plot
+                  density    d             draw a density plot
+                  boxplot    box           draw a horizontal boxplot
+                  colors                   show the list of available colors
 
-              Options:
+                  count      c             draw a baplot based on the number of 
+                                           occurrences (slow)
+              
+              General options:
+                  --help                   print command specific help menu
+                  --version                print the version of uplot
             MSG
+
+          # Actually, main_parser can take common optional arguments.
+          # However, these options dose not be shown in the help menu.
+          # I think the main help should be simple.
+          main_parser.on('--help', 'print sub-command help menu') do
+            puts main_parser.banner
+            puts
+            exit
+          end
         end
       end
 
       def sub_parser
         @sub_parser ||= create_default_parser do |parser|
           parser.banner = <<~MSG
-            Usage: uplot #{command} [options]
 
-            Options:
+            Usage: uplot #{command} [options] <in.tsv>
+
+            Options for #{command}:
           MSG
 
           case command
+
+          # If you type only `uplot` in the terminal.
           when nil
-            warn main_parser.help
+            warn main_parser.banner
+            warn "\n"
             exit 1
 
           when :barplot, :bar
-            parser.on('--symbol VAL', String) do |v|
+            parser.on_head('--symbol VAL', String, 'character to be used to plot the bars') do |v|
               params.symbol = v
             end
-            parser.on('--xscale VAL', String) do |v|
+            parser.on_head('--xscale VAL', String, 'axis scaling') do |v|
               params.xscale = v
             end
 
           when :count, :c
-            parser.on('--symbol VAL', String) do |v|
+            parser.on_head('--symbol VAL', String, 'character to be used to plot the bars') do |v|
               params.symbol = v
             end
 
           when :histogram, :hist
-            parser.on('-n', '--nbins VAL', Numeric) do |v|
+            parser.on_head('-n', '--nbins VAL', Numeric, 'approximate number of bins') do |v|
               params.nbins = v
             end
-            parser.on('--closed VAL', String) do |v|
+            parser.on_head('--closed VAL', String) do |v|
               params.closed = v
             end
-            parser.on('--symbol VAL', String) do |v|
+            parser.on_head('--symbol VAL', String, 'character to be used to plot the bars') do |v|
               params.symbol = v
             end
 
           when :lineplot, :line
-            parser.on('--canvas VAL', String) do |v|
+            parser.on_head('--canvas VAL', String, 'type of canvas') do |v|
               params.canvas = v
             end
-            parser.on('--xlim VAL', Array) do |v|
+            parser.on_head('--xlim VAL', Array, 'plotting range for the x coordinate') do |v|
               params.xlim = v.take(2)
             end
-            parser.on('--ylim VAL', Array) do |v|
+            parser.on_head('--ylim VAL', Array, 'plotting range for the y coordinate') do |v|
               params.ylim = v.take(2)
             end
 
           when :lineplots, :lines
-            parser.on('--canvas VAL', String) do |v|
+            parser.on_head('--canvas VAL', String) do |v|
               params.canvas = v
             end
-            parser.on('--xlim VAL', Array) do |v|
+            parser.on_head('--xlim VAL', Array, 'plotting range for the x coordinate') do |v|
               params.xlim = v.take(2)
             end
-            parser.on('--ylim VAL', Array) do |v|
+            parser.on_head('--ylim VAL', Array, 'plotting range for the y coordinate') do |v|
               params.ylim = v.take(2)
             end
 
           when :scatter, :s
-            parser.on('--canvas VAL', String) do |v|
+            parser.on_head('--canvas VAL', String) do |v|
               params.canvas = v
             end
-            parser.on('--xlim VAL', Array) do |v|
+            parser.on_head('--xlim VAL', Array, 'plotting range for the x coordinate') do |v|
               params.xlim = v.take(2)
             end
-            parser.on('--ylim VAL', Array) do |v|
+            parser.on_head('--ylim VAL', Array, 'plotting range for the y coordinate') do |v|
               params.ylim = v.take(2)
             end
 
           when :density, :d
-            parser.on('--grid', TrueClass) do |v|
+            parser.on_head('--grid', TrueClass) do |v|
               params.grid = v
             end
-            parser.on('--xlim VAL', Array) do |v|
+            parser.on_head('--xlim VAL', Array, 'plotting range for the x coordinate') do |v|
               params.xlim = v.take(2)
             end
-            parser.on('--ylim VAL', Array) do |v|
+            parser.on_head('--ylim VAL', Array, 'plotting range for the y coordinate') do |v|
               params.ylim = v.take(2)
             end
 
           when :boxplot, :box
-            parser.on('--xlim VAL', Array) do |v|
+            parser.on_head('--xlim VAL', Array, 'plotting range for the x coordinate') do |v|
               params.xlim = v.take(2)
             end
 
           when :colors
-            parser.on('-n', '--names', TrueClass) do |v|
+            parser.on_head('-n', '--names', 'show color names only', TrueClass) do |v|
               @color_names = v
             end
 

lib/uplot/plot.rb

@@ -10,13 +10,21 @@ module Uplot
     def barplot(data, params, count: false)
       headers = data.headers
       series = data.series
+      # `uplot count`
       if count
-        series = Preprocessing.count(series[0])
+        series = Preprocessing.count_values(series[0])
         params.title = headers[0] if headers
       end
-      params.title ||= headers[1] if headers
-      labels = series[0]
-      values = series[1].map(&:to_f)
+      if series.size == 1
+        # If there is only one series, use the line number for label.
+        params.title ||= headers[0] if headers
+        labels = Array.new(series[0].size) { |i| (i + 1).to_s }
+        values = series[0].map(&:to_f)
+      else
+        params.title ||= headers[1] if headers
+        labels = series[0]
+        values = series[1].map(&:to_f)
+      end
       UnicodePlot.barplot(labels, values, **params.to_hc)
     end
 
@@ -50,10 +58,10 @@ module Uplot
     end
 
     def get_method2(method1)
-      (method1.to_s + '!').to_sym
+      "#{method1}!".to_sym
     end
 
-    def xyy_plot(data, method1, params)
+    def plot_xyy(data, method1, params)
       headers = data.headers
       series = data.series
       method2 = get_method2(method1)
@@ -70,7 +78,7 @@ module Uplot
       plot
     end
 
-    def xyxy_plot(data, method1, params)
+    def plot_xyxy(data, method1, params)
       headers = data.headers
       series = data.series
       method2 = get_method2(method1)
@@ -87,34 +95,30 @@ module Uplot
       plot
     end
 
-    def lines(data, params, fmt = 'xyy')
-      check_series_size(data, fmt)
+    def plot_fmt(data, fmt, method1, params)
       case fmt
       when 'xyy'
-        xyy_plot(data, :lineplot, params)
+        plot_xyy(data, method1, params)
       when 'xyxy'
-        xyxy_plot(data, :lineplot, params)
+        plot_xyxy(data, method1, params)
+      else
+        raise "Unknown format: #{fmt}"
       end
     end
 
+    def lines(data, params, fmt = 'xyy')
+      check_series_size(data, fmt)
+      plot_fmt(data, fmt, :lineplot, params)
+    end
+
     def scatter(data, params, fmt = 'xyy')
       check_series_size(data, fmt)
-      case fmt
-      when 'xyy'
-        xyy_plot(data, :scatterplot, params)
-      when 'xyxy'
-        xyxy_plot(data, :scatterplot, params)
-      end
+      plot_fmt(data, fmt, :scatterplot, params)
     end
 
     def density(data, params, fmt = 'xyy')
       check_series_size(data, fmt)
-      case fmt
-      when 'xyy'
-        xyy_plot(data, :densityplot, params)
-      when 'xyxy'
-        xyxy_plot(data, :densityplot, params)
-      end
+      plot_fmt(data, fmt, :densityplot, params)
     end
 
     def boxplot(data, params)
@@ -125,12 +129,14 @@ module Uplot
       UnicodePlot.boxplot(headers, series, **params.to_hc)
     end
 
-    def colors
+    def colors(color_names = false)
       UnicodePlot::StyledPrinter::TEXT_COLORS.each do |k, v|
         print v
         print k
-        print "\t"
-        print '  ●'
+        unless color_names
+          print "\t"
+          print '  ●'
+        end
         print "\033[0m"
         print "\t"
       end

lib/uplot/preprocessing.rb

@@ -62,16 +62,14 @@ module Uplot
         else
           arr
         end
+      elsif headers
+        transpose2(arr[1..-1])
       else
-        if headers
-          transpose2(arr[1..-1])
-        else
-          transpose2(arr)
-        end
+        transpose2(arr)
       end
     end
 
-    def count(arr)
+    def count_values(arr)
       # tally was added in Ruby 2.7
       if Enumerable.method_defined? :tally
         arr.tally

lib/uplot/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Uplot
-  VERSION = '0.2.5'
+  VERSION = '0.2.8'
 end

test/uplot/command_test.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative '../test_helper.rb'
+require_relative '../test_helper'
 
 class UplotCommandTest < Test::Unit::TestCase
 end

test/uplot/plot_test.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative '../test_helper.rb'
+require_relative '../test_helper'
 
 class UplotPlotTest < Test::Unit::TestCase
 end

test/uplot/preprocessing_test.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative '../test_helper.rb'
+require_relative '../test_helper'
 
 class UplotPreprocessingTest < Test::Unit::TestCase
   def setup
@@ -125,8 +125,8 @@ class UplotPreprocessingTest < Test::Unit::TestCase
                                              [3, 5, 6]], false, false))
   end
 
-  test :count do
-    assert_equal([%i[a b c], [3, 2, 1]], @m.count(%i[a a a b b c]))
-    assert_equal([%i[c b a], [3, 2, 1]], @m.count(%i[a b b c c c]))
+  test :count_values do
+    assert_equal([%i[a b c], [3, 2, 1]], @m.count_values(%i[a a a b b c]))
+    assert_equal([%i[c b a], [3, 2, 1]], @m.count_values(%i[a b b c c c]))
   end
 end