quantitative 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 19fe65cd5c50b0b503abaa0e7c5be3949a284cf5a2b537d79b9cbdd69448041d
-  data.tar.gz: fe03ed6b2ddef6609cee31547cd84c1eac948bb8d10efb8c24c316673c693a62
+  metadata.gz: 5bfe61d98618c7cfb83052426689976be38c45e83fce9217a74a4f0392897b60
+  data.tar.gz: 061d9a0179eb913c5f5f5d9f1016998c2cbc0d65da9a774620a3b591f18a1f49
 SHA512:
-  metadata.gz: 9ce1d965a8e68f6fae76143dfc619ed98c8a5af559e9f26c67dd7685e60bf9b4cfa3ecf5f43908f01597862cb6d6389cebd40cf5897afed560a9e54ed79ea91e
-  data.tar.gz: ee8527e43aa4670175d20a20c6037af11227071ff0fe738344c4b9b91d2391335d210a9e5b305153e78edc75ca9acb802b56b2502223107a84366ae40ba55b7f
+  metadata.gz: 4154a9e589bcffd15b3415ace9c1ccc6b8d29ba5ecc0180e48259c649a746a157f58bd89aeabad4ffc4ac5edefe6f1892c94adcd001ba5d1f039a5bb46a8a9d0
+  data.tar.gz: 7ac2b4661e6c4b0e02fda9389f73b8d007b92e754e8b4fa821bb55dca1d085dfd7e2e3eb6608d520a2e2e6008eb837aa75e7c07c05addc28af577b92fe98f8c3

data/Gemfile.lock

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

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/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

@@ -4,6 +4,10 @@ require_relative "tick"
 
 module Quant
   module Ticks
+    # 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
 
@@ -67,6 +71,11 @@ module Quant
         [open_timestamp, close_timestamp] == [other.open_timestamp, other.close_timestamp]
       end
 
+      # 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
+
       # 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.
@@ -120,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

@@ -3,7 +3,7 @@
 module Quant
   module Ticks
     module Serializers
-      class OHLC < Tick
+      module OHLC
         # Returns a +Quant::Ticks::Tick+ from a valid JSON +String+.
         # @param json [String]
         # @param tick_class [Quant::Ticks::Tick]

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

@@ -39,7 +39,7 @@ module Quant
           Oj.dump to_h(tick)
         end
 
-        # Returns a Ruby +Hash+ comprised of the tick's key properties.
+        # Returns a Ruby +Hash+ comprised of the key properties for the tick.
         # @param tick [Quant::Ticks::Tick]
         # @return [Hash]
         # @example

data/lib/quant/ticks/spot.rb

@@ -60,6 +60,7 @@ module Quant
       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
@@ -72,7 +73,7 @@ module Quant
       end
 
       def inspect
-        "#<#{self.class.name} cp=#{close_price.to_f} ct=#{close_timestamp.strftime("%Y-%m-%d")} iv=#{interval.to_s} v=#{volume}>"
+        "#<#{self.class.name} #{interval} ct=#{close_timestamp} c=#{close_price.to_f} v=#{volume}>"
       end
     end
   end

data/lib/quant/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: quantitative
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - Michael Lang
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-02-13 00:00:00.000000000 Z
+date: 2024-02-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: oj
@@ -56,7 +56,9 @@ files:
 - lib/quant/mixins/trig.rb
 - lib/quant/mixins/weighted_average.rb
 - lib/quant/refinements/array.rb
-- lib/quant/ticks/core.rb
+- lib/quant/security.rb
+- lib/quant/security_class.rb
+- lib/quant/series.rb
 - lib/quant/ticks/ohlc.rb
 - lib/quant/ticks/serializers/ohlc.rb
 - lib/quant/ticks/serializers/spot.rb
@@ -90,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