Package {tbnb}

tbnb: Threshold-Based and Iterative Threshold-Based Naive Bayes Classifier

Description

The tbnb package implements the Threshold-Based Naive Bayes (Tb-NB) classifier and its iterative refinement (iTb-NB), proposed by Romano et al. (2023, 2024) for binary sentiment / text classification.

Details

The model computes, for each text document, a continuous log-likelihood ratio score from word presence / absence, and assigns the class by comparing the score against a decision threshold \tau that is estimated from the data via K-fold cross-validation on a user-selected criterion (accuracy, F1, MCC, balanced error, etc.). An optional iterative refinement procedure (iTb-NB) re-estimates the threshold locally in regions of class overlap, either by Gaussian kernel density estimation (mode = "kde") or by a Central Limit Theorem bootstrap approximation (mode = "clt").

Main entry points

• itbnb() – fit the model (formula + data.frame, or matrix interface).

• tbnb_preprocess() – build a text-preprocessing configuration.

• tbnb_embedding() – optional word-embedding augmentation of the Bag-of-Words (semantic neighbours expansion).

• tbnb_pvalues() – document- and feature-level p-values introduced in Romano (2025).

• predict.tbnb(), plot.tbnb() – standard S3 methods (use summary() and coef() for the other ones).

Author(s)

Maintainer: Maurizio Romano romano.maurizio@unica.it

References

Romano M., Contu G., Mola F., Conversano C. (2024). Threshold-based Naive Bayes classifier. Advances in Data Analysis and Classification, 18, 325–361. doi:10.1007/s11634-023-00536-8

Romano M., Zammarchi G., Conversano C. (2024). Iterative Threshold-Based Naive Bayes Classifier. Statistical Methods & Applications, 33, 235–265. doi:10.1007/s10260-023-00721-1

Romano M. (2025). Iterative Threshold-based Naive 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

Fit a Threshold-Based Naive Bayes classifier (Tb-NB / iTb-NB)

Description

itbnb() fits the Threshold-Based Naive Bayes classifier proposed by Romano et al. (2024) and, optionally, its iterative refinement (iTb-NB). The method is designed for binary classification of text documents but accepts any binary Bag-of-Words–style feature matrix.

Usage

itbnb(...)

## S3 method for class 'formula'
itbnb(
  formula,
  data,
  subset,
  na.action,
  preprocess = tbnb_preprocess(),
  embedding = NULL,
  alpha = 1,
  fit_prior = TRUE,
  class_prior = NULL,
  optimize_threshold = TRUE,
  criterion = "balanced_error",
  tau_grid = "observed",
  n_tau = 50L,
  K = 5L,
  random_state = 42L,
  iterative = FALSE,
  iter_mode = c("kde", "clt"),
  p_iter = 0.2,
  s_iter = 20L,
  clt_n_boot = 500L,
  clt_sample_size = 30L,
  language_col = NULL,
  ...
)

## Default S3 method:
itbnb(
  x,
  y,
  preprocess = NULL,
  embedding = NULL,
  alpha = 1,
  fit_prior = TRUE,
  class_prior = NULL,
  optimize_threshold = TRUE,
  criterion = "balanced_error",
  tau_grid = "observed",
  n_tau = 50L,
  K = 5L,
  random_state = 42L,
  iterative = FALSE,
  iter_mode = c("kde", "clt"),
  p_iter = 0.2,
  s_iter = 20L,
  clt_n_boot = 500L,
  clt_sample_size = 30L,
  doc_languages = NULL,
  ...
)

Arguments

Details

Two interfaces are provided:

1. Formula + data.frame (idiomatic R):

   itbnb(sentiment ~ text, data = reviews, ...)

   where the right-hand side names a single column of data that contains the raw text. The text is preprocessed internally with quanteda according to the tbnb_preprocess() configuration.

2. Matrix / dfm + response (advanced / pipeline use):

   itbnb(x = dfm, y = sentiment, ...)

   where x is an already-built binary document-feature matrix (any of: base matrix, Matrix sparse, quanteda::dfm, data.frame).

Value

An object of class "tbnb" with components: call, terms, xlevels, text_col, preprocess, embedding, feature_names, classes, class_prior, class_occurrences, feature_counts, log_pres, log_abs, alpha, threshold, criterion, optimizer, iterative, decisions.

References

Romano M., Contu G., Mola F., Conversano C. (2024). doi:10.1007/s11634-023-00536-8

Romano M., Zammarchi G., Conversano C. (2024). doi:10.1007/s10260-023-00721-1

Examples

# Toy synthetic dataset (formula interface)
reviews <- data.frame(
  sentiment = rep(c("pos", "neg"), each = 5),
  text = c(
    "great hotel friendly staff lovely view",
    "amazing room comfortable bed great breakfast",
    "wonderful stay clean rooms helpful staff",
    "fantastic location nice view comfortable",
    "lovely breakfast helpful staff great room",
    "dirty room rude staff terrible noise",
    "awful stay smelly room bad service",
    "noisy room rude reception dirty bathroom",
    "terrible breakfast cold food bad service",
    "horrible stay rude staff dirty noisy"
  ),
  stringsAsFactors = FALSE
)

fit <- itbnb(sentiment ~ text, data = reviews,
             preprocess = tbnb_preprocess(language = "english",
                                          min_count = 1, min_docfreq = 1),
             K = 2, n_tau = 10, iterative = FALSE)
predict(fit, newdata = reviews[1:3, ], type = "class")
summary(fit)

Plot the distribution of decision scores by class

Description

Plot the distribution of decision scores by class

Usage

## S3 method for class 'tbnb'
plot(x, newdata = NULL, y = NULL, breaks = 40, ...)

Arguments

Value

Invisibly, the numeric vector of decision scores computed for newdata, or NULL when newdata is not supplied. The function is called for its side effect of drawing the score distribution together with the estimated threshold(s).

Predictions from a fitted tbnb model

Description

Predictions from a fitted tbnb model

Usage

## S3 method for class 'tbnb'
predict(
  object,
  newdata,
  type = c("class", "score", "prob", "raw"),
  threshold = NULL,
  iterative = NULL,
  doc_languages = NULL,
  ...
)

Arguments

Value

A vector of the requested type.

Summary of a fitted Tb-NB / iTb-NB model

Description

Summary of a fitted Tb-NB / iTb-NB model

Usage

## S3 method for class 'tbnb'
summary(
  object,
  pvalues = FALSE,
  pvalue_method = c("clt", "kde"),
  pvalue_alpha = 0.05,
  ...
)

Arguments

Value

An object of class "tbnb_summary": a list collecting the class labels, the vocabulary size, the class priors, the Laplace smoothing parameter, the selection criterion and the estimated threshold, the most positive and most negative words, the cross-validated threshold-per-criterion table and, when pvalues = TRUE, the feature-level p-value table. A print method is provided.

Names of the criteria supported by itbnb() for threshold optimisation

Description

Names of the criteria supported by itbnb() for threshold optimisation

Usage

tbnb_available_criteria()

Value

Character vector of criterion names.

Categorise the vocabulary of a fitted Tb-NB / iTb-NB model

Description

Produces a partition of the model vocabulary into a finite set of user-meaningful categories that can then be fed into tbnb_posthoc_plots() for the post-hoc analyses described in Romano et al. (2024) — e.g. how the sentiment of food, staff, cleanliness etc. evolves over time, or differs across hotels.

Usage

tbnb_categorize(
  object,
  method = c("dbscan", "seed", "kmeans", "manual"),
  seeds = NULL,
  k = NULL,
  eps = NULL,
  minPts = 5L,
  n_categories_target = 10L,
  min_category_size = 5L,
  assignments = NULL,
  embedding = NULL,
  text_corpus = NULL,
  embedding_dim = 50L,
  embedding_iter = 15L,
  embedding_window = 5L,
  refine = FALSE,
  min_similarity = 0,
  features = NULL,
  hotel_reviews = FALSE,
  verbose = TRUE
)

Arguments

Details

Four methods are supported:

• method = "seed" (semi-supervised). The user supplies a named list of seed words per category; each remaining vocabulary word is assigned to the category whose centroid (mean of seed vectors) is closest in the embedding space (cosine similarity). With refine = TRUE the procedure iterates k-means-style by recomputing centroids from the current assignments until convergence.

• method = "kmeans" (unsupervised, K chosen). Standard k-means on the word vectors. Clusters are named ⁠cluster_1, ..., cluster_K⁠.

• method = "dbscan" (unsupervised, K automatic). Density-based clustering with eps and minPts. Noise points are sent to the special category "uncategorized". Requires the dbscan package.

• method = "manual". The user passes a named character vector (words -> category) or a data.frame with columns ⁠word, category⁠. No clustering is performed.

For the three embedding-based methods, the user may supply a pre-trained embedding (⁠embedding =⁠); otherwise a GloVe model is trained on the fly on text_corpus using text2vec.

Value

An S3 object of class "tbnb_categorization" with components:

• assignments — data.frame(word, category, log_odds, similarity) (the similarity column is NA for manual / dbscan / kmeans).

• categories — character vector of category names.

• method — the method used.

• centroids — for seed / kmeans: matrix of category centroids.

• embedding_used — the embedding matrix actually used (or NULL).

References

Romano M., Contu G., Mola F., Conversano C. (2024). Threshold-based Naive Bayes classifier. Advances in Data Analysis and Classification, 18, 325–361. doi:10.1007/s11634-023-00536-8

Examples

data(toy_reviews)
fit <- itbnb(sentiment ~ text, data = toy_reviews,
             preprocess = tbnb_preprocess(language = "english"))

# Manual categorisation (no embedding required)
cat_man <- tbnb_categorize(
  fit, method = "manual",
  assignments = c(staff = "service", room = "room",
                  breakfast = "food", view = "view"))
print(cat_man)

Configure the word-embedding semantic augmentation of the BoW

Description

At fit / predict time, for each token w in a document, the top-k most similar tokens in the embedding space are added to the document with weight 1 (presence). This enriches the Bag-of-Words with synonyms / semantic neighbours, which can help mitigate sparsity issues and out-of-vocabulary problems while leaving the Tb-NB word-interpretability intact.

Usage

tbnb_embedding(vectors, k = 3L, min_similarity = 0.5, self_include = TRUE)

Arguments

Details

This is an extension not present in the original Tb-NB / iTb-NB papers. It is disabled by default and must be explicitly enabled by passing the returned configuration to the embedding argument of itbnb().

Value

A tbnb_embedding configuration object.

Built-in seed words for hospitality / hotel reviews

Description

Returns the 12 reference categories used in the Booking.com analysis of Romano et al. (2024) — cleaning, comfort, position, price-quality-rate, services, staff, wifi, bar, food, hotel, room, sleep-quality — each populated with bilingual Italian + English seed words. The 13th category from the paper, "other", is the residual one and is handled automatically as "uncategorized".

Usage

tbnb_hospitality_seeds()

Details

Used by tbnb_categorize() when hotel_reviews = TRUE.

Value

A named list of character vectors (one per category).

Iterative refinement of the decision threshold (iTb-NB)

Description

Starting from a global threshold tau, the algorithm iteratively inspects the uncertainty region around it and proposes a refined local threshold by estimating the intersection of the two class-conditional score densities. The refinement is repeated until convergence, lack of data, or until the modes of the two densities become indistinguishable.

Usage

tbnb_iterate(
  scores,
  y,
  tau,
  p = 0.2,
  s = 20L,
  mode = c("kde", "clt"),
  clt_boot = 500L,
  clt_sample = 30L,
  epsilon = 0.001,
  max_iter = 50L
)

Arguments

Value

A data.frame of decisions, one row per refinement step, with columns: iteration, start, end, tau, x_max_pos, x_max_neg, direction ("r" if positive class mode is to the right of negative, "l" otherwise).

Compute all binary classification metrics from confusion counts

Description

Compute all binary classification metrics from confusion counts

Usage

tbnb_metrics(TP, FP, TN, FN)

Arguments

Value

A named list with the metrics listed in tbnb_available_criteria().

Cross-validated threshold optimisation for a Tb-NB classifier

Description

Given an already-fitted Tb-NB model and the training data used to fit it, explores a grid of candidate thresholds \tau and reports the best value for each available criterion.

Usage

tbnb_optimize_threshold(
  X,
  y,
  alpha = 1,
  fit_prior = TRUE,
  class_prior = NULL,
  tau_grid = "observed",
  n_tau = 50L,
  K = 5L,
  random_state = 42L
)

Arguments

Value

List with components:

• tau_grid – sorted grid of candidate thresholds;

• metric_mats – named list of ⁠K x n_tau⁠ matrices, one per metric;

• best_tau – named numeric vector of optimal \tau per criterion.

Generate post-hoc analysis plots from a fitted Tb-NB / iTb-NB model

Description

Combines the per-word sentiment scores from a fitted Tb-NB / iTb-NB model with a categorisation produced by tbnb_categorize() to generate the post-hoc plots described in Romano et al. (2024) — i.e. how each category contributes to overall sentiment, how sentiment evolves over time, which words are statistically significant within each category, etc.

Usage

tbnb_posthoc_plots(
  object,
  categorization,
  newdata,
  time_var = NULL,
  group_var = NULL,
  doc_languages = NULL,
  pvalues = NULL,
  which = c("category_score", "time_series", "feature_volcano", "category_distribution",
    "top_words_per_category"),
  top_n_words = 15L,
  exclude_words = NULL,
  exclude_top_quantile = NULL,
  exclude_carriers = FALSE,
  time_unit = c("month", "quarter", "year", "week"),
  palette = NULL,
  theme = "minimal"
)

Arguments

Details

The returned list contains ggplot2 objects so the user can further customise them, save them to disk via ggplot2::ggsave(), or arrange them in panels.

Value

A named list of ggplot objects (the keys are the entries of which).

References

Romano M., Contu G., Mola F., Conversano C. (2024). Threshold-based Naive Bayes classifier. Advances in Data Analysis and Classification, 18, 325–361. doi:10.1007/s11634-023-00536-8

Configure the text-preprocessing pipeline

Description

Helper used to build a configuration list to be passed to itbnb() via the preprocess argument. The pipeline is implemented on top of quanteda and produces a binary document-feature matrix that is fed to the Tb-NB core.

Usage

tbnb_preprocess(
  language = "english",
  lowercase = TRUE,
  remove_punct = TRUE,
  remove_numbers = TRUE,
  remove_symbols = TRUE,
  remove_url = TRUE,
  remove_stopwords = TRUE,
  extra_stopwords = NULL,
  stem = FALSE,
  stem_language = NULL,
  detect_engine = c("cld2", "cld3"),
  min_word_length = 2L,
  min_count = 1L,
  min_docfreq = 1L,
  min_words_per_doc = 3L,
  ngrams = 1L
)

Arguments

Details

The function supports both monolingual and multilingual corpora: set language to a vector of language names (e.g. c("italian", "english")) and the union of the corresponding stopword lists will be removed. Stemming, which is language-specific, is controlled by stem_language:

• stem_language = NULL (default) — no stemming.

• stem_language = "<lang>" — apply the Snowball stemmer for that language to every token (a sensible default when one language dominates the corpus; tokens from the minority language are stemmed with the "wrong" rules but in practice this is rarely harmful).

• stem_language = "per_document" — detect the language of each document with cld2 or cld3 (see detect_engine) and stem each document with the appropriate Snowball stemmer. Only documents detected as one of the languages in language are stemmed; documents detected as another language (or undetected) are left as-is.

The legacy boolean stem = TRUE is still accepted for back-compat: it is interpreted as stem_language = language[1].

Value

A named list of class "tbnb_preprocess" to be supplied to itbnb().

P-values for documents and features (Tb-NB / iTb-NB)

Description

Implements the p-value extension introduced in Romano (2025) for the Tb-NB / iTb-NB classifier. Two flavours are exposed via the type argument:

Usage

tbnb_pvalues(
  object,
  type = c("document", "feature"),
  newdata = NULL,
  method = c("clt", "kde"),
  alpha = 0.05,
  n_boot = 500L,
  sample_size = 30L,
  two_sided = NULL
)

Arguments

Details

• type = "document" — for each row of newdata, the per-class p-value of the observed log-likelihood ratio score \Lambda(c_i) under the training-set score distribution of each class (f^+(z) and f^-(z)). The two p-values are one-sided in the direction of class membership, so that small p_pos flags strong evidence against the "negative" hypothesis (i.e. evidence that the document is positive) and vice-versa.

• type = "feature" — for each token in the vocabulary, the two-sided p-value of its log-odds \Lambda(w_j) against the distribution of log-odds across all features under the null hypothesis of "no discrimination" (vocabulary-wide reference distribution).

Two reference-distribution estimators are supported:

• method = "clt" — bootstrap means with Normal approximation (Central Limit Theorem). This is the procedure proposed in the paper and yields more stable results.

• method = "kde" — Gaussian kernel density estimate of the training distribution, with p-values computed by numerical integration via stats::approx().

Value

An object of class tbnb_pvalues (a data.frame with attributes).

References

Romano, M. (2025). Iterative Threshold-based Naive 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

Examples

data(toy_reviews)
fit <- itbnb(sentiment ~ text, data = toy_reviews,
             preprocess = tbnb_preprocess(language = "english"))

# Document-level p-values
pv_doc <- tbnb_pvalues(fit, type = "document",
                       newdata = toy_reviews,
                       method = "clt")
head(pv_doc)

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

Per-document decision-function scores

Description

Computes the log-likelihood ratio score for each row of X given the fitted log-conditional probabilities.

Usage

tbnb_score(X, log_pres, log_abs)

Arguments

Details

Vectorised closed form: for each row, \sum_k x_k (L_w^+ - L_w^-) - (L_{\bar w}^+ - L_{\bar w}^-) + \sum_k (L_{\bar w}^+ - L_{\bar w}^-).

Value

A numeric vector with one entry per row of X, giving the continuous log-likelihood-ratio decision score of each document.

Toy hotel reviews dataset

Description

A small, hand-crafted dataset of 200 short fictional hotel reviews labelled as positive or negative. It is meant exclusively for illustration and unit tests; the wording is intentionally simple so that the Tb-NB classifier behaves intuitively on it.

Usage

toy_reviews

Format

A data.frame with 200 rows and 2 columns:

sentiment

Factor with two levels "neg" and "pos".

text

Character. The (short) review text.

Source

Synthetic data generated by the package authors. Inspired by the Booking.com reviews used in Romano et al. (2024).