Merge pull request #131 from thisandagain/develop

Release v4.2.0

README.md

@@ -41,6 +41,64 @@ console.dir(result);    // Score: 7, Comparative: 1.75
 
 ---
 
+### How it works
+#### AFINN 
+AFINN is a list of words rated for valence with an integer between minus five (negative) and plus five (positive). Sentiment analysis is performed by cross-checking the string tokens(words, emojis) with the AFINN list and getting their respective scores. The comparative score is simply: `sum of each token / number of tokens`. So for example let's take the following:
+
+`I love cats, but I am allergic to them.`
+
+That string results in the following:
+```javascript
+{
+    score: 1,
+    comparative: 0.1111111111111111,
+    tokens: [
+        'i',
+        'love',
+        'cats',
+        'but',
+        'i',
+        'am',
+        'allergic',
+        'to',
+        'them'
+    ],
+    words: [
+        'allergic',
+        'love'
+    ],
+    positive: [
+        'love'
+    ],
+    negative: [
+        'allergic'
+    ]
+}
+```
+
+* Returned Objects
+    * __Score__: Score calculated by adding the sentiment values of recongnized words.
+    * __Comparative__: Comparative score of the input string.
+    * __Token__: All the tokens like words or emojis found in the input string.
+    * __Words__: List of words from input string that were found in AFINN list. 
+    * __Positive__: List of postive words in input string that were found in AFINN list.
+    * __Negative__: List of negative words in input string that were found in AFINN list.
+
+In this case, love has a value of 3, allergic has a value of -2, and the remaining tokens are neutral with a value of 0. Because the string has 9 tokens the resulting comparative score looks like:
+`(3 + -2) / 9 = 0.111111111`
+
+This approach leaves you with a mid-point of 0 and the upper and lower bounds are constrained to positive and negative 5 respectively (the same as each token! 😸). For example, let's imagine an incredibly "positive" string with 200 tokens and where each token has an AFINN score of 5. Our resulting comparative score would look like this:
+
+```
+(max positive score * number of tokens) / number of tokens
+(5 * 200) / 200 = 5
+```
+
+#### Tokenization
+Tokenization works by splitting the lines of input string, then removing the special characters, and finally splitting it using spaces. This is used to get list of words in the string. 
+
+---
+
 ### Benchmarks
 A primary motivation for designing `sentiment` was performance. As such, it includes a benchmark script within the test directory that compares it against the [Sentimental](https://github.com/thinkroth/Sentimental) module which provides a nearly equivalent interface and approach. Based on these benchmarks, running on a MacBook Pro with Node v6.9.1, `sentiment` is **twice as fast** as alternative implementations:
 
@@ -74,8 +132,8 @@ Yelp:    0.67
 #### Rand Accuracy (AFINN + Additions)
 ```
 Amazon:  0.72 (+2%)
-IMDB:    0.76 (+0%)
-Yelp:    0.69 (+2%)
+IMDB:    0.77 (+1%)
+Yelp:    0.70 (+3%)
 ```
 
 ---

lib/index.js

@@ -16,7 +16,9 @@ var negators = {
     'wont': 1,
     'won\'t': 1,
     'isnt': 1,
-    'isn\'t': 1
+    'isn\'t': 1,
+    'wasnt': 1,
+    'wasn\'t': 1
 };
 
 /**

package.json

@@ -2,7 +2,7 @@
   "author": "Andrew Sliwinski <andrewsliwinski@acm.org>",
   "name": "sentiment",
   "description": "AFINN-based sentiment analysis for Node.js",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "license": "MIT",
   "homepage": "https://github.com/thisandagain/sentiment",
   "repository": {
@@ -24,7 +24,7 @@
     "Sentimental": "1.0.1",
     "benchmark": "^2.1.0",
     "eslint": "^4.6.1",
-    "tap": "^10.1.0"
+    "tap": "^11.0.1"
   },
   "engines": {
     "node": ">=4.0"