dphil 0.1.4

data/lib/dphil/cache.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "active_support/cache"
+require "active_support/notifications"
+
+module Dphil
+  module_function
+
+  def cache(key, params = nil)
+    @cache ||= defined?(::Rails.cache) ? ::Rails.cache : ActiveSupport::Cache::MemoryStore.new(size: 16_384)
+    full_key = String.new("Dphil-#{Dphil::VERSION}:cache:#{key}")
+    full_key << ":#{Digest::SHA1.base64digest(params.to_s)}" unless params.nil?
+    block_given? ? @cache.fetch(full_key, &Proc.new) : @cache.fetch(full_key)
+  end
+end

data/lib/dphil/change_list.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Dphil
+  class ChangeList
+  end
+end

data/lib/dphil/character.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+module Dphil
+  #
+  # Phylogenetic character for storing states and symbols.
+  #
+  # Immutable.
+  #
+  class Character
+    include Dphil::LDOutput
+
+    # Instantiates a new Character
+    # @overload initialize(id = nil, states = nil)
+    #   @param id [Integer] a character ID
+    #   @param states [Hash<Integer, String]] taxa and text-states +{ taxon_id => text_state }+
+    # @overload initialize(**opts = {})
+    #   @param [Hash] opts options or keyword values
+    #   @option opts [Integer] :id a character ID
+    #   @option opts [Hash<Integer, String]] :states taxa and text-states +{ taxon_id => text_state }+
+    def initialize(id = nil, states = nil, **opts)
+      @id = (opts[:id] || id)&.to_s.to_i
+      @taxa_states = (opts[:states] || states)
+                     .to_h.each_with_object({}) do |(taxon, state), acc|
+        next if state.blank?
+        taxon = taxon.to_s if taxon.is_a?(Symbol)
+        acc[taxon.to_i] = normalize_text(state)
+      end
+
+      unique_states = weighted_uniq(@taxa_states.values)
+      if unique_states.size > SYMBOL_ARRAY.size
+        raise ArgumentError,
+              "Too many states (found #{unique_states.size}, " \
+              "max #{SYMBOL_ARRAY.size})"
+      end
+
+      @states = {}
+      @state_totals = unique_states
+      unique_states.each_key.with_index do |state, index|
+        @states[SYMBOL_ARRAY[index]] = state
+      end
+      instance_variables.each { |ivar| instance_variable_get(ivar).freeze }
+    end
+
+    # @!attribute [r] id
+    # @return [Integer] character ID
+    attr_reader :id
+
+    # @!attribute [r] taxa
+    # @return [Set<Integer>] taxon IDs
+    def taxa
+      @taxa ||= Set.new(taxa_states.keys).freeze
+    end
+
+    # @!attribute [r] states
+    # @return [Hash<String, String>] text-states by symbol
+    attr_reader :states
+
+    # @!attribute [r] symbols
+    # @return [Hash<String, String>] symbols by text-state
+    def symbols
+      @symbols ||= states.invert.freeze
+    end
+
+    # @!attribute [r] state_list
+    # @return [Array<String>] text-states
+    def state_list
+      @state_list ||= states.values.freeze
+    end
+
+    # @!attribute [r] symbol_list
+    # @return [Array<String>] symbols
+    def symbol_list
+      @symbol_list ||= states.keys.freeze
+    end
+
+    # @!attribute [r] state_totals
+    # @return [Hash<String, Integer>] character state totals by text-state
+    attr_reader :state_totals
+
+    # @!attribute [r] symbol_totals
+    # @return [Hash<String, Integer>] character state totals by symbol
+    def symbol_totals
+      @symbol_totals ||= state_totals.transform_keys { |state| symbols[state] }.freeze
+    end
+
+    # @!attribute [r] taxa_states
+    # @return [Hash<Integer, String>] text-states by taxon ID
+    attr_reader :taxa_states
+
+    # @!attribute [r] taxa_symbols
+    # @return [Hash<Integer, String>] symbols by taxon ID
+    def taxa_symbols
+      @taxa_symbols ||= taxa_states.transform_values { |state| symbols[state] }.freeze
+    end
+
+    # @!attribute [r] states_taxa
+    # @return [Hash<String, Integer>] taxa IDs by text-state
+    def states_taxa
+      @states_taxa ||= (states.each_value.each_with_object({}) do |state, acc|
+        acc[state] = taxa_states.select { |_, tstate| state == tstate }.keys
+      end).freeze
+    end
+
+    # @!attribute [r] symbols_taxa
+    # @return [Hash<String, Integer>] taxa IDs by symbol
+    def symbols_taxa
+      @symbols_taxa ||= states_taxa.transform_keys { |state| symbols[state] }.freeze
+    end
+
+    # Get state from symbol
+    # @param  symbol [String] a symbol
+    # @return [String, nil] the associated text-state, or Nil if not found
+    def get_state(symbol)
+      states[normalize_text(symbol)]
+    end
+
+    # Get symbol from state
+    # @param state [String] a text-state
+    # @return [String, nil] the associated symbol, or Nil if not found
+    def get_symbol(state)
+      symbols[normalize_text(state)]
+    end
+
+    # Get taxa from state
+    # @param  symbol [String] a text-state
+    # @return [Array<Integer>] the associated taxa IDs
+    def get_taxa_state(state)
+      states_taxa[normalize_text(state)]
+    end
+
+    # Get taxa from symbol
+    # @param  symbol [String] a symbol
+    # @return [Array<Integer>] the associated taxa IDs
+    def get_taxa_symbol(symbol)
+      symbols_taxa[normalize_text(symbol)]
+    end
+
+    # Get state from taxon
+    # @param  taxon_id [Integer] a taxon ID
+    # @return [String, nil] the associated text-state, or Nil if not found
+    def get_state_taxon(taxon_id)
+      taxa_states[taxon_id.to_i]
+    end
+
+    # Get symbol from taxon
+    # @param  taxon_id [Integer] a taxon ID
+    # @return [String, nil] the associated symbol, or Nil if not found
+    def get_symbol_taxon(taxon_id)
+      taxa_symbols[taxon_id.to_i]
+    end
+
+    # Check if character is parsimony-informative
+    # (At least 2 variants occurring in at least 2 places)
+    # @return [Boolean] whether the character provides useful information
+    def informative?
+      @informative ||= (states.size > 1 && states_taxa.count { |_, v| v.size > 1 } > 1)
+    end
+
+    # Check if the character is invariant
+    # @return [Boolean] whether the character is constant (invariant)
+    def constant?
+      @constant ||= states.size <= 1
+    end
+
+    def to_h
+      {
+        id: id,
+        states: states,
+        symbols: symbols,
+        state_totals: state_totals,
+        taxa_states: taxa_states,
+        states_taxa: states_taxa,
+        is_informative: informative?,
+        is_constant: constant?,
+      }
+    end
+
+    def as_json(options = nil)
+      to_h.as_json(options)
+    end
+
+    # Pretty-print the object
+    # (used by Pry in particular)
+    def pretty_print(q)
+      q.object_group(self) do
+        q.breakable
+        q.group(1) do
+          q.text "@id=#{id}"
+          q.breakable
+          q.group(1, "{", "}") do
+            q.seplist(states) do |symbol, state|
+              q.text "#{state.inspect}(#{symbol})=#{states_taxa[state]}"
+            end
+          end
+        end
+      end
+    end
+
+    # @return [String] a string representation of the object.
+    def inspect
+      pretty_inspect.chomp
+    end
+    alias to_s inspect
+
+    private
+
+    # @param text [String] an arbitrary string of text
+    # @return [String] a Unicode-normalized, stripped, frozen copy
+    def normalize_text(text)
+      return if text.nil?
+      text = UNF::Normalizer.normalize(text.to_s, :nfc)
+      text.strip!
+      text.freeze
+    end
+
+    # Find all unique elements in an array and stably sort them by frequency.
+    # @param array [Array]
+    # @return [Hash] keys are unique input array elements, values are frequency
+    def weighted_uniq(array)
+      weighted_hash = array.each_with_object({}) do |v, acc|
+        acc[v] ||= 0
+        acc[v] += 1
+      end
+
+      n = 0
+      weighted_hash = weighted_hash.sort_by do |x|
+        n += 1
+        [-x[1], n]
+      end
+      weighted_hash.to_h
+    end
+
+    SYMBOL_ARRAY = IceNine.deep_freeze([*"A".."Z", *"a".."z"])
+    private_constant :SYMBOL_ARRAY
+  end
+end

data/lib/dphil/character_matrix.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Dphil
+  #
+  # A matrix of character states across taxa.
+  #
+  class CharacterMatrix
+    include LDOutput
+
+    # Instantiate a new CharacterMatrix from a UTF-8 CSV file
+    # @param infile [#read] the file/IO object to read
+    # @param transpose [Boolean] transpose the table 90° (headers in first column)
+    # @return [CharacterMatrix]
+    def self.from_csv(infile, transpose: false)
+      csv = CSV.read(infile, "r:bom|utf-8")
+      csv = csv.transpose if transpose
+      new(csv)
+    end
+
+    # Instantiate a new CharacterMatrix
+    # @param table [Array<Array<String>>] collation table (headers in first row)
+    def initialize(table)
+      @taxa_names = table.to_a.first.each_with_object({})
+                         .with_index do |(name, acc), index|
+        acc[index + 1] = normalize_text(name)
+      end
+      @taxa_ids = @taxa_names.invert
+
+      taxa_arr = @taxa_ids.values
+      @characters = (1...table.length).each_with_object({}) do |char_num, acc|
+        char_states = taxa_arr.zip(table[char_num]).to_h
+        acc[char_num] = Dphil::Character.new(id: char_num, states: char_states)
+      end
+
+      instance_variables.each { |ivar| instance_variable_get(ivar).freeze }
+    end
+
+    # @!attribute [r] taxa_names
+    # @return [Hash<Integer, String>] taxa names by ID
+    attr_reader :taxa_names
+
+    # @!attribute [r] taxa_ids
+    # @return [Hash<String, Integer>] taxa IDs by names
+    attr_reader :taxa_ids
+
+    # @!attribute [r] characters
+    # @return [Hash<Integer, Character>] characters by character ID
+    attr_reader :characters
+
+    # @!attribute [r] stats
+    # @return [Hash] the character statistics for the matrix
+    def stats
+      @stats ||= begin
+        hash = {
+          total: characters.count,
+          constant: 0,
+          uninformative: 0,
+          informative: 0,
+        }
+        characters.each_value do |char|
+          if char.constant?
+            hash[:constant] += 1
+          elsif char.informative?
+            hash[:informative] += 1
+          else
+            hash[:uninformative] += 1
+          end
+        end
+        hash
+      end.freeze
+    end
+
+    # Get character by ID
+    # @param char_id [Integer] a character ID
+    # @return [Character, nil] the associated Character, or Nil if not found.
+    def get_character(char_id)
+      characters[char_id.to_i]
+    end
+
+    def to_h
+      {
+        taxa_names: taxa_names,
+        characters: characters,
+      }
+    end
+
+    def as_json(options = nil)
+      to_h.as_json(options)
+    end
+
+    private
+
+    # @param text [String] an arbitrary string of text
+    # @return [String] a Unicode-normalized, stripped, frozen copy
+    def normalize_text(text)
+      return if text.nil?
+      text = UNF::Normalizer.normalize(text.to_s, :nfc)
+      text.strip!
+      text.freeze
+    end
+  end
+end

data/lib/dphil/cli.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "dphil"
+require "gli"
+
+module Dphil
+  #
+  # GLI-based CLI interface for the library.
+  #
+  # Not loaded automatically with the rest of the gem.
+  #
+  module CLI
+    extend GLI::App
+
+    program_desc "UBC Sanskrit digital philology CLI tool"
+    version Dphil::VERSION
+    subcommand_option_handling :normal
+    arguments :strict
+
+    desc "Be verbose in output"
+    switch :verbose, negatable: false
+
+    # Load individual CLI commands
+    commands_from "dphil/cli_commands"
+  end
+end

data/lib/dphil/cli_commands/csv2ld.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+Dphil::CLI.module_eval do
+  desc "Convert a CSV-format collation file into a JSON-LD dataset"
+  long_desc <<~EOS
+    Convert a CSV-format collation file into a JSON-LD dataset, generating trees
+    using PAUP as part of the process.
+    This expects each column of the CSV to represent data for a single taxon,
+    and the first row to contain the names of the taxa.
+  EOS
+
+  arg :csv_file
+
+  command :csv2ld do |c|
+    c.desc "Transpose rows/columns in CSV"
+    c.switch :t, :transpose, negatable: false
+
+    c.desc "Specify the location of the PAUP executable"
+    c.flag :p, :paup_cmd, arg_name: "file", default_value: "paup4"
+
+    c.desc "Include custom PAUP commands from a file in PAUP block of NEXUS output"
+    c.flag :d, :paup_data, arg_name: "file"
+
+    c.desc "Write JSON-LD output to file instead of STDOUT"
+    c.flag :o, :outfile, arg_name: "file"
+
+    c.action do |_, copts, args|
+      # Check that PAUP command exists
+      paup_cmd = `command -v #{Shellwords.shellescape(copts[:paup_cmd])}`.strip
+      raise "PAUP command `#{copts[:paup_cmd]}` could not be found." if paup_cmd.empty?
+
+      # Set absolute path of CSV input
+      csv_file = Pathname.new(args[0]).realpath
+
+      Dir.mktmpdir("dphil-csv2ld") do |dir|
+        Dir.chdir(dir) do
+          # Run Csv2Nex conversion
+          File.write("csv2ld.nex", Dphil::Csv2NexConverter.new(csv_file, copts).convert)
+
+          # Run PAUP
+          `#{paup_cmd} -n csv2ld.nex`
+
+          # Compile JSON-LD Dataset
+          matrix = Dphil::CharacterMatrix.from_csv(csv_file, transpose: copts[:transpose])
+          paup_trees = Dphil::PAUP.parse_trees("paup.log")
+          trees = paup_trees.each_with_object({}) do |(k, v), acc|
+            next unless k.is_a?(Integer)
+            acc[k] = Dphil::Tree.new(k, v[:lengths], v[:stats])
+          end
+
+          cons_tree = Dphil::NewickTree.tree_from_nex(
+            "con.tree",
+            taxa_map: matrix.taxa_names.transform_values { |v| v.gsub(/[\-\_]/, " ") }
+          )
+          trees[0] = cons_tree
+
+          dataset = Dphil::LDDataSet.new(matrix: matrix, trees: trees)
+          @dataset_ld = JSON.pretty_generate(dataset.as_jsonld)
+        end
+      end
+
+      if copts[:outfile].nil?
+        puts @dataset_ld
+      else
+        abs_outfile = Pathname.new(copts[:outfile]).expand_path
+        rel_outfile = abs_outfile.relative_path_from(Pathname.getwd)
+        puts "#{File.write(copts[:outfile], @dataset_ld)} bytes written to #{rel_outfile}"
+      end
+    end
+  end
+end