Parse annotations into lists of vectors
Change-Id: I9ee3a5c10ff997380b9661dd603f8ec83c6a91a8
diff --git a/man/fetchAnnotations-KorAPQuery-method.Rd b/man/fetchAnnotations-KorAPQuery-method.Rd
new file mode 100644
index 0000000..b2dc3bf
--- /dev/null
+++ b/man/fetchAnnotations-KorAPQuery-method.Rd
@@ -0,0 +1,79 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/KorAPQuery.R
+\name{fetchAnnotations,KorAPQuery-method}
+\alias{fetchAnnotations,KorAPQuery-method}
+\alias{fetchAnnotations}
+\title{Fetch annotations for all collected matches}
+\usage{
+\S4method{fetchAnnotations}{KorAPQuery}(kqo, foundry = "tt", verbose = kqo@korapConnection@verbose)
+}
+\arguments{
+\item{kqo}{object obtained from \code{\link[=corpusQuery]{corpusQuery()}} with collected matches. Note: the original corpus query should have \code{metadataOnly = FALSE} for annotation parsing to work.}
+
+\item{foundry}{string specifying the foundry to use for annotations (default: "tt" for Tree-Tagger)}
+
+\item{verbose}{print progress information if true}
+}
+\value{
+The updated \code{kqo} object with annotation columns added to \verb{@collectedMatches}
+}
+\description{
+\strong{\code{fetchAnnotations}} fetches annotations for all matches in the \verb{@collectedMatches} slot
+of a KorAPQuery object and adds annotation columns directly to the \verb{@collectedMatches}
+data frame. The method automatically uses the \code{matchID} from collected matches when
+available for safer and more reliable annotation retrieval, falling back to constructing
+URLs from \code{matchStart} and \code{matchEnd} if necessary.
+}
+\details{
+\strong{Important}: For copyright-restricted corpora, users must be authorized via \code{\link[=auth]{auth()}}
+and the initial corpus query must have \code{metadataOnly = FALSE} to ensure snippets are
+available for annotation parsing.
+
+The method parses XML snippet annotations and adds linguistic columns to the data frame:
+\itemize{
+\item \code{pos}: data frame with \code{left}, \code{match}, \code{right} columns, each containing list vectors of part-of-speech tags
+\item \code{lemma}: data frame with \code{left}, \code{match}, \code{right} columns, each containing list vectors of lemmas
+\item \code{morph}: data frame with \code{left}, \code{match}, \code{right} columns, each containing list vectors of morphological tags
+\item \code{atokens}: data frame with \code{left}, \code{match}, \code{right} columns, each containing list vectors of token text (from annotations)
+\item \code{annotation_snippet}: original XML snippet from the annotation API
+}
+}
+\examples{
+\dontrun{
+
+# Fetch annotations for matches using Tree-Tagger foundry
+# Note: Authorization required for copyright-restricted corpora
+q <- KorAPConnection() |>
+ auth() |>
+ corpusQuery("Ameisenplage", metadataOnly = FALSE) |>
+ fetchNext(maxFetch = 10) |>
+ fetchAnnotations()
+
+# Access linguistic annotations for match i:
+pos_tags <- q@collectedMatches$pos # Data frame with left/match/right columns for POS tags
+lemmas <- q@collectedMatches$lemma # Data frame with left/match/right columns for lemmas
+morphology <- q@collectedMatches$morph # Data frame with left/match/right columns for morphological tags
+atokens <- q@collectedMatches$atokens # Data frame with left/match/right columns for annotation token text
+raw_snippet <- q@collectedMatches$annotation_snippet[[i]] # Original XML snippet for match i
+
+# Access specific components:
+match_pos <- q@collectedMatches$pos$match[[i]] # POS tags for the matched tokens in match i
+left_lemmas <- q@collectedMatches$lemma$left[[i]] # Lemmas for the left context in match i
+right_tokens <- q@collectedMatches$atokens$right[[i]] # Token text for the right context in match i
+
+# Use a different foundry (e.g., mate-parser)
+q <- KorAPConnection() |>
+ auth() |>
+ corpusQuery("Ameisenplage", metadataOnly = FALSE) |>
+ fetchNext(maxFetch = 10) |>
+ fetchAnnotations(foundry = "mate")
+q@collectedMatches
+}
+}
+\seealso{
+Other corpus search functions:
+\code{\link{corpusQuery,KorAPConnection-method}},
+\code{\link{fetchAll,KorAPQuery-method}},
+\code{\link{fetchNext,KorAPQuery-method}}
+}
+\concept{corpus search functions}