% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/co_occurrence.R
\name{cooccurrence}
\alias{cooccurrence}
\title{Build a Co-occurrence Network}
\usage{
cooccurrence(
  data,
  field = NULL,
  by = NULL,
  sep = NULL,
  similarity = c("none", "jaccard", "cosine", "inclusion", "association", "dice",
    "equivalence", "relative"),
  threshold = 0,
  min_occur = 1L,
  diagonal = TRUE,
  top_n = NULL,
  ...
)
}
\arguments{
\item{data}{Input data. Accepts:
\itemize{
\item A \code{data.frame} with a delimited column (\code{field} + \code{sep}).
\item A \code{data.frame} in long/bipartite format (\code{field} + \code{by}).
\item A binary (0/1) \code{data.frame} or \code{matrix} (auto-detected).
\item A wide sequence \code{data.frame} or \code{matrix} (non-binary).
\item A \code{list} of character vectors (each element is a transaction).
}}

\item{field}{Character. The entity column — determines what the nodes are.
For delimited format, a single column whose values are split by \code{sep}.
For long/bipartite format, the item column. For multi-column delimited,
a vector of column names whose split values are pooled per row.}

\item{by}{Character or \code{NULL}. What links the nodes. For
long/bipartite format, the grouping column (e.g., \code{"paper_id"},
\code{"session_id"}). Each unique value of \code{by} defines one
transaction. If \code{NULL} (default), entities co-occur within the
same row/document.}

\item{sep}{Character or \code{NULL}. Separator for splitting delimited
fields (e.g., \code{";"}, \code{","}). Default \code{NULL}.}

\item{similarity}{Character. Similarity measure applied to the raw
co-occurrence counts. One of:
\describe{
\item{\code{"none"}}{Raw co-occurrence counts.}
\item{\code{"jaccard"}}{\eqn{C_{ij} / (f_i + f_j - C_{ij})}.}
\item{\code{"cosine"}}{\eqn{C_{ij} / \sqrt{f_i \cdot f_j}}
(Salton's cosine).}
\item{\code{"inclusion"}}{\eqn{C_{ij} / \min(f_i, f_j)}
(Simpson coefficient).}
\item{\code{"association"}}{\eqn{C_{ij} / (f_i \cdot f_j)}
(association strength / probabilistic affinity index;
van Eck & Waltman, 2009).}
\item{\code{"dice"}}{\eqn{2 C_{ij} / (f_i + f_j)}.}
\item{\code{"equivalence"}}{\eqn{C_{ij}^2 / (f_i \cdot f_j)}
(Salton's cosine squared).}
\item{\code{"relative"}}{Row-normalized: each row sums to 1.}
}}

\item{threshold}{Numeric. Minimum edge weight to retain. Edges below this
value are set to zero. Applied \emph{after} similarity normalization.
Default 0.}

\item{min_occur}{Integer. Minimum entity frequency (number of transactions
an entity must appear in). Entities below this threshold are dropped
before computing co-occurrence. Default 1 (keep all).}

\item{diagonal}{Logical. If \code{TRUE} (default), the diagonal of the
co-occurrence matrix is kept (item self-co-occurrence = item frequency).
If \code{FALSE}, the diagonal is zeroed.}

\item{top_n}{Integer or \code{NULL}. If specified, return only the top
\code{top_n} edges by weight. Default \code{NULL} (all edges).}

\item{...}{Currently unused.}
}
\value{
A \code{netobject} (undirected) with \code{method = "co_occurrence_fn"}.
The \code{$weights} matrix contains similarity (or raw) co-occurrence values.
The \code{$params} list stores the similarity method, threshold, and
the number of transactions.
}
\description{
Constructs an undirected co-occurrence network from various input formats.
Entities that appear together in the same transaction, document, or record
are connected, with edge weights reflecting raw counts or a similarity
measure. Argument names follow the citenets convention.
}
\details{
Six input formats are supported, auto-detected from the combination of
\code{field}, \code{by}, and \code{sep}:

\enumerate{
\item \strong{Delimited}: \code{field} + \code{sep} (single column).
Each cell is split by \code{sep}, trimmed, and de-duplicated per row.
\item \strong{Multi-column delimited}: \code{field} (vector) + \code{sep}.
Values from multiple columns are split, pooled, and de-duplicated per row.
\item \strong{Long bipartite}: \code{field} + \code{by}.
Groups by \code{by}; unique values of \code{field} within each group
form a transaction.
\item \strong{Binary matrix}: No \code{field}/\code{by}/\code{sep}, all
values 0/1. Columns are items, rows are transactions.
\item \strong{Wide sequence}: No \code{field}/\code{by}/\code{sep},
non-binary. Unique values across each row form a transaction.
\item \strong{List}: A plain list of character vectors.
}

The pipeline converts all formats into a list of character vectors
(transactions), optionally filters by \code{min_occur}, builds a binary
transaction matrix, computes \code{crossprod(B)} for the raw co-occurrence
counts, normalizes via the chosen \code{similarity}, then applies
\code{threshold} and \code{top_n} filtering.
}
\examples{
# Delimited field (e.g., keyword co-occurrence)
df <- data.frame(
  id = 1:4,
  keywords = c("network; graph", "graph; matrix; network",
               "matrix; algebra", "network; algebra; graph")
)
net <- cooccurrence(df, field = "keywords", sep = ";")

# Long/bipartite
long_df <- data.frame(
  paper = c(1, 1, 1, 2, 2, 3, 3),
  keyword = c("network", "graph", "matrix", "graph", "algebra",
              "network", "algebra")
)
net <- cooccurrence(long_df, field = "keyword", by = "paper")

# List of transactions
transactions <- list(c("A", "B"), c("B", "C"), c("A", "B", "C"))
net <- cooccurrence(transactions, similarity = "jaccard")

# Binary matrix
bin <- matrix(c(1,0,1, 1,1,0, 0,1,1), nrow = 3, byrow = TRUE,
              dimnames = list(NULL, c("X", "Y", "Z")))
net <- cooccurrence(bin)

}
\references{
van Eck, N. J., & Waltman, L. (2009). How to normalize co-occurrence
data? An analysis of some well-known similarity measures. \emph{Journal of
the American Society for Information Science and Technology}, 60(8),
1635--1651.
}
\seealso{
\code{\link{build_cna}} for sequence-positional co-occurrence via
\code{build_network()}.
}
