PheldItunesReporter 1.0.0

data/History.txt

@@ -0,0 +1,6 @@
+=== 1.0.0 / 2008-12-17
+
+* 1 major enhancement
+
+  * Birthday!
+

data/Manifest.txt

@@ -0,0 +1,8 @@
+History.txt
+Manifest.txt
+README.txt
+Rakefile
+bin/pheld_itunes_reporter
+lib/pheld_itunes_data_miner.rb
+lib/pheld_itunes_track.rb
+test/test_pheld_itunes_data_miner.rb

data/README.txt

@@ -0,0 +1,70 @@
+= PheldItunesReporter
+
+* http://rubyforge.org/projects/uwruby
+* http://uwruby.rubyforge.org/pheld_itunes_reporter
+
+== DESCRIPTION:
+
+PheldItunesReporter provides a library and corresponding executable script that calculate and report statistics for a given iTunes library file.  When executed, the script prints a text summary of all of the statistics it is capable of generating.  It also creates four .PNG image files with graphs of key statistics.
+
+== FEATURES/PROBLEMS:
+
+The included library can generate the following statistics about the tracks in the iTunes library:
+* total play time
+* total number of tracks
+* total number of genres
+* total number of artists
+* total number of albums
+* average year
+* N most popular genres
+* N most popular artists
+* N most popular years
+* number of tracks added for each year
+* correlation between bitrate and play count
+* correlation between rating and play count
+* guesstimated age of library owner
+
+== SYNOPSIS:
+
+To run the reporter script, simply navigate to the root of the source folder and type "./bin/pheld_itunes_reporter.rb <path_to_itunes_library.xml>".  All supported statistics are then printed and four image files with graphs are written to the current directory.
+
+The PheldItunesDataMiner library is used to parse the iTunes library XML and generate statistics.  No parameters are passed to the 'new' method.  To get statistics, a new data miner instance is created, then the 'parse' method is called.  Once that has been done, the other methods for statistics generation can be used.  
+
+Example:
+data_miner = PheldItunesDataMiner.new
+tracks = data_miner.parse_file('iTunes\ Music\ Library.xml')
+ten_most_popular_artists = data_miner.get_most_popular_artists(tracks, 10)
+
+== REQUIREMENTS:
+
+* Nokogiri >= 1.0.6
+* RMagick >= 2.8.0 
+
+== INSTALL:
+
+sudo gem install pheld_itunes_reporter
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2008 FIX
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,20 @@
+# -*- ruby -*-
+
+require 'rubygems'
+require 'hoe'
+require 'nokogiri'
+require 'rmagick'
+require 'gruff'
+require './lib/pheld_itunes_data_miner.rb'
+
+Hoe.new('PheldItunesReporter', PheldItunesDataMiner::VERSION) do |p|
+  p.rubyforge_name = 'uwruby'
+  p.developer('Peter Held', 'peter.t.held@gmail.com')
+  p.need_zip = true
+
+  p.extra_deps << ['nokogiri', '>= 1.0.6']
+  p.extra_deps << ['rmagick', '>= 2.8.0']
+  p.extra_deps << ['gruff', '>= 0.3.4']
+end
+
+# vim: syntax=Ruby

data/bin/pheld_itunes_reporter

@@ -0,0 +1,175 @@
+#!/usr/bin/ruby
+
+require 'rubygems'
+require 'optparse'  # for taking input
+require 'gruff'     # for generating graphs - requires RMagick...sorry!
+require 'lib/pheld_itunes_data_miner.rb'
+
+##
+# Student Name: Peter Held
+# Homework Week: 8
+#
+# This class outputs 4 PNG files.  Please see them for the graphs.  RMagick is required :(
+#
+
+
+class PheldItunesReporter
+  VERSION = '1.0.0'
+  
+  def initialize(options, itunes_library_file)
+    @number_of_popular = options.number_of_popular
+    @data_miner = PheldItunesDataMiner.new
+    @tracks = @data_miner.parse_file(itunes_library_file)
+  end
+
+  def self.run(args)
+    options = ItunesReporterParser.parse(args)
+    unless ARGV.length == 0
+      reporter = PheldItunesReporter.new(options, ARGV[0])
+      reporter.make_top_artists_graph
+      reporter.make_top_years_graph
+      reporter.make_top_genres_graph
+      reporter.make_tracks_added_by_year_graph
+      reporter.print_stats
+    end
+  end
+
+  def print_stats
+    @data_miner.print_stats(@tracks)
+  end
+
+  def print_correlation
+    rating_playcount_correlation = @data_miner.get_rating_playcount_correlation(@tracks)
+    puts "The correlation between rating and play count is: #{rating_playcount_correlation.to_s}."
+    bitrate_playcount_correlation = @data_miner.get_bitrate_playcount_correlation(@tracks)
+    puts "The correlation between bit rate and play count is: #{bitrate_playcount_correlation.to_s}."
+
+  end
+
+  def make_top_artists_graph
+    # set up the graph
+    graph = Gruff::SideBar.new
+    graph.title = "Top #{@number_of_popular.to_s} Artists"
+
+    # add the data
+    most_popular_artists = @data_miner.get_most_popular_artists(@tracks, @number_of_popular)
+
+    graph.data("Tracks per Artist", most_popular_artists.map {|item| item[1]})
+    labels = {}
+    @index = 0
+    most_popular_artists.each do |item|
+      labels[@index] = item[0]
+      @index += 1
+    end
+    graph.labels = labels
+
+    graph.maximum_value = ((most_popular_artists[0][1] / 10) * 10) + 10
+    graph.minimum_value = 0
+
+    graph.write("top_artists.png")
+  end
+
+  def make_top_years_graph
+    # set up the graph
+    graph = Gruff::SideBar.new
+    graph.title = "Top #{@number_of_popular.to_s} Years"
+
+    # add the data
+    most_popular_years = @data_miner.get_most_popular_years(@tracks, @number_of_popular)
+
+    # add the axis labels
+    graph.data("Tracks per year", most_popular_years.map {|item| item[1]})
+    labels = {}
+    index = 0
+    most_popular_years.each do |item|
+      labels[index] = item[0].to_s
+      index += 1
+    end
+    graph.labels = labels
+
+    graph.maximum_value = ((most_popular_years[0][1] / 10) * 10) + 10
+    graph.minimum_value = 0
+
+    graph.write("top_years.png")
+  end
+
+  def make_top_genres_graph
+    # set up the graph
+    graph = Gruff::SideBar.new
+    graph.title = "Top #{@number_of_popular.to_s} Genres"
+
+    # add the data
+    most_popular_genres = @data_miner.get_most_popular_genres(@tracks, @number_of_popular)
+
+    # add the axis labels
+    graph.data("Tracks per genre", most_popular_genres.map {|item| item[1]})
+    labels = {}
+    index = 0
+    most_popular_genres.each do |item|
+      labels[index] = item[0].to_s
+      index += 1
+    end
+    graph.labels = labels
+
+    graph.maximum_value = ((most_popular_genres[0][1] / 10) * 10) + 10
+    graph.minimum_value = 0
+
+    graph.write("top_genres.png")
+  end
+
+  def make_tracks_added_by_year_graph
+    # set up the graph
+    graph = Gruff::Bar.new
+    graph.title = "Tracks Added by Year"
+
+    # add the data
+    tracks_added_by_year = @data_miner.get_tracks_added_by_year(@tracks)
+
+    # add the axis labels
+    graph.data("Tracks Added", tracks_added_by_year.map {|item| item[1]})
+    labels = {}
+    index = 0
+    max = 0
+    tracks_added_by_year.each do |item|
+      labels[index] = item[0].to_s
+      index +=1
+
+      # keep track of the max value so we can format the Y axis
+      if item[1] > max
+        max = item[1]
+      end
+    end
+    graph.labels = labels
+
+    graph.maximum_value = ((max / 10) * 10) + 10
+    graph.minimum_value = 0
+
+    graph.write("tracks_added_by_year.png")
+  end
+end
+
+# Parser class to handle option flags
+class ItunesReporterParser
+  def self.parse(args)
+    # pp args
+
+    options = OpenStruct.new
+    options.number_of_popular = 10  # default to listing the top 10 popular things
+
+    opts = OptionParser.new do |opts|
+      opts.banner = "Usage: itunes_reporter.rb [options] <itunes_library_file_1> <itunes_library_file_2> ... <itunes_library_file_n>"
+
+      opts.separator ""
+      opts.separator "Specific options:"
+
+      opts.on("-n", "--number [NUMBER]", Integer, "Number of files to report for maximums.") do |number|
+        options.number_of_popular = number
+      end
+    end
+
+    opts.parse!(args)
+    options
+  end
+end
+
+PheldItunesReporter.run(ARGV) if $0 == __FILE__

data/lib/pheld_itunes_data_miner.rb

@@ -0,0 +1,405 @@
+#!/usr/bin/ruby
+
+require 'rubygems'
+require 'nokogiri'  # Nokogiri (XML parsing)
+require 'ostruct'   # OpenStruct
+require 'ftools'    # File
+require 'set'
+require 'lib/pheld_itunes_track.rb'
+
+##
+# Student Name: Peter Held
+# Homework Week: 8
+#
+#
+
+class PheldItunesDataMiner
+  VERSION = '1.0.0'
+
+  def self.run file_name
+    # read the tracks
+    idm = PheldItunesDataMiner.new
+    tracks = idm.parse_file(file_name)
+
+    # print the stats
+    idm.print_stats(tracks)
+  end
+
+  def print_stats tracks
+    # totals
+    puts "Track count: #{tracks.length.to_s}"
+    puts "Number of artists: #{get_number_of_artists(tracks).to_s}"
+    puts "Number of albums: #{get_number_of_albums(tracks).to_s}"
+    total_playtime = get_total_playtime(tracks)
+    puts "Total playtime: #{total_playtime[0].to_s} days, #{total_playtime[1].to_s} hours, #{total_playtime[2].to_s} minutes, #{total_playtime[3].to_s} seconds"
+
+    # popular stuff
+    ten_most_popular_artists = get_most_popular_artists(tracks, 10)
+    puts "Ten most popular artists:"
+    ten_most_popular_artists.each do |artist|
+      puts "\t\"#{artist[0]}\"  -  #{artist[1].to_s} tracks"
+    end
+    ten_most_popular_years = get_most_popular_years(tracks, 10)
+    puts "Ten most popular years:"
+    ten_most_popular_years.each do |year|
+      puts "\t\"#{year[0]}\"  -  #{year[1].to_s} tracks"
+    end
+    ten_most_popular_genres = get_most_popular_genres(tracks, 10)
+    puts "Ten most popular genres:"
+    ten_most_popular_genres.each do |genre|
+      puts "\t\"#{genre[0]}\"  -  #{genre[1].to_s} tracks"
+    end
+
+
+    # other interesting statistics
+    tracks_added_per_year = get_tracks_added_by_year(tracks)
+    puts "The number of tracks added each year was:"
+    tracks_added_per_year.each do |year|
+      puts "\t\"#{year[0].to_s}\"  -  #{year[1].to_s} tracks"
+    end
+    bitrate_playcount_correlation = get_bitrate_playcount_correlation(tracks)
+    puts "The correlation between bit rate and play count is: #{bitrate_playcount_correlation.to_s}."
+    rating_playcount_correlation = get_rating_playcount_correlation(tracks)
+    puts "The correlation between rating and play count is: #{rating_playcount_correlation.to_s}."
+    age_guess = guess_age(tracks)
+    puts "According to my calculations/assumptions and other peoples' research, your age is #{age_guess.to_s}."
+  end
+
+  def parse_file file_name
+    if !File.exists?(file_name)
+      return nil
+    end
+
+    file = File.new(file_name)
+    file_text = file.read
+
+    parse_library file_text
+  end
+
+  def parse_library library_xml
+    tracks = []
+    doc = Nokogiri::XML.parse(library_xml)
+
+    # get an array of the track xmls
+    last_key = nil
+    doc.xpath('/plist/dict/dict/dict').each do |track_xml|
+      track = PheldItunesTrack.new
+
+      track_xml.children.each do |element|
+        if (element.name == "key" )
+          last_key = element.text
+        else
+          case last_key
+          when "Track ID" then track.track_id = element.text.to_i
+          when "Name" then track.name = element.text.strip
+          when "Artist" then track.artist = element.text.strip
+          when "Album" then track.album = element.text.strip
+          when "Total Time" then track.total_time = element.text.to_i
+          when "Year" then track.year = element.text.to_i
+          when "Bit Rate" then track.bit_rate = element.text.to_i
+          when "Play Count" then track.play_count = element.text.to_i
+          when "Rating" then track.rating = element.text.to_i
+          when "Date Added" then track.date_added = Date.parse(element.text)
+          when "Genre" then track.genre = element.text.strip
+          end
+        end
+      end
+
+      tracks << track
+    end
+
+    tracks
+  end
+  
+  def get_number_of_artists tracks
+    # scrub the tracks for nils
+    scrubbed_tracks = tracks.delete_if {|track| track.artist == nil }
+
+    scrubbed_tracks.map { |track| track.artist }.uniq.length
+  end
+  
+  def get_number_of_albums tracks
+    # scrub the tracks for nils
+    scrubbed_tracks = tracks.delete_if {|track| track.album == nil }
+
+    scrubbed_tracks.map { |track| track.album }.uniq.length
+  end
+
+  def get_number_of_genres tracks
+    # scrub the tracks for nils
+    scrubbed_tracks = tracks.delete_if {|track| track.genre == nil }
+
+    scrubbed_tracks.map { |track| track.genre }.uniq.length
+  end
+  
+  def get_number_of_tracks tracks
+    tracks.length
+  end
+    
+  def get_total_playtime tracks
+    # scrub the tracks for nils
+    scrubbed_tracks = tracks.delete_if {|track| track.total_time == nil }
+
+    total_playtime = 0
+
+    scrubbed_tracks.each do |track|
+      total_playtime = total_playtime + track.total_time
+    end
+
+    # takes seconds, but iTunes stores in milliseconds
+    seconds_fraction_to_time(total_playtime / 1000)
+  end
+
+  def get_tracks_added_by_year tracks
+    # scrub the tracks for nils
+    scrubbed_tracks = tracks.delete_if {|track| track.date_added == nil}
+
+    tracks_added_by_year = {}    # hash to store year added counts
+
+    # get the list of track occurance counts
+    scrubbed_tracks.each do |track|
+      year_added = track.date_added.year
+
+      if tracks_added_by_year[year_added]
+        tracks_added_by_year[year_added] += 1
+      else
+        tracks_added_by_year[year_added] = 1
+      end
+    end
+
+    tracks_added_by_year.sort   # sort by year
+  end
+
+  def get_most_popular_artists tracks, list_depth
+    # scrub the tracks for nils
+    scrubbed_tracks = tracks.delete_if {|track| track.artist == nil }
+
+    artists = {}    # hash to store artist counts
+    top_artists = []
+
+    # get the list of artist occurance counts
+    scrubbed_tracks.each do |track|
+      if artists[track.artist]
+        artists[track.artist] += 1
+      else
+        artists[track.artist] = 1
+      end
+    end
+
+    # sort by the occurance counts
+    sorted_artists = artists.sort {|a,b| b[1]<=>a[1]}
+
+    if list_depth > 0
+      (0..(list_depth - 1)).each do |index|
+        if sorted_artists[index]
+          top_artists << [ sorted_artists[index][0], sorted_artists[index][1] ]
+        end
+      end
+    end
+
+    top_artists
+  end
+  
+  def get_most_popular_years tracks, list_depth
+    # scrub the tracks for nils
+    scrubbed_tracks = tracks.delete_if {|track| track.year == nil }
+
+    years = {}    # hash to store artist counts
+    top_years = []
+
+    # get the list of artist occurance counts
+    scrubbed_tracks.each do |track|
+      if years[track.year]  # make sure the list even has this many in it
+        years[track.year] = years[track.year] + 1
+      else
+        years[track.year] = 1
+      end
+    end
+
+    # sort by the occurance counts
+    sorted_years = years.sort {|a,b| b[1]<=>a[1]}
+
+    if list_depth > 0
+      (0..(list_depth - 1)).each do |index|
+        if sorted_years[index]  # make sure the list even has this many in it
+          top_years << [ sorted_years[index][0], sorted_years[index][1] ]
+        end
+      end
+    end
+
+    top_years
+  end
+
+  def get_most_popular_genres tracks, list_depth
+    # scrub the tracks for nils
+    scrubbed_tracks = tracks.delete_if {|track| track.genre == nil }
+
+    genres = {}    # hash to store genre counts
+    top_genres = []
+
+    # get the list of artist occurance counts
+    scrubbed_tracks.each do |track|
+      if genres[track.genre]
+        genres[track.genre] += 1
+      else
+        genres[track.genre] = 1
+      end
+    end
+
+    # sort by the occurance counts
+    sorted_genres = genres.sort {|a,b| b[1]<=>a[1]}
+
+    if list_depth > 0
+      (0..(list_depth - 1)).each do |index|
+        if sorted_genres[index]
+          top_genres << [ sorted_genres[index][0], sorted_genres[index][1] ]
+        end
+      end
+    end
+
+    top_genres
+  end
+  
+  def get_bitrate_playcount_correlation tracks
+    # scrub the tracks for nils
+    scrubbed_tracks = tracks.delete_if {|track| (track.bit_rate == nil) || (track.play_count == nil) || (track.date_added == nil)}
+
+    bit_rates = get_bit_rate scrubbed_tracks
+    play_counts = get_play_counts_normalized_for_date_added scrubbed_tracks
+
+    correlation(bit_rates, play_counts)
+  end
+
+  def get_rating_playcount_correlation tracks
+    # scrub the tracks for nils
+    scrubbed_tracks = tracks.delete_if {|track| (track.play_count == nil) || (track.rating == nil) || (track.date_added == nil)}
+
+    play_counts = get_play_counts_normalized_for_date_added scrubbed_tracks
+    ratings = get_rating scrubbed_tracks
+
+    correlation(play_counts, ratings)
+  end
+
+  # see http://www.mcgill.ca/reporter/39/01/expert/
+  def guess_age tracks
+    average_year = get_average_year(tracks)
+
+    Time.now.year - average_year + 14
+  end
+
+  def get_average_year tracks
+    # scrub the tracks for nils
+    scrubbed_tracks = tracks.delete_if {|track| track.year == nil}
+
+    total = 0
+    scrubbed_tracks.each do |track|
+      total += track.year
+    end
+    
+    total / tracks.length
+  end
+  
+  # Converts seconds to an array with days, hours, minutes and seconds
+  def seconds_fraction_to_time seconds
+    days = hours = mins = 0
+    
+    if seconds >=  60 then
+      mins = (seconds / 60).to_i 
+      seconds = (seconds % 60 ).to_i
+      
+      if mins >= 60 then
+        hours = (mins / 60).to_i 
+        mins = (mins % 60).to_i
+        
+        if hours >= 24 then
+          days = (hours / 24).to_i
+          hours = (hours % 24).to_i
+        end
+      end
+    end
+   
+    [days,hours,mins,seconds]
+  end
+
+  def get_play_count tracks
+    play_counts = []
+
+    tracks.each do |track|
+      play_counts << track.play_count
+    end
+
+    play_counts
+  end
+
+  def get_play_counts_normalized_for_date_added tracks
+    play_counts = []
+
+    tracks.each do |track|
+      play_counts << get_playcount_normalized_for_date_added(track)
+    end
+
+    play_counts
+  end
+
+  def get_rating tracks
+    ratings = []
+
+    tracks.each do |track|
+      ratings << track.rating
+    end
+
+    ratings
+  end
+
+  def get_bit_rate tracks
+    bit_rates = []
+
+    tracks.each do |track|
+      bit_rates << track.bit_rate
+    end
+
+    bit_rates
+  end
+
+  def get_playcount_normalized_for_date_added track
+    # Normalize for the age in days.  Multiplied by 10000 so that the values aren't fractions
+    # and the correlation() method can use them.
+    age_normalized = (10000 * track.play_count / (Date.today - track.date_added)).round
+    age_normalized
+  end
+
+  # From http://blog.trevorberg.com/2008/08/13/standard-deviation-and-correlation-coefficient-in-ruby/
+  def correlation(x, y)
+   # Calculate the necessary values
+   n = x.size
+
+   sum_x = sum(x)
+   sum_y = sum(y)
+
+   x_squared = x.map {|item| item*item }
+   y_squared = y.map {|item| item*item }
+
+   sum_x_squared = sum(x_squared)
+   sum_y_squared = sum(y_squared)
+
+   xy = []
+   x.each_with_index do |value, key|
+     xy << value * y[key]
+   end
+
+   sum_xy = sum(xy)
+
+   # Calculate the correlation value
+   left = n * sum_xy - sum_x * sum_y
+   right = ((n * sum_x_squared - sum_x**2) * (n * sum_y_squared - sum_y**2)) ** 0.5
+
+   left / right
+  end
+
+  # From http://blog.trevorberg.com/2008/08/13/standard-deviation-and-correlation-coefficient-in-ruby/
+  def sum(list)
+   list.inject( nil ) { |sum,x| sum ? sum+x : x };
+  end
+end
+
+ItunesDataMiner.run(ARGV[0]) if $0 == __FILE__