jakepeyser / runkeeper-hashmatch

Runkeeper Hashmatch discovers the running hashtag most aligned with your personality by using Watson Personality Insights and your Twitter timeline

runkeeper-hashmatch Overview

Runkeeper Hashmatch uses the IBM Watson Personality Insights service and Twitter to match you with the specific running hashtags. After inputting your Twitter handle, your tweets are sent to Personality Insights to analyze the text and output a personality profile. That profile is compared against the profiles of popular running hashtags, giving us a visualization of what hashtag you most align with. For more information on how the hashtag profiles are compiled, check out the Analyzing Hashtag Data section below.

Note: If you deploy the application in Bluemix using the above button, you will need to complete steps 9-14 below to finish the setup process.

Running the app on Bluemix

1. If you do not already have a Bluemix account, sign up here

2. Download and install the Cloud Foundry CLI tool

3. Clone the app to your local environment from your terminal using the following command:

$ git clone https://github.com/JakePeyser/runkeeper-hashmatch.git

4. cd into this newly created directory

5. Open the manifest.yml file and change the host value to something unique

The host you choose will determinate the subdomain of your application's URL: <host>.mybluemix.net

6. Connect to Bluemix in the command line tool and follow the prompts to log in:

$ cf api https://api.ng.bluemix.net
$ cf login

7. Create the Personality Insights service in Bluemix:

$ cf create-service personality_insights tiered runkeeper-personality-insights

8. Push your app to Bluemix. We need to perform additional steps once it is deployed, so we will add the --no-start option:

$ cf push --no-start

9. Create a Twitter app

10. Create a user-provided service to represent your Twitter app, taking the corresponding credentials from your Twitter app's Keys and Access Tokens page:

    $ cf cups runkeeper-twitter -p '{"access_token_key":"KEY","access_token_secret":"SECRET","consumer_key":"KEY","consumer_secret":"SECRET"}'
    

11. Bind this Twitter service to your app:

    $ cf bind-service runkeeper-hashmatch runkeeper-twitter
    

12. Create a managed MongoDB instance on Compose.io

    • Sign up for a Compose.io free trial and select MongoDB or use your existing account and create a new MongoDB deployment
    • Once your Mongo deployment has been provisioned, create a DB called runkeeperDB
    • Navigate to the Users tab of your new DB and select Add User. Assign your username and password as rk-admin and rk-key, respectively
    • Navigate to the Admin tab and note the host (e.g. horace.1.mongolayer.com) and port of your primary replica set

13. Go to the MongoDB by Compose service in the Bluemix catalog

    • Bind the service to runkeeper-hashmatch
    • Name the service runkeeper-mongo-db
    • Fill out your credentials with the info from the previous steps
    • Click Create

14. Restage your application, either by accepting the prompt after the last step or executing the following command:

    $ cf restage runkeeper-hashmatch
    

And voila! You now have your very own instance of Runkeeper Hashmatch running on Bluemix. Now all that is left is to populate your DB with hashtag pesonality data for comparisons. Check out the Analyzing Hashtag Data section for instructions on this process.

Running the app locally

1. If you do not already have a Bluemix account, sign up here

2. If you have not already, download node.js and install it on your local machine

3. Clone the app to your local environment from your terminal using the following command

$ git clone https://github.com/JakePeyser/runkeeper-hashmatch.git

4. cd into this newly created directory

5. Create a Personality Insights service using your Bluemix account and replace the corresponding credentials in your vcap-local.json file

6. Create a Twitter app and copy the credentials over to your vcap-local.json file

7. Install mongodb

8. Install the required npm packages using the following command:

$ npm install

9. Start mongodb in a separate terminal window:

$ mongod

10. Start the app in your original terminal window:

$ npm start

Your app will be automatically assigned to a port which will be logged to your terminal. To access the app, go to localhost:PORT in your browser. Now all that is left is to populate your DB with hashtag pesonality data for comparisons. Check out the Analyzing Hashtag Data section for instructions on this process. Happy developing!

Additional Setup

Creating a Twitter App

1. Sign up for Twitter or use your existing account to create a new Twitter app

   • Name it runkeeper-hashmatch-ID, substituting your GitHub username for ID
   • Give it a description
   • Use this project's GitHub repo or the URL of your fork as the website

2. Create your Twitter app access token

   • Navigate to the Keys and Access Tokens tab
   • Click the button labeled Create my access token

Analyzing Hashtag Data

/analyze/twitter/@hashtag: Finds users who have recently tweeted using #hashtag, collects their tweets, and stores them in the profiles collection in the database.

/analyze/personality/@hashtag: Aggregates users' tweets for the input hashtag and runs them through the Personality Insights API, saving the results in the hashtags collection in the database. If analysis for the hashtag already exists, it is overwritten with the new results

Note: Keep the Twitter API rate limiting policy in mind, as the first route hits the API an average of 25 times per call.

Routes

/like/@handle: Runs the Runkeeper Hashmatch algorithm on the input Twitter handle.

/lists/profiles: Lists the individuals whose tweets have been used as input for the personality analysis of the running hashtags.

/lists/users: Lists the users whose tweets have previously been analyzed by Personality Insights and compared to the aggregate personalities of the running hashtags.

/lists/hashtags: Lists the running hashtags and the number of respective users whose tweets were included as a part of their personality analysis.

/data/profiles: Sends back all profiles in the database in JSON format. Additional routes of id/@id and hashtag/@hashtag are available for returning a subset of profiles.

/data/users: Sends back all users in thee database in JSON format. The additional route of id/@id is available for returning a unique user.

/data/hashtags: Sends back all hashtags in the database in JSON format. The additional route of hashtag/@hashtag is available for returning a unique hashtag.

/data/images: Sends back all images for hashtags in the database in JSON format. The additional route of add/@url is available for adding additional images.

Troubleshooting

The primary source of debugging information for your Bluemix app is the logs. To see them, run the following command using the Cloud Foundry CLI:

$ cf logs runkeeper-hashmatch --recent

For more detailed information on troubleshooting your application, see the Troubleshooting section in the Bluemix documentation.

Contribute

We are more than happy to accept external contributions to this project, be it in the form of issues and pull requests. If you find a bug, please report it via the Issues section or even better, fork the project and submit a pull request with your fix! Pull requests will be evaulated on an individual basis based on value add to the sample application.

Special thanks to the development team behind Your Celebrity Match for the code base that this application was built on.

Privacy Notice

The capital-weather sample web application includes code to track deployments to Bluemix and other Cloud Foundry platforms. The following information is sent to a Deployment Tracker service on each deployment:

• Application Name (application_name)
• Space ID (space_id)
• Application Version (application_version)
• Application URIs (application_uris)

This data is collected from the VCAP_APPLICATION environment variable in IBM Bluemix and other Cloud Foundry platforms. This data is used by IBM to track metrics around deployments of sample applications to IBM Bluemix. Only deployments of sample applications that include code to ping the Deployment Tracker service will be tracked.

Disabling Deployment Tracking

Deployment tracking can be disabled by removing require("cf-deployment-tracker-client").track(); from the beginning of the app.js file.

runkeeper-hashmatch's Issues

Use vcap-local configs

Configure app to use cfenv npm package to manage credentials instead of .config file

Implement Handler for Big Five Comparison

Build back end code for comparing users based on their big five personality traits

Update Front End for RunKeeper

Update the original front end code so that it uses Runkeeper color palette and new UI

Implement Front End for Big Five Comparison

Change front end JS and markup for ingesting big five comparison

Build README for App

Create the README for the app based on the IBM-Bluemix repo guidelines so that the repo is self-serve for developers.

Populate Hashtag Collection

The rate limiting on the Twitter API prevents us from grabbing all the data we need at once. The back end has been re-architected to allow for tweet processing in bite-size pieces. This issue can track the status of populating the DB to make sure all hashtags are processed.

• runkeeper
• global5k
• runtoroutine
• runner
• runnerbliss
• run4fun
• runnerd
• jogging
• trailrunning
• marathon
• fitfam
• marathon
• halfmarathon
• bibchat
• runspiration
• runhappy
• cardio
• endurance
• fitmom
• fitfluential
• fitness
• fitnessaddict

Create Algorithm for Retrieving Data

Build the Twitter/Personality Insights data retrieval algorithm, designed with the solution from #1

Change /celebrities to list hashtags

Instead of listing Profiles, change this list view to show the hashtags and their personality breakdowns in the DB

Finalize Spectrum Words

Decide on final spectrum words for Needs and Values comparison parameters.

Transform base project

Update the base yourcelebritymatch repo to resemble what will be the runkeeper-hashmatch project

Solution Data Design

Determine which data will be stored and how it will be structured in the DB

Update Terms of Service

Update the terms of service page

Implement Handlers for Needs and Values Comparisons

Build back end code for comparing users based on their needs and values

Implement Front End for Needs and Values Comparisons

Change front end JS and markup for ingesting needs and values comparisons

Image for Hashtag

Populate more appropriate images for the hashtags in the DB

Improve memory management

App is crashing when running analysis repeatedly. Inspect memory management and fix large leaks.