Touch Time and Dribbles: NBA Player Tracking Analytics

What Touch Time and Dribbles Measure

Touch Time

Touch Time measures the average amount of time (in seconds) a player holds the ball per touch during a game. This metric is captured through optical tracking systems installed in NBA arenas.

Dribbles Per Touch

Dribbles Per Touch counts the average number of dribbles a player takes each time they possess the ball. This reveals offensive style and decision-making patterns.

Related Metrics

• Touches: Total number of times a player receives/controls the ball
• Front Court Touches: Touches in the offensive half court
• Time of Possession: Total seconds per game a player has the ball
• Elbow Touches: Touches at the free throw line extended areas
• Paint Touches: Touches inside the painted area

NBA Stats Tracking Data Sources

Official NBA Stats API

The NBA.com Stats platform provides comprehensive player tracking data through several endpoints:

Data Availability

• Historical Data: Player tracking available from 2013-14 season onwards
• Update Frequency: Daily updates during the NBA season
• Granularity: Game-level and season aggregate statistics
• Coverage: All NBA regular season and playoff games

Python Code: Retrieving Touch Time Data with nba_api

Setup and Installation

# Install required packages
pip install nba_api pandas matplotlib seaborn numpy

Fetching Touch Time and Dribble Statistics

import pandas as pd
import numpy as np
from nba_api.stats.endpoints import leaguedashptstats, playerdashptstats
from nba_api.stats.static import players, teams
import time

# Fetch league-wide touch time and dribbles data
def get_touch_time_data(season='2023-24', per_mode='PerGame'):
    """
    Retrieve touch time and dribbles per touch data for all players.

    Parameters:
    -----------
    season : str
        NBA season in format 'YYYY-YY' (e.g., '2023-24')
    per_mode : str
        'PerGame', 'Totals', or 'Per36'

    Returns:
    --------
    pandas.DataFrame with touch time metrics
    """

    # Request player tracking data for possessions
    pt_stats = leaguedashptstats.LeagueDashPtStats(
        league_id='00',
        per_mode_simple=per_mode,
        pt_measure_type='Possessions',
        season=season,
        season_type_all_star='Regular Season'
    )

    # Get the dataframe
    df = pt_stats.get_data_frames()[0]

    # Select relevant columns
    columns_of_interest = [
        'PLAYER_NAME', 'TEAM_ABBREVIATION', 'GP', 'MIN',
        'TOUCHES', 'FRONT_CT_TOUCHES', 'TIME_OF_POSS',
        'AVG_SEC_PER_TOUCH', 'AVG_DRIB_PER_TOUCH',
        'PTS', 'POSSESSIONS', 'PTS_PER_POSS'
    ]

    df_filtered = df[columns_of_interest].copy()

    # Filter for players with significant minutes (e.g., > 15 MPG)
    df_filtered = df_filtered[df_filtered['MIN'] > 15].reset_index(drop=True)

    return df_filtered


# Get individual player detailed touch data
def get_player_touch_details(player_name, season='2023-24'):
    """
    Get detailed touch time breakdown for a specific player.

    Parameters:
    -----------
    player_name : str
        Full name of the player
    season : str
        NBA season

    Returns:
    --------
    dict with multiple dataframes for different tracking categories
    """

    # Find player ID
    player_dict = players.find_players_by_full_name(player_name)
    if not player_dict:
        print(f"Player {player_name} not found")
        return None

    player_id = player_dict[0]['id']

    # Get different PT measure types
    measure_types = ['Possessions', 'Touches', 'Drives']

    player_data = {}

    for measure in measure_types:
        time.sleep(0.6)  # Respect API rate limits

        pt_player = playerdashptstats.PlayerDashPtStats(
            player_id=player_id,
            team_id=0,
            league_id='00',
            season=season,
            season_type_all_star='Regular Season',
            pt_measure_type=measure
        )

        player_data[measure] = pt_player.get_data_frames()[0]

    return player_data


# Example: Get current season data
print("Fetching NBA touch time and dribbles data...")
touch_df = get_touch_time_data(season='2023-24')

print(f"\nTop 10 players by average dribbles per touch:")
print(touch_df.nlargest(10, 'AVG_DRIB_PER_TOUCH')[
    ['PLAYER_NAME', 'TEAM_ABBREVIATION', 'AVG_DRIB_PER_TOUCH',
     'AVG_SEC_PER_TOUCH', 'TOUCHES']
])

print(f"\nTop 10 players by touch time (seconds per touch):")
print(touch_df.nlargest(10, 'AVG_SEC_PER_TOUCH')[
    ['PLAYER_NAME', 'TEAM_ABBREVIATION', 'AVG_SEC_PER_TOUCH',
     'AVG_DRIB_PER_TOUCH', 'TIME_OF_POSS']
])

# Get detailed data for a specific player
player_details = get_player_touch_details("Luka Doncic", season='2023-24')

if player_details:
    print(f"\nLuka Doncic Touch Time Details:")
    print(player_details['Possessions'][
        ['PLAYER_NAME', 'AVG_SEC_PER_TOUCH', 'AVG_DRIB_PER_TOUCH',
         'TOUCHES', 'TIME_OF_POSS']
    ])

Advanced Analysis: Efficiency by Touch Time

import matplotlib.pyplot as plt
import seaborn as sns

# Analyze relationship between touch time and scoring efficiency
def analyze_touch_time_efficiency(df):
    """
    Analyze how touch time correlates with scoring efficiency.
    """

    # Calculate points per touch
    df['PTS_PER_TOUCH'] = df['PTS'] / df['TOUCHES']

    # Create efficiency categories based on points per possession
    df['EFFICIENCY_LEVEL'] = pd.cut(
        df['PTS_PER_POSS'],
        bins=[0, 0.95, 1.05, 2.0],
        labels=['Below Average', 'Average', 'Above Average']
    )

    # Statistical summary
    print("Touch Time vs Efficiency Analysis:")
    print(df.groupby('EFFICIENCY_LEVEL')[
        ['AVG_SEC_PER_TOUCH', 'AVG_DRIB_PER_TOUCH', 'PTS_PER_POSS']
    ].mean())

    return df


# Run analysis
touch_df = analyze_touch_time_efficiency(touch_df)

# Visualization: Scatter plot
plt.figure(figsize=(12, 8))

scatter = plt.scatter(
    touch_df['AVG_SEC_PER_TOUCH'],
    touch_df['AVG_DRIB_PER_TOUCH'],
    c=touch_df['PTS_PER_POSS'],
    s=touch_df['TOUCHES'] * 2,
    alpha=0.6,
    cmap='RdYlGn'
)

plt.colorbar(scatter, label='Points Per Possession')
plt.xlabel('Average Seconds Per Touch', fontsize=12)
plt.ylabel('Average Dribbles Per Touch', fontsize=12)
plt.title('NBA Player Touch Time vs Dribbles (2023-24)', fontsize=14, fontweight='bold')
plt.grid(True, alpha=0.3)

# Annotate high-usage players
top_touches = touch_df.nlargest(5, 'TOUCHES')
for _, player in top_touches.iterrows():
    plt.annotate(
        player['PLAYER_NAME'],
        (player['AVG_SEC_PER_TOUCH'], player['AVG_DRIB_PER_TOUCH']),
        fontsize=9,
        alpha=0.7
    )

plt.tight_layout()
plt.savefig('touch_time_vs_dribbles.png', dpi=300, bbox_inches='tight')
plt.show()

print("\nVisualization saved as 'touch_time_vs_dribbles.png'")

R Code: Ball Handling Metrics with hoopR

Setup and Installation

# Install required packages
install.packages("hoopR")
install.packages("tidyverse")
install.packages("ggplot2")
install.packages("httr")
install.packages("jsonlite")

# Load libraries
library(hoopR)
library(tidyverse)
library(ggplot2)
library(httr)
library(jsonlite)

Accessing NBA Player Tracking Data

# Function to get touch time data via NBA Stats API
get_nba_touch_data <- function(season = "2023-24", per_mode = "PerGame") {

  # Construct API URL
  base_url <- "https://stats.nba.com/stats/leaguedashptstats"

  # API parameters
  params <- list(
    LeagueID = "00",
    PerMode = per_mode,
    PtMeasureType = "Possessions",
    Season = season,
    SeasonType = "Regular Season"
  )

  # Headers (NBA Stats API requires proper headers)
  headers <- c(
    `User-Agent` = "Mozilla/5.0",
    `Accept` = "application/json",
    `x-nba-stats-origin` = "stats.nba.com",
    `x-nba-stats-token` = "true",
    `Referer` = "https://stats.nba.com/"
  )

  # Make API request
  response <- GET(
    url = base_url,
    query = params,
    add_headers(.headers = headers)
  )

  # Check if request was successful
  if (status_code(response) != 200) {
    stop(paste("API request failed with status:", status_code(response)))
  }

  # Parse JSON response
  data <- content(response, as = "text") %>%
    fromJSON()

  # Extract data
  headers <- data$resultSets$headers[[1]]
  rows <- data$resultSets$rowSet[[1]]

  # Create data frame
  df <- as.data.frame(rows, stringsAsFactors = FALSE)
  colnames(df) <- headers

  # Convert numeric columns
  numeric_cols <- c("GP", "MIN", "TOUCHES", "FRONT_CT_TOUCHES",
                    "TIME_OF_POSS", "AVG_SEC_PER_TOUCH", "AVG_DRIB_PER_TOUCH",
                    "PTS", "POSSESSIONS", "PTS_PER_POSS")

  df[numeric_cols] <- lapply(df[numeric_cols], as.numeric)

  # Filter for qualified players (>15 MPG)
  df <- df %>%
    filter(MIN > 15) %>%
    arrange(desc(AVG_DRIB_PER_TOUCH))

  return(df)
}

# Fetch the data
cat("Fetching NBA touch time data...\n")
touch_data <- get_nba_touch_data(season = "2023-24")

# Display top players by dribbles per touch
cat("\nTop 10 Players by Dribbles Per Touch:\n")
touch_data %>%
  select(PLAYER_NAME, TEAM_ABBREVIATION, AVG_DRIB_PER_TOUCH,
         AVG_SEC_PER_TOUCH, TOUCHES) %>%
  head(10) %>%
  print()

# Display top players by touch time
cat("\nTop 10 Players by Touch Time (Seconds Per Touch):\n")
touch_data %>%
  arrange(desc(AVG_SEC_PER_TOUCH)) %>%
  select(PLAYER_NAME, TEAM_ABBREVIATION, AVG_SEC_PER_TOUCH,
         AVG_DRIB_PER_TOUCH, TIME_OF_POSS) %>%
  head(10) %>%
  print()

Statistical Analysis of Ball Handling Patterns

# Analyze ball handling patterns and efficiency
analyze_ball_handling <- function(df) {

  # Create derived metrics
  df <- df %>%
    mutate(
      PTS_PER_TOUCH = PTS / TOUCHES,
      POSS_PER_TOUCH = POSSESSIONS / TOUCHES,
      TOUCH_INTENSITY = AVG_SEC_PER_TOUCH * AVG_DRIB_PER_TOUCH,
      EFFICIENCY_RATING = case_when(
        PTS_PER_POSS >= 1.05 ~ "High",
        PTS_PER_POSS >= 0.95 ~ "Average",
        TRUE ~ "Low"
      )
    )

  # Summary statistics by efficiency level
  cat("\n=== Ball Handling Metrics by Efficiency Level ===\n")
  summary_stats <- df %>%
    group_by(EFFICIENCY_RATING) %>%
    summarise(
      N_Players = n(),
      Avg_Touch_Time = mean(AVG_SEC_PER_TOUCH, na.rm = TRUE),
      Avg_Dribbles = mean(AVG_DRIB_PER_TOUCH, na.rm = TRUE),
      Avg_Touches = mean(TOUCHES, na.rm = TRUE),
      Avg_PPP = mean(PTS_PER_POSS, na.rm = TRUE)
    ) %>%
    arrange(desc(Avg_PPP))

  print(summary_stats)

  # Correlation analysis
  cat("\n=== Correlation Analysis ===\n")
  cor_vars <- df %>%
    select(AVG_SEC_PER_TOUCH, AVG_DRIB_PER_TOUCH, TOUCHES,
           PTS_PER_POSS, TIME_OF_POSS) %>%
    na.omit()

  cor_matrix <- cor(cor_vars)
  print(round(cor_matrix, 3))

  return(df)
}

# Run analysis
touch_data <- analyze_ball_handling(touch_data)

# Linear regression: Does more dribbling lead to better scoring?
model <- lm(PTS_PER_POSS ~ AVG_DRIB_PER_TOUCH + AVG_SEC_PER_TOUCH +
            TOUCHES, data = touch_data)

cat("\n=== Regression Analysis: Touch Metrics vs Efficiency ===\n")
summary(model)

Advanced Visualization with ggplot2

# Create comprehensive touch time visualization
library(ggplot2)
library(ggrepel)

# 1. Scatter plot: Touch Time vs Dribbles
p1 <- ggplot(touch_data, aes(x = AVG_SEC_PER_TOUCH, y = AVG_DRIB_PER_TOUCH)) +
  geom_point(aes(size = TOUCHES, color = PTS_PER_POSS), alpha = 0.6) +
  scale_color_gradient2(
    low = "red", mid = "yellow", high = "green",
    midpoint = 1.0,
    name = "Points Per\nPossession"
  ) +
  scale_size_continuous(name = "Total Touches", range = c(2, 12)) +
  geom_text_repel(
    data = touch_data %>% top_n(8, TOUCHES),
    aes(label = PLAYER_NAME),
    size = 3,
    max.overlaps = 10
  ) +
  labs(
    title = "NBA Player Touch Time vs Dribbles Per Touch (2023-24)",
    subtitle = "Size represents total touches, color shows scoring efficiency",
    x = "Average Seconds Per Touch",
    y = "Average Dribbles Per Touch"
  ) +
  theme_minimal() +
  theme(
    plot.title = element_text(size = 14, face = "bold"),
    plot.subtitle = element_text(size = 10),
    legend.position = "right"
  )

print(p1)
ggsave("touch_time_analysis.png", p1, width = 12, height = 8, dpi = 300)

# 2. Distribution plots by player archetype
# Classify players by position/role based on metrics
touch_data <- touch_data %>%
  mutate(
    PLAYER_ARCHETYPE = case_when(
      AVG_DRIB_PER_TOUCH >= 4.0 ~ "Primary Ball Handler",
      AVG_DRIB_PER_TOUCH >= 2.5 ~ "Secondary Creator",
      AVG_DRIB_PER_TOUCH >= 1.5 ~ "Role Player",
      TRUE ~ "Big Man"
    )
  )

p2 <- ggplot(touch_data, aes(x = PLAYER_ARCHETYPE, y = AVG_SEC_PER_TOUCH,
                              fill = PLAYER_ARCHETYPE)) +
  geom_boxplot(alpha = 0.7) +
  geom_jitter(width = 0.2, alpha = 0.3, size = 2) +
  labs(
    title = "Touch Time Distribution by Player Archetype",
    x = "Player Archetype",
    y = "Average Seconds Per Touch"
  ) +
  theme_minimal() +
  theme(
    plot.title = element_text(size = 14, face = "bold"),
    legend.position = "none",
    axis.text.x = element_text(angle = 45, hjust = 1)
  )

print(p2)
ggsave("touch_time_by_archetype.png", p2, width = 10, height = 7, dpi = 300)

# 3. Efficiency heatmap
p3 <- ggplot(touch_data, aes(x = cut(AVG_SEC_PER_TOUCH, breaks = 5),
                              y = cut(AVG_DRIB_PER_TOUCH, breaks = 5))) +
  geom_bin2d(aes(fill = after_stat(count))) +
  scale_fill_gradient(low = "lightblue", high = "darkblue", name = "Player Count") +
  labs(
    title = "Player Distribution: Touch Time vs Dribbles Heatmap",
    x = "Touch Time (Seconds Per Touch)",
    y = "Dribbles Per Touch"
  ) +
  theme_minimal() +
  theme(
    plot.title = element_text(size = 14, face = "bold"),
    axis.text.x = element_text(angle = 45, hjust = 1)
  )

print(p3)
ggsave("touch_dribble_heatmap.png", p3, width = 10, height = 7, dpi = 300)

cat("\nVisualizations saved successfully!\n")

Analysis of Different Player Archetypes

Point Guards and Primary Ball Handlers

Wing Scorers and Secondary Creators

3-and-D Players and Role Players

Centers and Bigs

Comparative Analysis Across Archetypes

# Python code to analyze archetypes
def classify_player_archetype(row):
    """Classify players into archetypes based on touch metrics."""
    dribbles = row['AVG_DRIB_PER_TOUCH']
    touch_time = row['AVG_SEC_PER_TOUCH']

    if dribbles >= 4.5:
        return 'Primary Ball Handler'
    elif dribbles >= 2.5:
        return 'Secondary Creator'
    elif dribbles >= 1.5:
        return 'Role Player'
    else:
        return 'Big Man'

# Apply classification
touch_df['ARCHETYPE'] = touch_df.apply(classify_player_archetype, axis=1)

# Compare efficiency across archetypes
archetype_analysis = touch_df.groupby('ARCHETYPE').agg({
    'AVG_SEC_PER_TOUCH': 'mean',
    'AVG_DRIB_PER_TOUCH': 'mean',
    'TOUCHES': 'mean',
    'PTS_PER_POSS': 'mean',
    'PTS': 'mean',
    'PLAYER_NAME': 'count'
}).round(2)

archetype_analysis.columns = [
    'Avg Touch Time', 'Avg Dribbles', 'Avg Touches',
    'Points/Possession', 'Avg Points', 'Player Count'
]

print("\n=== Player Archetype Comparison ===")
print(archetype_analysis.sort_values('Avg Dribbles', ascending=False))

# Visualize archetype distributions
import matplotlib.pyplot as plt
import seaborn as sns

fig, axes = plt.subplots(2, 2, figsize=(14, 10))

# Touch time by archetype
sns.boxplot(data=touch_df, x='ARCHETYPE', y='AVG_SEC_PER_TOUCH', ax=axes[0, 0])
axes[0, 0].set_title('Touch Time Distribution by Archetype')
axes[0, 0].set_xlabel('')
axes[0, 0].tick_params(axis='x', rotation=45)

# Dribbles by archetype
sns.boxplot(data=touch_df, x='ARCHETYPE', y='AVG_DRIB_PER_TOUCH', ax=axes[0, 1])
axes[0, 1].set_title('Dribbles Per Touch by Archetype')
axes[0, 1].set_xlabel('')
axes[0, 1].tick_params(axis='x', rotation=45)

# Efficiency by archetype
sns.boxplot(data=touch_df, x='ARCHETYPE', y='PTS_PER_POSS', ax=axes[1, 0])
axes[1, 0].set_title('Scoring Efficiency by Archetype')
axes[1, 0].axhline(y=1.0, color='r', linestyle='--', alpha=0.5, label='League Avg')
axes[1, 0].tick_params(axis='x', rotation=45)
axes[1, 0].legend()

# Archetype distribution
archetype_counts = touch_df['ARCHETYPE'].value_counts()
axes[1, 1].pie(archetype_counts.values, labels=archetype_counts.index,
               autopct='%1.1f%%', startangle=90)
axes[1, 1].set_title('Distribution of Player Archetypes')

plt.tight_layout()
plt.savefig('archetype_analysis.png', dpi=300, bbox_inches='tight')
plt.show()

Visualizations and Data Representation

Python Matplotlib Visualizations

1. Touch Time vs Efficiency Scatter Plot

import matplotlib.pyplot as plt
import seaborn as sns
import numpy as np

# Create comprehensive visualization dashboard
def create_touch_time_dashboard(df):
    """
    Create a multi-panel dashboard for touch time analysis.
    """

    fig = plt.figure(figsize=(16, 12))
    gs = fig.add_gridspec(3, 2, hspace=0.3, wspace=0.3)

    # 1. Main scatter: Touch Time vs Dribbles
    ax1 = fig.add_subplot(gs[0, :])
    scatter = ax1.scatter(
        df['AVG_SEC_PER_TOUCH'],
        df['AVG_DRIB_PER_TOUCH'],
        s=df['TOUCHES'] * 3,
        c=df['PTS_PER_POSS'],
        cmap='RdYlGn',
        alpha=0.6,
        edgecolors='black',
        linewidth=0.5
    )

    # Add colorbar
    cbar = plt.colorbar(scatter, ax=ax1)
    cbar.set_label('Points Per Possession', fontsize=10)

    # Add reference lines
    ax1.axhline(y=df['AVG_DRIB_PER_TOUCH'].median(),
                color='gray', linestyle='--', alpha=0.5, label='Median Dribbles')
    ax1.axvline(x=df['AVG_SEC_PER_TOUCH'].median(),
                color='gray', linestyle='--', alpha=0.5, label='Median Touch Time')

    # Annotate top players
    top_players = df.nlargest(5, 'TOUCHES')
    for _, player in top_players.iterrows():
        ax1.annotate(
            player['PLAYER_NAME'],
            (player['AVG_SEC_PER_TOUCH'], player['AVG_DRIB_PER_TOUCH']),
            fontsize=8,
            alpha=0.8,
            bbox=dict(boxstyle='round,pad=0.3', facecolor='yellow', alpha=0.3)
        )

    ax1.set_xlabel('Average Seconds Per Touch', fontsize=11)
    ax1.set_ylabel('Average Dribbles Per Touch', fontsize=11)
    ax1.set_title('NBA Player Touch Time vs Dribbles Per Touch (2023-24)',
                  fontsize=14, fontweight='bold')
    ax1.legend(loc='upper left', fontsize=9)
    ax1.grid(True, alpha=0.3)

    # 2. Distribution: Touch Time
    ax2 = fig.add_subplot(gs[1, 0])
    ax2.hist(df['AVG_SEC_PER_TOUCH'], bins=30, color='skyblue',
             edgecolor='black', alpha=0.7)
    ax2.axvline(df['AVG_SEC_PER_TOUCH'].mean(), color='red',
                linestyle='--', linewidth=2, label=f"Mean: {df['AVG_SEC_PER_TOUCH'].mean():.2f}")
    ax2.set_xlabel('Seconds Per Touch', fontsize=10)
    ax2.set_ylabel('Frequency', fontsize=10)
    ax2.set_title('Distribution of Touch Time', fontsize=12, fontweight='bold')
    ax2.legend()
    ax2.grid(True, alpha=0.3, axis='y')

    # 3. Distribution: Dribbles Per Touch
    ax3 = fig.add_subplot(gs[1, 1])
    ax3.hist(df['AVG_DRIB_PER_TOUCH'], bins=30, color='lightcoral',
             edgecolor='black', alpha=0.7)
    ax3.axvline(df['AVG_DRIB_PER_TOUCH'].mean(), color='darkred',
                linestyle='--', linewidth=2, label=f"Mean: {df['AVG_DRIB_PER_TOUCH'].mean():.2f}")
    ax3.set_xlabel('Dribbles Per Touch', fontsize=10)
    ax3.set_ylabel('Frequency', fontsize=10)
    ax3.set_title('Distribution of Dribbles Per Touch', fontsize=12, fontweight='bold')
    ax3.legend()
    ax3.grid(True, alpha=0.3, axis='y')

    # 4. Top 10 players by Touch Time
    ax4 = fig.add_subplot(gs[2, 0])
    top_touch_time = df.nlargest(10, 'AVG_SEC_PER_TOUCH')
    y_pos = np.arange(len(top_touch_time))
    ax4.barh(y_pos, top_touch_time['AVG_SEC_PER_TOUCH'], color='steelblue')
    ax4.set_yticks(y_pos)
    ax4.set_yticklabels(top_touch_time['PLAYER_NAME'], fontsize=9)
    ax4.invert_yaxis()
    ax4.set_xlabel('Seconds Per Touch', fontsize=10)
    ax4.set_title('Top 10: Longest Touch Time', fontsize=12, fontweight='bold')
    ax4.grid(True, alpha=0.3, axis='x')

    # 5. Top 10 players by Dribbles Per Touch
    ax5 = fig.add_subplot(gs[2, 1])
    top_dribbles = df.nlargest(10, 'AVG_DRIB_PER_TOUCH')
    y_pos = np.arange(len(top_dribbles))
    ax5.barh(y_pos, top_dribbles['AVG_DRIB_PER_TOUCH'], color='coral')
    ax5.set_yticks(y_pos)
    ax5.set_yticklabels(top_dribbles['PLAYER_NAME'], fontsize=9)
    ax5.invert_yaxis()
    ax5.set_xlabel('Dribbles Per Touch', fontsize=10)
    ax5.set_title('Top 10: Most Dribbles Per Touch', fontsize=12, fontweight='bold')
    ax5.grid(True, alpha=0.3, axis='x')

    plt.suptitle('NBA Touch Time & Dribbles Analysis Dashboard',
                 fontsize=16, fontweight='bold', y=0.995)

    plt.savefig('touch_time_dashboard.png', dpi=300, bbox_inches='tight')
    plt.show()

    print("Dashboard saved as 'touch_time_dashboard.png'")

# Create the dashboard
create_touch_time_dashboard(touch_df)

2. Time Series Analysis (Season Progression)

# Track how touch time evolves throughout a season
from nba_api.stats.endpoints import playergamelog
import datetime

def get_player_touch_time_trend(player_name, season='2023-24'):
    """
    Get game-by-game touch time trends for a player.
    Note: Game-level touch data requires combining multiple sources.
    """

    # Find player ID
    player_dict = players.find_players_by_full_name(player_name)
    if not player_dict:
        return None

    player_id = player_dict[0]['id']

    # Get season aggregate data (API limitation: game-level tracking not directly available)
    # This is a simplified version - full game-level tracking requires more complex queries

    pt_player = playerdashptstats.PlayerDashPtStats(
        player_id=player_id,
        team_id=0,
        league_id='00',
        season=season,
        season_type_all_star='Regular Season',
        pt_measure_type='Possessions'
    )

    season_data = pt_player.get_data_frames()[0]

    return season_data

# Visualize trends for multiple star players
star_players = ['Luka Doncic', 'Stephen Curry', 'LeBron James', 'Kevin Durant']
comparison_data = []

for player in star_players:
    time.sleep(0.6)
    data = get_player_touch_time_trend(player)
    if data is not None and not data.empty:
        comparison_data.append({
            'Player': player,
            'Touch_Time': data['AVG_SEC_PER_TOUCH'].values[0],
            'Dribbles': data['AVG_DRIB_PER_TOUCH'].values[0],
            'Touches': data['TOUCHES'].values[0]
        })

comparison_df = pd.DataFrame(comparison_data)

# Comparison bar chart
fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(14, 6))

# Touch Time comparison
ax1.bar(comparison_df['Player'], comparison_df['Touch_Time'], color='teal')
ax1.set_ylabel('Seconds Per Touch', fontsize=11)
ax1.set_title('Star Player Touch Time Comparison', fontsize=13, fontweight='bold')
ax1.tick_params(axis='x', rotation=45)
ax1.grid(True, alpha=0.3, axis='y')

# Dribbles comparison
ax2.bar(comparison_df['Player'], comparison_df['Dribbles'], color='orange')
ax2.set_ylabel('Dribbles Per Touch', fontsize=11)
ax2.set_title('Star Player Dribbles Per Touch Comparison', fontsize=13, fontweight='bold')
ax2.tick_params(axis='x', rotation=45)
ax2.grid(True, alpha=0.3, axis='y')

plt.tight_layout()
plt.savefig('star_player_comparison.png', dpi=300, bbox_inches='tight')
plt.show()

R ggplot2 Advanced Visualizations

Faceted Analysis by Conference/Division

library(ggplot2)
library(dplyr)
library(tidyr)

# Prepare data with team divisions (simplified - would need team lookup)
# Create league average comparison

create_advanced_visualizations <- function(df) {

  # 1. Density plot: Touch metrics distribution
  p1 <- df %>%
    select(AVG_SEC_PER_TOUCH, AVG_DRIB_PER_TOUCH) %>%
    pivot_longer(cols = everything(), names_to = "Metric", values_to = "Value") %>%
    ggplot(aes(x = Value, fill = Metric)) +
    geom_density(alpha = 0.5) +
    scale_fill_manual(
      values = c("AVG_SEC_PER_TOUCH" = "steelblue",
                 "AVG_DRIB_PER_TOUCH" = "coral"),
      labels = c("Seconds Per Touch", "Dribbles Per Touch")
    ) +
    labs(
      title = "Distribution of Touch Time Metrics",
      x = "Value",
      y = "Density",
      fill = "Metric"
    ) +
    theme_minimal() +
    theme(plot.title = element_text(size = 14, face = "bold"))

  print(p1)
  ggsave("touch_metrics_density.png", p1, width = 10, height = 6, dpi = 300)

  # 2. Quadrant analysis
  median_touch_time <- median(df$AVG_SEC_PER_TOUCH, na.rm = TRUE)
  median_dribbles <- median(df$AVG_DRIB_PER_TOUCH, na.rm = TRUE)

  df <- df %>%
    mutate(
      Quadrant = case_when(
        AVG_SEC_PER_TOUCH >= median_touch_time &
          AVG_DRIB_PER_TOUCH >= median_dribbles ~ "High Touch/High Dribble",
        AVG_SEC_PER_TOUCH >= median_touch_time &
          AVG_DRIB_PER_TOUCH < median_dribbles ~ "High Touch/Low Dribble",
        AVG_SEC_PER_TOUCH < median_touch_time &
          AVG_DRIB_PER_TOUCH >= median_dribbles ~ "Low Touch/High Dribble",
        TRUE ~ "Low Touch/Low Dribble"
      )
    )

  p2 <- ggplot(df, aes(x = AVG_SEC_PER_TOUCH, y = AVG_DRIB_PER_TOUCH)) +
    geom_vline(xintercept = median_touch_time, linetype = "dashed",
               color = "gray50", size = 1) +
    geom_hline(yintercept = median_dribbles, linetype = "dashed",
               color = "gray50", size = 1) +
    geom_point(aes(color = Quadrant, size = TOUCHES), alpha = 0.6) +
    scale_size_continuous(range = c(2, 10), name = "Total Touches") +
    labs(
      title = "Touch Time Quadrant Analysis",
      subtitle = "Divided by median values",
      x = "Average Seconds Per Touch",
      y = "Average Dribbles Per Touch",
      color = "Playing Style"
    ) +
    theme_minimal() +
    theme(
      plot.title = element_text(size = 14, face = "bold"),
      legend.position = "right"
    )

  print(p2)
  ggsave("touch_quadrant_analysis.png", p2, width = 12, height = 8, dpi = 300)

  # 3. Efficiency by touch intensity
  p3 <- df %>%
    mutate(Touch_Intensity = cut(AVG_SEC_PER_TOUCH * AVG_DRIB_PER_TOUCH,
                                  breaks = 5,
                                  labels = c("Very Low", "Low", "Medium",
                                            "High", "Very High"))) %>%
    ggplot(aes(x = Touch_Intensity, y = PTS_PER_POSS, fill = Touch_Intensity)) +
    geom_boxplot(alpha = 0.7, outlier.alpha = 0.5) +
    geom_jitter(width = 0.2, alpha = 0.2, size = 1.5) +
    geom_hline(yintercept = 1.0, linetype = "dashed",
               color = "red", size = 1, alpha = 0.7) +
    labs(
      title = "Scoring Efficiency by Touch Intensity",
      subtitle = "Touch Intensity = Seconds Per Touch × Dribbles Per Touch",
      x = "Touch Intensity Level",
      y = "Points Per Possession"
    ) +
    theme_minimal() +
    theme(
      plot.title = element_text(size = 14, face = "bold"),
      legend.position = "none"
    )

  print(p3)
  ggsave("efficiency_by_intensity.png", p3, width = 10, height = 7, dpi = 300)

  cat("\nAll visualizations created successfully!\n")
}

# Generate visualizations
create_advanced_visualizations(touch_data)

Practical Applications

1. Offensive Role Identification

# Identify optimal role for a player
def recommend_offensive_role(player_data):
    """
    Recommend offensive role based on touch metrics.
    """
    touch_time = player_data['AVG_SEC_PER_TOUCH']
    dribbles = player_data['AVG_DRIB_PER_TOUCH']
    efficiency = player_data['PTS_PER_POSS']

    if dribbles >= 5.0 and touch_time >= 4.0:
        if efficiency >= 1.0:
            return "Elite Primary Ball Handler"
        else:
            return "High-Usage Player (Efficiency Concerns)"

    elif dribbles >= 3.0 and touch_time >= 2.5:
        return "Secondary Creator/Combo Guard"

    elif dribbles <= 2.0 and touch_time <= 2.5:
        if efficiency >= 1.1:
            return "Efficient Role Player (Ideal 3-and-D)"
        else:
            return "Role Player (Limited Creation)"

    else:
        return "Hybrid Player (Versatile)"

# Apply to dataset
touch_df['RECOMMENDED_ROLE'] = touch_df.apply(recommend_offensive_role, axis=1)

print("\nRecommended Roles Distribution:")
print(touch_df['RECOMMENDED_ROLE'].value_counts())

2. Load Management and Fatigue Analysis

# Calculate workload score
def calculate_ball_handling_workload(df):
    """
    Create composite workload metric from touch data.
    """
    # Normalize metrics to 0-100 scale
    df['TOUCH_LOAD'] = (df['TIME_OF_POSS'] / df['TIME_OF_POSS'].max()) * 100
    df['DRIBBLE_INTENSITY'] = (df['AVG_DRIB_PER_TOUCH'] /
                               df['AVG_DRIB_PER_TOUCH'].max()) * 100
    df['TOUCH_FREQUENCY'] = (df['TOUCHES'] / df['TOUCHES'].max()) * 100

    # Composite workload score
    df['WORKLOAD_SCORE'] = (
        df['TOUCH_LOAD'] * 0.4 +
        df['DRIBBLE_INTENSITY'] * 0.3 +
        df['TOUCH_FREQUENCY'] * 0.3
    )

    return df

touch_df = calculate_ball_handling_workload(touch_df)

# Identify high-workload players
high_workload = touch_df.nlargest(15, 'WORKLOAD_SCORE')[
    ['PLAYER_NAME', 'TEAM_ABBREVIATION', 'TIME_OF_POSS',
     'AVG_DRIB_PER_TOUCH', 'WORKLOAD_SCORE']
]

print("\nPlayers with Highest Ball-Handling Workload:")
print(high_workload)

3. Defensive Game Planning

# Generate defensive scouting report
def generate_defensive_scouting(player_name, df):
    """
    Create defensive game plan based on touch metrics.
    """
    player_data = df[df['PLAYER_NAME'] == player_name]

    if player_data.empty:
        return "Player not found"

    player = player_data.iloc[0]

    report = f"\n{'='*60}\n"
    report += f"DEFENSIVE SCOUTING REPORT: {player_name}\n"
    report += f"{'='*60}\n\n"

    report += f"Touch Metrics:\n"
    report += f"  - Avg Touch Time: {player['AVG_SEC_PER_TOUCH']:.2f} seconds\n"
    report += f"  - Avg Dribbles: {player['AVG_DRIB_PER_TOUCH']:.2f} per touch\n"
    report += f"  - Total Touches: {player['TOUCHES']:.0f} per game\n"
    report += f"  - Time of Possession: {player['TIME_OF_POSS']:.1f} minutes\n"
    report += f"  - Efficiency: {player['PTS_PER_POSS']:.3f} PPP\n\n"

    report += "Defensive Strategy:\n"

    if player['AVG_DRIB_PER_TOUCH'] >= 5.0:
        report += "  • HIGH DRIBBLE USER - Apply physical ball pressure\n"
        report += "  • Force to weak hand, set traps on predictable dribble moves\n"
        report += "  • Anticipate hesitation and between-legs combinations\n"

    if player['AVG_SEC_PER_TOUCH'] >= 4.0:
        report += "  • HIGH TOUCH TIME - Deny ball entry, make them work\n"
        report += "  • Implement aggressive pick-and-roll coverage\n"
        report += "  • Consider switch-heavy schemes to limit rhythm\n"

    if player['AVG_DRIB_PER_TOUCH'] <= 2.0:
        report += "  • QUICK DECISION MAKER - Contest early, no open looks\n"
        report += "  • Focus on off-ball denial and closeout discipline\n"
        report += "  • Don't allow catch-and-shoot opportunities\n"

    if player['TIME_OF_POSS'] >= 7.0:
        report += "  • BALL DOMINANT - Apply full game pressure to induce fatigue\n"
        report += "  • Force into tough shots late in shot clock\n"

    report += f"\nKey Focus: "
    if player['PTS_PER_POSS'] >= 1.1:
        report += "HIGHLY EFFICIENT - Do not help off shooters\n"
    else:
        report += "Force into their primary actions\n"

    return report

# Example reports
print(generate_defensive_scouting("Luka Doncic", touch_df))
print(generate_defensive_scouting("Stephen Curry", touch_df))

4. Player Development and Skill Training

# Track player development over multiple seasons
track_player_development <- function(player_name, seasons) {

  development_data <- data.frame()

  for (season in seasons) {
    Sys.sleep(0.6)  # Rate limiting

    season_data <- get_nba_touch_data(season = season)

    player_season <- season_data %>%
      filter(PLAYER_NAME == player_name) %>%
      mutate(Season = season)

    if (nrow(player_season) > 0) {
      development_data <- rbind(development_data, player_season)
    }
  }

  return(development_data)
}

# Visualize development trajectory
plot_player_development <- function(development_df, player_name) {

  p <- ggplot(development_df, aes(x = Season, group = 1)) +
    geom_line(aes(y = AVG_SEC_PER_TOUCH, color = "Touch Time"),
              size = 1.2) +
    geom_line(aes(y = AVG_DRIB_PER_TOUCH, color = "Dribbles"),
              size = 1.2) +
    geom_point(aes(y = AVG_SEC_PER_TOUCH, color = "Touch Time"),
               size = 3) +
    geom_point(aes(y = AVG_DRIB_PER_TOUCH, color = "Dribbles"),
               size = 3) +
    scale_color_manual(
      values = c("Touch Time" = "steelblue", "Dribbles" = "coral")
    ) +
    labs(
      title = paste(player_name, "- Ball Handling Development"),
      subtitle = "Evolution of touch time and dribbles per touch",
      x = "Season",
      y = "Value",
      color = "Metric"
    ) +
    theme_minimal() +
    theme(
      plot.title = element_text(size = 14, face = "bold"),
      axis.text.x = element_text(angle = 45, hjust = 1)
    )

  return(p)
}

# Example usage (would need multiple seasons of data)
# seasons <- c("2020-21", "2021-22", "2022-23", "2023-24")
# dev_data <- track_player_development("Anthony Edwards", seasons)
# plot_player_development(dev_data, "Anthony Edwards")

5. Team Composition and Roster Construction

# Analyze team touch distribution
def analyze_team_touch_distribution(team_abbrev, df):
    """
    Evaluate touch time distribution for a specific team.
    """
    team_df = df[df['TEAM_ABBREVIATION'] == team_abbrev].copy()

    if team_df.empty:
        return "Team not found"

    # Calculate touch concentration
    total_touches = team_df['TOUCHES'].sum()
    team_df['TOUCH_SHARE'] = (team_df['TOUCHES'] / total_touches) * 100

    # Sort by touches
    team_df = team_df.sort_values('TOUCHES', ascending=False)

    print(f"\n{'='*70}")
    print(f"TEAM TOUCH DISTRIBUTION ANALYSIS: {team_abbrev}")
    print(f"{'='*70}\n")

    print("Top 5 Players by Touch Share:")
    print(team_df.head(5)[
        ['PLAYER_NAME', 'TOUCHES', 'TOUCH_SHARE',
         'AVG_SEC_PER_TOUCH', 'AVG_DRIB_PER_TOUCH', 'PTS_PER_POSS']
    ].to_string(index=False))

    # Calculate team metrics
    top_3_touch_share = team_df.head(3)['TOUCH_SHARE'].sum()
    avg_team_touch_time = team_df['AVG_SEC_PER_TOUCH'].mean()
    avg_team_dribbles = team_df['AVG_DRIB_PER_TOUCH'].mean()

    print(f"\n\nTeam Summary:")
    print(f"  Top 3 Touch Concentration: {top_3_touch_share:.1f}%")
    print(f"  Team Avg Touch Time: {avg_team_touch_time:.2f} seconds")
    print(f"  Team Avg Dribbles: {avg_team_dribbles:.2f} per touch")

    print(f"\n  Roster Balance Assessment:")
    if top_3_touch_share > 60:
        print("  ⚠ HIGH CONCENTRATION - Top-heavy roster, limited depth")
    elif top_3_touch_share < 45:
        print("  ✓ DISTRIBUTED - Balanced touch distribution")
    else:
        print("  ✓ MODERATE - Reasonable concentration with star players")

    if avg_team_dribbles > 3.0:
        print("  • Ball-dominant roster - requires spacing")
    else:
        print("  • Movement-oriented roster - good for pace")

    # Visualize team distribution
    plt.figure(figsize=(12, 6))

    plt.subplot(1, 2, 1)
    plt.pie(team_df.head(8)['TOUCH_SHARE'],
            labels=team_df.head(8)['PLAYER_NAME'],
            autopct='%1.1f%%',
            startangle=90)
    plt.title(f'{team_abbrev} Touch Distribution (Top 8)')

    plt.subplot(1, 2, 2)
    x = range(len(team_df.head(8)))
    plt.bar(x, team_df.head(8)['AVG_DRIB_PER_TOUCH'],
            alpha=0.7, label='Dribbles/Touch')
    plt.bar(x, team_df.head(8)['AVG_SEC_PER_TOUCH'],
            alpha=0.7, label='Seconds/Touch')
    plt.xticks(x, team_df.head(8)['PLAYER_NAME'], rotation=45, ha='right')
    plt.ylabel('Value')
    plt.title(f'{team_abbrev} Player Touch Metrics')
    plt.legend()
    plt.grid(True, alpha=0.3, axis='y')

    plt.tight_layout()
    plt.savefig(f'{team_abbrev}_touch_distribution.png', dpi=300, bbox_inches='tight')
    plt.show()

# Example team analysis
analyze_team_touch_distribution('DAL', touch_df)  # Dallas Mavericks
analyze_team_touch_distribution('BOS', touch_df)  # Boston Celtics

Advanced Topics and Future Directions

Integration with Other Tracking Data

Touch time and dribbles data becomes even more valuable when combined with:

• Shot Quality Metrics: Expected field goal percentage based on dribbles before shot
• Defender Distance: How touch time varies under different defensive pressure
• Court Location: Touch patterns in different zones (perimeter, paint, elbow)
• Passing Data: Touch time before assists vs. touch time before shots
• Player Tracking Speed: Dribble speed and acceleration metrics

Machine Learning Applications

Advanced analytics teams are using touch data for:

• Play Type Classification: Automatically categorize possessions based on touch patterns
• Performance Prediction: Forecast player efficiency based on historical touch metrics
• Lineup Optimization: Predict offensive rating based on combined touch profiles
• Matchup Analysis: Identify optimal defender assignments based on touch tendencies

Limitations and Considerations

• Context Dependency: Touch metrics must be interpreted within team system and offensive scheme
• Sample Size: Small sample sizes can produce misleading per-game averages
• Role Changes: Players transitioning roles may show unusual patterns temporarily
• Injury Impact: Touch time can decrease during injury recovery periods
• Garbage Time: Late-game situations with large leads can skew metrics