Metadata-Version: 2.4
Name: topic-specificity
Version: 0.1.0
Summary: Calculate topic specificity for LDA, LSA & HDP.
Home-page: https://github.com/abigailyuan/topic_specificity
Author: Meng Yuan
Author-email: meng.yuan@unimelb.edu.au
Maintainer: Meng Yuan
Maintainer-email: meng.yuan@unimelb.edu.au
Project-URL: Paper, https://doi.org/10.1145/3578337.3605118
Project-URL: CITATION, https://github.com/abigailyuan/topic_specificity/blob/main/CITATION.cff
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: scikit-learn
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: maintainer
Dynamic: maintainer-email
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Topic Specificity

**Topic Specificity** is a measure for evaluating the concentration and distinctness of topics within a document corpus. It quantifies how well each topic stands out from the background noise by comparing document-level topic weights against a corpus-wide threshold. A higher specificity score indicates a topic that is more clearly defined and less diffuse across documents.

This package implements the specificity measure described in:

> **Yuan, M., Lin, P., Rashidi, L., & Zobel, J. (2023).** “Assessment of the Quality of Topic Models for Information Retrieval Applications.” *Proceedings of the 9th ACM SIGIR International Conference on the Theory of Information Retrieval (ICTIR ’23)*, 265–274. DOI: [10.1145/3578337.3605118](https://doi.org/10.1145/3578337.3605118)

---

## Installation

You can install this package locally in editable (development) mode:

```bash
pip install -e .
```

Or, once it is published on PyPI, install it directly:

```bash
pip install topic-specificity
```

## Usage Examples

Below are some quick examples showing how to calculate topic specificity scores and Z-scores.

### 1. Calculate Specificity for All Topics

```python
from topic_specificity import calculate_specificity_for_all_topics
from gensim.models.ldamodel import LdaModel
from gensim.corpora.dictionary import Dictionary

# — assume you have preprocessed texts —
texts = [["human", "interface", "computer"], ["survey", "user", "computer", "system"]]
dictionary = Dictionary(texts)
corpus = [dictionary.doc2bow(text) for text in texts]

# Train a simple LDA model
lda = LdaModel(corpus=corpus, id2word=dictionary, num_topics=2, random_state=42)

# Compute specificity scores
spec_scores = calculate_specificity_for_all_topics(
    model=lda,
    corpus=corpus,
    mode='lda',
    threshold_mode='gmm',         # options: 'median', 'percentile', 'gmm'
    specificity_mode='sqrt'       # options: 'diff', 'sqrt'
)

print("Specificity scores:", spec_scores)
```

### 2. Calculate Z-Scores (Effect Sizes)

```python

from topic_specificity import calculate_Zi_scores

# Using the same LDA model & corpus as above:
z_scores = calculate_Zi_scores(
    model=lda,
    corpus=corpus,
    mode='lda'
)

print("Z-scores per topic:", z_scores)

```

### 3. LSA or HDP Models
The same functions work for LSA or HDP--just change the mode:
```python
from gensim.models.lsimodel import LsiModel
from gensim.models.hdpmodel import HdpModel

# Example for LSA:
lsa = LsiModel(corpus=corpus, id2word=dictionary, num_topics=2)
lsa_scores = calculate_specificity_for_all_topics(lsa, corpus, mode='lsa',
                                                  threshold_mode='median',
                                                  specificity_mode='diff')
print("LSA specificity:", lsa_scores)

# Example for HDP:
hdp = HdpModel(corpus=corpus, id2word=dictionary)
hdp_scores = calculate_specificity_for_all_topics(hdp, corpus, mode='hdp',
                                                  threshold_mode='percentile',
                                                  specificity_mode='sqrt')
print("HDP specificity:", hdp_scores)

```

## Citation

If you use **topic\_specificity** in your work, please cite:

```bibtex
@inproceedings{yuan2023assessment,
  author    = {Yuan, Meng and Lin, Pauline and Rashidi, Lida and Zobel, Justin},
  title     = {Assessment of the Quality of Topic Models for Information Retrieval Applications},
  booktitle = {Proceedings of the 9th ACM SIGIR International Conference on the Theory of Information Retrieval (ICTIR ’23)},
  year      = {2023},
  location  = {Taipei, Taiwan},
  pages     = {265--274},
  doi       = {10.1145/3578337.3605118},
}
```

DOI: [https://doi.org/10.1145/3578337.3605118](https://doi.org/10.1145/3578337.3605118)


