% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/create_citation_network.R
\name{describe_citation_clusters}
\alias{describe_citation_clusters}
\title{Describe Citation Clusters by Section Using Reference Title N-grams}
\usage{
describe_citation_clusters(
  citation_analysis_results,
  top_n = 10,
  min_word_length = 3,
  remove_stopwords = TRUE,
  ngram_range = c(1, 2),
  custom_stopwords = NULL
)
}
\arguments{
\item{citation_analysis_results}{A list object returned by \code{analyze_scientific_content()},
containing at least:
\itemize{
\item \code{citations}: A tibble with \code{citation_text_clean} and \code{section} columns
\item \code{citation_references_mapping}: A tibble linking citations to references with
\code{citation_text_clean}, \code{ref_full_text}, and \code{matched_ref_id}
\item \code{parsed_references}: A tibble with \code{ref_id} and \code{ref_full_text}
}}

\item{top_n}{Integer. Number of top terms to return per section. Default is 10.}

\item{min_word_length}{Integer. Minimum character length for tokens to be included.
Default is 3.}

\item{remove_stopwords}{Logical. Whether to remove English stopwords. Default is TRUE.}

\item{ngram_range}{Integer vector of length 2. Range of n-gram sizes to extract.
Default is \code{c(1, 2)} for unigrams and bigrams.}

\item{custom_stopwords}{Character vector. Additional stopwords to remove beyond the
default English stopwords. Default is NULL.}
}
\value{
A list of class \code{"citation_cluster_description"} with:
\itemize{
\item \code{cluster_descriptions}: A tibble with columns \code{section}, \code{ngram},
\code{n}, \code{tf}, \code{idf}, \code{tf_idf}, and \code{ngram_size} (1 or 2)
\item \code{cluster_summary}: A tibble with one row per section containing
\code{section}, \code{n_references}, and \code{top_terms} (comma-separated string)
\item \code{cluster_references}: A tibble mapping \code{section} to \code{ref_full_text}
}
}
\description{
Generates textual descriptions of citation clusters grouped by document section.
For each section, the function extracts the most representative unigrams and bigrams
from the titles of cited references, ranked by TF-IDF score. This helps understand
the thematic focus of each section's bibliography.
}
\details{
The function works by:
\enumerate{
\item Joining citations with their matched references, grouped by section
\item Extracting the title portion from each reference's full text
\item Tokenizing titles into unigrams and bigrams
\item Computing TF-IDF scores where each section is treated as a document
\item Selecting the top terms per section ranked by TF-IDF
}

Title extraction uses the pattern after \code{(YYYY).} up to the next period.
If no year pattern is found, text after the first period is used as fallback.
}
\examples{
\dontrun{
results <- analyze_scientific_content(pdf_path)
cluster_desc <- describe_citation_clusters(results)

# View top terms per section
cluster_desc$cluster_summary

# View detailed TF-IDF scores
cluster_desc$cluster_descriptions
}

}
