Metadata-Version: 2.4
Name: classivax
Version: 0.1.0
Summary: Classify vaccine-related news headlines into topic categories using a Recognizing Textual Entailment (RTE) approach.
Author: Luiz Felipe Fernandes Neves
License: MIT
Project-URL: Homepage, https://github.com/lffernandes08/classivax
Project-URL: Repository, https://github.com/lffernandes08/classivax
Project-URL: Model, https://huggingface.co/LuizNeves/BERT-NLI-vaccine-v2
Project-URL: Paper, https://doi.org/10.5117/CCR2025.1.1.NEVE
Keywords: nlp,text-classification,natural-language-inference,textual-entailment,vaccine,science-communication,computational-social-science
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: transformers>=4.30
Requires-Dist: torch>=2.0
Requires-Dist: pandas>=1.5
Dynamic: license-file

# ClassiVax

Classify vaccine-related news headlines into topic categories using a **Recognizing Textual Entailment (RTE)** approach, powered by the [`LuizNeves/BERT-NLI-vaccine-v2`](https://huggingface.co/LuizNeves/BERT-NLI-vaccine-v2) model.

Built on the method described in:

> Neves, L. F. F., Camargo, C. Q., & Massarani, L. (2025). Boosting Transformers: Recognizing Textual Entailment for Classification of Vaccine News Coverage. *Computational Communication Research*, 7(1), 1–32. https://doi.org/10.5117/CCR2025.1.1.NEVE

## Installation

```bash
pip install classivax
```

## Usage

### Default classes (10 vaccine-related topics from the paper)

```python
from classivax import ClassiVaxClassifier

clf = ClassiVaxClassifier()

result = clf.classify("Twitter will begin removing vaccine misinformation")
print(result["class"])   # "Vaccine Hesitancy and Mis-/Disinformation"
print(result["score"])   # e.g. 0.999
```

### Batch classification

```python
headlines = [
    "Twitter will begin removing vaccine misinformation",
    "Britain begins coronavirus vaccine rollout",
    "COVID-19 vaccination key to economic recovery",
]

df = clf.classify_batch(headlines)
print(df)
```

### Custom classes

The underlying RTE approach also supports classifying text against any set of natural-language class descriptions you define — not just the original 10 classes.

```python
custom_classes = {
    "Vaccine Safety Debate": "The headline discusses concerns, controversies, or debates about vaccine safety",
    "Vaccine Logistics": "The headline discusses shipping, storage, cold chain, or distribution logistics for vaccines",
}

clf = ClassiVaxClassifier(classes=custom_classes)
result = clf.classify("Cold storage shortages delay vaccine shipments to rural areas")
print(result["class"])  # "Vaccine Logistics"
```

**Note:** the underlying model was fine-tuned specifically on English-language, vaccine-related headlines from 2020–2021. Using custom classes outside this domain is supported, but accuracy has not been formally evaluated beyond the original study's scope — treat results on very different domains with appropriate caution.

## The 10 default classes

| Class | Description |
|---|---|
| Global Access to Vaccine | Initiatives for equal access to COVID-19 vaccines (e.g., COVAX), and/or the need to combat inequity, ensure global distribution, and contain the disease, especially in low- and middle-income countries |
| Science and Technology | The science behind vaccine development, including research, studies, safety and efficacy trials, emergency approval, and side effects |
| Public Health Policies | Vaccine mandates, vaccine passports, and/or other public health policies such as social distancing, quarantine, lockdowns, and mask mandates |
| Vaccination Rollout/Campaign | Vaccination rollout, campaigns, priority groups, vaccine deals, and/or the monitoring of vaccination rates |
| Vaccine Hesitancy and Mis-/Disinformation | The circulation of disinformation and misinformation regarding vaccines, which contribute to vaccine hesitancy and reluctance |
| Public Endorsement to Vaccine | Public endorsement and incentive for vaccines, such as celebrities and artists getting vaccinated |
| Institutional Affairs | Institutional and governmental issues, political disputes, conflicts, political authorities, and export bans |
| Problems in Vaccination | Problems in vaccination, such as delays, fraud, disparities, vaccine shortages |
| Public Perception of Vaccine | Opinion polls and surveys on the public perception of vaccines and/or willingness to get vaccinated |
| Economic Consequences | The impacts and benefits of vaccination on the economy |

## How it works

For each headline, the classifier tests it against every class description as a text-hypothesis pair, following the entailment framework: the headline is the *text* (T), and each class description is a candidate *hypothesis* (H). The class whose description achieves the highest entailment score is selected as the prediction.

## Citation

If you use this library or the underlying model in your research, please cite:

```bibtex
@article{neves2025boosting,
  title={Boosting Transformers: Recognizing Textual Entailment for Classification of Vaccine News Coverage},
  author={Neves, Luiz F. F. and Camargo, Chico Q. and Massarani, Luisa},
  journal={Computational Communication Research},
  volume={7},
  number={1},
  pages={1--32},
  year={2025},
  doi={10.5117/CCR2025.1.1.NEVE}
}
```

## License

MIT
