nba 0.1.1 → 0.2.0

data/lib/nba/play.rb

@@ -0,0 +1,258 @@
+module NBA
+  # Represents a single play in a game's play-by-play data
+  class Play < Shale::Mapper
+    include Equalizer.new(:game_id, :event_num)
+
+    # @!attribute [rw] game_id
+    #   Returns the game ID
+    #   @api public
+    #   @example
+    #     play.game_id #=> "0022400001"
+    #   @return [String] the game ID
+    attribute :game_id, Shale::Type::String
+
+    # @!attribute [rw] event_num
+    #   Returns the event number
+    #   @api public
+    #   @example
+    #     play.event_num #=> 1
+    #   @return [Integer] the event number
+    attribute :event_num, Shale::Type::Integer
+
+    # @!attribute [rw] event_msg_type
+    #   Returns the event message type
+    #   @api public
+    #   @example
+    #     play.event_msg_type #=> 2
+    #   @return [Integer] the event message type
+    attribute :event_msg_type, Shale::Type::Integer
+
+    # @!attribute [rw] event_msg_action_type
+    #   Returns the event message action type
+    #   @api public
+    #   @example
+    #     play.event_msg_action_type #=> 79
+    #   @return [Integer] the event message action type
+    attribute :event_msg_action_type, Shale::Type::Integer
+
+    # @!attribute [rw] period
+    #   Returns the period number
+    #   @api public
+    #   @example
+    #     play.period #=> 1
+    #   @return [Integer] the period number
+    attribute :period, Shale::Type::Integer
+
+    # @!attribute [rw] wc_time_string
+    #   Returns the wall clock time string
+    #   @api public
+    #   @example
+    #     play.wc_time_string #=> "8:05 PM"
+    #   @return [String] the wall clock time
+    attribute :wc_time_string, Shale::Type::String
+
+    # @!attribute [rw] pc_time_string
+    #   Returns the period clock time string
+    #   @api public
+    #   @example
+    #     play.pc_time_string #=> "11:45"
+    #   @return [String] the period clock time
+    attribute :pc_time_string, Shale::Type::String
+
+    # @!attribute [rw] home_description
+    #   Returns the home team's play description
+    #   @api public
+    #   @example
+    #     play.home_description #=> "Curry 3PT Jump Shot (3 PTS)"
+    #   @return [String] the home description
+    attribute :home_description, Shale::Type::String
+
+    # @!attribute [rw] neutral_description
+    #   Returns the neutral play description
+    #   @api public
+    #   @example
+    #     play.neutral_description #=> "Jump Ball"
+    #   @return [String] the neutral description
+    attribute :neutral_description, Shale::Type::String
+
+    # @!attribute [rw] visitor_description
+    #   Returns the visitor team's play description
+    #   @api public
+    #   @example
+    #     play.visitor_description #=> "James Turnover"
+    #   @return [String] the visitor description
+    attribute :visitor_description, Shale::Type::String
+
+    # @!attribute [rw] score
+    #   Returns the current score
+    #   @api public
+    #   @example
+    #     play.score #=> "105 - 102"
+    #   @return [String] the score (e.g., "105 - 102")
+    attribute :score, Shale::Type::String
+
+    # @!attribute [rw] score_margin
+    #   Returns the score margin
+    #   @api public
+    #   @example
+    #     play.score_margin #=> "3"
+    #   @return [String] the score margin
+    attribute :score_margin, Shale::Type::String
+
+    # @!attribute [rw] player1_id
+    #   Returns the first player's ID
+    #   @api public
+    #   @example
+    #     play.player1_id #=> 201939
+    #   @return [Integer] the player ID
+    attribute :player1_id, Shale::Type::Integer
+
+    # @!attribute [rw] player1_name
+    #   Returns the first player's name
+    #   @api public
+    #   @example
+    #     play.player1_name #=> "Stephen Curry"
+    #   @return [String] the player name
+    attribute :player1_name, Shale::Type::String
+
+    # @!attribute [rw] player1_team_id
+    #   Returns the first player's team ID
+    #   @api public
+    #   @example
+    #     play.player1_team_id #=> 1610612744
+    #   @return [Integer] the team ID
+    attribute :player1_team_id, Shale::Type::Integer
+
+    # @!attribute [rw] player1_team_abbreviation
+    #   Returns the first player's team abbreviation
+    #   @api public
+    #   @example
+    #     play.player1_team_abbreviation #=> "GSW"
+    #   @return [String] the team abbreviation
+    attribute :player1_team_abbreviation, Shale::Type::String
+
+    # @!attribute [rw] player2_id
+    #   Returns the second player's ID
+    #   @api public
+    #   @example
+    #     play.player2_id #=> 2544
+    #   @return [Integer] the player ID
+    attribute :player2_id, Shale::Type::Integer
+
+    # @!attribute [rw] player2_name
+    #   Returns the second player's name
+    #   @api public
+    #   @example
+    #     play.player2_name #=> "LeBron James"
+    #   @return [String] the player name
+    attribute :player2_name, Shale::Type::String
+
+    # @!attribute [rw] player2_team_id
+    #   Returns the second player's team ID
+    #   @api public
+    #   @example
+    #     play.player2_team_id #=> 1610612747
+    #   @return [Integer] the team ID
+    attribute :player2_team_id, Shale::Type::Integer
+
+    # @!attribute [rw] player2_team_abbreviation
+    #   Returns the second player's team abbreviation
+    #   @api public
+    #   @example
+    #     play.player2_team_abbreviation #=> "LAL"
+    #   @return [String] the team abbreviation
+    attribute :player2_team_abbreviation, Shale::Type::String
+
+    # @!attribute [rw] player3_id
+    #   Returns the third player's ID
+    #   @api public
+    #   @example
+    #     play.player3_id #=> 203507
+    #   @return [Integer] the player ID
+    attribute :player3_id, Shale::Type::Integer
+
+    # @!attribute [rw] player3_name
+    #   Returns the third player's name
+    #   @api public
+    #   @example
+    #     play.player3_name #=> "Draymond Green"
+    #   @return [String] the player name
+    attribute :player3_name, Shale::Type::String
+
+    # @!attribute [rw] player3_team_id
+    #   Returns the third player's team ID
+    #   @api public
+    #   @example
+    #     play.player3_team_id #=> 1610612744
+    #   @return [Integer] the team ID
+    attribute :player3_team_id, Shale::Type::Integer
+
+    # @!attribute [rw] player3_team_abbreviation
+    #   Returns the third player's team abbreviation
+    #   @api public
+    #   @example
+    #     play.player3_team_abbreviation #=> "GSW"
+    #   @return [String] the team abbreviation
+    attribute :player3_team_abbreviation, Shale::Type::String
+
+    # @!attribute [rw] video_available
+    #   Returns whether video is available for this play
+    #   @api public
+    #   @example
+    #     play.video_available #=> 1
+    #   @return [Integer] 1 if available, 0 if not
+    attribute :video_available, Shale::Type::Integer
+
+    # Returns the primary description for this play
+    #
+    # @api public
+    # @example
+    #   play.description #=> "Curry 3PT Jump Shot"
+    # @return [String, nil] the description
+    def description
+      home_description || visitor_description || neutral_description
+    end
+
+    # Returns the game object for this play
+    #
+    # @api public
+    # @example
+    #   play.game #=> #<NBA::Game>
+    # @return [Game, nil] the game object
+    def game
+      Games.find(game_id)
+    end
+
+    # Returns the first player involved in this play
+    #
+    # @api public
+    # @example
+    #   play.player1 #=> #<NBA::Player>
+    # @return [Player, nil] the player object
+    def player1
+      Players.find(player1_id)
+    end
+
+    # Returns the second player involved in this play
+    #
+    # @api public
+    # @example
+    #   play.player2 #=> #<NBA::Player>
+    # @return [Player, nil] the player object
+    def player2
+      Players.find(player2_id)
+    end
+
+    # Returns the third player involved in this play
+    #
+    # @api public
+    # @example
+    #   play.player3 #=> #<NBA::Player>
+    # @return [Player, nil] the player object
+    def player3
+      Players.find(player3_id)
+    end
+
+    alias_method :player, :player1
+  end
+end

data/lib/nba/play_by_play.rb

@@ -0,0 +1,85 @@
+require_relative "client"
+require_relative "response_parser"
+require_relative "play"
+require_relative "utils"
+
+module NBA
+  # Provides methods to retrieve play-by-play data for games
+  module PlayByPlay
+    # Result set name for play-by-play data
+    # @return [String] the result set name
+    RESULT_SET_NAME = "PlayByPlay".freeze
+
+    # Retrieves play-by-play data for a game
+    #
+    # @api public
+    # @example
+    #   plays = NBA::PlayByPlay.find(game: "0022400001")
+    #   plays.each { |p| puts "#{p.pc_time_string}: #{p.description}" }
+    # @param game [String, Game] the game ID or Game object
+    # @param start_period [Integer] the starting period (default 1)
+    # @param end_period [Integer] the ending period (default 10)
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of plays
+    def self.find(game:, start_period: 1, end_period: 10, client: CLIENT)
+      path = "playbyplayv2?GameID=#{Utils.extract_id(game)}&StartPeriod=#{start_period}&EndPeriod=#{end_period}"
+      ResponseParser.parse(client.get(path), result_set: RESULT_SET_NAME) { |data| build_play(data) }
+    end
+
+    # Builds a play from API data
+    # @api private
+    # @return [Play]
+    def self.build_play(data)
+      Play.new(**event_info(data), **descriptions(data), **player1_info(data),
+        **player2_info(data), **player3_info(data))
+    end
+    private_class_method :build_play
+
+    # Extracts event information from data
+    # @api private
+    # @return [Hash]
+    def self.event_info(data)
+      {game_id: data["GAME_ID"], event_num: data["EVENTNUM"], event_msg_type: data["EVENTMSGTYPE"],
+       event_msg_action_type: data["EVENTMSGACTIONTYPE"], period: data["PERIOD"],
+       wc_time_string: data["WCTIMESTRING"], pc_time_string: data["PCTIMESTRING"]}
+    end
+    private_class_method :event_info
+
+    # Extracts description attributes from data
+    # @api private
+    # @return [Hash]
+    def self.descriptions(data)
+      {home_description: data["HOMEDESCRIPTION"], neutral_description: data["NEUTRALDESCRIPTION"],
+       visitor_description: data["VISITORDESCRIPTION"], score: data["SCORE"],
+       score_margin: data["SCOREMARGIN"], video_available: data["VIDEO_AVAILABLE_FLAG"]}
+    end
+    private_class_method :descriptions
+
+    # Extracts player 1 information from data
+    # @api private
+    # @return [Hash]
+    def self.player1_info(data)
+      {player1_id: data["PLAYER1_ID"], player1_name: data["PLAYER1_NAME"],
+       player1_team_id: data["PLAYER1_TEAM_ID"], player1_team_abbreviation: data["PLAYER1_TEAM_ABBREVIATION"]}
+    end
+    private_class_method :player1_info
+
+    # Extracts player 2 information from data
+    # @api private
+    # @return [Hash]
+    def self.player2_info(data)
+      {player2_id: data["PLAYER2_ID"], player2_name: data["PLAYER2_NAME"],
+       player2_team_id: data["PLAYER2_TEAM_ID"], player2_team_abbreviation: data["PLAYER2_TEAM_ABBREVIATION"]}
+    end
+    private_class_method :player2_info
+
+    # Extracts player 3 information from data
+    # @api private
+    # @return [Hash]
+    def self.player3_info(data)
+      {player3_id: data["PLAYER3_ID"], player3_name: data["PLAYER3_NAME"],
+       player3_team_id: data["PLAYER3_TEAM_ID"], player3_team_abbreviation: data["PLAYER3_TEAM_ABBREVIATION"]}
+    end
+    private_class_method :player3_info
+  end
+end

data/lib/nba/play_by_play_v3.rb

@@ -0,0 +1,91 @@
+require_relative "client"
+require_relative "response_parser"
+require_relative "play"
+require_relative "utils"
+
+module NBA
+  # Provides methods to retrieve play-by-play V3 data for games
+  module PlayByPlayV3
+    # Result set name for play-by-play data
+    # @return [String] the result set name
+    RESULT_SET_NAME = "PlayByPlay".freeze
+
+    # Retrieves play-by-play V3 data for a game
+    #
+    # @api public
+    # @example
+    #   plays = NBA::PlayByPlayV3.find(game: "0022400001")
+    #   plays.each { |p| puts "#{p.pc_time_string}: #{p.description}" }
+    # @param game [String, Game] the game ID or Game object
+    # @param start_period [Integer] the starting period (default 0)
+    # @param end_period [Integer] the ending period (default 14)
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of plays
+    def self.find(game:, start_period: 0, end_period: 14, client: CLIENT)
+      path = "playbyplayv3?GameID=#{Utils.extract_id(game)}&StartPeriod=#{start_period}&EndPeriod=#{end_period}"
+      ResponseParser.parse(client.get(path), result_set: RESULT_SET_NAME) { |data| build_play(data) }
+    end
+
+    # Builds a play from API data
+    # @api private
+    # @param data [Hash] the row data
+    # @return [Play] the play object
+    def self.build_play(data)
+      Play.new(**event_info(data), **descriptions(data), **player1_info(data),
+        **player2_info(data), **player3_info(data))
+    end
+    private_class_method :build_play
+
+    # Extracts event information from data
+    # @api private
+    # @param data [Hash] the row data
+    # @return [Hash] event info attributes
+    def self.event_info(data)
+      {game_id: data["GAME_ID"], event_num: data["EVENTNUM"], event_msg_type: data["EVENTMSGTYPE"],
+       event_msg_action_type: data["EVENTMSGACTIONTYPE"], period: data["PERIOD"],
+       wc_time_string: data["WCTIMESTRING"], pc_time_string: data["PCTIMESTRING"]}
+    end
+    private_class_method :event_info
+
+    # Extracts description attributes from data
+    # @api private
+    # @param data [Hash] the row data
+    # @return [Hash] description attributes
+    def self.descriptions(data)
+      {home_description: data["HOMEDESCRIPTION"], neutral_description: data["NEUTRALDESCRIPTION"],
+       visitor_description: data["VISITORDESCRIPTION"], score: data["SCORE"],
+       score_margin: data["SCOREMARGIN"], video_available: data["VIDEO_AVAILABLE_FLAG"]}
+    end
+    private_class_method :descriptions
+
+    # Extracts player 1 information from data
+    # @api private
+    # @param data [Hash] the row data
+    # @return [Hash] player 1 attributes
+    def self.player1_info(data)
+      {player1_id: data["PLAYER1_ID"], player1_name: data["PLAYER1_NAME"],
+       player1_team_id: data["PLAYER1_TEAM_ID"], player1_team_abbreviation: data["PLAYER1_TEAM_ABBREVIATION"]}
+    end
+    private_class_method :player1_info
+
+    # Extracts player 2 information from data
+    # @api private
+    # @param data [Hash] the row data
+    # @return [Hash] player 2 attributes
+    def self.player2_info(data)
+      {player2_id: data["PLAYER2_ID"], player2_name: data["PLAYER2_NAME"],
+       player2_team_id: data["PLAYER2_TEAM_ID"], player2_team_abbreviation: data["PLAYER2_TEAM_ABBREVIATION"]}
+    end
+    private_class_method :player2_info
+
+    # Extracts player 3 information from data
+    # @api private
+    # @param data [Hash] the row data
+    # @return [Hash] player 3 attributes
+    def self.player3_info(data)
+      {player3_id: data["PLAYER3_ID"], player3_name: data["PLAYER3_NAME"],
+       player3_team_id: data["PLAYER3_TEAM_ID"], player3_team_abbreviation: data["PLAYER3_TEAM_ABBREVIATION"]}
+    end
+    private_class_method :player3_info
+  end
+end

data/lib/nba/play_type_stat.rb

@@ -0,0 +1,206 @@
+module NBA
+  # Represents synergy play type statistics
+  class PlayTypeStat < Shale::Mapper
+    include Equalizer.new(:player_id, :play_type, :type_grouping)
+
+    # @!attribute [rw] player_id
+    #   Returns the player ID
+    #   @api public
+    #   @example
+    #     stat.player_id #=> 201939
+    #   @return [Integer] the player 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] the player name
+    attribute :player_name, Shale::Type::String
+
+    # @!attribute [rw] team_id
+    #   Returns the team ID
+    #   @api public
+    #   @example
+    #     stat.team_id #=> 1610612744
+    #   @return [Integer] the team ID
+    attribute :team_id, Shale::Type::Integer
+
+    # @!attribute [rw] team_abbreviation
+    #   Returns the team abbreviation
+    #   @api public
+    #   @example
+    #     stat.team_abbreviation #=> "GSW"
+    #   @return [String] the team abbreviation
+    attribute :team_abbreviation, Shale::Type::String
+
+    # @!attribute [rw] play_type
+    #   Returns the play type
+    #   @api public
+    #   @example
+    #     stat.play_type #=> "Isolation"
+    #   @return [String] the play type
+    attribute :play_type, Shale::Type::String
+
+    # @!attribute [rw] type_grouping
+    #   Returns the type grouping (Offensive or Defensive)
+    #   @api public
+    #   @example
+    #     stat.type_grouping #=> "offensive"
+    #   @return [String] the type grouping
+    attribute :type_grouping, Shale::Type::String
+
+    # @!attribute [rw] gp
+    #   Returns games played
+    #   @api public
+    #   @example
+    #     stat.gp #=> 74
+    #   @return [Integer] games played
+    attribute :gp, Shale::Type::Integer
+
+    # @!attribute [rw] poss
+    #   Returns possessions
+    #   @api public
+    #   @example
+    #     stat.poss #=> 150
+    #   @return [Integer] possessions
+    attribute :poss, Shale::Type::Integer
+
+    # @!attribute [rw] poss_pct
+    #   Returns possession percentage
+    #   @api public
+    #   @example
+    #     stat.poss_pct #=> 0.15
+    #   @return [Float] possession percentage
+    attribute :poss_pct, Shale::Type::Float
+
+    # @!attribute [rw] pts
+    #   Returns points
+    #   @api public
+    #   @example
+    #     stat.pts #=> 180
+    #   @return [Integer] points
+    attribute :pts, Shale::Type::Integer
+
+    # @!attribute [rw] pts_pct
+    #   Returns points percentage
+    #   @api public
+    #   @example
+    #     stat.pts_pct #=> 0.20
+    #   @return [Float] points percentage
+    attribute :pts_pct, Shale::Type::Float
+
+    # @!attribute [rw] fgm
+    #   Returns field goals made
+    #   @api public
+    #   @example
+    #     stat.fgm #=> 60
+    #   @return [Integer] field goals made
+    attribute :fgm, Shale::Type::Integer
+
+    # @!attribute [rw] fga
+    #   Returns field goals attempted
+    #   @api public
+    #   @example
+    #     stat.fga #=> 130
+    #   @return [Integer] field goals attempted
+    attribute :fga, Shale::Type::Integer
+
+    # @!attribute [rw] fg_pct
+    #   Returns field goal percentage
+    #   @api public
+    #   @example
+    #     stat.fg_pct #=> 0.462
+    #   @return [Float] field goal percentage
+    attribute :fg_pct, Shale::Type::Float
+
+    # @!attribute [rw] efg_pct
+    #   Returns effective field goal percentage
+    #   @api public
+    #   @example
+    #     stat.efg_pct #=> 0.538
+    #   @return [Float] effective field goal percentage
+    attribute :efg_pct, Shale::Type::Float
+
+    # @!attribute [rw] ft_poss_pct
+    #   Returns free throw possession percentage
+    #   @api public
+    #   @example
+    #     stat.ft_poss_pct #=> 0.12
+    #   @return [Float] free throw possession percentage
+    attribute :ft_poss_pct, Shale::Type::Float
+
+    # @!attribute [rw] tov_poss_pct
+    #   Returns turnover possession percentage
+    #   @api public
+    #   @example
+    #     stat.tov_poss_pct #=> 0.08
+    #   @return [Float] turnover possession percentage
+    attribute :tov_poss_pct, Shale::Type::Float
+
+    # @!attribute [rw] sf_poss_pct
+    #   Returns shooting foul possession percentage
+    #   @api public
+    #   @example
+    #     stat.sf_poss_pct #=> 0.10
+    #   @return [Float] shooting foul possession percentage
+    attribute :sf_poss_pct, Shale::Type::Float
+
+    # @!attribute [rw] ppp
+    #   Returns points per possession
+    #   @api public
+    #   @example
+    #     stat.ppp #=> 1.2
+    #   @return [Float] points per possession
+    attribute :ppp, Shale::Type::Float
+
+    # @!attribute [rw] percentile
+    #   Returns the percentile ranking
+    #   @api public
+    #   @example
+    #     stat.percentile #=> 0.85
+    #   @return [Float] percentile
+    attribute :percentile, Shale::Type::Float
+
+    # Returns the player object
+    #
+    # @api public
+    # @example
+    #   stat.player #=> #<NBA::Player>
+    # @return [Player, nil] the player object
+    def player
+      Players.find(player_id)
+    end
+
+    # Returns the team object
+    #
+    # @api public
+    # @example
+    #   stat.team #=> #<NBA::Team>
+    # @return [Team, nil] the team object
+    def team
+      Teams.find(team_id)
+    end
+
+    # Returns whether this is offensive play type
+    #
+    # @api public
+    # @example
+    #   stat.offensive? #=> true
+    # @return [Boolean] true if offensive
+    def offensive?
+      type_grouping.eql?("offensive")
+    end
+
+    # Returns whether this is defensive play type
+    #
+    # @api public
+    # @example
+    #   stat.defensive? #=> true
+    # @return [Boolean] true if defensive
+    def defensive?
+      type_grouping.eql?("defensive")
+    end
+  end
+end