Updated README file

README.md

@@ -1,199 +1,242 @@
 ---
 library_name: transformers
-tags: []
+tags:
+- stance-detection
+- political-science
+- multilingual
+- nli
+- deberta
+- group-appeals
+language:
+- en
+- de
+base_model: MoritzLaurer/mDeBERTa-v3-base-xnli-multilingual-nli-2mil7
 ---
 
-# Model Card for Model ID
-
-<!-- Provide a quick summary of what the model is/does. -->
-
+# Model Card for mDeBERTa Stance Detection (No Context)
 
+A multilingual stance detection model fine-tuned for detecting political stance towards specific groups in text without contextual information.
 
 ## Model Details
 
 ### Model Description
 
-<!-- Provide a longer summary of what this model is. -->
-
-This is the model card of a 🤗 transformers model that has been pushed on the Hub. This model card has been automatically generated.
+This model is a fine-tuned mDeBERTa-v3-base that performs stance classification using Natural Language Inference (NLI) to determine whether political text expresses positive, negative, or neutral stance towards specific target groups. The model processes focal sentences without additional context.
 
-- **Developed by:** [More Information Needed]
-- **Funded by [optional]:** [More Information Needed]
-- **Shared by [optional]:** [More Information Needed]
-- **Model type:** [More Information Needed]
-- **Language(s) (NLP):** [More Information Needed]
-- **License:** [More Information Needed]
-- **Finetuned from model [optional]:** [More Information Needed]
+- **Developed by:** Will Horne, Alona O. Dolinsky and Lena Maria Huber
+- **Model type:** Sequence Classification (NLI-based stance detection)
+- **Language(s) (NLP):** English, German (multilingual)
+- **Finetuned from model:** MoritzLaurer/mDeBERTa-v3-base-xnli-multilingual-nli-2mil7
 
-### Model Sources [optional]
+### Model Sources
 
-<!-- Provide the basic links for the model. -->
-
-- **Repository:** [More Information Needed]
-- **Paper [optional]:** [More Information Needed]
-- **Demo [optional]:** [More Information Needed]
+- **Repository:** rwillh11/mdeberta_NLI_stance_NoContext
+- **Base Model:** [MoritzLaurer/mDeBERTa-v3-base-xnli-multilingual-nli-2mil7](https://huggingface.co/MoritzLaurer/mDeBERTa-v3-base-xnli-multilingual-nli-2mil7)
 
 ## Uses
 
-<!-- Address questions around how the model is intended to be used, including the foreseeable users of the model and those affected by the model. -->
-
 ### Direct Use
 
-<!-- This section is for the model use without fine-tuning or plugging into a larger ecosystem/app. -->
-
-[More Information Needed]
+The model is designed for researchers analyzing political discourse and stance towards specific groups in political text, trained and validated using party manifestos. It takes a natural sentence and a target group as input and classifies the stance as positive, negative, or neutral.
 
-### Downstream Use [optional]
+### Downstream Use
 
-<!-- This section is for the model use when fine-tuned for a task, or when plugged into a larger ecosystem/app -->
-
-[More Information Needed]
+This model can be integrated into larger political text analysis pipelines for:
+- Political manifestos analysis
+- Group appeals detection in political communication
+- Comparative political research across countries and languages
 
 ### Out-of-Scope Use
 
-<!-- This section addresses misuse, malicious use, and uses that the model will not work well for. -->
-
-[More Information Needed]
+This model should not be used for:
+- General sentiment analysis (not group-specific)
+- Real-time social media monitoring without human oversight
+- Making decisions about individuals or groups
+- Content moderation without additional validation
 
 ## Bias, Risks, and Limitations
 
-<!-- This section is meant to convey both technical and sociotechnical limitations. -->
+### Technical Limitations
+- Trained specifically on political manifesto text; performance may vary on other text types
+- Focus sentences without context may lack nuance present in full paragraphs
+- Limited to three stance categories (positive, negative, neutral)
 
-[More Information Needed]
+### Bias Considerations
+- Training data consists of political manifestos from specific countries and time periods
+- May reflect biases present in political discourse of training data
+- Group detection and stance classification may vary across different political contexts
 
 ### Recommendations
 
-<!-- This section is meant to convey recommendations with respect to the bias, risk, and technical limitations. -->
-
-Users (both direct and downstream) should be made aware of the risks, biases and limitations of the model. More information needed for further recommendations.
+Users should be aware that this model:
+- Is designed for research purposes in political science
+- Should be validated on specific domains before deployment
+- May require human oversight for sensitive applications
+- Performance may vary across different types of groups and political contexts
 
 ## How to Get Started with the Model
 
-Use the code below to get started with the model.
-
-[More Information Needed]
+```python
+from transformers import AutoTokenizer, AutoModelForSequenceClassification
+import torch
+
+# Load model and tokenizer
+model_name = "rwillh11/mdeberta_NLI_stance_NoContext"
+tokenizer = AutoTokenizer.from_pretrained(model_name)
+model = AutoModelForSequenceClassification.from_pretrained(model_name)
+
+# Example usage
+text = "We will increase funding for schools to better support students."
+target_group = "students"
+
+# Create hypotheses for each stance
+hypotheses = {
+    "positive": f"The text is positive towards {target_group}.",
+    "negative": f"The text is negative towards {target_group}.",
+    "neutral": f"The text is neutral, or contains no stance, towards {target_group}."
+}
+
+# Get predictions for each hypothesis
+results = {}
+for stance, hypothesis in hypotheses.items():
+    inputs = tokenizer(text, hypothesis, return_tensors="pt", truncation=True)
+    with torch.no_grad():
+        outputs = model(**inputs)
+        probs = torch.softmax(outputs.logits, dim=-1)
+        entailment_prob = probs[0][0].item()  # Probability of entailment
+        results[stance] = entailment_prob
+
+# Select stance with highest entailment probability
+predicted_stance = max(results, key=results.get)
+print(f"Predicted stance towards '{target_group}': {predicted_stance}")
+```
 
 ## Training Details
 
 ### Training Data
 
-<!-- This should link to a Dataset Card, perhaps with a short stub of information on what the training data is all about as well as documentation related to data pre-processing or additional filtering. -->
-
-[More Information Needed]
+The model was trained on political manifesto data containing:
+- **Languages:** English and German
+- **Text Type:** Political manifesto sentences at natural sentence level
+- **Labels:** Three-class stance classification (positive, negative, neutral)
+- **Groups:** Various political target groups (citizens, specific demographics, etc.)
+- **Original dataset:** 7,567 text-group pairs
+- **Training Size:** 12,104 expanded training examples (~6,054 original texts × 2 hypotheses each)
+- **Test Size:** 4,539 expanded test examples (~1,513 original texts × 3 hypotheses each)
 
 ### Training Procedure
 
-<!-- This relates heavily to the Technical Specifications. Content here should link to that section when it is relevant to the training procedure. -->
-
-#### Preprocessing [optional]
-
-[More Information Needed]
-
+#### Preprocessing
+- Texts tokenized using mDeBERTa tokenizer with max length 512
+- NLI format: premise (political text) + hypothesis (stance towards group)
+- Each text paired with both true and false hypotheses for binary classification
 
 #### Training Hyperparameters
-
-- **Training regime:** [More Information Needed] <!--fp32, fp16 mixed precision, bf16 mixed precision, bf16 non-mixed precision, fp16 non-mixed precision, fp8 mixed precision -->
-
-#### Speeds, Sizes, Times [optional]
-
-<!-- This section provides information about throughput, start/end time, checkpoint size if relevant, etc. -->
-
-[More Information Needed]
+- **Training regime:** Mixed precision training
+- **Optimizer:** AdamW with weight decay
+- **Learning rate:** Optimized via Optuna (range: 1e-5 to 4e-5)
+- **Weight decay:** Optimized via Optuna (range: 0.01 to 0.3)
+- **Warmup ratio:** Optimized via Optuna (range: 0.0 to 0.1)
+- **Epochs:** 10 per trial
+- **Batch size:** 16 (train and eval)
+- **Trials:** 20 total (10 + 10 batches)
+- **Metric for selection:** F1 Macro
+- **Seed:** 42 (deterministic training)
+
+#### Training Infrastructure
+- **Hardware:** CUDA-enabled GPU
+- **Framework:** Transformers, PyTorch
+- **Hyperparameter optimization:** Optuna
+- **Deterministic training:** All random seeds fixed
 
 ## Evaluation
 
-<!-- This section describes the evaluation protocols and provides the results. -->
-
 ### Testing Data, Factors & Metrics
 
 #### Testing Data
-
-<!-- This should link to a Dataset Card if possible. -->
-
-[More Information Needed]
+- 20% holdout from original dataset
+- Multilingual political manifesto sentences
+- Balanced across stance classes and languages
 
 #### Factors
-
-<!-- These are the things the evaluation is disaggregating by, e.g., subpopulations or domains. -->
-
-[More Information Needed]
+The model was evaluated across:
+- **Languages:** English and German text
+- **Stance classes:** Positive, negative, neutral
+- **Group types:** Various political target groups
 
 #### Metrics
-
-<!-- These are the evaluation metrics being used, ideally with a description of why. -->
-
-[More Information Needed]
+Primary metrics used for evaluation:
+- **F1 Macro:** Primary optimization metric (treats all classes equally)
+- **F1 Micro:** Overall classification accuracy
+- **Balanced Accuracy:** Accounts for class imbalance
+- **Precision/Recall (Macro & Micro):** Detailed performance measures
 
 ### Results
 
-[More Information Needed]
-
-#### Summary
+**Best Model Performance (Trial 19):**
+- **F1 Macro:** ~0.80 (varies by epoch)
+- **F1 Micro:** ~0.84
+- **Accuracy:** ~0.84
+- **Balanced Accuracy:** ~0.79
 
+The model demonstrates strong performance across stance categories with deterministic results confirmed through multiple prediction runs.
 
+## Model Examination
 
-## Model Examination [optional]
-
-<!-- Relevant interpretability work for the model goes here -->
-
-[More Information Needed]
+The model uses Natural Language Inference to transform stance detection into a binary entailment task:
+- For each text-group pair, generates three hypotheses (positive/negative/neutral stance)
+- Selects the hypothesis with highest entailment probability
+- This approach leverages pre-trained NLI capabilities for stance classification
 
 ## Environmental Impact
 
-<!-- Total emissions (in grams of CO2eq) and additional considerations, such as electricity usage, go here. Edit the suggested text below accordingly -->
-
-Carbon emissions can be estimated using the [Machine Learning Impact calculator](https://mlco2.github.io/impact#compute) presented in [Lacoste et al. (2019)](https://arxiv.org/abs/1910.09700).
+Training involved hyperparameter optimization with 20 trials, each training for 10 epochs.
 
-- **Hardware Type:** [More Information Needed]
-- **Hours used:** [More Information Needed]
-- **Cloud Provider:** [More Information Needed]
-- **Compute Region:** [More Information Needed]
-- **Carbon Emitted:** [More Information Needed]
+- **Hardware Type:** CUDA-enabled GPU
+- **Hours used:** Estimated 10-15 hours (including hyperparameter search)
+- **Cloud Provider:** Google Colab
+- **Compute Region:** Variable
+- **Carbon Emitted:** Not precisely measured
 
-## Technical Specifications [optional]
+## Technical Specifications
 
 ### Model Architecture and Objective
-
-[More Information Needed]
+- **Base Architecture:** mDeBERTa-v3-base (278M parameters)
+- **Task:** Natural Language Inference for stance detection
+- **Input:** Text pair (political sentence + stance hypothesis)
+- **Output:** Binary classification (entailment/non-entailment)
+- **Objective:** Cross-entropy loss with F1 Macro optimization
 
 ### Compute Infrastructure
 
-[More Information Needed]
-
 #### Hardware
-
-[More Information Needed]
+- GPU-accelerated training (CUDA)
+- Mixed precision training support
 
 #### Software
+- Transformers library
+- PyTorch framework
+- Optuna for hyperparameter optimization
+- scikit-learn for metrics
 
-[More Information Needed]
-
-## Citation [optional]
+## Citation
 
-<!-- If there is a paper or blog post introducing the model, the APA and Bibtex information for that should go in this section. -->
+If you use this model in your research, please cite:
 
 **BibTeX:**
+```bibtex
+@misc{mdeberta_stance_nocontext,
+  title={mDeBERTa Stance Detection Model for Political Group Appeals},
+  author={Research Team},
+  year={2024},
+  url={https://huggingface.co/rwillh11/mdeberta_NLI_stance_NoContext}
+}
+```
 
-[More Information Needed]
-
-**APA:**
-
-[More Information Needed]
-
-## Glossary [optional]
-
-<!-- If relevant, include terms and calculations in this section that can help readers understand the model or model card. -->
-
-[More Information Needed]
-
-## More Information [optional]
-
-[More Information Needed]
-
-## Model Card Authors [optional]
+## Model Card Authors
 
-[More Information Needed]
+Research team studying group appeals in political discourse.
 
 ## Model Card Contact
 
-[More Information Needed]
+For questions about this model, please open an issue in the repository or contact the research team through appropriate academic channels.