nba 0.1.1 → 0.2.0

data/lib/nba/league_dash_player_pt_shot_stat.rb

@@ -0,0 +1,193 @@
+require "equalizer"
+require "shale"
+require_relative "players"
+require_relative "teams"
+
+module NBA
+  # Represents league-wide player tracking shot statistics
+  #
+  # @api public
+  class LeagueDashPlayerPtShotStat < Shale::Mapper
+    include Equalizer.new(:player_id, :g)
+
+    # @!attribute [rw] player_id
+    #   Returns the player ID
+    #   @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] player_last_team_id
+    #   Returns the player's last team ID
+    #   @api public
+    #   @example
+    #     stat.player_last_team_id #=> 1610612744
+    #   @return [Integer, nil] the team's ID
+    attribute :player_last_team_id, Shale::Type::Integer
+
+    # @!attribute [rw] player_last_team_abbreviation
+    #   Returns the player's last team abbreviation
+    #   @api public
+    #   @example
+    #     stat.player_last_team_abbreviation #=> "GSW"
+    #   @return [String, nil] the team's abbreviation
+    attribute :player_last_team_abbreviation, Shale::Type::String
+
+    # @!attribute [rw] age
+    #   Returns the player's age
+    #   @api public
+    #   @example
+    #     stat.age #=> 36
+    #   @return [Float, nil] the player's age
+    attribute :age, Shale::Type::Float
+
+    # @!attribute [rw] gp
+    #   Returns games played
+    #   @api public
+    #   @example
+    #     stat.gp #=> 74
+    #   @return [Integer, nil] games played
+    attribute :gp, Shale::Type::Integer
+
+    # @!attribute [rw] g
+    #   Returns number of games
+    #   @api public
+    #   @example
+    #     stat.g #=> 74
+    #   @return [Integer, nil] games
+    attribute :g, Shale::Type::Integer
+
+    # @!attribute [rw] fga_frequency
+    #   Returns field goal attempt frequency
+    #   @api public
+    #   @example
+    #     stat.fga_frequency #=> 0.35
+    #   @return [Float, nil] field goal attempt frequency
+    attribute :fga_frequency, Shale::Type::Float
+
+    # @!attribute [rw] fgm
+    #   Returns field goals made
+    #   @api public
+    #   @example
+    #     stat.fgm #=> 7.2
+    #   @return [Float, nil] field goals made
+    attribute :fgm, Shale::Type::Float
+
+    # @!attribute [rw] fga
+    #   Returns field goals attempted
+    #   @api public
+    #   @example
+    #     stat.fga #=> 15.3
+    #   @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.472
+    #   @return [Float, nil] 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.561
+    #   @return [Float, nil] effective field goal percentage
+    attribute :efg_pct, Shale::Type::Float
+
+    # @!attribute [rw] fg2a_frequency
+    #   Returns 2-point field goal attempt frequency
+    #   @api public
+    #   @example
+    #     stat.fg2a_frequency #=> 0.45
+    #   @return [Float, nil] 2-point field goal attempt frequency
+    attribute :fg2a_frequency, Shale::Type::Float
+
+    # @!attribute [rw] fg2m
+    #   Returns 2-point field goals made
+    #   @api public
+    #   @example
+    #     stat.fg2m #=> 4.1
+    #   @return [Float, nil] 2-point field goals made
+    attribute :fg2m, Shale::Type::Float
+
+    # @!attribute [rw] fg2a
+    #   Returns 2-point field goals attempted
+    #   @api public
+    #   @example
+    #     stat.fg2a #=> 7.8
+    #   @return [Float, nil] 2-point field goals attempted
+    attribute :fg2a, Shale::Type::Float
+
+    # @!attribute [rw] fg2_pct
+    #   Returns 2-point field goal percentage
+    #   @api public
+    #   @example
+    #     stat.fg2_pct #=> 0.526
+    #   @return [Float, nil] 2-point field goal percentage
+    attribute :fg2_pct, Shale::Type::Float
+
+    # @!attribute [rw] fg3a_frequency
+    #   Returns 3-point field goal attempt frequency
+    #   @api public
+    #   @example
+    #     stat.fg3a_frequency #=> 0.55
+    #   @return [Float, nil] 3-point field goal attempt frequency
+    attribute :fg3a_frequency, Shale::Type::Float
+
+    # @!attribute [rw] fg3m
+    #   Returns 3-point field goals made
+    #   @api public
+    #   @example
+    #     stat.fg3m #=> 4.8
+    #   @return [Float, nil] 3-point field goals made
+    attribute :fg3m, Shale::Type::Float
+
+    # @!attribute [rw] fg3a
+    #   Returns 3-point field goals attempted
+    #   @api public
+    #   @example
+    #     stat.fg3a #=> 11.2
+    #   @return [Float, nil] 3-point field goals attempted
+    attribute :fg3a, Shale::Type::Float
+
+    # @!attribute [rw] fg3_pct
+    #   Returns 3-point field goal percentage
+    #   @api public
+    #   @example
+    #     stat.fg3_pct #=> 0.428
+    #   @return [Float, nil] 3-point field goal percentage
+    attribute :fg3_pct, 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 player's team
+    #
+    # @api public
+    # @example
+    #   stat.team #=> #<NBA::Team id=1610612744 ...>
+    # @return [Team, nil] the team object
+    def team
+      Teams.find(player_last_team_id)
+    end
+  end
+end

data/lib/nba/league_dash_player_shot_location_stat.rb

@@ -0,0 +1,265 @@
+require "equalizer"
+require "shale"
+require_relative "players"
+require_relative "teams"
+
+module NBA
+  # Represents league-wide player shot location statistics
+  #
+  # @api public
+  class LeagueDashPlayerShotLocationStat < Shale::Mapper
+    include Equalizer.new(:player_id, :team_id)
+
+    # @!attribute [rw] player_id
+    #   Returns the player ID
+    #   @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 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] 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] restricted_area_fgm
+    #   Returns restricted area field goals made
+    #   @api public
+    #   @example
+    #     stat.restricted_area_fgm #=> 2.5
+    #   @return [Float, nil] restricted area field goals made
+    attribute :restricted_area_fgm, Shale::Type::Float
+
+    # @!attribute [rw] restricted_area_fga
+    #   Returns restricted area field goals attempted
+    #   @api public
+    #   @example
+    #     stat.restricted_area_fga #=> 4.2
+    #   @return [Float, nil] restricted area field goals attempted
+    attribute :restricted_area_fga, Shale::Type::Float
+
+    # @!attribute [rw] restricted_area_fg_pct
+    #   Returns restricted area field goal percentage
+    #   @api public
+    #   @example
+    #     stat.restricted_area_fg_pct #=> 0.595
+    #   @return [Float, nil] restricted area field goal percentage
+    attribute :restricted_area_fg_pct, Shale::Type::Float
+
+    # @!attribute [rw] in_the_paint_non_ra_fgm
+    #   Returns in the paint (non-RA) field goals made
+    #   @api public
+    #   @example
+    #     stat.in_the_paint_non_ra_fgm #=> 1.2
+    #   @return [Float, nil] in the paint field goals made
+    attribute :in_the_paint_non_ra_fgm, Shale::Type::Float
+
+    # @!attribute [rw] in_the_paint_non_ra_fga
+    #   Returns in the paint (non-RA) field goals attempted
+    #   @api public
+    #   @example
+    #     stat.in_the_paint_non_ra_fga #=> 2.8
+    #   @return [Float, nil] in the paint field goals attempted
+    attribute :in_the_paint_non_ra_fga, Shale::Type::Float
+
+    # @!attribute [rw] in_the_paint_non_ra_fg_pct
+    #   Returns in the paint (non-RA) field goal percentage
+    #   @api public
+    #   @example
+    #     stat.in_the_paint_non_ra_fg_pct #=> 0.428
+    #   @return [Float, nil] in the paint field goal percentage
+    attribute :in_the_paint_non_ra_fg_pct, Shale::Type::Float
+
+    # @!attribute [rw] mid_range_fgm
+    #   Returns mid-range field goals made
+    #   @api public
+    #   @example
+    #     stat.mid_range_fgm #=> 0.8
+    #   @return [Float, nil] mid-range field goals made
+    attribute :mid_range_fgm, Shale::Type::Float
+
+    # @!attribute [rw] mid_range_fga
+    #   Returns mid-range field goals attempted
+    #   @api public
+    #   @example
+    #     stat.mid_range_fga #=> 2.1
+    #   @return [Float, nil] mid-range field goals attempted
+    attribute :mid_range_fga, Shale::Type::Float
+
+    # @!attribute [rw] mid_range_fg_pct
+    #   Returns mid-range field goal percentage
+    #   @api public
+    #   @example
+    #     stat.mid_range_fg_pct #=> 0.381
+    #   @return [Float, nil] mid-range field goal percentage
+    attribute :mid_range_fg_pct, Shale::Type::Float
+
+    # @!attribute [rw] left_corner_3_fgm
+    #   Returns left corner 3 field goals made
+    #   @api public
+    #   @example
+    #     stat.left_corner_3_fgm #=> 0.4
+    #   @return [Float, nil] left corner 3 field goals made
+    attribute :left_corner_3_fgm, Shale::Type::Float
+
+    # @!attribute [rw] left_corner_3_fga
+    #   Returns left corner 3 field goals attempted
+    #   @api public
+    #   @example
+    #     stat.left_corner_3_fga #=> 0.9
+    #   @return [Float, nil] left corner 3 field goals attempted
+    attribute :left_corner_3_fga, Shale::Type::Float
+
+    # @!attribute [rw] left_corner_3_fg_pct
+    #   Returns left corner 3 field goal percentage
+    #   @api public
+    #   @example
+    #     stat.left_corner_3_fg_pct #=> 0.444
+    #   @return [Float, nil] left corner 3 field goal percentage
+    attribute :left_corner_3_fg_pct, Shale::Type::Float
+
+    # @!attribute [rw] right_corner_3_fgm
+    #   Returns right corner 3 field goals made
+    #   @api public
+    #   @example
+    #     stat.right_corner_3_fgm #=> 0.3
+    #   @return [Float, nil] right corner 3 field goals made
+    attribute :right_corner_3_fgm, Shale::Type::Float
+
+    # @!attribute [rw] right_corner_3_fga
+    #   Returns right corner 3 field goals attempted
+    #   @api public
+    #   @example
+    #     stat.right_corner_3_fga #=> 0.7
+    #   @return [Float, nil] right corner 3 field goals attempted
+    attribute :right_corner_3_fga, Shale::Type::Float
+
+    # @!attribute [rw] right_corner_3_fg_pct
+    #   Returns right corner 3 field goal percentage
+    #   @api public
+    #   @example
+    #     stat.right_corner_3_fg_pct #=> 0.429
+    #   @return [Float, nil] right corner 3 field goal percentage
+    attribute :right_corner_3_fg_pct, Shale::Type::Float
+
+    # @!attribute [rw] above_the_break_3_fgm
+    #   Returns above the break 3 field goals made
+    #   @api public
+    #   @example
+    #     stat.above_the_break_3_fgm #=> 2.8
+    #   @return [Float, nil] above the break 3 field goals made
+    attribute :above_the_break_3_fgm, Shale::Type::Float
+
+    # @!attribute [rw] above_the_break_3_fga
+    #   Returns above the break 3 field goals attempted
+    #   @api public
+    #   @example
+    #     stat.above_the_break_3_fga #=> 7.2
+    #   @return [Float, nil] above the break 3 field goals attempted
+    attribute :above_the_break_3_fga, Shale::Type::Float
+
+    # @!attribute [rw] above_the_break_3_fg_pct
+    #   Returns above the break 3 field goal percentage
+    #   @api public
+    #   @example
+    #     stat.above_the_break_3_fg_pct #=> 0.389
+    #   @return [Float, nil] above the break 3 field goal percentage
+    attribute :above_the_break_3_fg_pct, Shale::Type::Float
+
+    # @!attribute [rw] backcourt_fgm
+    #   Returns backcourt field goals made
+    #   @api public
+    #   @example
+    #     stat.backcourt_fgm #=> 0.0
+    #   @return [Float, nil] backcourt field goals made
+    attribute :backcourt_fgm, Shale::Type::Float
+
+    # @!attribute [rw] backcourt_fga
+    #   Returns backcourt field goals attempted
+    #   @api public
+    #   @example
+    #     stat.backcourt_fga #=> 0.1
+    #   @return [Float, nil] backcourt field goals attempted
+    attribute :backcourt_fga, Shale::Type::Float
+
+    # @!attribute [rw] backcourt_fg_pct
+    #   Returns backcourt field goal percentage
+    #   @api public
+    #   @example
+    #     stat.backcourt_fg_pct #=> 0.0
+    #   @return [Float, nil] backcourt field goal percentage
+    attribute :backcourt_fg_pct, Shale::Type::Float
+
+    # @!attribute [rw] corner_3_fgm
+    #   Returns corner 3 field goals made (combined left and right)
+    #   @api public
+    #   @example
+    #     stat.corner_3_fgm #=> 0.7
+    #   @return [Float, nil] corner 3 field goals made
+    attribute :corner_3_fgm, Shale::Type::Float
+
+    # @!attribute [rw] corner_3_fga
+    #   Returns corner 3 field goals attempted (combined left and right)
+    #   @api public
+    #   @example
+    #     stat.corner_3_fga #=> 1.6
+    #   @return [Float, nil] corner 3 field goals attempted
+    attribute :corner_3_fga, Shale::Type::Float
+
+    # @!attribute [rw] corner_3_fg_pct
+    #   Returns corner 3 field goal percentage (combined left and right)
+    #   @api public
+    #   @example
+    #     stat.corner_3_fg_pct #=> 0.438
+    #   @return [Float, nil] corner 3 field goal percentage
+    attribute :corner_3_fg_pct, 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 player's 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_player_shot_locations.rb

@@ -0,0 +1,210 @@
+require "json"
+require_relative "client"
+require_relative "collection"
+require_relative "league_dash_player_shot_location_stat"
+require_relative "utils"
+
+module NBA
+  # Provides methods to retrieve league-wide player shot location statistics
+  #
+  # @api public
+  module LeagueDashPlayerShotLocations
+    # Result set name for shot locations
+    # @return [String] the result set name
+    SHOT_LOCATIONS = "ShotLocations".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
+
+    # By 5-foot zone distance range
+    # @return [String] the distance range
+    BY_ZONE = "By Zone".freeze
+
+    # Retrieves all league-wide player shot location statistics
+    #
+    # @api public
+    # @example
+    #   stats = NBA::LeagueDashPlayerShotLocations.all(season: 2024)
+    #   stats.first.restricted_area_fg_pct #=> 0.595
+    # @param season [Integer] the season year
+    # @param season_type [String] the season type
+    # @param per_mode [String] the per mode
+    # @param distance_range [String] the distance range
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of player shot location statistics
+    def self.all(season: Utils.current_season, season_type: REGULAR_SEASON, per_mode: PER_GAME,
+      distance_range: BY_ZONE, client: CLIENT)
+      path = build_path(season, season_type: season_type, per_mode: per_mode, distance_range: distance_range)
+      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)
+      "leaguedashplayershotlocations?LeagueID=00&Season=#{season_str}" \
+        "&SeasonType=#{opts.fetch(:season_type)}&PerMode=#{opts.fetch(:per_mode)}" \
+        "&DistanceRange=#{opts.fetch(:distance_range)}"
+    end
+    private_class_method :build_path
+
+    # Parses the API response into stat objects
+    #
+    # @api private
+    # @return [Collection] collection of player shot location 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?(SHOT_LOCATIONS) }
+    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 = build_headers(result_set)
+      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 flat header array from nested headers
+    #
+    # @api private
+    # @return [Array<String>, nil] the flattened headers
+    def self.build_headers(result_set)
+      headers = result_set["headers"]
+      return unless headers
+
+      headers.flat_map { |h| h["columnNames"] }
+    end
+    private_class_method :build_headers
+
+    # Builds a single stat object from API data
+    #
+    # @api private
+    # @return [LeagueDashPlayerShotLocationStat] the stat object
+    def self.build_stat(data)
+      LeagueDashPlayerShotLocationStat.new(**identity_info(data), **restricted_area_info(data),
+        **paint_info(data), **mid_range_info(data), **corner_3_info(data), **above_break_3_info(data),
+        **backcourt_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"],
+       age: data["AGE"]}
+    end
+    private_class_method :identity_info
+
+    # Extracts restricted area shooting information from data
+    #
+    # @api private
+    # @return [Hash] the restricted area information hash
+    def self.restricted_area_info(data)
+      {restricted_area_fgm: data["Restricted Area FGM"],
+       restricted_area_fga: data["Restricted Area FGA"],
+       restricted_area_fg_pct: data["Restricted Area FG_PCT"]}
+    end
+    private_class_method :restricted_area_info
+
+    # Extracts in the paint (non-RA) shooting information from data
+    #
+    # @api private
+    # @return [Hash] the paint information hash
+    def self.paint_info(data)
+      {in_the_paint_non_ra_fgm: data["In The Paint (Non-RA) FGM"],
+       in_the_paint_non_ra_fga: data["In The Paint (Non-RA) FGA"],
+       in_the_paint_non_ra_fg_pct: data["In The Paint (Non-RA) FG_PCT"]}
+    end
+    private_class_method :paint_info
+
+    # Extracts mid-range shooting information from data
+    #
+    # @api private
+    # @return [Hash] the mid-range information hash
+    def self.mid_range_info(data)
+      {mid_range_fgm: data["Mid-Range FGM"], mid_range_fga: data["Mid-Range FGA"],
+       mid_range_fg_pct: data["Mid-Range FG_PCT"]}
+    end
+    private_class_method :mid_range_info
+
+    # Extracts corner 3 shooting information from data
+    #
+    # @api private
+    # @return [Hash] the corner 3 information hash
+    def self.corner_3_info(data)
+      {left_corner_3_fgm: data["Left Corner 3 FGM"],
+       left_corner_3_fga: data["Left Corner 3 FGA"],
+       left_corner_3_fg_pct: data["Left Corner 3 FG_PCT"],
+       right_corner_3_fgm: data["Right Corner 3 FGM"],
+       right_corner_3_fga: data["Right Corner 3 FGA"],
+       right_corner_3_fg_pct: data["Right Corner 3 FG_PCT"],
+       corner_3_fgm: data["Corner 3 FGM"], corner_3_fga: data["Corner 3 FGA"],
+       corner_3_fg_pct: data["Corner 3 FG_PCT"]}
+    end
+    private_class_method :corner_3_info
+
+    # Extracts above the break 3 shooting information from data
+    #
+    # @api private
+    # @return [Hash] the above the break 3 information hash
+    def self.above_break_3_info(data)
+      {above_the_break_3_fgm: data["Above the Break 3 FGM"],
+       above_the_break_3_fga: data["Above the Break 3 FGA"],
+       above_the_break_3_fg_pct: data["Above the Break 3 FG_PCT"]}
+    end
+    private_class_method :above_break_3_info
+
+    # Extracts backcourt shooting information from data
+    #
+    # @api private
+    # @return [Hash] the backcourt information hash
+    def self.backcourt_info(data)
+      {backcourt_fgm: data["Backcourt FGM"], backcourt_fga: data["Backcourt FGA"],
+       backcourt_fg_pct: data["Backcourt FG_PCT"]}
+    end
+    private_class_method :backcourt_info
+  end
+end