Project Purpose

The purpose of this project is to compare media coverage of the National Basketball Association (NBA) and the Women’s National Basketball Association (WNBA) using aggregated story counts collected from Media Cloud. By examiining the volume of news coverage received by each league over time, the project provides an initial assessment of differences in media attention between men’s and women’s professional basketball.

Data Source

Data were obtained from Media Cloud, an open-source platform that collects and analyzes online news content. Story counts were collected from April 19, 2025, through October 21, 2025.

The following search queries were used:

NBA

""LeBron James" OR "Shai Gilgeous-Alexander" OR NBA"

WNBA

""A'ja Wilson" OR "Caitlin Clark" OR WNBA"

Daily story counts were retrieved through the Media Cloud Application Programming Interface (API) and later aggregated into weekly totals.

Project Output

After running the code, it produced two primary outputs:

The first output was an interactive Plotly line graph that illustrated weekly media coverage volume for the NBA and WNBA. The red line represented story counts for the NBA, and the blue line represented story counts for the WNBA.

The second output was a summary statistics table showing total stories, minimums, maximums, medians, means, and standard deviations for each league.

Together, these outputs allow users to examine overall coverage volume and how coverage changed throughout the study period.

Project Development Process

While artificial intelligence (AI) assisted with troubleshooting, code revisions, and documentation, decisions regarding the project topic, search terms, data source, analysis design, and interpretation remained my responsibility.

What I Learned

During this project, I gained experience working with APIs, automated date collection, and data visualizationin R Studio.

These are the specific skills I developed during the process of this project:

The project also demonstrated how computational tools can be used to collect and analyze media coverage at a scale that would be difficult to achieve through manual data collection.

How the Code Works

Step 1: Install and Load Required Packages

The script begins by identifying the R packages needed for the analysis, including tidyverse, httr2, lubridate, plotly, knitr, and kableExtra. It checks whether each package is installed and installs any missing packages automatically. Once all required packages are available, they are loaded into the R session.

Step 2: Verify the Media Cloud API Key

Before collecting data, the script checks whether a valid Media Cloud API key is stored in the user’s system environment. If no API key is found, the script stops and displays an error message. If a key is available, it is stored in the object mc_key for use in API requests.

Step 3: Define the Date Range

The script specifies the time period to be analyzed. For this project, data were collected between April 19, 2025, and October 21, 2025. These dates are later supplied to the Media Cloud API when requesting story counts.

Step 4: Define the Topics and Search Queries

The script creates a set of search queries that represent the topics being studied. For this project, the analysis focuses on the National Basketball Association (NBA) and the Women’s National Basketball Association (WNBA). The NBA query searches for stories containing “LeBron James,” “Shai Gilgeous-Alexander,” or “NBA,” while the WNBA query searches for stories containing “A’ja Wilson,” “Caitlin Clark,” or “WNBA.”

Step 5: Create a Function to Retrieve Story Counts

A custom function, mc_counts_over_time(), is created to communicate with the Media Cloud API. This function submits a search query along with the selected dates and collection information. Media Cloud returns daily story-count data, which are converted into a data frame for analysis.

Step 6: Download Daily Counts for All Topics

The script loops through each search query and downloads daily story-count data from Media Cloud. Each set of results is labeled according to its topic (NBA or WNBA). A 35-second delay is included between requests to avoid exceeding Media Cloud’s API rate limits.

Step 7: Examine the Downloaded Data

After the data are downloaded, the script displays the first several rows and the structure of the data set. This allows the user to verify that the download completed successfully and that the variables are formatted correctly.

Step 8: Convert Daily Counts to Weekly Counts

The downloaded daily data are aggregated into weekly totals. First, each date is assigned to a calendar week using the floor_date() function. The script then groups observations by topic and week and calculates the total number of stories that occurred during each week.

Step 9: Examine Weekly Counts

The weekly data set is displayed so that the user can inspect the aggregated results before proceeding to summary statistics and visualization.

Step 10A: Create Summary Statistics

The script calculates descriptive statistics for each topic. These statistics include the total number of stories, weekly minimum, weekly maximum, weekly median, weekly mean, and weekly standard deviation. The results are then formatted into a professional table using the knitr and kableExtra packages.

Step 10B: Create an Interactive Visualization

An interactive line graph is created using the plotly package. The graph displays weekly story counts for the NBA and WNBA over time. Users can interact with the graph by zooming, panning, and using the built-in range slider to focus on specific periods.

Step 11: Export Weekly Data

The weekly story-count data are exported as a CSV file named weekly_story_counts.csv. This file can be opened in spreadsheet software such as Microsoft Excel or imported into other statistical programs.

Step 12: Create a Wide-Format Data Set

The final step restructures the data into a wide format. Instead of having separate rows for NBA and WNBA observations each week, the data are reorganized so that each week appears once with separate columns for NBA and WNBA story counts. This data set is then exported as weekly_story_counts_wide.csv.

The Complete Script

############################################################
# STEP 1: Install and Load Required Packages
# This step installs any missing packages and then
# loads the packages needed for the analysis.
############################################################

required_packages <- c(
  "tidyverse",
  "httr2",
  "lubridate",
  "plotly",
  "knitr",
  "kableExtra"
)

for (pkg in required_packages) {
  if (!requireNamespace(pkg, quietly = TRUE)) {
    install.packages(pkg)
  }
}

library(tidyverse)
library(httr2)
library(lubridate)
library(plotly)
library(knitr)
library(kableExtra)

############################################################
# STEP 2: Verify Media Cloud API Key
############################################################

if (!nzchar(Sys.getenv("MEDIACLOUD_KEY"))) {
  stop(
    "No Media Cloud API key was found.\n",
    "Run the setup section at the top of the script once,\n",
    "then restart R and try again."
  )
}

mc_key <- Sys.getenv("MEDIACLOUD_KEY")

############################################################
# STEP 3: Define the Date Range
# Enter the beginning and ending dates for the
# period you want to analyze.
############################################################

start_date <- "2025-04-19"
end_date   <- "2025-10-21"

############################################################
# STEP 4: Define Your Topics
# Each topic consists of a topic label and a Media
# Cloud search query.
############################################################

# Agenda-setting query example:

topics <- c(
  "NBA" =
    "\"LeBron James\" OR \"Shai Gilgeous-Alexander\" OR NBA",
  
  "WNBA" =
    "\"A'ja Wilson\" OR \"Caitlin Clark\" OR WNBA"
)

# Framing query example:

# topics <- c(
#   "Economic Frame" =
#     "(immigration OR migrant) AND
#      (jobs OR labor OR economy)",
#
#   "Crime Frame" =
#     "(immigration OR migrant) AND
#      (crime OR drugs OR gang)",
#
#   "Humanitarian Frame" =
#     "(immigration OR migrant) AND
#      (refugee OR asylum OR family)"
# )

############################################################
# STEP 5: Create a Function to Retrieve Daily
# Story Counts
# This function sends a query to Media Cloud and
# retrieves daily story counts.
############################################################

mc_counts_over_time <- function(
    query,
    start_date,
    end_date,
    collection_id = 34412234
) {
  
  resp <-
    request(
      "https://search.mediacloud.org/api/search/count-over-time"
    ) |>
    req_headers(
      Authorization = paste("Token", mc_key)
    ) |>
    req_url_query(
      q = query,
      start = start_date,
      end = end_date,
      platform = "onlinenews-mediacloud",
      cs = collection_id
    ) |>
    req_perform()
  
  results <- resp |> resp_body_json()
  
  map_dfr(
    results$count_over_time$counts,
    as_tibble
  ) |>
    mutate(
      date = as.Date(date)
    )
}

############################################################
# STEP 6: Download Daily Counts for All Topics
# This step retrieves daily counts for every topic
# defined in the topics object.
#
# Media Cloud limits API requests, so a pause is
# inserted between queries.
############################################################

topic_data <-
  imap_dfr(
    topics,
    function(search_string, topic_name) {
      
      message("Downloading: ", topic_name)
      
      results <-
        mc_counts_over_time(
          query = search_string,
          start_date = start_date,
          end_date = end_date
        )
      
      Sys.sleep(35)
      
      results |>
        mutate(
          topic = topic_name
        )
    }
  )

############################################################
# STEP 7: Examine the Downloaded Daily Data
# This step displays the first few rows of the
# downloaded data.
############################################################

head(topic_data)
glimpse(topic_data)

############################################################
# STEP 8: Convert Daily Counts to Weekly Counts
# This step aggregates daily story counts into
# weekly totals for easier visualization.
############################################################

weekly_counts <-
  topic_data |>
  mutate(
    week = floor_date(
      date,
      unit = "week"
    )
  ) |>
  group_by(
    topic,
    week
  ) |>
  summarise(
    stories = sum(count),
    .groups = "drop"
  )

############################################################
# STEP 9: Examine Weekly Counts
# This step displays the weekly data that will be
# graphed.
############################################################

weekly_counts

############################################################
# STEP 10A: Summarize Coverage by Topic
# This step calculates descriptive statistics for
# weekly story counts and displays the results in
# a formatted table.
############################################################

topic_summary <-
  weekly_counts |>
  group_by(topic) |>
  summarise(
    Total_Stories = sum(stories),
    Weekly_Minimum = min(stories),
    Weekly_Maximum = max(stories),
    Weekly_Median = median(stories),
    Weekly_Mean = round(mean(stories), 2),
    Weekly_SD = round(sd(stories), 2),
    .groups = "drop"
  ) |>
  arrange(desc(Total_Stories))

Table <-
  topic_summary |>
  kbl(
    caption = "Media Cloud Topic Summary Statistics",
    align = "lrrrrrr"
  ) |>
  kable_styling(
    full_width = FALSE,
    bootstrap_options = c(
      "striped",
      "hover",
      "condensed"
    )
  )

Table

############################################################
# STEP 10B: Create an Interactive Plotly Graph
# This step creates a line graph showing weekly
# story volume for each topic.
############################################################

Graph <- plot_ly(
  data = weekly_counts,
  x = ~week,
  y = ~stories,
  color = ~topic,
  colors = "Set1",
  type = "scatter",
  mode = "lines+markers"
) |>
  layout(
    title = "Weekly U.S. Coverage Volume",
    xaxis = list(
      title = "Week (with range slider)",
      rangeslider = list(visible = TRUE)
    ),
    yaxis = list(
      title = "Weekly Story Count"
    )
  )

Graph

############################################################
# STEP 11: Save Weekly Counts as a CSV File
# This step exports the weekly counts to a CSV file
# that can be opened in Excel or imported into
# other software.
############################################################

write_csv(
  weekly_counts,
  "weekly_story_counts.csv"
)

############################################################
# STEP 12: Create a Wide-Format Version
# This step creates a spreadsheet with one row per
# week and one column for each topic.
############################################################

weekly_counts_wide <-
  weekly_counts |>
  pivot_wider(
    names_from = topic,
    values_from = stories
  ) |>
  arrange(week)

write_csv(
  weekly_counts_wide,
  "weekly_story_counts_wide.csv"
)

weekly_counts_wide