nba 0.1.1 → 0.2.0

data/lib/nba/league_dash_pt_defend_stat.rb

@@ -0,0 +1,145 @@
+require "equalizer"
+require "shale"
+require_relative "players"
+require_relative "teams"
+
+module NBA
+  # Represents league-wide player defensive statistics
+  #
+  # @api public
+  class LeagueDashPtDefendStat < Shale::Mapper
+    include Equalizer.new(:player_id, :team_id)
+
+    # @!attribute [rw] player_id
+    #   Returns the player ID (close defender)
+    #   @api public
+    #   @example
+    #     stat.player_id #=> 201939
+    #   @return [Integer, nil] the player's ID
+    attribute :player_id, Shale::Type::Integer
+
+    # @!attribute [rw] player_name
+    #   Returns the player name
+    #   @api public
+    #   @example
+    #     stat.player_name #=> "Stephen Curry"
+    #   @return [String, nil] the player's name
+    attribute :player_name, Shale::Type::String
+
+    # @!attribute [rw] team_id
+    #   Returns the player's last team ID
+    #   @api public
+    #   @example
+    #     stat.team_id #=> 1610612744
+    #   @return [Integer, nil] the team's ID
+    attribute :team_id, Shale::Type::Integer
+
+    # @!attribute [rw] team_abbreviation
+    #   Returns the player's last team abbreviation
+    #   @api public
+    #   @example
+    #     stat.team_abbreviation #=> "GSW"
+    #   @return [String, nil] the team's abbreviation
+    attribute :team_abbreviation, Shale::Type::String
+
+    # @!attribute [rw] player_position
+    #   Returns the player's position
+    #   @api public
+    #   @example
+    #     stat.player_position #=> "G"
+    #   @return [String, nil] the player's position
+    attribute :player_position, Shale::Type::String
+
+    # @!attribute [rw] age
+    #   Returns the player's age
+    #   @api public
+    #   @example
+    #     stat.age #=> 36.0
+    #   @return [Float, nil] the player's age
+    attribute :age, Shale::Type::Float
+
+    # @!attribute [rw] gp
+    #   Returns games played
+    #   @api public
+    #   @example
+    #     stat.gp #=> 82
+    #   @return [Integer, nil] games played
+    attribute :gp, Shale::Type::Integer
+
+    # @!attribute [rw] g
+    #   Returns games (alias for games played)
+    #   @api public
+    #   @example
+    #     stat.g #=> 82
+    #   @return [Integer, nil] games
+    attribute :g, Shale::Type::Integer
+
+    # @!attribute [rw] freq
+    #   Returns frequency percentage
+    #   @api public
+    #   @example
+    #     stat.freq #=> 0.089
+    #   @return [Float, nil] frequency percentage
+    attribute :freq, Shale::Type::Float
+
+    # @!attribute [rw] d_fgm
+    #   Returns defended field goals made
+    #   @api public
+    #   @example
+    #     stat.d_fgm #=> 245
+    #   @return [Float, nil] defended field goals made
+    attribute :d_fgm, Shale::Type::Float
+
+    # @!attribute [rw] d_fga
+    #   Returns defended field goals attempted
+    #   @api public
+    #   @example
+    #     stat.d_fga #=> 612
+    #   @return [Float, nil] defended field goals attempted
+    attribute :d_fga, Shale::Type::Float
+
+    # @!attribute [rw] d_fg_pct
+    #   Returns defended field goal percentage
+    #   @api public
+    #   @example
+    #     stat.d_fg_pct #=> 0.400
+    #   @return [Float, nil] defended field goal percentage
+    attribute :d_fg_pct, Shale::Type::Float
+
+    # @!attribute [rw] normal_fg_pct
+    #   Returns normal (uncontested) field goal percentage
+    #   @api public
+    #   @example
+    #     stat.normal_fg_pct #=> 0.450
+    #   @return [Float, nil] normal field goal percentage
+    attribute :normal_fg_pct, Shale::Type::Float
+
+    # @!attribute [rw] pct_plusminus
+    #   Returns percentage plus/minus (difference from normal)
+    #   @api public
+    #   @example
+    #     stat.pct_plusminus #=> -0.050
+    #   @return [Float, nil] percentage plus/minus
+    attribute :pct_plusminus, Shale::Type::Float
+
+    # Returns the player
+    #
+    # @api public
+    # @example
+    #   stat.player #=> #<NBA::Player id=201939 ...>
+    # @return [Player, nil] the player object
+    def player
+      Players.find(player_id)
+    end
+
+    # Returns the team
+    #
+    # @api public
+    # @example
+    #   stat.team #=> #<NBA::Team id=1610612744 ...>
+    # @return [Team, nil] the team object
+    def team
+      Teams.find(team_id)
+    end
+  end
+end

data/lib/nba/league_dash_pt_stats.rb

@@ -0,0 +1,152 @@
+require "json"
+require_relative "client"
+require_relative "collection"
+require_relative "league_dash_pt_stats_stat"
+require_relative "utils"
+
+module NBA
+  # Provides methods to retrieve league-wide player and team tracking statistics
+  #
+  # @api public
+  module LeagueDashPtStats
+    # Result set name for league dash PT stats
+    # @return [String] the result set name
+    LEAGUE_DASH_PT_STATS = "LeagueDashPtStats".freeze
+
+    # Regular season type constant
+    # @return [String] the season type
+    REGULAR_SEASON = "Regular Season".freeze
+
+    # Playoffs season type constant
+    # @return [String] the season type
+    PLAYOFFS = "Playoffs".freeze
+
+    # Per game mode constant
+    # @return [String] the per mode
+    PER_GAME = "PerGame".freeze
+
+    # Totals mode constant
+    # @return [String] the per mode
+    TOTALS = "Totals".freeze
+
+    # Player mode constant
+    # @return [String] the player or team mode
+    PLAYER = "Player".freeze
+
+    # Team mode constant
+    # @return [String] the player or team mode
+    TEAM = "Team".freeze
+
+    # Speed and distance measure type constant
+    # @return [String] the PT measure type
+    SPEED_DISTANCE = "SpeedDistance".freeze
+
+    # Retrieves all league-wide player or team tracking statistics
+    #
+    # @api public
+    # @example
+    #   stats = NBA::LeagueDashPtStats.all(season: 2024)
+    #   stats.first.avg_speed #=> 4.25
+    # @param season [Integer] the season year
+    # @param season_type [String] the season type
+    # @param per_mode [String] the per mode
+    # @param player_or_team [String] whether to get player or team stats
+    # @param pt_measure_type [String] the PT measure type
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of tracking statistics
+    def self.all(season: Utils.current_season, season_type: REGULAR_SEASON, per_mode: PER_GAME,
+      player_or_team: PLAYER, pt_measure_type: SPEED_DISTANCE, client: CLIENT)
+      path = build_path(season, season_type: season_type, per_mode: per_mode,
+        player_or_team: player_or_team, pt_measure_type: pt_measure_type)
+      response = client.get(path)
+      parse_response(response)
+    end
+
+    # Builds the API request path
+    #
+    # @api private
+    # @return [String] the request path
+    def self.build_path(season, opts)
+      season_str = Utils.format_season(season)
+      "leaguedashptstats?LeagueID=00&Season=#{season_str}" \
+        "&SeasonType=#{opts.fetch(:season_type)}" \
+        "&PerMode=#{opts.fetch(:per_mode)}&PlayerOrTeam=#{opts.fetch(:player_or_team)}" \
+        "&PtMeasureType=#{opts.fetch(:pt_measure_type)}"
+    end
+    private_class_method :build_path
+
+    # Parses the API response into stat objects
+    #
+    # @api private
+    # @return [Collection] collection of PT stats
+    def self.parse_response(response)
+      return Collection.new if response.nil? || response.empty?
+
+      data = JSON.parse(response)
+      result_set = find_result_set(data)
+      build_stats(result_set)
+    end
+    private_class_method :parse_response
+
+    # Finds the result set by name
+    #
+    # @api private
+    # @return [Hash, nil] the result set hash or nil if not found
+    def self.find_result_set(data)
+      result_sets = data["resultSets"]
+      return unless result_sets
+
+      result_sets.find { |rs| rs["name"].eql?(LEAGUE_DASH_PT_STATS) }
+    end
+    private_class_method :find_result_set
+
+    # Builds stats collection from result set
+    #
+    # @api private
+    # @return [Collection] the stats collection
+    def self.build_stats(result_set)
+      return Collection.new unless result_set
+
+      headers = result_set["headers"]
+      rows = result_set["rowSet"]
+      return Collection.new unless headers && rows
+
+      Collection.new(rows.map { |row| build_stat(headers.zip(row).to_h) })
+    end
+    private_class_method :build_stats
+
+    # Builds a single stat object from API data
+    #
+    # @api private
+    # @return [LeagueDashPtStatsStat] the stat object
+    def self.build_stat(data)
+      LeagueDashPtStatsStat.new(**identity_info(data), **speed_info(data))
+    end
+    private_class_method :build_stat
+
+    # Extracts identity information from data
+    #
+    # @api private
+    # @return [Hash] the identity information hash
+    def self.identity_info(data)
+      {player_id: data["PLAYER_ID"], player_name: data["PLAYER_NAME"],
+       team_id: data["TEAM_ID"], team_abbreviation: data["TEAM_ABBREVIATION"],
+       team_name: data["TEAM_NAME"], age: data["AGE"],
+       gp: data["GP"], w: data["W"], l: data["L"],
+       min: data["MIN"]}
+    end
+    private_class_method :identity_info
+
+    # Extracts speed and distance information from data
+    #
+    # @api private
+    # @return [Hash] the speed and distance statistics hash
+    def self.speed_info(data)
+      {dist_feet: data["DIST_FEET"], dist_miles: data["DIST_MILES"],
+       dist_miles_off: data["DIST_MILES_OFF"], dist_miles_def: data["DIST_MILES_DEF"],
+       avg_speed: data["AVG_SPEED"], avg_speed_off: data["AVG_SPEED_OFF"],
+       avg_speed_def: data["AVG_SPEED_DEF"]}
+    end
+    private_class_method :speed_info
+  end
+end

data/lib/nba/league_dash_pt_stats_stat.rb

@@ -0,0 +1,169 @@
+require "equalizer"
+require "shale"
+require_relative "players"
+require_relative "teams"
+
+module NBA
+  # Represents league-wide player or team speed and distance tracking statistics
+  #
+  # @api public
+  class LeagueDashPtStatsStat < Shale::Mapper
+    include Equalizer.new(:player_id, :team_id)
+
+    # @!attribute [rw] player_id
+    #   Returns the player ID (for player mode)
+    #   @api public
+    #   @example
+    #     stat.player_id #=> 201939
+    #   @return [Integer, nil] the player's ID
+    attribute :player_id, Shale::Type::Integer
+
+    # @!attribute [rw] player_name
+    #   Returns the player name (for player mode)
+    #   @api public
+    #   @example
+    #     stat.player_name #=> "Stephen Curry"
+    #   @return [String, nil] the player's name
+    attribute :player_name, Shale::Type::String
+
+    # @!attribute [rw] team_id
+    #   Returns the team ID
+    #   @api public
+    #   @example
+    #     stat.team_id #=> 1610612744
+    #   @return [Integer, nil] the team's ID
+    attribute :team_id, Shale::Type::Integer
+
+    # @!attribute [rw] team_abbreviation
+    #   Returns the team abbreviation
+    #   @api public
+    #   @example
+    #     stat.team_abbreviation #=> "GSW"
+    #   @return [String, nil] the team's abbreviation
+    attribute :team_abbreviation, Shale::Type::String
+
+    # @!attribute [rw] team_name
+    #   Returns the team name (for team mode)
+    #   @api public
+    #   @example
+    #     stat.team_name #=> "Golden State Warriors"
+    #   @return [String, nil] the team's name
+    attribute :team_name, Shale::Type::String
+
+    # @!attribute [rw] age
+    #   Returns the player's age (for player mode)
+    #   @api public
+    #   @example
+    #     stat.age #=> 36.0
+    #   @return [Float, nil] the player's age
+    attribute :age, Shale::Type::Float
+
+    # @!attribute [rw] gp
+    #   Returns games played
+    #   @api public
+    #   @example
+    #     stat.gp #=> 82
+    #   @return [Integer, nil] games played
+    attribute :gp, Shale::Type::Integer
+
+    # @!attribute [rw] w
+    #   Returns wins
+    #   @api public
+    #   @example
+    #     stat.w #=> 50
+    #   @return [Integer, nil] wins
+    attribute :w, Shale::Type::Integer
+
+    # @!attribute [rw] l
+    #   Returns losses
+    #   @api public
+    #   @example
+    #     stat.l #=> 32
+    #   @return [Integer, nil] losses
+    attribute :l, Shale::Type::Integer
+
+    # @!attribute [rw] min
+    #   Returns minutes played
+    #   @api public
+    #   @example
+    #     stat.min #=> 32.5
+    #   @return [Float, nil] minutes played
+    attribute :min, Shale::Type::Float
+
+    # @!attribute [rw] dist_feet
+    #   Returns distance traveled in feet
+    #   @api public
+    #   @example
+    #     stat.dist_feet #=> 12500.5
+    #   @return [Float, nil] distance in feet
+    attribute :dist_feet, Shale::Type::Float
+
+    # @!attribute [rw] dist_miles
+    #   Returns distance traveled in miles
+    #   @api public
+    #   @example
+    #     stat.dist_miles #=> 2.37
+    #   @return [Float, nil] distance in miles
+    attribute :dist_miles, Shale::Type::Float
+
+    # @!attribute [rw] dist_miles_off
+    #   Returns distance traveled on offense in miles
+    #   @api public
+    #   @example
+    #     stat.dist_miles_off #=> 1.15
+    #   @return [Float, nil] distance on offense in miles
+    attribute :dist_miles_off, Shale::Type::Float
+
+    # @!attribute [rw] dist_miles_def
+    #   Returns distance traveled on defense in miles
+    #   @api public
+    #   @example
+    #     stat.dist_miles_def #=> 1.22
+    #   @return [Float, nil] distance on defense in miles
+    attribute :dist_miles_def, Shale::Type::Float
+
+    # @!attribute [rw] avg_speed
+    #   Returns average speed
+    #   @api public
+    #   @example
+    #     stat.avg_speed #=> 4.25
+    #   @return [Float, nil] average speed
+    attribute :avg_speed, Shale::Type::Float
+
+    # @!attribute [rw] avg_speed_off
+    #   Returns average speed on offense
+    #   @api public
+    #   @example
+    #     stat.avg_speed_off #=> 4.15
+    #   @return [Float, nil] average speed on offense
+    attribute :avg_speed_off, Shale::Type::Float
+
+    # @!attribute [rw] avg_speed_def
+    #   Returns average speed on defense
+    #   @api public
+    #   @example
+    #     stat.avg_speed_def #=> 4.35
+    #   @return [Float, nil] average speed on defense
+    attribute :avg_speed_def, Shale::Type::Float
+
+    # Returns the player
+    #
+    # @api public
+    # @example
+    #   stat.player #=> #<NBA::Player id=201939 ...>
+    # @return [Player, nil] the player object
+    def player
+      Players.find(player_id)
+    end
+
+    # Returns the team
+    #
+    # @api public
+    # @example
+    #   stat.team #=> #<NBA::Team id=1610612744 ...>
+    # @return [Team, nil] the team object
+    def team
+      Teams.find(team_id)
+    end
+  end
+end

data/lib/nba/league_dash_pt_team_defend.rb

@@ -0,0 +1,158 @@
+require "json"
+require_relative "client"
+require_relative "collection"
+require_relative "league_dash_pt_team_defend_stat"
+require_relative "utils"
+
+module NBA
+  # Provides methods to retrieve league-wide team defensive tracking statistics
+  #
+  # @api public
+  module LeagueDashPtTeamDefend
+    # Result set name for league dash PT team defend
+    # @return [String] the result set name
+    LEAGUE_DASH_PT_TEAM_DEFEND = "LeagueDashPtTeamDefend".freeze
+
+    # Regular season type constant
+    # @return [String] the season type
+    REGULAR_SEASON = "Regular Season".freeze
+
+    # Playoffs season type constant
+    # @return [String] the season type
+    PLAYOFFS = "Playoffs".freeze
+
+    # Per game mode constant
+    # @return [String] the per mode
+    PER_GAME = "PerGame".freeze
+
+    # Totals mode constant
+    # @return [String] the per mode
+    TOTALS = "Totals".freeze
+
+    # Overall defense category constant
+    # @return [String] the defense category
+    OVERALL = "Overall".freeze
+
+    # 3 Pointers defense category constant
+    # @return [String] the defense category
+    THREE_POINTERS = "3 Pointers".freeze
+
+    # 2 Pointers defense category constant
+    # @return [String] the defense category
+    TWO_POINTERS = "2 Pointers".freeze
+
+    # Less than 6ft defense category constant
+    # @return [String] the defense category
+    LESS_THAN_6FT = "Less Than 6Ft".freeze
+
+    # Less than 10ft defense category constant
+    # @return [String] the defense category
+    LESS_THAN_10FT = "Less Than 10Ft".freeze
+
+    # Greater than 15ft defense category constant
+    # @return [String] the defense category
+    GREATER_THAN_15FT = "Greater Than 15Ft".freeze
+
+    # Retrieves all league-wide team defensive tracking statistics
+    #
+    # @api public
+    # @example
+    #   stats = NBA::LeagueDashPtTeamDefend.all(season: 2024)
+    #   stats.first.d_fg_pct #=> 0.421
+    # @param season [Integer] the season year
+    # @param season_type [String] the season type
+    # @param per_mode [String] the per mode
+    # @param defense_category [String] the defense category
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of team defensive statistics
+    def self.all(season: Utils.current_season, season_type: REGULAR_SEASON, per_mode: PER_GAME,
+      defense_category: OVERALL, client: CLIENT)
+      path = build_path(season, season_type: season_type, per_mode: per_mode, defense_category: defense_category)
+      response = client.get(path)
+      parse_response(response)
+    end
+
+    # Builds the API request path
+    #
+    # @api private
+    # @return [String] the request path
+    def self.build_path(season, opts)
+      season_str = Utils.format_season(season)
+      "leaguedashptteamdefend?LeagueID=00&Season=#{season_str}" \
+        "&SeasonType=#{opts.fetch(:season_type)}" \
+        "&PerMode=#{opts.fetch(:per_mode)}&DefenseCategory=#{opts.fetch(:defense_category)}"
+    end
+    private_class_method :build_path
+
+    # Parses the API response into stat objects
+    #
+    # @api private
+    # @return [Collection] collection of PT team defend stats
+    def self.parse_response(response)
+      return Collection.new if response.nil? || response.empty?
+
+      data = JSON.parse(response)
+      result_set = find_result_set(data)
+      build_stats(result_set)
+    end
+    private_class_method :parse_response
+
+    # Finds the result set by name
+    #
+    # @api private
+    # @return [Hash, nil] the result set hash or nil if not found
+    def self.find_result_set(data)
+      result_sets = data["resultSets"]
+      return unless result_sets
+
+      result_sets.find { |rs| rs["name"].eql?(LEAGUE_DASH_PT_TEAM_DEFEND) }
+    end
+    private_class_method :find_result_set
+
+    # Builds stats collection from result set
+    #
+    # @api private
+    # @return [Collection] the stats collection
+    def self.build_stats(result_set)
+      return Collection.new unless result_set
+
+      headers = result_set["headers"]
+      rows = result_set["rowSet"]
+      return Collection.new unless headers && rows
+
+      Collection.new(rows.map { |row| build_stat(headers.zip(row).to_h) })
+    end
+    private_class_method :build_stats
+
+    # Builds a single stat object from API data
+    #
+    # @api private
+    # @return [LeagueDashPtTeamDefendStat] the stat object
+    def self.build_stat(data)
+      LeagueDashPtTeamDefendStat.new(**identity_info(data), **defensive_info(data))
+    end
+    private_class_method :build_stat
+
+    # Extracts identity information from data
+    #
+    # @api private
+    # @return [Hash] the identity information hash
+    def self.identity_info(data)
+      {team_id: data["TEAM_ID"], team_name: data["TEAM_NAME"],
+       team_abbreviation: data["TEAM_ABBREVIATION"],
+       gp: data["GP"], g: data["G"]}
+    end
+    private_class_method :identity_info
+
+    # Extracts defensive statistics information from data
+    #
+    # @api private
+    # @return [Hash] the defensive statistics hash
+    def self.defensive_info(data)
+      {freq: data["FREQ"], d_fgm: data["D_FGM"], d_fga: data["D_FGA"],
+       d_fg_pct: data["D_FG_PCT"], normal_fg_pct: data["NORMAL_FG_PCT"],
+       pct_plusminus: data["PCT_PLUSMINUS"]}
+    end
+    private_class_method :defensive_info
+  end
+end