Document Serbian WordNet sentiment classifier and research paper

Expand model card with task, labels, original base model, paper citation, paired classifiers, inference example, archived results and provenance. Preserve historical training records and declared license. README-only update; no model artifacts or repository visibility changes.

README.md

@@ -1,39 +1,141 @@
 ---
-base_model: Tanor/SRGPTSENTNEG2
+base_model: jerteh/gpt2-orao
 tags:
-- generated_from_trainer
+- serbian
+- sentiment-analysis
+- wordnet
+- sentiwordnet
+- lexicon-induction
 metrics:
 - f1
 model-index:
 - name: SRGPTSENTNEG2
   results: []
+language:
+- sr
+library_name: transformers
+pipeline_tag: text-classification
+base_model_relation: finetune
+widget:
+- text: koji oseća radost i zadovoljstvo
+  example_title: Illustrative Serbian gloss
 ---
 
-<!-- This model card has been generated automatically according to the information the Trainer had access to. You
-should probably proofread and complete it, then remove this comment. -->
-
 # SRGPTSENTNEG2
 
-This model is a fine-tuned version of [Tanor/SRGPTSENTNEG2](https://huggingface.co/Tanor/SRGPTSENTNEG2) on the None dataset.
-It achieves the following results on the evaluation set:
-- Loss: 0.1820
-- F1: 0.3235
+This is a **negative-polarity classifier for Serbian WordNet synset glosses**, fine-tuned from the GPT2-Orao model family. It is a component of the **S6 sentiment-lexicon construction method** described in:
+
+Saša Petalinkar, Ranka M. Stanković, and Milica Ikonić Nešić (2025). **Comparative analysis of methods for creating a sentiment lexicon of the Serbian WordNet.** *The Electronic Library*, 43(4), 547–577. [Paper and DOI](https://doi.org/10.1108/EL-08-2024-0253).
+
+[Companion code and sentiment lexicons](https://github.com/sasa5linkar/Serbian-WordNet-Sentiment-Lexicon-Analysis) · [Paired classifier](https://huggingface.co/Tanor/SRGPTSENTPOS2) · [Original base model](https://huggingface.co/jerteh/gpt2-orao)
+
+## Model identity and task
+
+| Field | Value |
+|---|---|
+| Model ID | `Tanor/SRGPTSENTNEG2` |
+| Architecture | `GPT2ForSequenceClassification` |
+| Original base model | [`jerteh/gpt2-orao`](https://huggingface.co/jerteh/gpt2-orao) |
+| Input | A Serbian synset gloss, representing one lexical meaning |
+| Target | Negative vs non-negative polarity |
+| Dataset expansion iteration | **2** (`T2`) |
+| Label 0 | `NON-NEGATIVE` |
+| Label 1 | `NEGATIVE` |
+| Derived lexicon family | **S6** |
+| Paired classifier, same iteration | [`Tanor/SRGPTSENTPOS2`](https://huggingface.co/Tanor/SRGPTSENTPOS2) |
+
+The linked training script initializes the classifier from `jerteh/gpt2-orao`. `SRGPT` is the project naming convention for the GPT2-Orao sentiment classifiers.
+
+A non-negative label is the complement of the target class. It does not by itself mean that the gloss has the opposite polarity. A separate classifier handles that polarity.
+
+## Training data and construction method
+
+The paper constructs polarity-labeled synsets from Serbian WordNet, starting from curated positive, negative, and objective seed sets and expanding through semantic relations. The initial sets reported in the paper contain 149 positive, 219 negative, and 19,475 objective synsets. Polarity-preserving relations expand the corresponding set; antonymy contributes to the opposite polarity. The selected datasets are `T0`, `T2`, `T4`, and `T6`, after zero, two, four, and six expansion iterations.
+
+This checkpoint is associated with **T2 and the NEG classification task**. Its numerical suffix is a dataset-expansion iteration, not an epoch count or a lexicon identifier.
+
+The [training script](https://github.com/sasa5linkar/Serbian-WordNet-Sentiment-Lexicon-Analysis/blob/833582dbbf561a902fc5b872248db12bf529b3d9/trainSRGPT.py) reads `Sysnet` from `X_train_UPNEG2.csv` and the target `NEG` from `y_train_UPNEG2.csv`, replaces missing text with an empty string, and creates a stratified validation subset of **20% of that training CSV**, with `random_state=42`. The `UP` inputs are the non-lemmatized gloss variant in the [dataset-generation script](https://github.com/sasa5linkar/Serbian-WordNet-Sentiment-Lexicon-Analysis/blob/833582dbbf561a902fc5b872248db12bf529b3d9/create_sets.py).
+
+The paper and code snapshot have different split descriptions: the paper describes an 80/10/10 split for neural models, while the scripts split existing training CSV files and `create_sets.py` leaves the initial split size at the library default. Exact checkpoint-specific sample assignments are not supplied in the public revision. The `train_sets/` files referenced by the scripts are absent from that revision. Reconstructing the experiment requires the relevant lexical resources and saved preparation/split information; the paper's proportions alone do not establish this checkpoint's split.
+
+## Use in sentiment lexicon S6
+
+For each iteration, the POS model estimates positive-class probability `p_pos` and the NEG model estimates negative-class probability `p_neg`. The [lexicon-building code](https://github.com/sasa5linkar/Serbian-WordNet-Sentiment-Lexicon-Analysis/blob/833582dbbf561a902fc5b872248db12bf529b3d9/sentiwordnet_calculator.py) combines them as:
 
-## Model description
+```text
+POS = p_pos * (1 - p_neg)
+NEG = p_neg * (1 - p_pos)
+OBJ = 1 - POS - NEG
+```
 
-More information needed
+It averages each score across the four iteration-specific pairs. A single checkpoint is one component of this construction; its two class probabilities are not the final three lexicon scores.
 
-## Intended uses & limitations
+| Iteration | POS classifier | NEG classifier |
+|---|---|---|
+| 0 | [SRGPTSENTPOS0](https://huggingface.co/Tanor/SRGPTSENTPOS0) | [SRGPTSENTNEG0](https://huggingface.co/Tanor/SRGPTSENTNEG0) |
+| 2 | [SRGPTSENTPOS2](https://huggingface.co/Tanor/SRGPTSENTPOS2) | [SRGPTSENTNEG2](https://huggingface.co/Tanor/SRGPTSENTNEG2) |
+| 4 | [SRGPTSENTPOS4](https://huggingface.co/Tanor/SRGPTSENTPOS4) | [SRGPTSENTNEG4](https://huggingface.co/Tanor/SRGPTSENTNEG4) |
+| 6 | [SRGPTSENTPOS6](https://huggingface.co/Tanor/SRGPTSENTPOS6) | [SRGPTSENTNEG6](https://huggingface.co/Tanor/SRGPTSENTNEG6) |
 
-More information needed
+## Usage
 
-## Training and evaluation data
+This example reads one gloss and returns both class probabilities. It pins the model to the weights revision present before the documentation update.
 
-More information needed
+```python
+import torch
+from transformers import AutoModelForSequenceClassification, AutoTokenizer
 
-## Training procedure
+MODEL_ID = "Tanor/SRGPTSENTNEG2"
+WEIGHTS_REVISION = "609984070541e85cc2f51e0bafdfeeb42653c25c"
+tokenizer = AutoTokenizer.from_pretrained(MODEL_ID, revision=WEIGHTS_REVISION)
+model = AutoModelForSequenceClassification.from_pretrained(
+    MODEL_ID, revision=WEIGHTS_REVISION
+)
+model.eval()
 
-### Training hyperparameters
+# An illustrative gloss, not a benchmark item or a claimed prediction.
+inputs = tokenizer(
+    "koji oseća radost i zadovoljstvo",
+    return_tensors="pt", truncation=True, max_length=300,
+)
+with torch.inference_mode():
+    probabilities = model(**inputs).logits.softmax(dim=-1)[0]
+scores = {model.config.id2label[i]: float(p) for i, p in enumerate(probabilities)}
+print(scores)
+```
+
+The model uses standard PyTorch/Transformers sequence-classification classes, without custom remote code. The example requires PyTorch and Transformers. Where a Trainer record is available below, it includes software versions from the original run. No example prediction or benchmark score was generated for this documentation update.
+
+## Evaluation and provenance
+
+### Archived test report
+
+The companion repository contains an [evaluation report for SRGPT, NEG, T2](https://github.com/sasa5linkar/Serbian-WordNet-Sentiment-Lexicon-Analysis/blob/833582dbbf561a902fc5b872248db12bf529b3d9/reports/SRGPT/report_UPNEG2.csv.txt). It is preserved below, with class 0 = `NON-NEGATIVE` and class 1 = `NEGATIVE`. Metric values retain the source's rounding; support values are sample counts. The confusion matrix uses that class order.
+
+```text
+[[4404   16]
+ [  59   17]]
+
+              precision    recall  f1-score   support
+
+           0       0.99      1.00      0.99      4420
+           1       0.52      0.22      0.31        76
+
+    accuracy                           0.98      4496
+   macro avg       0.75      0.61      0.65      4496
+weighted avg       0.98      0.98      0.98      4496
+```
+
+This is an archived experiment artifact, not a new evaluation. The report does not record a model-weight SHA, so its exact correspondence to the currently hosted weights has not been independently re-established. These binary-classification metrics are separate from evaluation of the derived lexicon and from sentiment evaluation of full sentences.
+
+### Preserved Trainer record
+
+The following validation summary and training log are retained from the [previous model card](https://huggingface.co/Tanor/SRGPTSENTNEG2/blob/609984070541e85cc2f51e0bafdfeeb42653c25c/README.md), without recomputing them. The recorded F1 is a training-validation metric, separate from the archived test report above and from lexicon or sentence-level sentiment evaluation. The source training code uses binary F1 for target label 1 when `eval="f1"` is selected.
+
+- Loss: 0.1820
+- F1: 0.3235
+
+#### Training hyperparameters
 
 The following hyperparameters were used during training:
 - learning_rate: 2e-05
@@ -46,7 +148,7 @@ The following hyperparameters were used during training:
 - lr_scheduler_type: linear
 - num_epochs: 32
 
-### Training results
+#### Training results
 
 | Training Loss | Epoch | Step  | Validation Loss | F1     |
 |:-------------:|:-----:|:-----:|:---------------:|:------:|
@@ -57,9 +159,69 @@ The following hyperparameters were used during training:
 | 0.0403        | 5.0   | 13485 | 0.1820          | 0.3235 |
 
 
-### Framework versions
+#### Framework versions
 
 - Transformers 4.31.0
 - Pytorch 2.1.0.dev20230801
 - Datasets 2.14.2
 - Tokenizers 0.13.3
+
+The Trainer record and the linked source script are separate provenance sources. In particular, the recorded optimizer may differ from the script's `adafactor` setting; the historical record is retained without asserting that the linked script reproduces that exact run.
+
+## Settings in the archived training source
+
+These settings describe the linked code revision, not a replacement for the per-run Trainer record.
+
+| Setting | Source-code value |
+|---|---|
+| Maximum tokenized input length | 300 |
+| Learning rate | 2e-5 |
+| Training batch size per device | 1 |
+| Evaluation batch size per device | 1 |
+| Gradient accumulation | 4 steps |
+| Optimizer | Adafactor |
+| Weight decay | 0.01 |
+| Validation split seed | 42 |
+| Evaluation and saving | Each epoch |
+| Early stopping patience | 3 evaluation calls |
+| Epoch budget in experiment notebooks | Up to 32 |
+
+The paper reports early-stopping patience of 3. The linked family script also uses 3.
+
+## Intended use and limitations
+
+- Intended for research on polarity of Serbian WordNet meanings and construction or analysis of Serbian sentiment lexicons.
+- Training inputs are glosses. Performance on reviews, news, social media, and documents requires separate evaluation; this checkpoint is not documented as a general sentence-sentiment benchmark model.
+- Class imbalance is visible in the archived report. Read accuracy and weighted averages alongside target-class precision, recall, F1, and support.
+- Labels depend on seed selection and semantic-relation expansion. Polysemy, domain-specific polarity, and propagation errors can affect predictions. English-to-Serbian alignment alone does not establish polarity in Serbian.
+- Softmax outputs are model scores; probability calibration is not established by this card.
+- The model performs no sense selection for a word in context. Applying the lexicon to text requires a separate choice or aggregation of meanings.
+
+## License
+
+No license is declared in this model repository's model-card metadata. A new license has not been inferred from the code repository or the base model. Contact the model authors to clarify reuse terms; code and external lexical resources have separate terms.
+
+## Citation
+
+When using this model family or the resulting lexicon-construction method, cite the paper and record the model ID and revision used.
+
+```bibtex
+@article{petalinkar2025sentimentlexicon,
+  author = {Petalinkar, Saša and Stanković, Ranka M. and Ikonić Nešić, Milica},
+  title = {Comparative analysis of methods for creating a sentiment lexicon of the Serbian WordNet},
+  journal = {The Electronic Library},
+  year = {2025},
+  volume = {43},
+  number = {4},
+  pages = {547--577},
+  doi = {10.1108/EL-08-2024-0253},
+  url = {https://doi.org/10.1108/EL-08-2024-0253}
+}
+```
+
+## Version and documentation sources
+
+- Weights/configuration revision documented here: [`609984070541e85cc2f51e0bafdfeeb42653c25c`](https://huggingface.co/Tanor/SRGPTSENTNEG2/tree/609984070541e85cc2f51e0bafdfeeb42653c25c). This pins the hosted checkpoint; it does not prove which weights produced every table in the paper.
+- Companion code revision: [`833582dbbf561a902fc5b872248db12bf529b3d9`](https://github.com/sasa5linkar/Serbian-WordNet-Sentiment-Lexicon-Analysis/tree/833582dbbf561a902fc5b872248db12bf529b3d9).
+- BERTić initialization is recorded in [Prepare and load models.ipynb](https://github.com/sasa5linkar/Serbian-WordNet-Sentiment-Lexicon-Analysis/blob/833582dbbf561a902fc5b872248db12bf529b3d9/Prepare%20and%20load%20models.ipynb); GPT2-Orao and Jerteh-355 initialization is recorded in their training scripts.
+- Documentation expanded on 23 September 2026 using the paper, model configuration, repository source, archived evaluation report, and any pre-existing Trainer record. Weights, tokenizer files, and model configuration were not changed by this documentation update.