nba 0.1.1 → 0.2.0

data/lib/nba/league_dash_pt_team_defend_stat.rb

@@ -0,0 +1,110 @@
+require "equalizer"
+require "shale"
+require_relative "teams"
+
+module NBA
+  # Represents league-wide team defensive statistics
+  #
+  # @api public
+  class LeagueDashPtTeamDefendStat < Shale::Mapper
+    include Equalizer.new(:team_id)
+
+    # @!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_name
+    #   Returns the team name
+    #   @api public
+    #   @example
+    #     stat.team_name #=> "Golden State Warriors"
+    #   @return [String, nil] the team's name
+    attribute :team_name, Shale::Type::String
+
+    # @!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] 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.0
+    #   @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.0
+    #   @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 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_team_clutch.rb

@@ -0,0 +1,211 @@
+require "json"
+require_relative "client"
+require_relative "collection"
+require_relative "league_dash_team_clutch_stat"
+require_relative "utils"
+
+module NBA
+  # Provides methods to retrieve league-wide clutch team statistics
+  module LeagueDashTeamClutch
+    # Result set name for league dash team clutch
+    # @return [String] the result set name
+    LEAGUE_DASH_TEAM_CLUTCH = "LeagueDashTeamClutch".freeze
+
+    # Season type constant for regular season
+    # @return [String] the season type
+    REGULAR_SEASON = "Regular Season".freeze
+
+    # Season type constant for playoffs
+    # @return [String] the season type
+    PLAYOFFS = "Playoffs".freeze
+
+    # Per mode constant for per game stats
+    # @return [String] the per mode
+    PER_GAME = "PerGame".freeze
+
+    # Per mode constant for totals
+    # @return [String] the per mode
+    TOTALS = "Totals".freeze
+
+    # Per mode constant for per 100 possessions
+    # @return [String] the per mode
+    PER_100 = "Per100Possessions".freeze
+
+    # Clutch time constant for last 5 minutes
+    # @return [String] the clutch time
+    LAST_5_MINUTES = "Last 5 Minutes".freeze
+
+    # Clutch time constant for last 4 minutes
+    # @return [String] the clutch time
+    LAST_4_MINUTES = "Last 4 Minutes".freeze
+
+    # Clutch time constant for last 3 minutes
+    # @return [String] the clutch time
+    LAST_3_MINUTES = "Last 3 Minutes".freeze
+
+    # Clutch time constant for last 2 minutes
+    # @return [String] the clutch time
+    LAST_2_MINUTES = "Last 2 Minutes".freeze
+
+    # Clutch time constant for last 1 minute
+    # @return [String] the clutch time
+    LAST_1_MINUTE = "Last 1 Minute".freeze
+
+    # Ahead/behind constant for ahead or behind
+    # @return [String] the ahead/behind value
+    AHEAD_OR_BEHIND = "Ahead or Behind".freeze
+
+    # Ahead/behind constant for behind or tied
+    # @return [String] the ahead/behind value
+    BEHIND_OR_TIED = "Behind or Tied".freeze
+
+    # Ahead/behind constant for ahead or tied
+    # @return [String] the ahead/behind value
+    AHEAD_OR_TIED = "Ahead or Tied".freeze
+
+    # Retrieves league-wide clutch team statistics
+    #
+    # @api public
+    # @example
+    #   stats = NBA::LeagueDashTeamClutch.all(season: 2024)
+    #   stats.each { |s| puts "#{s.team_name}: #{s.pts} clutch PPG" }
+    # @param season [Integer] the season year
+    # @param season_type [String] the season type
+    # @param clutch_time [String] the clutch time definition
+    # @param ahead_behind [String] the ahead/behind filter
+    # @param point_diff [Integer] the point differential
+    # @param per_mode [String] the per mode
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of clutch team stats
+    def self.all(season: Utils.current_season, season_type: REGULAR_SEASON, clutch_time: LAST_5_MINUTES,
+      ahead_behind: AHEAD_OR_BEHIND, point_diff: 5, per_mode: PER_GAME, client: CLIENT)
+      opts = {season_type: season_type, clutch_time: clutch_time, ahead_behind: ahead_behind,
+              point_diff: point_diff, per_mode: per_mode}
+      path = build_path(season, opts)
+      response = client.get(path)
+      parse_response(response, season)
+    end
+
+    # Builds the API path
+    #
+    # @api private
+    # @param season [Integer] the season year
+    # @param opts [Hash] the request options
+    # @return [String] the API path
+    def self.build_path(season, opts)
+      season_str = Utils.format_season(season)
+      "leaguedashteamclutch?LeagueID=00&Season=#{season_str}&SeasonType=#{opts.fetch(:season_type)}" \
+        "&ClutchTime=#{opts.fetch(:clutch_time)}&AheadBehind=#{opts.fetch(:ahead_behind)}" \
+        "&PointDiff=#{opts.fetch(:point_diff)}&PerMode=#{opts.fetch(:per_mode)}&MeasureType=Base"
+    end
+    private_class_method :build_path
+
+    # Parses the API response
+    #
+    # @api private
+    # @param response [String, nil] the JSON response body
+    # @param season [Integer] the season year
+    # @return [Collection] a collection of clutch team stats
+    def self.parse_response(response, season)
+      return Collection.new unless response
+
+      data = JSON.parse(response)
+      result_set = find_result_set(data)
+      return Collection.new unless result_set
+
+      build_stats(result_set, Utils.format_season(season))
+    end
+    private_class_method :parse_response
+
+    # Finds the result set
+    #
+    # @api private
+    # @param data [Hash] the parsed JSON data
+    # @return [Hash, nil] the result set
+    def self.find_result_set(data)
+      result_sets = data["resultSets"]
+      return unless result_sets
+
+      result_sets.find { |rs| rs["name"].eql?(LEAGUE_DASH_TEAM_CLUTCH) }
+    end
+    private_class_method :find_result_set
+
+    # Builds stats collection from result set
+    #
+    # @api private
+    # @param result_set [Hash] the result set
+    # @param season_id [String] the season ID
+    # @return [Collection] collection of clutch team stats
+    def self.build_stats(result_set, season_id)
+      headers = result_set["headers"]
+      rows = result_set["rowSet"]
+      return Collection.new unless headers && rows
+
+      stats = rows.map { |row| build_stat(headers, row, season_id) }
+      Collection.new(stats)
+    end
+    private_class_method :build_stats
+
+    # Builds a single clutch team stat
+    #
+    # @api private
+    # @param headers [Array<String>] the column headers
+    # @param row [Array] the row data
+    # @param season_id [String] the season ID
+    # @return [LeagueDashTeamClutchStat] the clutch team stat
+    def self.build_stat(headers, row, season_id)
+      data = headers.zip(row).to_h
+      LeagueDashTeamClutchStat.new(**stat_attributes(data, season_id))
+    end
+    private_class_method :build_stat
+
+    # Extracts all stat attributes
+    #
+    # @api private
+    # @param data [Hash] the stat data
+    # @param season_id [String] the season ID
+    # @return [Hash] the stat attributes
+    def self.stat_attributes(data, season_id)
+      identity_attributes(data, season_id).merge(shooting_attributes(data), counting_attributes(data))
+    end
+    private_class_method :stat_attributes
+
+    # Extracts identity attributes
+    #
+    # @api private
+    # @param data [Hash] the stat data
+    # @param season_id [String] the season ID
+    # @return [Hash] the identity attributes
+    def self.identity_attributes(data, season_id)
+      {team_id: data["TEAM_ID"], team_name: data["TEAM_NAME"],
+       gp: data["GP"], w: data["W"], l: data["L"],
+       w_pct: data["W_PCT"], min: data["MIN"], season_id: season_id}
+    end
+    private_class_method :identity_attributes
+
+    # Extracts shooting attributes
+    #
+    # @api private
+    # @param data [Hash] the stat data
+    # @return [Hash] the shooting attributes
+    def self.shooting_attributes(data)
+      {fgm: data["FGM"], fga: data["FGA"], fg_pct: data["FG_PCT"],
+       fg3m: data["FG3M"], fg3a: data["FG3A"], fg3_pct: data["FG3_PCT"],
+       ftm: data["FTM"], fta: data["FTA"], ft_pct: data["FT_PCT"]}
+    end
+    private_class_method :shooting_attributes
+
+    # Extracts counting stats attributes
+    #
+    # @api private
+    # @param data [Hash] the stat data
+    # @return [Hash] the counting attributes
+    def self.counting_attributes(data)
+      {oreb: data["OREB"], dreb: data["DREB"], reb: data["REB"],
+       ast: data["AST"], tov: data["TOV"], stl: data["STL"],
+       blk: data["BLK"], pf: data["PF"], pts: data["PTS"],
+       plus_minus: data["PLUS_MINUS"]}
+    end
+    private_class_method :counting_attributes
+  end
+end

data/lib/nba/league_dash_team_clutch_stat.rb

@@ -0,0 +1,237 @@
+require "equalizer"
+require "shale"
+
+module NBA
+  # Represents clutch-time team statistics
+  #
+  # @api public
+  class LeagueDashTeamClutchStat < Shale::Mapper
+    include Equalizer.new(:team_id, :season_id)
+
+    # @!attribute [rw] team_id
+    #   Returns the team ID
+    #   @api public
+    #   @example
+    #     stat.team_id #=> 1610612744
+    #   @return [Integer, nil] the team ID
+    attribute :team_id, Shale::Type::Integer
+
+    # @!attribute [rw] team_name
+    #   Returns the team name
+    #   @api public
+    #   @example
+    #     stat.team_name #=> "Golden State Warriors"
+    #   @return [String, nil] the team name
+    attribute :team_name, Shale::Type::String
+
+    # @!attribute [rw] season_id
+    #   Returns the season ID
+    #   @api public
+    #   @example
+    #     stat.season_id #=> "2024-25"
+    #   @return [String, nil] the season ID
+    attribute :season_id, Shale::Type::String
+
+    # @!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 #=> 46
+    #   @return [Integer, nil] wins
+    attribute :w, Shale::Type::Integer
+
+    # @!attribute [rw] l
+    #   Returns losses
+    #   @api public
+    #   @example
+    #     stat.l #=> 36
+    #   @return [Integer, nil] losses
+    attribute :l, Shale::Type::Integer
+
+    # @!attribute [rw] w_pct
+    #   Returns win percentage
+    #   @api public
+    #   @example
+    #     stat.w_pct #=> 0.561
+    #   @return [Float, nil] win percentage
+    attribute :w_pct, Shale::Type::Float
+
+    # @!attribute [rw] min
+    #   Returns minutes played
+    #   @api public
+    #   @example
+    #     stat.min #=> 5.0
+    #   @return [Float, nil] minutes played
+    attribute :min, Shale::Type::Float
+
+    # @!attribute [rw] fgm
+    #   Returns field goals made
+    #   @api public
+    #   @example
+    #     stat.fgm #=> 3.2
+    #   @return [Float, nil] field goals made
+    attribute :fgm, Shale::Type::Float
+
+    # @!attribute [rw] fga
+    #   Returns field goals attempted
+    #   @api public
+    #   @example
+    #     stat.fga #=> 7.5
+    #   @return [Float, nil] field goals attempted
+    attribute :fga, Shale::Type::Float
+
+    # @!attribute [rw] fg_pct
+    #   Returns field goal percentage
+    #   @api public
+    #   @example
+    #     stat.fg_pct #=> 0.427
+    #   @return [Float, nil] field goal percentage
+    attribute :fg_pct, Shale::Type::Float
+
+    # @!attribute [rw] fg3m
+    #   Returns three pointers made
+    #   @api public
+    #   @example
+    #     stat.fg3m #=> 1.2
+    #   @return [Float, nil] three pointers made
+    attribute :fg3m, Shale::Type::Float
+
+    # @!attribute [rw] fg3a
+    #   Returns three pointers attempted
+    #   @api public
+    #   @example
+    #     stat.fg3a #=> 3.5
+    #   @return [Float, nil] three pointers attempted
+    attribute :fg3a, Shale::Type::Float
+
+    # @!attribute [rw] fg3_pct
+    #   Returns three point percentage
+    #   @api public
+    #   @example
+    #     stat.fg3_pct #=> 0.343
+    #   @return [Float, nil] three point percentage
+    attribute :fg3_pct, Shale::Type::Float
+
+    # @!attribute [rw] ftm
+    #   Returns free throws made
+    #   @api public
+    #   @example
+    #     stat.ftm #=> 2.0
+    #   @return [Float, nil] free throws made
+    attribute :ftm, Shale::Type::Float
+
+    # @!attribute [rw] fta
+    #   Returns free throws attempted
+    #   @api public
+    #   @example
+    #     stat.fta #=> 2.5
+    #   @return [Float, nil] free throws attempted
+    attribute :fta, Shale::Type::Float
+
+    # @!attribute [rw] ft_pct
+    #   Returns free throw percentage
+    #   @api public
+    #   @example
+    #     stat.ft_pct #=> 0.800
+    #   @return [Float, nil] free throw percentage
+    attribute :ft_pct, Shale::Type::Float
+
+    # @!attribute [rw] oreb
+    #   Returns offensive rebounds
+    #   @api public
+    #   @example
+    #     stat.oreb #=> 0.8
+    #   @return [Float, nil] offensive rebounds
+    attribute :oreb, Shale::Type::Float
+
+    # @!attribute [rw] dreb
+    #   Returns defensive rebounds
+    #   @api public
+    #   @example
+    #     stat.dreb #=> 2.2
+    #   @return [Float, nil] defensive rebounds
+    attribute :dreb, Shale::Type::Float
+
+    # @!attribute [rw] reb
+    #   Returns total rebounds
+    #   @api public
+    #   @example
+    #     stat.reb #=> 3.0
+    #   @return [Float, nil] total rebounds
+    attribute :reb, Shale::Type::Float
+
+    # @!attribute [rw] ast
+    #   Returns assists
+    #   @api public
+    #   @example
+    #     stat.ast #=> 1.8
+    #   @return [Float, nil] assists
+    attribute :ast, Shale::Type::Float
+
+    # @!attribute [rw] tov
+    #   Returns turnovers
+    #   @api public
+    #   @example
+    #     stat.tov #=> 1.2
+    #   @return [Float, nil] turnovers
+    attribute :tov, Shale::Type::Float
+
+    # @!attribute [rw] stl
+    #   Returns steals
+    #   @api public
+    #   @example
+    #     stat.stl #=> 0.6
+    #   @return [Float, nil] steals
+    attribute :stl, Shale::Type::Float
+
+    # @!attribute [rw] blk
+    #   Returns blocks
+    #   @api public
+    #   @example
+    #     stat.blk #=> 0.3
+    #   @return [Float, nil] blocks
+    attribute :blk, Shale::Type::Float
+
+    # @!attribute [rw] pf
+    #   Returns personal fouls
+    #   @api public
+    #   @example
+    #     stat.pf #=> 1.5
+    #   @return [Float, nil] personal fouls
+    attribute :pf, Shale::Type::Float
+
+    # @!attribute [rw] pts
+    #   Returns points
+    #   @api public
+    #   @example
+    #     stat.pts #=> 9.6
+    #   @return [Float, nil] points
+    attribute :pts, Shale::Type::Float
+
+    # @!attribute [rw] plus_minus
+    #   Returns plus/minus
+    #   @api public
+    #   @example
+    #     stat.plus_minus #=> 0.8
+    #   @return [Float, nil] plus/minus
+    attribute :plus_minus, Shale::Type::Float
+
+    # Returns the team object
+    #
+    # @api public
+    # @example
+    #   stat.team #=> #<NBA::Team>
+    # @return [Team, nil] the team object
+    def team
+      Teams.find(team_id)
+    end
+  end
+end

data/lib/nba/league_dash_team_pt_shot.rb

@@ -0,0 +1,150 @@
+require "json"
+require_relative "client"
+require_relative "collection"
+require_relative "league_dash_team_pt_shot_stat"
+require_relative "utils"
+
+module NBA
+  # Provides methods to retrieve league-wide team tracking shot statistics
+  #
+  # @api public
+  module LeagueDashTeamPtShot
+    # Result set name for league dash team PT shots
+    # @return [String] the result set name
+    LEAGUE_DASH_PT_SHOTS = "LeagueDashPTShots".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
+
+    # Retrieves all league-wide team tracking shot statistics
+    #
+    # @api public
+    # @example
+    #   stats = NBA::LeagueDashTeamPtShot.all(season: 2024)
+    #   stats.first.fg_pct #=> 0.472
+    # @param season [Integer] the season year
+    # @param season_type [String] the season type
+    # @param per_mode [String] the per mode
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of team tracking shot statistics
+    def self.all(season: Utils.current_season, season_type: REGULAR_SEASON, per_mode: PER_GAME, client: CLIENT)
+      path = build_path(season, season_type: season_type, per_mode: per_mode)
+      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)
+      "leaguedashteamptshot?LeagueID=00&Season=#{season_str}" \
+        "&SeasonType=#{opts.fetch(:season_type)}&PerMode=#{opts.fetch(:per_mode)}"
+    end
+    private_class_method :build_path
+
+    # Parses the API response into stat objects
+    #
+    # @api private
+    # @return [Collection] collection of team PT shot 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_SHOTS) }
+    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 [LeagueDashTeamPtShotStat] the stat object
+    def self.build_stat(data)
+      LeagueDashTeamPtShotStat.new(**identity_info(data), **shooting_info(data), **two_point_info(data),
+        **three_point_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 shooting information from data
+    #
+    # @api private
+    # @return [Hash] the shooting information hash
+    def self.shooting_info(data)
+      {fga_frequency: data["FGA_FREQUENCY"], fgm: data["FGM"],
+       fga: data["FGA"], fg_pct: data["FG_PCT"], efg_pct: data["EFG_PCT"]}
+    end
+    private_class_method :shooting_info
+
+    # Extracts 2-point shooting information from data
+    #
+    # @api private
+    # @return [Hash] the 2-point shooting information hash
+    def self.two_point_info(data)
+      {fg2a_frequency: data["FG2A_FREQUENCY"], fg2m: data["FG2M"],
+       fg2a: data["FG2A"], fg2_pct: data["FG2_PCT"]}
+    end
+    private_class_method :two_point_info
+
+    # Extracts 3-point shooting information from data
+    #
+    # @api private
+    # @return [Hash] the 3-point shooting information hash
+    def self.three_point_info(data)
+      {fg3a_frequency: data["FG3A_FREQUENCY"], fg3m: data["FG3M"],
+       fg3a: data["FG3A"], fg3_pct: data["FG3_PCT"]}
+    end
+    private_class_method :three_point_info
+  end
+end