% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/pmCollect.R
\name{pmCollect}
\alias{pmCollect}
\title{Collect and process PubMed bibliographic data in one step}
\usage{
pmCollect(
  query = NULL,
  terms = NULL,
  fields = "Title/Abstract",
  language = NULL,
  pub_type = NULL,
  date_range = NULL,
  mesh_terms = NULL,
  limit = 2000,
  enrich = FALSE,
  format = "bibliometrix",
  api_key = NULL,
  batch_size = 200,
  verbose = TRUE
)
}
\arguments{
\item{query}{is a character. A PubMed search query in Entrez syntax.
Alternatively, if \code{terms} is provided, the query is built automatically
using \code{\link{pmQueryBuild}} and this argument is ignored.}

\item{terms}{is a character or character vector or NULL. Search terms passed to
\code{\link{pmQueryBuild}}. When provided, a query is built automatically
and the \code{query} argument is ignored. Default is \code{NULL}.}

\item{fields}{is a character or character vector. PubMed search tags used
when building the query from \code{terms}. Default is \code{"Title/Abstract"}.}

\item{language}{is a character or NULL. Language filter for query building.
Default is \code{NULL}.}

\item{pub_type}{is a character or NULL. Publication type filter for query building.
Default is \code{NULL}.}

\item{date_range}{is a character vector of length 2 or NULL. Date range
in format \code{c("YYYY", "YYYY")}. Default is \code{NULL}.}

\item{mesh_terms}{is a character or character vector or NULL. MeSH terms
for query building. Default is \code{NULL}.}

\item{limit}{is numeric. Maximum number of records to download.
Default is \code{2000}.}

\item{enrich}{is logical. If \code{TRUE}, citation counts (TC) and cited
references (CR) are added via \code{\link{pmEnrichCitations}}.
Default is \code{FALSE} because enrichment makes 2 API calls per article
and can be slow for large collections.}

\item{format}{is a character. Output format passed to \code{\link{pmApi2df}}.
Either \code{"bibliometrix"} (default) or \code{"raw"}.}

\item{api_key}{is a character or NULL. NCBI API key. Can also be set via
the environment variable \code{PUBMED_API_KEY} or \code{ENTREZ_KEY}.
Default is \code{NULL}.}

\item{batch_size}{is numeric. Records per API request. Default is 200.}

\item{verbose}{is logical. If \code{TRUE} (default), prints progress messages.}
}
\value{
a data frame containing bibliographic records, compatible with the
\code{bibliometrix} package when \code{format = "bibliometrix"}.
}
\description{
A convenience wrapper that executes the full pubmedR workflow:
query building, record count check, metadata download, conversion to
data frame, and (optionally) citation enrichment via NCBI E-Link.
}
\details{
This function chains together the core pubmedR functions in the recommended order:
\enumerate{
  \item \strong{Query}: If \code{terms} is provided, builds the query with
        \code{\link{pmQueryBuild}}; otherwise uses the \code{query} string directly.
  \item \strong{Count}: Checks the total number of matching records with
        \code{\link{pmQueryTotalCount}}.
  \item \strong{Download}: Fetches metadata with \code{\link{pmApiRequest}}.
  \item \strong{Convert}: Transforms XML to a data frame with \code{\link{pmApi2df}}.
  \item \strong{Enrich} (optional): Adds citation data with
        \code{\link{pmEnrichCitations}}.
}
}
\examples{

\donttest{
# Using a raw query string
M <- pmCollect(
  query = "bibliometric*[Title/Abstract] AND english[LA] AND 2020:2024[DP]",
  limit = 50
)

# Using the query builder parameters
M <- pmCollect(
  terms = "bibliometric*",
  language = "english",
  pub_type = "Journal Article",
  date_range = c("2020", "2024"),
  limit = 50
)

# With citation enrichment (slower, requires extra API calls)
M <- pmCollect(
  terms = "bibliometric*",
  date_range = c("2023", "2024"),
  limit = 10,
  enrich = TRUE
)
}

}
\seealso{
\code{\link{pmQueryBuild}}, \code{\link{pmQueryTotalCount}},
\code{\link{pmApiRequest}}, \code{\link{pmApi2df}}, \code{\link{pmEnrichCitations}}
}
