the perceptron
Astute music recommendations

See in action: http://theperceptron.com

by maryrosecook
maryrosecook.com
maryrosecook@maryrosecook.com

---

A user types in an artist they like and gets recommended other, connected artists.  Connections include friendship, 
music critic recommendation, a record release on the same label, co-occurrence on mixtapes and in people's music 
collections, and appearance at the same gig. 

Each recommended artist has a description, sample track, links to the artist's Myspace and website, and a 'like' button.


When a user says they like a recommended artist, listens to the artist's sample track or visits one of the artist's 
websites, the perceptron increases its trust in the connection's data source.  Afterwards, recommendations from that 
source are shown more prominently.

---

Initial setup

- Pull the code to your machine.

- Create a folder called log in the root of your app.

- Set up the database:
  - Create the database.
  - Create a database.yml file in config/
  - Add your dev database details. e.g:
      development:
          adapter: mysql
          database: theperceptron_development
          username: root
          password: 
          host: localhost
  - Create the database structure:
    - In your terminal:
        cd route/to/theperceptron/folder
        rake db:schema:load
  - Add rows for each data source to the sources table:
    - Run the query in db/sources_table.sql

- Get the required API keys:
  - Yahoo: http://developer.yahoo.com/wsregapp/index.php
  - Last.fm: http://www.last.fm/api/account

- Configure the application:
  - Go into the config/ directory and rename the config.example.yml file to config.yml
  - Fill in your Yahoo API key, Last.fm API key.

- Start the app:
  - In your terminal:
    - Go into the application directory (theperceptron/).
    - ruby script/server

- Create your admin user:
  - Navigate to your locally running version of the perceptron.
  - Click the sign up link, enter your details and save.
  - In your database admin application:
    - Go into the users table.
    - Find the user your just created.
    - Change the 0 in the admin column to a 1.
    
- Administration help:
  - You have an array of administration links (the cryptic letters) in the site's menu bar.
  - You also have an admin bar below each recommendation.
    - website
      - r: clear the website URL stored for this artist.
      - x: clear website URL stored for this artist *and* reject that specific string as wrong so it will not be scraped 
      in the future.
    - myspace
      - r: clear the Myspace URL stored for this artist.
      - x: clear myspace URL stored for this artist *and* reject that specific string as wrong so it will not be scraped 
      in the future.
    - wikipedia
      - r: clear the Wikipedia URL stored for this artist.
      - x: clear Wikipedia URL stored for this artist *and* reject that specific string as wrong so it will not be 
      scraped in the future.
    - track
      - r: clear the sample track URL stored for this artist.
      - x: clear sample track URL stored for this artist *and* reject that specific string as wrong so it will not be 
      scraped in the future.
    - cn: change artist's name to something else.
    - an: add an alternative name to this artist e.g. add Bjork to Björk
    - m: merge all this artist's data with all the data for another artist.
  - x: delete this artist.
  - 27215: id of this artist in the artists table.

- Set up data gathering:
  - You will probably need to automate the gathering of recommendation and artist data.
  - Add entries to your crontab to periodically call the scraping functions.  Mine are below.
  - You may need to change the timings. You will almost certainly need to change the path to the app code and the path 
  to ruby,

  44 * * * * cd /home/admin/public_html/theperceptron.com/current && /usr/bin/ruby script/runner -e production 
  'HypeMachineBlogSource.scrape'
  5  * * * * cd /home/admin/public_html/theperceptron.com/current && /usr/bin/ruby script/runner -e production 
  'MyspaceBandFriendsSource::scrape(nil, true, 100)'
  20 * * * * cd /home/admin/public_html/theperceptron.com/current && /usr/bin/ruby script/runner -e production 
  'Artisting.update_artist_details()'
  10 1 * * * cd /home/admin/public_html/theperceptron.com/current && /usr/bin/ruby script/runner -e production 
  'Recommendation::generate_user_recommendations()'
  2  5 * * * cd /home/admin/public_html/theperceptron.com/current && /usr/bin/ruby script/runner -e production 
  'TinyMixTapesSource.scrape()'
  0,3,7,11,15,19,23,27,31,35,39,43,47,51,55,59 * * * * cd /home/admin/public_html/theperceptron.com/current && 
  /usr/bin/ruby script/runner -e production 'Grading::recalculate_link_grades()'
  19 2 * * * cd /home/admin/public_html/theperceptron.com/current && /usr/bin/ruby script/runner -e production 
  'SourceGrade::recalculate_source_grades()'
  41 * * * * cd /home/admin/public_html/theperceptron.com/current && /usr/bin/ruby script/runner -e production 
  'MyspaceBillsSource.scrape'
  42 6 * * * cd /home/admin/public_html/theperceptron.com/current && /usr/bin/ruby script/runner -e production 
  'TempArtistAssociation::convert_temp_artist_associations()'
  45 * * * * cd /home/admin/public_html/theperceptron.com/current && /usr/bin/ruby script/runner -e production 
  'Artisting::delete_bad_sample_track_urls()'
  50 4 * * * cd /home/admin/public_html/theperceptron.com/current && /usr/bin/ruby script/runner -e production 
  'AbsolutePunkSource.scrape()'


---

How the site works

- Basic approach:
  - Make links between artists via:
    - Tiny Mix Tapes recommendation.
    - Epitonic recommendation.
    - Myspace friendship.
    - Frequent coincidence of purchase on Emusic.
    - Frequent coincidence on mp3 blogs.
    - Last.fm recommendation.
    - Coincidence on gig rosters.
    - Suggestion by users.

- Weight the sources of links by examining user behaviour:
  - User liking/disliking an artist.
  - User adding an artist to their playlist.
  - User visiting an artist's Myspace, website or Wikipedia page.

- Artist data:
  - Automatically scraped and shown to user:
    - sample track
    - Wikipedia summary
    - website link
    - Myspace link

  - Admin:
    - Can reject scraped pieces of data.
      - Click 'x' to ignore a specific value for a specific piece of data.  (That value won't be scraped again.)
      - Click 'r' to delete that piece of data (and re-scrape as normal).
    - Artist identity:
      - Merge two artists.
      - Delete or rename artist.
      - Add alternative name for artist.
    - Tasks that scrape artist links and artist data should be put in a cron job (see crons in /script). 


---

Some great bands: At The Drive-In, The Blood Brothers, Bob Dylan, Circle Takes The Square, Dear And The Headlights, Des 
Ark, Dilute, Heavens To Betsy, Julie Ruin, Love Lost But Not Forgotten, Maximillian Colby, Meshuggah, Orchid, The Paper 
Chase, Sonic Youth, Sunset Rubdown, Team Dresch, Tracy + The Plastics, V For Vendetta, Xiu Xiu.