quantitative 0.1.1 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7b99f939e67992ff9a3659ef69ef8ff4bd5897baba1d269c491a7db7d1717c85
-  data.tar.gz: e9f456c34e16ed0c44b4b23f6e274ed44cce4ca6ad7fe654602dbd73afc281bc
+  metadata.gz: 5bfe61d98618c7cfb83052426689976be38c45e83fce9217a74a4f0392897b60
+  data.tar.gz: 061d9a0179eb913c5f5f5d9f1016998c2cbc0d65da9a774620a3b591f18a1f49
 SHA512:
-  metadata.gz: 4fca7722561f54543b92a7b50700eed4cb706b9bfca65405a8a101908b6ae49b547bcdd2cd13c4656c94a30ad817225118c22c905e47076c88f8feff85947bc4
-  data.tar.gz: 78b256560d7aec2ee19833618bd19e89f6c87ae718ad966b1d18caa18e08727b37d1232b169bce1fbc0b4ca4bac951e956fd4efefaa27450d533769f68d8ac23
+  metadata.gz: 4154a9e589bcffd15b3415ace9c1ccc6b8d29ba5ecc0180e48259c649a746a157f58bd89aeabad4ffc4ac5edefe6f1892c94adcd001ba5d1f039a5bb46a8a9d0
+  data.tar.gz: 7ac2b4661e6c4b0e02fda9389f73b8d007b92e754e8b4fa821bb55dca1d085dfd7e2e3eb6608d520a2e2e6008eb837aa75e7c07c05addc28af577b92fe98f8c3

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    quantitative (0.1.1)
+    quantitative (0.1.3)
       oj (~> 3.10)
 
 GEM

data/README.md

@@ -1,5 +1,7 @@
 # Quantitative
 
+[![Gem Version](https://badge.fury.io/rb/quantitative.svg)](https://badge.fury.io/rb/quantitative)
+
 STATUS: ALPHA - very early stages!  The framework is very much a work in progress and I am rapidly introducing new things and changing existing things around.
 
 Quantitative is a statistical and quantitative library for Ruby 3.x for trading stocks, cryptocurrency, and forex.  It provides a number of classes and modules for working with time-series data, financial data, and other quantitative data.  It is designed to be fast, efficient, and easy to use.

data/lib/quant/errors.rb

@@ -5,4 +5,5 @@ module Quant
   class InvalidInterval < Error; end
   class InvalidResolution < Error; end
   class ArrayMaxSizeError < Error; end
+  class SecurityClassError < Error; end
 end

data/lib/quant/interval.rb

@@ -167,7 +167,13 @@ module Quant
     alias seconds duration
 
     def ==(other)
-      interval == other&.interval
+      if other.is_a? String
+        interval.to_s == other
+      elsif other.is_a? Symbol
+        interval == MAPPINGS[other]&.fetch(:interval, nil)
+      else
+        interval == other&.interval
+      end
     end
 
     def ticks_per_minute

data/lib/quant/refinements/array.rb

@@ -100,7 +100,7 @@ module Quant
       end
 
       # Computes the mean of the array.  When +n+ is specified, the mean is computed over
-      # the last +n+ elements.
+      # the last +n+ elements, otherwise it is computed over the entire array.
       #
       # @param n [Integer] the number of elements to compute the mean over
       # @return [Float]
@@ -112,7 +112,7 @@ module Quant
       end
 
       # Computes the Exponential Moving Average (EMA) of the array.  When +n+ is specified,
-      # the EMA is computed over the last +n+ elements.
+      # the EMA is computed over the last +n+ elements, otherwise it is computed over the entire array.
       # An Array of EMA's is returned, with the first entry always the first value in the subset.
       #
       # @params n [Integer] the number of elements to compute the EMA over.
@@ -130,7 +130,7 @@ module Quant
       end
 
       # Computes the Simple Moving Average (SMA) of the array.  When +n+ is specified,
-      # the SMA is computed over the last +n+ elements.
+      # the SMA is computed over the last +n+ elements, otherwise it is computed over the entire array.
       # An Array of SMA's is returned, with the first entry always the first value in the subset.
       #
       # @param n [Integer] the number of elements to compute the SMA over
@@ -146,7 +146,7 @@ module Quant
       end
 
       # Computes the Weighted Moving Average (WMA) of the array.  When +n+ is specified,
-      # the WMA is computed over the last +n+ elements.
+      # the WMA is computed over the last +n+ elements, otherwise it is computed over the entire array.
       # An Array of WMA's is returned, with the first entry always the first value in the subset.
       #
       # @param n [Integer] the number of elements to compute the WMA over
@@ -168,7 +168,8 @@ module Quant
       end
 
       # Computes the Standard Deviation of the array.  When +n+ is specified,
-      # the Standard Deviation is computed over the last +n+ elements.
+      # the Standard Deviation is computed over the last +n+ elements,
+      # otherwise it is computed over the entire array.
       #
       # @param n [Integer] the number of elements to compute the Standard Deviation over.
       # @return [Float]

data/lib/quant/security.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require_relative "security_class"
+
+module Quant
+  # A +Security+ is a representation of a financial instrument such as a stock, option, future, or currency.
+  # It is used to represent the instrument that is being traded, analyzed, or managed.
+  # @example
+  #   security = Quant::Security.new(symbol: "AAPL", name: "Apple Inc.", security_class: :stock, exchange: "NASDAQ")
+  #   security.symbol # => "AAPL"
+  #   security.name # => "Apple Inc."
+  #   security.stock? # => true
+  #   security.option? # => false
+  #   security.future? # => false
+  #   security.currency? # => false
+  #   security.exchange # => "NASDAQ"
+  #   security.to_h # => { "s" => "AAPL", "n" => "Apple Inc.", "sc" => "stock", "x" => "NASDAQ" }
+  class Security
+    attr_reader :symbol, :name, :security_class, :id, :exchange, :source, :meta, :created_at, :updated_at
+
+    def initialize(
+      symbol:,
+      name: nil,
+      id: nil,
+      active: true,
+      tradeable: true,
+      exchange: nil,
+      source: nil,
+      security_class: nil,
+      created_at: Quant.current_time,
+      updated_at: Quant.current_time,
+      meta: {}
+    )
+      raise ArgumentError, "symbol is required" unless symbol
+
+      @symbol = symbol.to_s.upcase
+      @name = name
+      @id = id
+      @tradeable = tradeable
+      @active = active
+      @exchange = exchange
+      @source = source
+      @security_class = SecurityClass.new(security_class)
+      @created_at = created_at
+      @updated_at = updated_at
+      @meta = meta
+    end
+
+    def active?
+      !!@active
+    end
+
+    def tradeable?
+      !!@tradeable
+    end
+
+    SecurityClass::CLASSES.each do |class_name|
+      define_method("#{class_name}?") do
+        security_class == class_name
+      end
+    end
+
+    def to_h(full: false)
+      return { "s" => symbol } unless full
+
+      { "s" => symbol,
+        "n" => name,
+        "id" => id,
+        "t" => tradeable?,
+        "a" => active?,
+        "x" => exchange,
+        "sc" => security_class.to_s,
+        "src" => source.to_s }
+    end
+
+    def to_json(*args, full: false)
+      Oj.dump(to_h(full: full), *args)
+    end
+  end
+end

data/lib/quant/security_class.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Quant
+  # Stocks (Equities): Represent ownership in a company. Stockholders are entitled to a share
+  # of the company's profits and have voting rights at shareholder meetings.
+
+  # Bonds (Fixed-Income Securities): Debt instruments where an investor lends money to an entity
+  # (government or corporation) in exchange for periodic interest payments and the return of
+  #  the principal amount at maturity.
+
+  # Mutual Funds: Pooled funds managed by an investment company. Investors buy shares in the mutual
+  # fund, and the fund invests in a diversified portfolio of stocks, bonds, or other securities.
+
+  # Exchange-Traded Funds (ETFs): Similar to mutual funds but traded on stock exchanges.
+  # ETFs can track an index, commodity, bonds, or a basket of assets.
+
+  # Options: Derivative securities that give the holder the right (but not the obligation) to buy
+  # or sell an underlying asset at a predetermined price before or at expiration.
+
+  # Futures: Contracts that obligate the buyer to purchase or the seller to sell an
+  # asset at a predetermined future date and price.
+
+  # Real Estate Investment Trusts (REITs): Companies that own, operate, or finance income-generating
+  # real estate. Investors can buy shares in a REIT, which provides them with a share of the
+  # income produced by the real estate.
+
+  # Cryptocurrencies: Digital or virtual currencies that use cryptography for security and operate on
+  # decentralized networks, typically based on blockchain technology. Examples include Bitcoin, Ethereum, and Ripple.
+
+  # Preferred Stock: A type of stock that has priority over common stock in terms of dividend
+  # payments and asset distribution in the event of liquidation.
+
+  # Treasury Securities: Issued by the government to raise funds. Types include Treasury bills (T-bills),
+  # Treasury notes (T-notes), and Treasury bonds (T-bonds).
+
+  # Mortgage-Backed Securities (MBS): Securities that represent an ownership interest in a pool of mortgage loans.
+  # Investors receive payments based on the interest and principal of the underlying loans.
+
+  # Commodities: Physical goods such as gold, silver, oil, or agricultural products, traded on commodity exchanges.
+
+  # Foreign Exchange (Forex): The market where currencies are traded. Investors can buy and sell currencies to
+  # profit from changes in exchange rates.
+  class SecurityClass
+    CLASSES = %i(
+      bond
+      commodity
+      cryptocurrency
+      etf
+      forex
+      future
+      mbs
+      mutual_fund
+      option
+      preferred_stock
+      reit
+      stock
+      treasury_note
+    ).freeze
+
+    attr_reader :security_class
+
+    def initialize(name)
+      return if @security_class = from_standard(name)
+
+      @security_class = from_alternate(name.to_s.downcase.to_sym) unless name.nil?
+      raise_unknown_security_class_error(name) unless security_class
+    end
+
+    CLASSES.each do |class_name|
+      define_method("#{class_name}?") do
+        security_class == class_name
+      end
+    end
+
+    def raise_unknown_security_class_error(name)
+      raise SecurityClassError, "Unknown security class: #{name.inspect}"
+    end
+
+    def to_s
+      security_class.to_s
+    end
+
+    def to_h
+      { "sc" => security_class }
+    end
+
+    def to_json(*args)
+      Oj.dump(to_h, *args)
+    end
+
+    def ==(other)
+      case other
+      when String then from_alternate(other.to_sym) == security_class
+      when Symbol then from_alternate(other) == security_class
+      when SecurityClass then other.security_class == security_class
+      else
+        false
+      end
+    end
+
+    private
+
+    ALTERNATE_NAMES = {
+      us_equity: :stock,
+      crypto: :cryptocurrency,
+    }.freeze
+
+    def from_standard(name)
+      name if CLASSES.include?(name)
+    end
+
+    def from_alternate(alt_name)
+      from_standard(alt_name) || ALTERNATE_NAMES[alt_name]
+    end
+  end
+end

data/lib/quant/series.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Quant
+  # Ticks belong to the first series they're associated with always.
+  # There are no provisions for series merging their ticks to one series!
+  # Indicators will be computed against the parent series of a list of ticks, so we
+  # can safely work with subsets of a series and indicators will compute just once.
+  class Series
+    include Enumerable
+    extend Forwardable
+
+    def self.from_file(filename:, symbol:, interval:, folder: nil)
+      symbol = symbol.to_s.upcase
+      interval = Interval[interval]
+
+      filename = Rails.root.join("historical", folder, "#{symbol.upcase}.txt") if filename.nil?
+      raise "File #{filename} does not exist" unless File.exist?(filename)
+
+      lines = File.read(filename).split("\n")
+      ticks = lines.map{ |line| Quant::Ticks::OHLC.from_json(line) }
+
+      from_ticks(symbol: symbol, interval: interval, ticks: ticks)
+    end
+
+    def self.from_json(symbol:, interval:, json:)
+      from_hash symbol: symbol, interval: interval, hash: Oj.load(json)
+    end
+
+    def self.from_hash(symbol:, interval:, hash:)
+      ticks = hash.map { |tick_hash| Quant::Ticks::OHLC.from(tick_hash) }
+      from_ticks(symbol: symbol, interval: interval, ticks: ticks)
+    end
+
+    def self.from_ticks(symbol:, interval:, ticks:)
+      ticks = ticks.sort_by(&:close_timestamp)
+
+      new(symbol: symbol, interval: interval).tap do |series|
+        ticks.each { |tick| series << tick }
+      end
+    end
+
+    attr_reader :symbol, :interval, :ticks
+
+    def initialize(symbol:, interval:)
+      @symbol = symbol
+      @interval = interval
+      @ticks = []
+    end
+
+    def limit_iterations(start_iteration, stop_iteration)
+      selected_ticks = ticks[start_iteration..stop_iteration]
+      return self if selected_ticks.size == ticks.size
+
+      self.class.from_ticks(symbol: symbol, interval: interval, ticks: selected_ticks)
+    end
+
+    def limit(period)
+      selected_ticks = ticks.select{ |tick| period.cover?(tick.close_timestamp) }
+      return self if selected_ticks.size == ticks.size
+
+      self.class.from_ticks(symbol: symbol, interval: interval, ticks: selected_ticks)
+    end
+
+    def_delegator :@ticks, :[]
+    def_delegator :@ticks, :size
+    def_delegator :@ticks, :each
+    def_delegator :@ticks, :select
+    def_delegator :@ticks, :select!
+    def_delegator :@ticks, :reject
+    def_delegator :@ticks, :reject!
+    def_delegator :@ticks, :first
+    def_delegator :@ticks, :last
+
+    def highest
+      ticks.max_by(&:high_price)
+    end
+
+    def lowest
+      ticks.min_by(&:low_price)
+    end
+
+    def ==(other)
+      [symbol, interval, ticks] == [other.symbol, other.interval, other.ticks]
+    end
+
+    def dup
+      self.class.from_ticks(symbol: symbol, interval: interval, ticks: ticks)
+    end
+
+    def inspect
+      "#<#{self.class.name} symbol=#{symbol} interval=#{interval} ticks=#{ticks.size}>"
+    end
+
+    def <<(tick)
+      @ticks << tick.assign_series(self)
+    end
+
+    def to_h
+      { "symbol" => symbol,
+        "interval" => interval,
+        "ticks" => ticks.map(&:to_h) }
+    end
+
+    def to_json(*args)
+      Oj.dump(to_h, *args)
+    end
+  end
+end

data/lib/quant/ticks/ohlc.rb

@@ -1,125 +1,107 @@
-require_relative 'value'
+# frozen_string_literal: true
+
+require_relative "tick"
 
 module Quant
   module Ticks
-    # serialized keys
-    # ot: open timestamp
-    # ct: close timestamp
-    # iv: interval
-
-    # o: open price
-    # h: high price
-    # l: low price
-    # c: close price
-
-    # bv: base volume
-    # tv: target volume
-    # ct: close timestamp
-
-    # t: trades
-    # g: green
-    # j: doji
-    class OHLC < Value
-      def self.from(hash)
-        new \
-          open_timestamp: hash["ot"],
-          close_timestamp: hash["ct"],
-          interval: hash["iv"],
-
-          open_price: hash["o"],
-          high_price: hash["h"],
-          low_price: hash["l"],
-          close_price: hash["c"],
-
-          base_volume: hash["bv"],
-          target_volume: hash["tv"],
-
-          trades: hash["t"],
-          green: hash["g"],
-          doji: hash["j"]
-      end
-
-      def self.from_json(json)
-        from Oj.load(json)
-      end
-
-      def initialize(open_timestamp:,
-                     close_timestamp:,
-                     interval: nil,
-
-                     open_price:,
-                     high_price:,
-                     low_price:,
-                     close_price:,
-
-                     base_volume: 0.0,
-                     target_volume: 0.0,
-
-                     trades: 0,
-                     green: false,
-                     doji: nil)
-
-        super(price: close_price, timestamp: close_timestamp, interval: interval, trades: trades)
+    # An +OHLC+ is a bar or candle for a point in time that has an open, high, low, and close price.
+    # It is the most common form of a +Tick+ and is usually used to representa time period such as a
+    # minute, hour, day, week, or month.  The +OHLC+ is used to represent the price action of an asset
+    # The interval of the +OHLC+ is the time period that the +OHLC+ represents, such has hourly, daily, weekly, etc.
+    class OHLC < Tick
+      include TimeMethods
+
+      attr_reader :interval, :series
+      attr_reader :close_timestamp, :open_timestamp
+      attr_reader :open_price, :high_price, :low_price, :close_price
+      attr_reader :base_volume, :target_volume, :trades
+      attr_reader :green, :doji
+
+      def initialize(
+        open_timestamp:,
+        close_timestamp:,
+
+        open_price:,
+        high_price:,
+        low_price:,
+        close_price:,
+
+        interval: nil,
+
+        volume: nil,
+        base_volume: nil,
+        target_volume: nil,
+
+        trades: nil,
+        green: nil,
+        doji: nil
+      )
         @open_timestamp = extract_time(open_timestamp)
+        @close_timestamp = extract_time(close_timestamp)
+
         @open_price = open_price.to_f
         @high_price = high_price.to_f
         @low_price = low_price.to_f
+        @close_price = close_price.to_f
+
+        @interval = Interval[interval]
 
-        @base_volume = base_volume.to_i
-        @target_volume = target_volume.to_i
+        @base_volume = (volume || base_volume).to_i
+        @target_volume = (target_volume || @base_volume).to_i
+        @trades = trades.to_i
 
         @green = green.nil? ? compute_green : green
         @doji = doji.nil? ? compute_doji : doji
+        super()
       end
 
+      alias price close_price
+      alias timestamp close_timestamp
+      alias volume base_volume
+
       def hl2; ((high_price + low_price) / 2.0) end
       def oc2; ((open_price + close_price) / 2.0) end
       def hlc3; ((high_price + low_price + close_price) / 3.0) end
       def ohlc4; ((open_price + high_price + low_price + close_price) / 4.0) end
 
+      # The corresponding? method helps determine that the other tick's timestamp is the same as this tick's timestamp,
+      # which is useful when aligning ticks between two separate series where one starts or ends at a different time,
+      # or when there may be gaps in the data between the two series.
       def corresponding?(other)
         [open_timestamp, close_timestamp] == [other.open_timestamp, other.close_timestamp]
       end
 
-      # percent change from open to close
-      def delta
-        ((open_price / close_price) - 1.0) * 100
+      # Two OHLC ticks are equal if their interval, close_timestamp, and close_price are equal.
+      def ==(other)
+        [interval, close_timestamp, close_price] == [other.interval, other.close_timestamp, other.close_price]
       end
 
-      def to_h
-        { "ot" => open_timestamp,
-          "ct" => close_timestamp,
-          "iv" => interval.to_s,
-
-          "o" => open_price,
-          "h" => high_price,
-          "l" => low_price,
-          "c" => close_price,
-
-          "bv" => base_volume,
-          "tv" => target_volume,
-
-          "t" => trades,
-          "g" => green,
-          "j" => doji }
+      # Returns the percent daily price change from open_price to close_price, ranging from 0.0 to 1.0.
+      # A positive value means the price increased, and a negative value means the price decreased.
+      # A value of 0.0 means no change.
+      # @return [Float]
+      def daily_price_change
+        ((open_price / close_price) - 1.0)
+      rescue ZeroDivisionError
+        0.0
       end
 
-      def as_price(value)
-        series.nil? ? value : series.as_price(value)
-      end
-
-      def to_s
-        ots = interval.daily? ? open_timestamp.strftime('%Y-%m-%d') : open_timestamp.strftime('%Y-%m-%d %H:%M:%S')
-        cts = interval.daily? ? close_timestamp.strftime('%Y-%m-%d') : close_timestamp.strftime('%Y-%m-%d %H:%M:%S')
-        "#{ots}: o: #{as_price(open_price)}, h: #{as_price(high_price)}, l: #{as_price(low_price)}, c: #{as_price(close_price)} :#{cts}"
+      # Calculates the absolute change from the open_price to the close_price, divided by the average of the
+      # open_price and close_price. This method will give a value between 0 and 2, where 0 means no change,
+      # 1 means the price doubled, and 2 means the price went to zero.
+      # This method is useful for comparing the volatility of different assets.
+      # @return [Float]
+      def daily_price_change_ratio
+        @price_change ||= ((open_price - close_price) / oc2).abs
       end
 
+      # Set the #green? property to true when the close_price is greater than or equal to the open_price.
       def compute_green
         close_price >= open_price
       end
 
       def green?
-        close_price > open_price
+        @green
       end
 
       def red?
@@ -130,10 +112,10 @@ module Quant
         @doji
       end
 
-      def price_change
-        @price_change ||= ((open_price - close_price) / oc2).abs
-      end
-
+      # Computes a doji candlestick pattern.  A doji is a candlestick pattern that occurs when the open and close
+      # are the same or very close to the same.  The high and low are also very close to the same.  The doji pattern
+      # is a sign of indecision in the market. It is a sign that the market is not sure which way to go.
+      # @return [Boolean]
       def compute_doji
         body_bottom, body_top = [open_price, close_price].sort
 
@@ -147,6 +129,10 @@ module Quant
 
         body_ratio < 0.025 && head_ratio > 1.0 && tail_ratio > 1.0
       end
+
+      def inspect
+        "#<#{self.class.name} #{interval} ct=#{close_timestamp.iso8601} o=#{open_price} h=#{high_price} l=#{low_price} c=#{close_price} v=#{volume}>"
+      end
     end
   end
 end

data/lib/quant/ticks/serializers/ohlc.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Quant
+  module Ticks
+    module Serializers
+      module OHLC
+        # Returns a +Quant::Ticks::Tick+ from a valid JSON +String+.
+        # @param json [String]
+        # @param tick_class [Quant::Ticks::Tick]
+        # @return [Quant::Ticks::Tick]
+        # @example
+        #  json =
+        #  Quant::Ticks::Serializers::Tick.from_json(json, tick_class: Quant::Ticks::Spot)
+        def self.from_json(json, tick_class:)
+          hash = Oj.load(json)
+          from(hash, tick_class: tick_class)
+        end
+
+        # Returns a +Hash+ of the Spot tick's key properties
+        #
+        # Serialized Keys:
+        #
+        # - ot: open timestamp
+        # - ct: close timestamp
+        # - iv: interval
+        # - o: open price
+        # - h: high price
+        # - l: low price
+        # - c: close price
+        # - bv: base volume
+        # - tv: target volume
+        # - t: trades
+        # - g: green
+        # - j: doji
+        #
+        # @param tick [Quant::Ticks::Tick]
+        # @return [Hash]
+        # @example
+        #  Quant::Ticks::Serializers::Tick.to_h(tick)
+        #  # => { "ot" => [Time], "ct" => [Time], "iv" => "1m", "o" => 1.0, "h" => 2.0,
+        #  #      "l" => 0.5, "c" => 1.5, "bv" => 6.0, "tv" => 5.0, "t" => 1, "g" => true, "j" => true }
+        def self.to_h(tick)
+          { "ot" => tick.open_timestamp,
+            "ct" => tick.close_timestamp,
+            "iv" => tick.interval.to_s,
+
+            "o" => tick.open_price,
+            "h" => tick.high_price,
+            "l" => tick.low_price,
+            "c" => tick.close_price,
+
+            "bv" => tick.base_volume,
+            "tv" => tick.target_volume,
+
+            "t" => tick.trades,
+            "g" => tick.green,
+            "j" => tick.doji }
+        end
+
+        def self.from(hash, tick_class:)
+          tick_class.new \
+            open_timestamp: hash["ot"],
+            close_timestamp: hash["ct"],
+            interval: hash["iv"],
+
+            open_price: hash["o"],
+            high_price: hash["h"],
+            low_price: hash["l"],
+            close_price: hash["c"],
+
+            base_volume: hash["bv"],
+            target_volume: hash["tv"],
+
+            trades: hash["t"],
+            green: hash["g"],
+            doji: hash["j"]
+        end
+      end
+    end
+  end
+end

data/lib/quant/ticks/serializers/spot.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Quant
+  module Ticks
+    module Serializers
+      class Spot < Tick
+        # Returns a +Quant::Ticks::Tick+ from a valid JSON +String+.
+        # @param json [String]
+        # @param tick_class [Quant::Ticks::Tick]
+        # @return [Quant::Ticks::Tick]
+        # @example
+        #  json = "{\"ct\":\"2024-01-15 03:12:23 UTC\", \"cp\":5.0, \"iv\":\"1d\", \"bv\":0.0, \"tv\":0.0, \"t\":0}"
+        #  Quant::Ticks::Serializers::Tick.from_json(json, tick_class: Quant::Ticks::Spot)
+        def self.from_json(json, tick_class:)
+          hash = Oj.load(json)
+          from(hash, tick_class: tick_class)
+        end
+
+        # Returns a +Hash+ of the Spot tick's key properties
+        #
+        # Serialized Keys:
+        #
+        # - ct: close timestamp
+        # - iv: interval
+        # - cp: close price
+        # - bv: base volume
+        # - tv: target volume
+        # - t: trades
+        #
+        # @param tick [Quant::Ticks::Tick]
+        # @return [Hash]
+        # @example
+        #  Quant::Ticks::Serializers::Tick.to_h(tick)
+        #  # => { "ct" => "2024-02-13 03:12:23 UTC", "cp" => 5.0, "iv" => "1d", "bv" => 0.0, "tv" => 0.0, "t" => 0 }
+        def self.to_h(tick)
+          { "ct" => tick.close_timestamp,
+            "cp" => tick.close_price,
+            "iv" => tick.interval.to_s,
+            "bv" => tick.base_volume,
+            "tv" => tick.target_volume,
+            "t" => tick.trades }
+        end
+
+        def self.from(hash, tick_class:)
+          tick_class.new(
+            close_timestamp: hash["ct"],
+            close_price: hash["cp"],
+            interval: hash["iv"],
+            base_volume: hash["bv"],
+            target_volume: hash["tv"],
+            trades: hash["t"]
+          )
+        end
+      end
+    end
+  end
+end

data/lib/quant/ticks/serializers/tick.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Quant
+  module Ticks
+    module Serializers
+      # The +Tick+ class serializes and deserializes +Tick+ objects to and from various formats.
+      # These classes are wired into the Tick classes and are used to convert +Tick+ objects to and from
+      # Ruby hashes, JSON strings, and CSV strings.  They're not typically used directly, but are extracted
+      # to make it easier to provide custom serialization and deserialization for +Tick+ objects not shipped
+      # with the library.
+      # @abstract
+      class Tick
+        # Returns a +String+ that is a valid CSV row
+        # @param tick [Quant::Ticks::Tick]
+        # @param headers [Boolean]
+        # @return [String]
+        # @example
+        #  Quant::Ticks::Serializers::Tick.to_csv(tick)
+        #  # => "1d,9999,5.0\n"
+        # @example
+        #  Quant::Ticks::Serializers::Tick.to_csv(tick, headers: true)
+        #  # => "iv,ct,cp\n1d,9999,5.0\n"
+        def self.to_csv(tick, headers: false)
+          hash = to_h(tick)
+          row = CSV::Row.new(hash.keys, hash.values)
+          return row.to_csv unless headers
+
+          header_row = CSV::Row.new(hash.keys, hash.keys)
+          header_row.to_csv << row.to_csv
+        end
+
+        # Returns a +String+ that is a valid JSON representation of the tick's key properties.
+        # @param tick [Quant::Ticks::Tick]
+        # @return [String]
+        # @example
+        #  Quant::Ticks::Serializers::Tick.to_json(tick)
+        #  # => "{\"iv\":\"1d\",\"ct\":9999,\"cp\":5.0}"
+        def self.to_json(tick)
+          Oj.dump to_h(tick)
+        end
+
+        # Returns a Ruby +Hash+ comprised of the key properties for the tick.
+        # @param tick [Quant::Ticks::Tick]
+        # @return [Hash]
+        # @example
+        #  Quant::Ticks::Serializers::Tick.to_h(tick)
+        #  # => { "iv" => "1d", "ct" => 9999, "cp" => 5.0 }
+        def self.to_h(instance)
+          raise NotImplementedError
+        end
+
+        # Returns a +Quant::Ticks::Tick+ from a Ruby +Hash+.
+        # @param hash [Hash]
+        # @param tick_class [Quant::Ticks::Tick]
+        # @return [Quant::Ticks::Tick]
+        # @example
+        #  hash = { "ct" => 2024-01-15 03:12:23 UTC", "cp" => 5.0, "iv" => "1d", "bv" => 0.0, "tv" => 0.0, "t" => 0}
+        #  Quant::Ticks::Serializers::Tick.from(hash, tick_class: Quant::Ticks::Spot)
+        def self.from(hash, tick_class:)
+          raise NotImplementedError
+        end
+
+        # Returns a +Quant::Ticks::Tick+ from a valid JSON +String+.
+        # @param json [String]
+        # @param tick_class [Quant::Ticks::Tick]
+        # @return [Quant::Ticks::Tick]
+        # @example
+        #  json = "{\"ct\":\"2024-01-15 03:12:23 UTC\", \"cp\":5.0, \"iv\":\"1d\", \"bv\":0.0, \"tv\":0.0, \"t\":0}"
+        #  Quant::Ticks::Serializers::Tick.from_json(json, tick_class: Quant::Ticks::Spot)
+        def self.from_json(json, tick_class:)
+          hash = Oj.load(json)
+          from(hash, tick_class: tick_class)
+        end
+      end
+    end
+  end
+end

data/lib/quant/ticks/spot.rb

@@ -1,32 +1,79 @@
 # frozen_string_literal: true
 
+require_relative "tick"
+
 module Quant
   module Ticks
-    class Spot < Value
-      def self.from(hash)
-        new(close_timestamp: hash["ct"], close_price: hash["c"], base_volume: hash["bv"], target_volume: hash["tv"])
-      end
+    # A +Spot+ is a single price point in time.  It is the most basic form of a +Tick+ and is usually used to represent
+    # a continuously streaming tick that just has a single price point at a given point in time.
+    # @example
+    #   spot = Quant::Ticks::Spot.new(price: 100.0, timestamp: Time.now)
+    #   spot.price # => 100.0
+    #   spot.timestamp # => 2018-01-01 12:00:00 UTC
+    #
+    # @example
+    #   spot = Quant::Ticks::Spot.from({ "p" => 100.0, "t" => "2018-01-01 12:00:00 UTC", "bv" => 1000 })
+    #   spot.price # => 100.0
+    #   spot.timestamp # => 2018-01-01 12:00:00 UTC
+    #   spot.volume # => 1000
+    class Spot < Tick
+      include TimeMethods
+
+      attr_reader :interval, :series
+      attr_reader :close_timestamp, :open_timestamp
+      attr_reader :open_price, :high_price, :low_price, :close_price
+      attr_reader :base_volume, :target_volume, :trades
+
+      def initialize(
+        price: nil,
+        timestamp: nil,
+        close_price: nil,
+        close_timestamp: nil,
+        volume: nil,
+        interval: nil,
+        base_volume: nil,
+        target_volume: nil,
+        trades: nil
+      )
+        raise ArgumentError, "Must supply a spot price as either :price or :close_price" unless price || close_price
+
+        @close_price = (close_price || price).to_f
 
-      def self.from_json(json)
-        from Oj.load(json)
+        @interval = Interval[interval]
+
+        @close_timestamp = extract_time(timestamp || close_timestamp || Quant.current_time)
+        @open_timestamp = @close_timestamp
+
+        @base_volume = (volume || base_volume).to_i
+        @target_volume = (target_volume || @base_volume).to_i
+
+        @trades = trades.to_i
+        super()
       end
 
-      def initialize(close_timestamp:, close_price:, interval: nil, base_volume: 0.0, target_volume: 0.0, trades: 0)
-        super(price: close_price, timestamp: close_timestamp, interval: interval, volume: base_volume, trades: trades)
-        @target_volume = target_volume.to_i
+      alias timestamp close_timestamp
+      alias price close_price
+      alias oc2 close_price
+      alias hl2 close_price
+      alias hlc3 close_price
+      alias ohlc4 close_price
+      alias delta close_price
+      alias volume base_volume
+
+      # Two ticks are equal if they have the same close price and close timestamp.
+      def ==(other)
+        [close_price, close_timestamp] == [other.close_price, other.close_timestamp]
       end
 
+      # The corresponding? method helps determine that the other tick's timestamp is the same as this tick's timestamp,
+      # which is useful when aligning ticks between two separate series where one starts or ends at a different time,
+      # or when there may be gaps in the data between the two series.
       def corresponding?(other)
         close_timestamp == other.close_timestamp
       end
 
-      def to_h
-        { "ct" => close_timestamp,
-          "c" => close_price,
-          "iv" => interval.to_s,
-          "bv" => base_volume,
-          "tv" => target_volume,
-          "t" => trades }
+      def inspect
+        "#<#{self.class.name} #{interval} ct=#{close_timestamp} c=#{close_price.to_f} v=#{volume}>"
       end
     end
   end

data/lib/quant/ticks/tick.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Quant
+  module Ticks
+    # +Tick+ is the abstract ancestor for all Ticks and holds the logic for interacting with series and indicators.
+    # The public interface is devoid of properties around price, volume, and timestamp, etc.  Descendant classes
+    # are responsible for defining the properties and how they are represented.
+    #
+    # The +Tick+ class is designed to be immutable and is intended to be used as a value object.  This means that
+    # once a +Tick+ is created, it cannot be changed.  This is important for the integrity of the series and
+    # indicators that depend on the ticks within the series.
+    #
+    # When a tick is added to a series, it is locked into the series and ownership cannot be changed.  This is important
+    # for the integrity of the series and indicators that depend on the ticks within the series.  This is a key design
+    # to being able to being able to not only compute indicators on the ticks just once, but also avoid recomputing
+    # indicators when series are limited/sliced/filtered into subsets of the original series.
+    #
+    # Ticks can be serialized to and from Ruby Hash, JSON strings, and CSV strings.
+    class Tick
+      # Returns a +Tick+ from a Ruby +Hash+.  The default serializer is used to generate the +Tick+.
+      # @param hash [Hash]
+      # @param serializer_class [Class] The serializer class to use for the conversion.
+      # @return [Quant::Ticks::Tick]
+      # @example
+      #   hash = { "timestamp" => "2018-01-01 12:00:00 UTC", "price" => 100.0, "volume" => 1000 }
+      #   Quant::Ticks::Tick.from(hash)
+      #   # => #<Quant::Ticks::Spot:0x00007f9e3b8b3e08 @timestamp=2018-01-01 12:00:00 UTC, @price=100.0, @volume=1000>
+      def self.from(hash, serializer_class: default_serializer_class)
+        serializer_class.from(hash, tick_class: self)
+      end
+
+      # Returns a +Tick+ from a JSON string.  The default serializer is used to generate the +Tick+.
+      # @param json [String]
+      # @param serializer_class [Class] The serializer class to use for the conversion.
+      # @return [Quant::Ticks::Tick]
+      # @example
+      #   json = "{\"timestamp\":\"2018-01-01 12:00:00 UTC\",\"price\":100.0,\"volume\":1000}"
+      #   Quant::Ticks::Tick.from_json(json)
+      #   # => #<Quant::Ticks::Spot:0x00007f9e3b8b3e08 @timestamp=2018-01-01 12:00:00 UTC, @price=100.0, @volume=1000>
+      def self.from_json(json, serializer_class: default_serializer_class)
+        serializer_class.from_json(json, tick_class: self)
+      end
+
+      attr_reader :series
+
+      def initialize
+        # Set the series by appending to the series or calling #assign_series method
+        @series = nil
+      end
+
+      # Ticks always belong to the first series they're assigned so we can easily spin off
+      # sub-sets or new series with the same ticks while allowing each series to have
+      # its own state and full control over the ticks within its series
+      def assign_series(new_series)
+        assign_series!(new_series) if @series.nil?
+        self
+      end
+
+      # Ticks always belong to the first series they're assigned so we can easily spin off
+      # sub-sets or new series with the same ticks.  However, if you need to reassign the
+      # series, you can use this method to force the change of series ownership.
+      #
+      # The series interval is also assigned to the tick if it is not already set.
+      def assign_series!(new_series)
+        @series = new_series
+        @interval = new_series.interval if @interval.nil?
+        self
+      end
+
+      # Returns a Ruby hash for the Tick.  The default serializer is used to generate the hash.
+      #
+      # @param serializer_class [Class] the serializer class to use for the conversion.
+      # @example
+      #   tick.to_h
+      #   # => { timestamp: "2018-01-01 12:00:00 UTC", price: 100.0, volume: 1000 }
+      def to_h(serializer_class: default_serializer_class)
+        serializer_class.to_h(self)
+      end
+
+      # Returns a JSON string for the Tick.  The default serializer is used to generate the JSON string.
+      #
+      # @param serializer_class [Class] the serializer class to use for the conversion.
+      # @example
+      #   tick.to_json
+      #   # => "{\"timestamp\":\"2018-01-01 12:00:00 UTC\",\"price\":100.0,\"volume\":1000}"
+      def to_json(serializer_class: default_serializer_class)
+        serializer_class.to_json(self)
+      end
+
+      # Returns a CSV row as a String for the Tick.  The default serializer is used to generate the CSV string.
+      # If headers is true, two lines returned separated by newline.
+      # The first line is the header row and the second line is the data row.
+      #
+      # @param serializer_class [Class] the serializer class to use for the conversion.
+      # @example
+      #   tick.to_csv(headers: true)
+      #   # => "timestamp,price,volume\n2018-01-01 12:00:00 UTC,100.0,1000\n"
+      def to_csv(serializer_class: default_serializer_class, headers: false)
+        serializer_class.to_csv(self, headers: headers)
+      end
+
+      # Reflects the serializer class from the tick's class name.
+      # @note internal use only.
+      def self.default_serializer_class
+        Object.const_get "Quant::Ticks::Serializers::#{name.split("::").last}"
+      end
+
+      # Reflects the serializer class from the tick's class name.
+      # @note internal use only.
+      def default_serializer_class
+        self.class.default_serializer_class
+      end
+    end
+  end
+end

data/lib/quant/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Quant
-  VERSION = "0.1.1"
+  VERSION = "0.1.3"
 end

data/lib/quantitative.rb

@@ -3,6 +3,7 @@
 require "time"
 require "date"
 require "oj"
+require "csv"
 
 lib_folder = File.expand_path(File.join(File.dirname(__FILE__)))
 quant_folder = File.join(lib_folder, "quant")

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: quantitative
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.3
 platform: ruby
 authors:
 - Michael Lang
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-02-12 00:00:00.000000000 Z
+date: 2024-02-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: oj
@@ -56,12 +56,15 @@ files:
 - lib/quant/mixins/trig.rb
 - lib/quant/mixins/weighted_average.rb
 - lib/quant/refinements/array.rb
-- lib/quant/ticks/core.rb
-- lib/quant/ticks/indicator_points.rb
+- lib/quant/security.rb
+- lib/quant/security_class.rb
+- lib/quant/series.rb
 - lib/quant/ticks/ohlc.rb
-- lib/quant/ticks/serializers/value.rb
+- lib/quant/ticks/serializers/ohlc.rb
+- lib/quant/ticks/serializers/spot.rb
+- lib/quant/ticks/serializers/tick.rb
 - lib/quant/ticks/spot.rb
-- lib/quant/ticks/value.rb
+- lib/quant/ticks/tick.rb
 - lib/quant/time_methods.rb
 - lib/quant/time_period.rb
 - lib/quant/version.rb
@@ -89,7 +92,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.5
+rubygems_version: 3.5.6
 signing_key:
 specification_version: 4
 summary: Quantitative and statistical tools written for Ruby 3.x for trading and finance.

data/lib/quant/ticks/core.rb

@@ -1,8 +0,0 @@
-# frozen_string_literal: true
-
-module Quant
-  module Ticks
-    class Core
-    end
-  end
-end

data/lib/quant/ticks/indicator_points.rb

@@ -1,22 +0,0 @@
-# frozen_string_literal: true
-
-module Quant
-  module Ticks
-    class IndicatorPoints
-      attr_reader :points
-
-      def initialize(tick:)
-        @tick = tick
-        @points = {}
-      end
-
-      def [](indicator)
-        points[indicator]
-      end
-
-      def []=(indicator, point)
-        points[indicator] = point
-      end
-    end
-  end
-end

data/lib/quant/ticks/serializers/value.rb

@@ -1,23 +0,0 @@
-# frozen_string_literal: true
-
-module Quant
-  module Ticks
-    module Serializers
-      module Value
-        module_function
-
-        def to_h(instance)
-          { "iv" => instance.interval.to_s,
-            "ct" => instance.close_timestamp.to_i,
-            "cp" => instance.close_price,
-            "bv" => instance.base_volume,
-            "tv" => instance.target_volume }
-        end
-
-        def to_json(instance)
-          Oj.dump to_h(instance)
-        end
-      end
-    end
-  end
-end

data/lib/quant/ticks/value.rb

@@ -1,88 +0,0 @@
-# frozen_string_literal: true
-
-module Quant
-  module Ticks
-    # Value ticks are the most basic ticks and are used to represent a single price point (no open, high, low, close, etc.)
-    # and a single timestamp.  Usually, these are best used in streaming data where ticks are flowing in every second or whatever
-    # interval that's appropriate for the data source.
-    # Often indicators and charts still want a universal public interface (i.e. open_price, high_price, volume, etc.), so we add
-    # those methods here and inherit and redefine upstream as appropriate.
-    #
-    # For Value ticks:
-    # * The +price+ given is set for all *_price fields.
-    # * The +volume+ is set for both base and target volume.
-    # * The +timestamp+ is set for both open and close timestamps.
-    class Value
-      include TimeMethods
-
-      attr_reader :interval, :series
-      attr_reader :close_timestamp, :open_timestamp
-      attr_reader :open_price, :high_price, :low_price, :close_price
-      attr_reader :base_volume, :target_volume, :trades
-      attr_reader :green, :doji
-
-      def initialize(price:, timestamp: Quant.current_time, interval: nil, volume: 0, trades: 0)
-        @interval = Interval[interval]
-
-        @close_timestamp = extract_time(timestamp)
-        @open_timestamp = @close_timestamp
-
-        @close_price = price.to_f
-        @open_price = close_price
-        @high_price = close_price
-        @low_price = close_price
-
-        @base_volume = volume.to_i
-        @target_volume = volume.to_i
-        @trades = trades.to_i
-
-        # Set the series by appending to the series
-        @series = nil
-      end
-
-      alias oc2 close_price
-      alias hl2 close_price
-      alias hlc3 close_price
-      alias ohlc4 close_price
-      alias delta close_price
-      alias volume base_volume
-
-      def corresponding?(other)
-        close_timestamp == other.close_timestamp
-      end
-
-      def ==(other)
-        to_h == other.to_h
-      end
-
-      # ticks are immutable across series so we can easily initialize sub-sets or new series
-      # with the same ticks while allowing each series to have its own state and full
-      # control over the ticks within its series
-      def assign_series(new_series)
-        assign_series!(new_series) if @series.nil?
-
-        # dup.tap do |new_tick|
-        #   # new_tick.instance_variable_set(:@series, new_series)
-        #   new_tick.instance_variable_set(:@indicators, indicators)
-        # end
-      end
-
-      def assign_series!(new_series)
-        @series = new_series
-        self
-      end
-
-      def inspect
-        "#<#{self.class.name} iv=#{interval} ct=#{close_timestamp.strftime("%Y-%m-%d")} o=#{open_price} c=#{close_price} v=#{volume}>"
-      end
-
-      def to_h
-        Quant::Ticks::Serializers::Value.to_h(self)
-      end
-
-      def to_json(*_args)
-        Quant::Ticks::Serializers::Value.to_json(self)
-      end
-    end
-  end
-end