Improve model card: Update license, add languages, expand sections, and include usage example

README.md

@@ -1,25 +1,50 @@
 ---
+base_model:
+- microsoft/mdeberta-v3-base
 library_name: transformers
-tags:
-- generated_from_trainer
+license: cc-by-4.0
+languages:
+- ar
+- de
+- en
+- it
+- bg
+- el
+- pl
+- ro
+- uk
 metrics:
 - accuracy
 - f1
+pipeline_tag: text-classification
+tags:
+- generated_from_trainer
+- deberta
+- multilingual
+- subjectivity-detection
 model-index:
 - name: mdeberta-v3-base-subjectivity-sentiment-multilingual-no-arabic
   results: []
-license: mit
-base_model:
-- microsoft/mdeberta-v3-base
-pipeline_tag: text-classification
+datasets:
+- MatteoFasulo/clef2025_checkthat_task1_subjectivity
+language:
+- ar
+- de
+- bg
+- el
+- it
+- ro
+- uk
+- en
+- pl
 ---
 
-<!-- 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. -->
-
 # mdeberta-v3-base-subjectivity-sentiment-multilingual-no-arabic
 
-This model is a fine-tuned version of [microsoft/mdeberta-v3-base](https://huggingface.co/microsoft/mdeberta-v3-base) on the [CheckThat! Lab Task 1 Subjectivity Detection at CLEF 2025](arxiv.org/abs/2507.11764).
+This model is a fine-tuned version of [microsoft/mdeberta-v3-base](https://huggingface.co/microsoft/mdeberta-v3-base) for **Subjectivity Detection in News Articles**, as presented in the paper [AI Wizards at CheckThat! 2025: Enhancing Transformer-Based Embeddings with Sentiment for Subjectivity Detection in News Articles](https://huggingface.co/papers/2507.11764). It was developed by AI Wizards for their participation in the CLEF 2025 CheckThat! Lab Task 1.
+
+**Code:** [https://github.com/MatteoFasulo/clef2025-checkthat](https://github.com/MatteoFasulo/clef2025-checkthat)
+
 It achieves the following results on the evaluation set:
 - Loss: 0.8900
 - Macro F1: 0.7969
@@ -32,15 +57,41 @@ It achieves the following results on the evaluation set:
 
 ## Model description
 
-More information needed
+This model is designed to classify sentences as **subjective** (opinion-laden) or **objective** in news articles. This task is a key component in combating misinformation, improving fact-checking pipelines, and supporting journalists.
+
+The primary strategy of this model, based on `mDeBERTaV3-base`, involves enhancing transformer-based embeddings by integrating sentiment scores derived from an auxiliary model. This sentiment-augmented architecture significantly boosts performance, especially the subjective F1 score. The model also employs decision threshold calibration, optimized on the development set, to effectively address class imbalance prevalent across the datasets.
+
+**Key Contributions from the paper:**
+1.  **Sentiment-Augmented Fine-Tuning**: Enriches embedding-based models by integrating sentiment scores from an auxiliary model, notably improving subjective sentence detection.
+2.  **Diverse Model Coverage**: Benchmarked across multilingual BERT variants (like mDeBERTaV3-base) for all official CLEF languages.
+3.  **Threshold Calibration for Imbalance**: A simple yet effective method to tune decision thresholds on each language's development data to enhance macro-F1 performance.
 
 ## Intended uses & limitations
 
-More information needed
+**Intended Uses:**
+This model is intended for subjectivity detection in news articles, classifying sentences as subjective or objective. It has been evaluated across:
+*   **Monolingual settings:** Arabic, German, English, Italian, and Bulgarian.
+*   **Zero-shot transfer:** Tested on unseen languages such as Greek, Polish, Romanian, and Ukrainian.
+*   **Multilingual training.**
+
+Its capabilities make it suitable for applications that require discerning factual statements from opinions, such as:
+*   Combating misinformation by identifying biased or opinionated content.
+*   Improving automated fact-checking pipelines.
+*   Assisting journalists in content analysis and report generation.
+
+**Limitations:**
+*   The model's performance is optimized for news articles; its effectiveness might vary on text from other domains (e.g., social media, conversational text) with different linguistic characteristics or content styles.
+*   While decision threshold calibration is used to mitigate class imbalance, extreme imbalances in specific datasets might still affect performance.
+*   The paper notes an initial submission error where an incorrect train/dev mix was used, leading to under-calibrated thresholds and lower initial scores in the multilingual track. While corrected results are reported, this highlights sensitivity to data preparation and calibration.
 
 ## Training and evaluation data
 
-More information needed
+The model was fine-tuned on datasets provided for the **CLEF 2025 CheckThat! Lab Task 1: Subjectivity Detection in News Articles**.
+
+*   **Training and development datasets** were provided for monolingual settings in Arabic, German, English, Italian, and Bulgarian.
+*   **Final evaluation** included additional unseen languages such as Greek, Romanian, Polish, and Ukrainian to assess the model's generalization capabilities.
+
+The training process involved enhancing sentence representations by integrating sentiment scores from an auxiliary model. Class imbalance, which was a notable characteristic across these languages, was addressed through decision threshold calibration during training.
 
 ## Training procedure
 
@@ -72,4 +123,109 @@ The following hyperparameters were used during training:
 - Transformers 4.47.0
 - Pytorch 2.5.1+cu121
 - Datasets 3.3.1
-- Tokenizers 0.21.0
+- Tokenizers 0.21.0
+
+## How to use
+
+You can use this model directly with the Hugging Face `transformers` library for text classification:
+
+```python
+import torch
+import torch.nn as nn
+from transformers import DebertaV2Model, DebertaV2Config, AutoTokenizer, PreTrainedModel, pipeline, AutoModelForSequenceClassification 
+from transformers.models.deberta.modeling_deberta import ContextPooler
+
+sent_pipe = pipeline(
+    "sentiment-analysis",
+    model="cardiffnlp/twitter-xlm-roberta-base-sentiment",
+    tokenizer="cardiffnlp/twitter-xlm-roberta-base-sentiment",
+    top_k=None,  # return all 3 sentiment scores
+)
+
+class CustomModel(PreTrainedModel):
+    config_class = DebertaV2Config
+    def __init__(self, config, sentiment_dim=3, num_labels=2, *args, **kwargs):
+        super().__init__(config, *args, **kwargs)
+        self.deberta = DebertaV2Model(config)
+        self.pooler = ContextPooler(config)
+        output_dim = self.pooler.output_dim
+        self.dropout = nn.Dropout(0.1)
+        self.classifier = nn.Linear(output_dim + sentiment_dim, num_labels)
+
+    def forward(self, input_ids, positive, neutral, negative, token_type_ids=None, attention_mask=None, labels=None):
+        outputs = self.deberta(input_ids=input_ids, attention_mask=attention_mask)
+        encoder_layer = outputs[0]
+        pooled_output = self.pooler(encoder_layer)
+        sentiment_features = torch.stack((positive, neutral, negative), dim=1).to(pooled_output.dtype)
+        combined_features = torch.cat((pooled_output, sentiment_features), dim=1)
+        logits = self.classifier(self.dropout(combined_features))
+        return {'logits': logits}
+
+model_name = "MatteoFasulo/mdeberta-v3-base-subjectivity-sentiment-multilingual-no-arabic"
+tokenizer = AutoTokenizer.from_pretrained("microsoft/mdeberta-v3-base")
+config = DebertaV2Config.from_pretrained(
+    model_name, 
+    num_labels=2, 
+    id2label={0: 'OBJ', 1: 'SUBJ'}, 
+    label2id={'OBJ': 0, 'SUBJ': 1},
+    output_attentions=False, 
+    output_hidden_states=False
+)
+model = CustomModel(config=config, sentiment_dim=3, num_labels=2).from_pretrained(model_name)
+
+def classify_subjectivity(text: str):
+    # get full sentiment distribution
+    dist = sent_pipe(text)[0]
+    pos = next(d["score"] for d in dist if d["label"] == "positive")
+    neu = next(d["score"] for d in dist if d["label"] == "neutral")
+    neg = next(d["score"] for d in dist if d["label"] == "negative")
+
+    # tokenize the text
+    inputs = tokenizer(text, padding=True, truncation=True, max_length=256, return_tensors='pt')
+
+    # feeding in the three sentiment scores
+    with torch.no_grad():
+        outputs = model(
+            input_ids=inputs["input_ids"],
+            attention_mask=inputs["attention_mask"],
+            positive=torch.tensor(pos).unsqueeze(0).float(),
+            neutral=torch.tensor(neu).unsqueeze(0).float(),
+            negative=torch.tensor(neg).unsqueeze(0).float()
+        )
+
+    # compute probabilities and pick the top label
+    probs = torch.softmax(outputs.get('logits')[0], dim=-1)
+    label = model.config.id2label[int(probs.argmax())]
+    score = probs.max().item()
+
+    return {"label": label, "score": score}
+
+examples = [
+    "The company reported a 10% increase in revenue for the last quarter.",
+    "Die angegebenen Fehlerquoten können daher nur für symptomatische Patienten gelten.",
+    "Si smonta qui definitivamente la narrazione per cui le scelte energetiche possono essere frutto esclusivo di valutazioni “tecniche” e non politiche.",
+]
+for text in examples:
+    result = classify_subjectivity(text)
+    print(f"Text: {text}")
+    print(f"→ Subjectivity: {result['label']} (score={result['score']:.2f})\n")
+
+```
+
+For more detailed usage, including training and evaluation scripts, please refer to the [GitHub repository](https://github.com/MatteoFasulo/clef2025-checkthat).
+
+## Citation
+
+If you find our work helpful or inspiring, please feel free to cite it:
+
+```bibtex
+@misc{fasulo2025aiwizardscheckthat2025,
+      title={AI Wizards at CheckThat! 2025: Enhancing Transformer-Based Embeddings with Sentiment for Subjectivity Detection in News Articles}, 
+      author={Matteo Fasulo and Luca Babboni and Luca Tedeschini},
+      year={2025},
+      eprint={2507.11764},
+      archivePrefix={arXiv},
+      primaryClass={cs.CL},
+      url={https://arxiv.org/abs/2507.11764}, 
+}
+```