% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/mine_text.R
\name{mine_text}
\alias{mine_text}
\title{Build a Term-Frequency Table}
\usage{
mine_text(docs, ngmin = 1, ngmax = ngmin, sparse = NULL)
}
\arguments{
\item{docs}{'list' or 'character' vector.
Document text to analyze. Each element holds the extracted text of a single
document and may itself be a character vector (its pieces are concatenated).
\code{NA} values are dropped. If unnamed, elements are numbered sequentially.}

\item{ngmin, ngmax}{'integer' numbers.
Minimum and maximum number of words per term (n-gram). The default
(\code{ngmin = ngmax = 1}) counts single words. Values greater than one require the
\pkg{RWeka} package and that the \code{JAVA_HOME} environment variable point to a
Java installation. Recommended for a single document only.}

\item{sparse}{'numeric' number greater than 0 and less than 1, or \code{NULL}.
Maximum allowed sparsity: terms appearing in a smaller proportion of documents
are removed. For example, \code{sparse = 0.99} removes terms more sparse than 0.99,
while \code{sparse = 0.01} retains only terms appearing in nearly every document.
The default (\code{NULL}) disables sparse-term removal.}
}
\value{
A 'data.frame' term-frequency table with columns \code{term}, \code{pub_id}, and
\code{freq}, giving the number of times each term occurs in each document. Rows with
a zero count are omitted, and the table is sorted by term (ascending) then
frequency (descending).
}
\description{
Build a term-frequency table from document text.
A term is a single word or, when n-gram tokenization is enabled, an ordered
sequence of words.
}
\details{
Documents are cleaned before counting: URLs, escaped unicode sequences,
HTML tags, and selected punctuation are removed; text is lowercased; numbers,
English and SMART stopwords, and remaining punctuation are stripped; and
whitespace is collapsed. HTML entities are decoded when the \pkg{textutils}
package is available. When n-grams are requested, terms containing a repeated
word are discarded.
}
\examples{
d <- c(
  "The quick brown fox jumps over the lazy lazy dog.",
  "Pack my brown box.",
  "Jazz fly brown dog."
) |>
  mine_text()

d <- list(
  "A" = "The quick brown fox jumps over the lazy lazy dog.",
  "B" = c("Pack my brown box.", NA, "Jazz fly brown dog."),
  "C" = NA_character_
) |>
  mine_text()
}
\seealso{
\code{\link{search_terms}} to search within the resulting table, and
\code{\link{make_wordcloud}} to create a word cloud from it.
}
\author{
J.C. Fisher, U.S. Geological Survey, Idaho Water Science Center
}
