compare_compressors 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 8962f01ee986bcfd6c301100f04565ae6844d4ed
+  data.tar.gz: e1e02bb86cc4bc150c599f439e59a06718c5be9d
+SHA512:
+  metadata.gz: 41d405711e8947af177e741d819df1416e24838ca77ef672571e811d6419e21e0c732b0feba92d928acee5becac5f5e4dda70ef64e872d96d9d3ed18edbb1812
+  data.tar.gz: eb4ce9b89346ee291e9778ea5450180772c2788792a2272bd8757a21fd018e1702a2dfec5fe1ebc053f04784132fd6d57ad0d59e272c38c029c4925eb1add646

data/README.md

@@ -0,0 +1,132 @@
+# compare_compressors
+
+https://github.com/jdleesmiller/compare_compressors
+
+[![Build Status](https://travis-ci.org/jdleesmiller/compare_compressors.svg?branch=master)](https://travis-ci.org/jdleesmiller/compare_compressors)
+
+## Synopsis
+
+Evaluate different compression tools and their settings by running them on a sample of data.
+
+See [this blog post for an example of how to use the tool](TODO).
+
+### Usage
+
+This utility has many system dependencies, so the easiest way to run it is via Docker:
+
+```shell
+$ docker pull jdleesmiller/compare_compressors
+```
+
+Generally you will run a `compare` step, followed by a `plot` or `summarize` step.
+
+#### Compare
+
+This step runs the compressors on the sample files and saves the results to a CSV. Assuming that your sample files are in a folder called `data` in the current directory, and they are called `test1`, `test2`, etc.., the command would look like:
+
+```
+docker run --rm \
+  --volume `pwd`/data:/home/app/compare_compressors/data:ro \
+  --volume /tmp:/tmp \ # optional
+  jdleesmiller/compare_compressors compare data/test* >data/compare.csv
+```
+
+where:
+
+- The `--rm` flag tells docker to remove the container when it's finished.
+
+- The ```--volume `pwd`/data:/home/app/compare_compressors/data:ro``` flag mounts `./data` on the host inside the container, so the utility can access the sample files. The trick here is that `/home/app/compare_compressors` is the utility's working directory inside the container, so the relative paths `data/test*` for the sample files will be the same both inside and outside of the container. The `:ro` makes it a read only mount; this is optional, but it provides added assurance that the utility won't change your data files.
+
+- The `--volume /tmp:/tmp` flag is optional but may improve performance. The utility does its compression and decompression in `/tmp` inside the container, and all of the writes inside the container go through Docker's union file system. By mounting `/tmp` on the host, we bypass the union file system. (Ideally, we'd just do this in the Dockerfile, but unfortunately it's 10x slower on Docker for Mac; hopefully that will improve soon.)
+
+#### Plot
+
+Once you've generated a CSV with results, the tool can read the CSV and generate a `gnuplot` script to plot the results. Note that you need to have `gnuplot` installed on the host for this to work.
+
+There are several plotting commands: `plot` gives you a 2D plot of compression time vs compressed size. There is also a `--decompression` option to plot decompression time vs compressed size instead.
+
+```
+docker run --rm \
+  --volume `pwd`/data:/home/app/compare_compressors/data:ro \
+  --volume /tmp:/tmp \
+  jdleesmiller/compare_compressors plot data/compare.csv | gnuplot
+```
+
+The `plot_costs` command takes three cost coefficients: cost per GiB of stored data, cost per hour to run the compression program, and cost per hour to run the decompression program. The program then computes a simple linear cost function. To keep the plot in 2D, the two time costs are added together.
+
+```
+docker run --rm \
+  --volume `pwd`/data:/home/app/compare_compressors/data:ro \
+  --gibyte-cost 56.05 \
+  --compression-hour-cost 32.35 \
+  --decompression-hour-cost 177.91 \
+  --currency '£' \
+  jdleesmiller/compare_compressors plot_costs data/compare.csv | gnuplot
+```
+
+#### Summarize
+
+Print a list of the compressors and settings in descending order by cost. The cost function is of the same form as for `plot_costs`.
+
+```
+docker run --rm \
+  --volume `pwd`/data:/home/app/compare_compressors/data \
+  --gibyte-cost 56.05 \
+  --compression-hour-cost 32.35 \
+  --decompression-hour-cost 177.91 \
+  --currency '£' \
+  jdleesmiller/compare_compressors summarize data/compare.csv
+```
+
+## Requirements
+
+A linux-like `/usr/bin/time` utility is required, along with several system packages. See the [Dockerfile](Dockerfile) for a list of the packages that this utility depends on. To make the plot, you will also need `gnuplot`.
+
+If you are installing natively, without docker, you will need ruby and then to install the gem:
+
+```
+$ gem install compare_compressors
+```
+
+## Development
+
+For development, you will probably want (1) override the default entrypoint and (2) mount the application root inside the container. To run the tests, for example:
+
+```
+docker run --rm -it --entrypoint='' \
+  --volume=compare_compressors_bundle:/home/app/compare_compressors/.bundle \
+  --volume=`pwd`:/home/app/compare_compressors \
+  compare_compressors bundle exec rake
+```
+
+The only caveat is that you need to preserve the `.bundle` folder inside the container by mounting it as a volume; the above command does this using a named volume, `compare_compressors_bundle`, which will persist between runs and be easier to identify in the `docker volume ls` output.
+
+## Related
+
+- See [this blog post for an example of how to use the tool](TODO).
+- For many more compression algorithms, see https://quixdb.github.io/squash-benchmark/
+
+## License
+
+(The MIT License)
+
+Copyright (c) 2017 John Lees-Miller
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/bin/compare_compressors

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'compare_compressors'
+
+CompareCompressors::CommandLineInterface.start(ARGV)

data/lib/compare_compressors.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'English'
+
+require_relative 'compare_compressors/version'
+
+require_relative 'compare_compressors/comparer'
+require_relative 'compare_compressors/cost_model'
+require_relative 'compare_compressors/result'
+require_relative 'compare_compressors/group_result'
+require_relative 'compare_compressors/costed_group_result'
+
+require_relative 'compare_compressors/plotter'
+require_relative 'compare_compressors/plotters/cost_plotter'
+require_relative 'compare_compressors/plotters/raw_plotter'
+require_relative 'compare_compressors/plotters/size_plotter'
+
+require_relative 'compare_compressors/compressor'
+require_relative 'compare_compressors/compressors/brotli_compressor'
+require_relative 'compare_compressors/compressors/bzip2_compressor'
+require_relative 'compare_compressors/compressors/gzip_compressor'
+require_relative 'compare_compressors/compressors/seven_zip_compressor'
+require_relative 'compare_compressors/compressors/xz_compressor'
+require_relative 'compare_compressors/compressors/zstd_compressor'
+
+require_relative 'compare_compressors/command_line_interface'
+
+#
+# Compare compression algorithms.
+#
+module CompareCompressors
+  COMPRESSORS = [
+    BrotliCompressor,
+    Bzip2Compressor,
+    GzipCompressor,
+    SevenZipCompressor,
+    XzCompressor,
+    ZstdCompressor
+  ].map(&:new).freeze
+end

data/lib/compare_compressors/command_line_interface.rb

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+require 'csv'
+require 'thor'
+
+module CompareCompressors
+  #
+  # Handle generic command line options and run the relevant command.
+  #
+  class CommandLineInterface < Thor
+    desc \
+      'version',
+      'print version (also available as --version)'
+    def version
+      puts "compare_compressors-#{CompareCompressors::VERSION}"
+      COMPRESSORS.each do |compressor|
+        puts format('%10s: %s', compressor.name, compressor.version || '?')
+      end
+    end
+    map %w(--version -v) => :version
+
+    desc \
+      'compare <target files>',
+      'Run compression tools on targets and write a CSV'
+    def compare(*targets)
+      CSV do |csv|
+        Comparer.new.run(csv, COMPRESSORS, targets)
+      end
+    end
+
+    class <<self
+      def scale_option
+        option \
+          :scale,
+          type: :numeric,
+          desc: 'scale factor from sample targets to full dataset',
+          default: 1.0
+      end
+
+      def use_cpu_time_option
+        option \
+          :use_cpu_time,
+          type: :boolean,
+          desc: 'use CPU time rather than elapsed time',
+          default: CostModel::DEFAULT_USE_CPU_TIME
+      end
+
+      def cost_options
+        option \
+          :gibyte_cost,
+          type: :numeric,
+          desc: 'storage cost per gigabyte of compressed output',
+          default: CostModel::DEFAULT_GIBYTE_COST
+        option \
+          :compression_hour_cost,
+          type: :numeric,
+          desc: 'compute cost per hour of CPU time for compression',
+          default: CostModel::DEFAULT_HOUR_COST
+        option \
+          :decompression_hour_cost,
+          type: :numeric,
+          desc: 'compute cost per hour of CPU time for decompression',
+          default: CostModel::DEFAULT_HOUR_COST
+        option \
+          :currency,
+          type: :string,
+          desc: 'currency symbol for display',
+          default: CostModel::DEFAULT_CURRENCY
+      end
+
+      def plot_options
+        option \
+          :terminal,
+          desc: 'the terminal line for gnuplot',
+          default: Plotter::DEFAULT_TERMINAL
+        option \
+          :output,
+          desc: 'the output name for gnuplot',
+          default: Plotter::DEFAULT_OUTPUT
+        option \
+          :pareto_only,
+          desc: 'plot only non-dominated compressor-level pairs',
+          type: :boolean,
+          default: true
+        option \
+          :logscale_size,
+          desc: 'use a log10 scale for the size (lucky you if you need this)',
+          type: :boolean,
+          default: Plotter::DEFAULT_LOGSCALE_SIZE
+        option \
+          :autoscale_fix,
+          desc: 'zoom axes to fit the points tightly',
+          type: :boolean,
+          default: Plotter::DEFAULT_AUTOSCALE_FIX
+        option \
+          :show_labels,
+          desc: 'show compression level labels on the plot',
+          type: :boolean,
+          default: Plotter::DEFAULT_SHOW_LABELS
+        option \
+          :lmargin,
+          desc: 'adjust lmargin (workaround if y label is cut off on png)',
+          type: :numeric,
+          default: Plotter::DEFAULT_LMARGIN
+        option \
+          :title,
+          desc: 'main title (must not contain double quotes)',
+          type: :string,
+          default: Plotter::DEFAULT_TITLE
+      end
+    end
+
+    desc \
+      'plot [csv file]',
+      'Write a gnuplot script for a basic 2D plot with the CSV from compare'
+    scale_option
+    use_cpu_time_option
+    plot_options
+    option \
+      :decompression,
+      desc: 'show decompression time instead of compression time',
+      type: :boolean,
+      default: SizePlotter::DEFAULT_DECOMPRESSION
+    def plot(csv_file = nil)
+      results = read_results(csv_file)
+      group_results = GroupResult.group(results, scale: options[:scale])
+      plotter = make_plotter(
+        SizePlotter, options,
+        decompression: options[:decompression]
+      )
+      plotter.plot(group_results, pareto_only: options[:pareto_only])
+    end
+
+    desc \
+      'plot_3d [csv file]',
+      'Write a gnuplot script for a 3D plot with the CSV from compare'
+    scale_option
+    use_cpu_time_option
+    plot_options
+    def plot_3d(csv_file = nil)
+      results = read_results(csv_file)
+      group_results = GroupResult.group(results, scale: options[:scale])
+      plotter = make_plotter(RawPlotter, options)
+      plotter.plot(group_results, pareto_only: options[:pareto_only])
+    end
+
+    desc \
+      'plot_costs [csv file]',
+      'Write a gnuplot script for a 2D cost plot with the CSV from compare'
+    scale_option
+    use_cpu_time_option
+    cost_options
+    plot_options
+    option \
+      :show_cost_contours,
+      desc: 'show cost function contours',
+      type: :boolean,
+      default: CostPlotter::DEFAULT_SHOW_COST_CONTOURS
+    def plot_costs(csv_file = nil)
+      results = read_results(csv_file)
+      group_results = GroupResult.group(results, scale: options[:scale])
+      cost_model = make_cost_model(options)
+      costed_group_results =
+        CostedGroupResult.from_group_results(cost_model, group_results)
+      plotter = make_plotter(
+        CostPlotter, options, cost_model,
+        show_cost_contours: options[:show_cost_contours]
+      )
+      plotter.plot(costed_group_results, pareto_only: options[:pareto_only])
+    end
+
+    desc \
+      'summarize [csv file]',
+      'Read CSV from compare and write out a summary'
+    scale_option
+    use_cpu_time_option
+    cost_options
+    option \
+      :top,
+      desc: 'number of results to include',
+      type: :numeric,
+      default: CostModel::DEFAULT_SUMMARIZE_TOP
+    def summarize(csv_file = nil)
+      results = read_results(csv_file)
+      group_results = GroupResult.group(results, scale: options[:scale])
+      cost_model = make_cost_model(options)
+      costed_group_results =
+        CostedGroupResult.from_group_results(cost_model, group_results)
+      puts cost_model.summarize(costed_group_results, options[:top])
+    end
+
+    private
+
+    def make_cost_model(options)
+      CostModel.new(
+        gibyte_cost: options[:gibyte_cost],
+        compression_hour_cost: options[:compression_hour_cost],
+        decompression_hour_cost: options[:decompression_hour_cost],
+        use_cpu_time: options[:use_cpu_time],
+        currency: options[:currency]
+      )
+    end
+
+    def make_plotter(klass, options, *args, **kwargs)
+      klass.new(
+        *args,
+        terminal: options[:terminal],
+        output: options[:output],
+        logscale_size: options[:logscale_size],
+        autoscale_fix: options[:autoscale_fix],
+        show_labels: options[:show_labels],
+        lmargin: options[:lmargin],
+        title: options[:title],
+        use_cpu_time: options[:use_cpu_time],
+        **kwargs
+      )
+    end
+
+    def read_results(csv_file)
+      Result.read_csv(csv_file ? File.read(csv_file) : STDIN)
+    end
+  end
+end

data/lib/compare_compressors/comparer.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'fileutils'
+require 'tmpdir'
+
+module CompareCompressors
+  #
+  # Run compressors on targets and record the results.
+  #
+  # The general approach is, for each target:
+  #
+  # 1. Copy the original target (read only) to a temporary folder (read write);
+  #    the copy is the 'work target'.
+  # 2. Hash the work target so we can make sure we don't change it.
+  # 3. For each compressor and level, compress the work target.
+  # 4. Remove the work target (if the compressor left it)
+  # 5. Decompress the compressed target; this should restore the work target.
+  # 6. Check the work target's hash before we start the next compressor or
+  #    level, to make sure the compression hasn't broken it somehow.
+  #
+  # This approach is a bit complicated, but it lets us (1) make sure we don't
+  # change the original targets, since they're copied, (2) make sure we
+  # don't accidentally change the work target during the run, which would
+  # invalidate the results, and (3) avoid copying the work target from the
+  # target repeatedly.
+  #
+  class Comparer
+    #
+    # @param [CSV] csv CSV writer for output
+    # @param [Array<Compressor>] compressors
+    # @param [Array<String>] targets pathnames of targets (read only)
+    #
+    def run(csv, compressors, targets)
+      csv << Result.members
+      targets.each do |target|
+        Dir.mktmpdir do |tmp|
+          work_target = stage_target(tmp, target)
+          evaluate_target(csv, compressors, target, work_target)
+        end
+      end
+      nil
+    end
+
+    private
+
+    def stage_target(tmp, target)
+      pathname = File.join(tmp, 'data')
+      FileUtils.cp target, pathname
+      pathname
+    end
+
+    def evaluate_target(csv, compressors, target, work_target)
+      target_digest = find_digest(work_target)
+      compressors.each do |compressor|
+        compressor.levels.each do |level|
+          if find_digest(work_target) != target_digest
+            raise "digest mismatch: #{compressor.name}" \
+              " level #{level} on #{target}"
+          end
+          csv << compressor.evaluate(target, work_target, level)
+        end
+      end
+    end
+
+    def find_digest(pathname)
+      Digest::SHA256.file(pathname).hexdigest
+    end
+  end
+end