nba 0.1.1 → 0.2.0

data/lib/nba/league_hustle_stats_team.rb

@@ -0,0 +1,157 @@
+require "json"
+require_relative "client"
+require_relative "collection"
+require_relative "utils"
+
+module NBA
+  # Provides methods to retrieve league-wide team hustle statistics
+  module LeagueHustleStatsTeam
+    # Result set name for hustle stats
+    # @return [String] the result set name
+    HUSTLE_STATS_TEAM = "HustleStatsTeam".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
+
+    # Retrieves league-wide team hustle statistics
+    #
+    # @api public
+    # @example
+    #   stats = NBA::LeagueHustleStatsTeam.all(season: 2024)
+    #   stats.each { |s| puts "#{s.team_name}: #{s.deflections} deflections" }
+    # @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 hustle stats
+    def self.all(season: Utils.current_season, season_type: REGULAR_SEASON, per_mode: PER_GAME, client: CLIENT)
+      path = build_path(season, season_type, per_mode)
+      response = client.get(path)
+      parse_response(response)
+    end
+
+    # Builds the API path
+    #
+    # @api private
+    # @param season [Integer] the season year
+    # @param season_type [String] the season type
+    # @param per_mode [String] the per mode
+    # @return [String] the API path
+    def self.build_path(season, season_type, per_mode)
+      season_str = Utils.format_season(season)
+      "leaguehustlestatsteam?LeagueID=00&Season=#{season_str}&SeasonType=#{season_type}&PerMode=#{per_mode}"
+    end
+    private_class_method :build_path
+
+    # Parses the API response
+    #
+    # @api private
+    # @param response [String] the JSON response body
+    # @return [Collection] a collection of team hustle stats
+    def self.parse_response(response)
+      return Collection.new unless response
+
+      data = JSON.parse(response)
+      result_set = find_result_set(data)
+      return Collection.new unless result_set
+
+      headers = result_set["headers"]
+      rows = result_set["rowSet"]
+      return Collection.new unless headers && rows
+
+      stats = rows.map { |row| build_team_stat(headers, row) }
+      Collection.new(stats)
+    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?(HUSTLE_STATS_TEAM) }
+    end
+    private_class_method :find_result_set
+
+    # Builds a team stat from a row
+    #
+    # @api private
+    # @param headers [Array<String>] the column headers
+    # @param row [Array] the row data
+    # @return [LeagueHustleStatsTeamStat] the team stat object
+    def self.build_team_stat(headers, row)
+      data = headers.zip(row).to_h
+      LeagueHustleStatsTeamStat.new(**team_stat_attributes(data))
+    end
+    private_class_method :build_team_stat
+
+    # Extracts team stat attributes from row data
+    #
+    # @api private
+    # @param data [Hash] the team stat row data
+    # @return [Hash] the team stat attributes
+    def self.team_stat_attributes(data)
+      identity_attributes(data).merge(hustle_attributes(data), box_out_attributes(data))
+    end
+    private_class_method :team_stat_attributes
+
+    # Extracts identity attributes
+    #
+    # @api private
+    # @param data [Hash] the team stat data
+    # @return [Hash] the identity attributes
+    def self.identity_attributes(data)
+      {team_id: data["TEAM_ID"], team_name: data["TEAM_NAME"],
+       min: data["MIN"]}
+    end
+    private_class_method :identity_attributes
+
+    # Extracts hustle attributes
+    #
+    # @api private
+    # @param data [Hash] the team stat data
+    # @return [Hash] the hustle attributes
+    def self.hustle_attributes(data)
+      {contested_shots: data["CONTESTED_SHOTS"],
+       contested_shots_2pt: data["CONTESTED_SHOTS_2PT"],
+       contested_shots_3pt: data["CONTESTED_SHOTS_3PT"],
+       deflections: data["DEFLECTIONS"], charges_drawn: data["CHARGES_DRAWN"],
+       screen_assists: data["SCREEN_ASSISTS"], screen_ast_pts: data["SCREEN_AST_PTS"],
+       off_loose_balls_recovered: data["OFF_LOOSE_BALLS_RECOVERED"],
+       def_loose_balls_recovered: data["DEF_LOOSE_BALLS_RECOVERED"],
+       loose_balls_recovered: data["LOOSE_BALLS_RECOVERED"],
+       pct_loose_balls_recovered_off: data["PCT_LOOSE_BALLS_RECOVERED_OFF"],
+       pct_loose_balls_recovered_def: data["PCT_LOOSE_BALLS_RECOVERED_DEF"]}
+    end
+    private_class_method :hustle_attributes
+
+    # Extracts box out attributes
+    #
+    # @api private
+    # @param data [Hash] the team stat data
+    # @return [Hash] the box out attributes
+    def self.box_out_attributes(data)
+      {off_boxouts: data["OFF_BOXOUTS"], def_boxouts: data["DEF_BOXOUTS"],
+       box_outs: data["BOX_OUTS"],
+       pct_box_outs_off: data["PCT_BOX_OUTS_OFF"], pct_box_outs_def: data["PCT_BOX_OUTS_DEF"]}
+    end
+    private_class_method :box_out_attributes
+  end
+end

data/lib/nba/league_hustle_stats_team_stat.rb

@@ -0,0 +1,179 @@
+require "equalizer"
+require "shale"
+
+module NBA
+  # Represents league-wide hustle statistics for a team
+  class LeagueHustleStatsTeamStat < Shale::Mapper
+    include Equalizer.new(:team_id)
+
+    # @!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_name
+    #   Returns the team name
+    #   @api public
+    #   @example
+    #     stat.team_name #=> "Golden State Warriors"
+    #   @return [String] the team name
+    attribute :team_name, Shale::Type::String
+
+    # @!attribute [rw] min
+    #   Returns total minutes played
+    #   @api public
+    #   @example
+    #     stat.min #=> 19680.0
+    #   @return [Float] total minutes
+    attribute :min, Shale::Type::Float
+
+    # @!attribute [rw] contested_shots
+    #   Returns contested shots
+    #   @api public
+    #   @example
+    #     stat.contested_shots #=> 2856
+    #   @return [Integer] contested shots
+    attribute :contested_shots, Shale::Type::Integer
+
+    # @!attribute [rw] contested_shots_2pt
+    #   Returns contested 2-point shots
+    #   @api public
+    #   @example
+    #     stat.contested_shots_2pt #=> 1842
+    #   @return [Integer] contested 2-point shots
+    attribute :contested_shots_2pt, Shale::Type::Integer
+
+    # @!attribute [rw] contested_shots_3pt
+    #   Returns contested 3-point shots
+    #   @api public
+    #   @example
+    #     stat.contested_shots_3pt #=> 1014
+    #   @return [Integer] contested 3-point shots
+    attribute :contested_shots_3pt, Shale::Type::Integer
+
+    # @!attribute [rw] deflections
+    #   Returns deflections
+    #   @api public
+    #   @example
+    #     stat.deflections #=> 1024
+    #   @return [Integer] deflections
+    attribute :deflections, Shale::Type::Integer
+
+    # @!attribute [rw] charges_drawn
+    #   Returns charges drawn
+    #   @api public
+    #   @example
+    #     stat.charges_drawn #=> 42
+    #   @return [Integer] charges drawn
+    attribute :charges_drawn, Shale::Type::Integer
+
+    # @!attribute [rw] screen_assists
+    #   Returns screen assists
+    #   @api public
+    #   @example
+    #     stat.screen_assists #=> 1856
+    #   @return [Integer] screen assists
+    attribute :screen_assists, Shale::Type::Integer
+
+    # @!attribute [rw] screen_ast_pts
+    #   Returns points from screen assists
+    #   @api public
+    #   @example
+    #     stat.screen_ast_pts #=> 3712
+    #   @return [Integer] screen assist points
+    attribute :screen_ast_pts, Shale::Type::Integer
+
+    # @!attribute [rw] off_loose_balls_recovered
+    #   Returns offensive loose balls recovered
+    #   @api public
+    #   @example
+    #     stat.off_loose_balls_recovered #=> 312
+    #   @return [Integer] offensive loose balls recovered
+    attribute :off_loose_balls_recovered, Shale::Type::Integer
+
+    # @!attribute [rw] def_loose_balls_recovered
+    #   Returns defensive loose balls recovered
+    #   @api public
+    #   @example
+    #     stat.def_loose_balls_recovered #=> 428
+    #   @return [Integer] defensive loose balls recovered
+    attribute :def_loose_balls_recovered, Shale::Type::Integer
+
+    # @!attribute [rw] loose_balls_recovered
+    #   Returns total loose balls recovered
+    #   @api public
+    #   @example
+    #     stat.loose_balls_recovered #=> 740
+    #   @return [Integer] loose balls recovered
+    attribute :loose_balls_recovered, Shale::Type::Integer
+
+    # @!attribute [rw] pct_loose_balls_recovered_off
+    #   Returns percentage of offensive loose balls recovered
+    #   @api public
+    #   @example
+    #     stat.pct_loose_balls_recovered_off #=> 0.422
+    #   @return [Float] percentage of offensive loose balls recovered
+    attribute :pct_loose_balls_recovered_off, Shale::Type::Float
+
+    # @!attribute [rw] pct_loose_balls_recovered_def
+    #   Returns percentage of defensive loose balls recovered
+    #   @api public
+    #   @example
+    #     stat.pct_loose_balls_recovered_def #=> 0.578
+    #   @return [Float] percentage of defensive loose balls recovered
+    attribute :pct_loose_balls_recovered_def, Shale::Type::Float
+
+    # @!attribute [rw] off_boxouts
+    #   Returns offensive box outs
+    #   @api public
+    #   @example
+    #     stat.off_boxouts #=> 245
+    #   @return [Integer] offensive box outs
+    attribute :off_boxouts, Shale::Type::Integer
+
+    # @!attribute [rw] def_boxouts
+    #   Returns defensive box outs
+    #   @api public
+    #   @example
+    #     stat.def_boxouts #=> 1256
+    #   @return [Integer] defensive box outs
+    attribute :def_boxouts, Shale::Type::Integer
+
+    # @!attribute [rw] box_outs
+    #   Returns total box outs
+    #   @api public
+    #   @example
+    #     stat.box_outs #=> 1501
+    #   @return [Integer] total box outs
+    attribute :box_outs, Shale::Type::Integer
+
+    # @!attribute [rw] pct_box_outs_off
+    #   Returns percentage of offensive box outs
+    #   @api public
+    #   @example
+    #     stat.pct_box_outs_off #=> 0.163
+    #   @return [Float] percentage of offensive box outs
+    attribute :pct_box_outs_off, Shale::Type::Float
+
+    # @!attribute [rw] pct_box_outs_def
+    #   Returns percentage of defensive box outs
+    #   @api public
+    #   @example
+    #     stat.pct_box_outs_def #=> 0.837
+    #   @return [Float] percentage of defensive box outs
+    attribute :pct_box_outs_def, 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_lineup_viz.rb

@@ -0,0 +1,184 @@
+require "json"
+require_relative "client"
+require_relative "collection"
+require_relative "league_lineup_viz_stat"
+require_relative "utils"
+
+module NBA
+  # Provides methods to retrieve league lineup visualization statistics
+  #
+  # @api public
+  module LeagueLineupViz
+    # Result set name for lineup visualization
+    # @return [String] the result set name
+    LEAGUE_LINEUP_VIZ = "LeagueLineupViz".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
+
+    # Base measure type constant
+    # @return [String] the measure type
+    BASE = "Base".freeze
+
+    # Advanced measure type constant
+    # @return [String] the measure type
+    ADVANCED = "Advanced".freeze
+
+    # Group quantity for 5-man lineups
+    # @return [Integer] the group quantity
+    FIVE_MAN = 5
+
+    # Group quantity for 4-man lineups
+    # @return [Integer] the group quantity
+    FOUR_MAN = 4
+
+    # Group quantity for 3-man lineups
+    # @return [Integer] the group quantity
+    THREE_MAN = 3
+
+    # Group quantity for 2-man lineups
+    # @return [Integer] the group quantity
+    TWO_MAN = 2
+
+    # Retrieves all league lineup visualization statistics
+    #
+    # @api public
+    # @example
+    #   stats = NBA::LeagueLineupViz.all(season: 2024)
+    #   stats.first.group_name #=> "S. Curry - K. Thompson - ..."
+    # @param season [Integer] the season year
+    # @param season_type [String] the season type
+    # @param per_mode [String] the per mode
+    # @param measure_type [String] the measure type
+    # @param group_quantity [Integer] the lineup size
+    # @param minutes_min [Integer] minimum minutes filter
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of lineup visualization statistics
+    def self.all(season: Utils.current_season, season_type: REGULAR_SEASON, per_mode: PER_GAME,
+      measure_type: BASE, group_quantity: FIVE_MAN, minutes_min: 0, client: CLIENT)
+      path = build_path(season, season_type: season_type, per_mode: per_mode, measure_type: measure_type,
+        group_quantity: group_quantity, minutes_min: minutes_min)
+      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)
+      "leaguelineupviz?LeagueID=00&Season=#{season_str}&SeasonType=#{opts.fetch(:season_type)}" \
+        "&PerMode=#{opts.fetch(:per_mode)}&MeasureType=#{opts.fetch(:measure_type)}" \
+        "&GroupQuantity=#{opts.fetch(:group_quantity)}&MinutesMin=#{opts.fetch(:minutes_min)}"
+    end
+    private_class_method :build_path
+
+    # Parses the API response into stat objects
+    #
+    # @api private
+    # @return [Collection] collection of lineup visualization 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_LINEUP_VIZ) }
+    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 [LeagueLineupVizStat] the stat object
+    def self.build_stat(data)
+      LeagueLineupVizStat.new(**identity_info(data), **rating_info(data), **shooting_info(data),
+        **opponent_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)
+      {group_id: data["GROUP_ID"], group_name: data["GROUP_NAME"],
+       team_id: data["TEAM_ID"], team_abbreviation: data["TEAM_ABBREVIATION"]}
+    end
+    private_class_method :identity_info
+
+    # Extracts rating information from data
+    #
+    # @api private
+    # @return [Hash] the rating information hash
+    def self.rating_info(data)
+      {min: data["MIN"], off_rating: data["OFF_RATING"],
+       def_rating: data["DEF_RATING"], net_rating: data["NET_RATING"],
+       pace: data["PACE"], ts_pct: data["TS_PCT"],
+       fta_rate: data["FTA_RATE"], tm_ast_pct: data["TM_AST_PCT"]}
+    end
+    private_class_method :rating_info
+
+    # Extracts shooting information from data
+    #
+    # @api private
+    # @return [Hash] the shooting information hash
+    def self.shooting_info(data)
+      {pct_fga_2pt: data["PCT_FGA_2PT"], pct_fga_3pt: data["PCT_FGA_3PT"],
+       pct_pts_2pt_mr: data["PCT_PTS_2PT_MR"], pct_pts_fb: data["PCT_PTS_FB"],
+       pct_pts_ft: data["PCT_PTS_FT"], pct_pts_paint: data["PCT_PTS_PAINT"],
+       pct_ast_fgm: data["PCT_AST_FGM"], pct_uast_fgm: data["PCT_UAST_FGM"]}
+    end
+    private_class_method :shooting_info
+
+    # Extracts opponent stats information from data
+    #
+    # @api private
+    # @return [Hash] the opponent stats information hash
+    def self.opponent_info(data)
+      {opp_fg3_pct: data["OPP_FG3_PCT"], opp_efg_pct: data["OPP_EFG_PCT"],
+       opp_fta_rate: data["OPP_FTA_RATE"], opp_tov_pct: data["OPP_TOV_PCT"]}
+    end
+    private_class_method :opponent_info
+  end
+end