From b98497216a139853fb09c9f9a4e711bc0dc68ad2 Mon Sep 17 00:00:00 2001 From: David Oti Date: Thu, 20 Aug 2026 18:38:56 +0100 Subject: [PATCH] Reorganize README.md to clarify relationship to VADER and update scoring changes for version 3.0.0 --- README.md | 77 +++++++++++++++++++++++++++++++------------------------ 1 file changed, 44 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index 2bd4b30..47d2fd4 100644 --- a/README.md +++ b/README.md @@ -10,27 +10,6 @@ PHP Sentiment Analyzer is a lexicon and rule-based sentiment analysis tool for P * Emoticon * Emoji -## Relationship to VADER - -**This package matches reference Python -[vaderSentiment](https://github.com/cjhutto/vaderSentiment) 3.3.2 exactly.** - -The lexicon files are byte-identical to upstream, and the rule engine is a -faithful port — including reference VADER's own quirks, so that scores agree -rather than merely being close. Conformance is verified, not asserted: - -```bash -composer conformance -``` - -That scores a 350-case corpus with both implementations and fails if a single -case differs. It runs in CI on every push. - -Before 3.0.0 this was not true — the port diverged from reference on 47% of -cases, most importantly by applying negation at roughly a third of its intended -strength. See [MIGRATION.md](https://github.com/davmixcool/php-sentiment-analyzer/blob/master/MIGRATION.md) -if you are upgrading from 1.x or 2.x, because **your scores will change**. - ## Requirements * PHP 8.1 and above @@ -41,12 +20,12 @@ if you are upgrading from 1.x or 2.x, because **your scores will change**. ## Contents -* [Relationship to VADER](#relationship-to-vader) * [Install](#install) * [Modern API](#modern-api) * [Simple Usage](#simple-usage) * [Advanced Usage](#advanced-usage) * [Upgrading](#upgrading) +* [Relationship to VADER](#relationship-to-vader) * [License](#license) * [Reference](#reference) @@ -204,21 +183,53 @@ String: To be or not to be? ------------- {"neg":0,"neu":1,"pos":0,"compound":0 ### Upgrading -**1.3.0 changes scores for some text.** `_never_check()` previously zeroed the -sentiment of any word within two tokens of "so" or "this", so ordinary phrasing -returned neutral. That is fixed: +**3.0.0 changes scores.** The scoring engine is now a faithful port of reference +Python VADER; roughly 45% of test cases moved. Previous behaviour was wrong most +importantly in negation, which was applied at about a third of its intended +strength. -| Input | Before | After | +| Input | 2.x | 3.0 | | --- | --- | --- | -| `this is good` | 0.0000 | +0.4404 | -| `this is bad` | 0.0000 | -0.5423 | -| `so good` | 0.0000 | +0.4877 | +| `aint good` | -0.1423 | **-0.3412** | +| `I have never been so happy` | -0.2699 | **+0.6948** | +| `good!!!!` | 0.0000 | **+0.6209** | +| `he is a kind person` | 0.0000 | **+0.5267** | +| `the shit` | +0.6124 | **-0.5574** | + +**If you store sentiment scores or compare them against thresholds, re-score +affected text after upgrading.** A threshold tuned against 2.x will behave +differently — usually catching more genuinely negative text than before. -The genuine "never" behaviour is unchanged: `never so good` still scores -0.2385. +If you need score stability, stay on the maintained 2.x line: -If you store sentiment scores or compare them against thresholds, re-score any -affected text after upgrading. Full details in the -[changelog](https://github.com/davmixcool/php-sentiment-analyzer/blob/master/CHANGELOG.md). +```bash +composer require davmixcool/php-sentiment-analyzer:^2.0 +``` + +Three lines are maintained: **3.x** (matches reference VADER), **2.x** (scores +frozen), **1.x** (PHP below 8.1). Full detail in +[MIGRATION.md](https://github.com/davmixcool/php-sentiment-analyzer/blob/master/MIGRATION.md). + +### Relationship to VADER + +**This package matches reference Python +[vaderSentiment](https://github.com/cjhutto/vaderSentiment) 3.3.2 exactly.** + +The lexicon files are byte-identical to upstream, and the rule engine is a +faithful port — including reference VADER's own quirks, so that scores agree +rather than merely being close. Conformance is verified, not asserted: + +```bash +composer conformance +``` + +That scores a 350-case corpus with both implementations and fails if a single +case differs. It runs in CI on every push. + +Before 3.0.0 this was not true — the port diverged from reference on 47% of +cases, most importantly by applying negation at roughly a third of its intended +strength. See [MIGRATION.md](https://github.com/davmixcool/php-sentiment-analyzer/blob/master/MIGRATION.md) +if you are upgrading from 1.x or 2.x, because **your scores will change**. ### License