tbnb — Threshold-Based and Iterative Threshold-Based Naive Bayes (R)

tbnb implements the Threshold-Based Naive Bayes (Tb-NB) classifier and its iterative refinement (iTb-NB) for binary sentiment / text classification problems, following an idiomatic R API (formula + data.frame, S3 methods, predict(), summary(), coef(), plot()).

Why Tb-NB / iTb-NB?

Classical Naive Bayes outputs poorly-calibrated posterior probabilities when conditional independence is violated. Tb-NB sidesteps the issue by:

• computing a continuous log-likelihood ratio score per document;
• learning an optimal decision threshold τ via K-fold cross-validation on a user-selected criterion (accuracy, F1, MCC, balanced error, etc.);
• optionally refining the boundary locally in regions of class overlap via iTb-NB (KDE or CLT-bootstrap densities).

Models are described in:

• Romano M., Contu G., Mola F., Conversano C. (2024). Threshold-based Naive Bayes classifier. Adv. Data Anal. Classif. 18, 325–361. doi:10.1007/s11634-023-00536-8
• Romano M., Zammarchi G., Conversano C. (2024). Iterative Threshold-Based Naive Bayes Classifier. Stat. Methods Appl. 33, 235–265. doi:10.1007/s10260-023-00721-1
• Romano M. (2025). Iterative Threshold-based Naïve Bayes classifier: further interpretability with p-values. In E. di Bella, V. Gioia, C. Lagazio & S. Zaccarin (Eds.), Statistics for Innovation I: SIS 2025, Short Papers, Plenary, Specialized, and Solicited Sessions (Chap. 41). Italian Statistical Society Series on Advances in Statistics. Springer, Cham. doi:10.1007/978-3-031-96736-8_41

Installation

install.packages("tbnb")

Quick start

library(tbnb)

data(toy_reviews)

# Formula + data interface (no manual text preprocessing required)
fit <- itbnb(
  sentiment ~ text,
  data       = toy_reviews,
  preprocess = tbnb_preprocess(language = "english"),
  criterion  = "balanced_error",
  K          = 5,
  iterative  = TRUE,
  iter_mode  = "kde"
)

summary(fit)
predict(fit, newdata = toy_reviews[1:5, ], type = "class")
predict(fit, newdata = toy_reviews[1:5, ], type = "score")
plot(fit, newdata = toy_reviews, y = toy_reviews$sentiment)

Matrix interface

If you already have a document-feature matrix (e.g. a quanteda::dfm or a Matrix sparse matrix), pass it directly via x / y:

fit <- itbnb(x = my_dfm, y = sentiment, criterion = "f1")

P-value extension (SIS 2025)

The package implements the p-value extension proposed in Romano (2025, doi:10.1007/978-3-031-96736-8_41): for any fitted model you can compute document-level p-values (how extreme is each document's score under the per-class score distribution) and feature-level p-values (which words are statistically significant predictors, not just "top-K by log-odds").

# Per-document p-values + uncertainty flag
pv_doc <- tbnb_pvalues(fit, type = "document",
                       newdata = toy_reviews,
                       method  = "clt")     # or "kde"
head(pv_doc)

# Per-feature p-values
pv_feat <- tbnb_pvalues(fit, type = "feature", method = "clt")
head(pv_feat[order(pv_feat$p_value), ], 10)

# summary() integrates the significant-feature ranking
summary(fit, pvalues = TRUE, pvalue_method = "clt")

Optional: word-embedding extension

Beyond the original papers, tbnb supports an optional semantic augmentation of the Bag-of-Words using a word-embedding model (approach C in the design notes): for each token in a document, the top-k nearest neighbours in the embedding space are added to the BoW. This can help with sparsity and synonym handling while leaving Tb-NB's word-level interpretability intact.

emb <- tbnb_embedding(my_glove_matrix, k = 3, min_similarity = 0.6)
fit <- itbnb(sentiment ~ text, data = reviews, embedding = emb)

This extension is not part of the original Tb-NB / iTb-NB papers and must be explicitly enabled.

License

GPL (>= 3)