Refuse cacheAs files written before the scores were corrected
A cacheAs file holds a finished analysis, association scores included,
and 1.4.0 computes those differently. A file written by 1.3.0 would
therefore be handed back with numbers that would not be arrived at again,
and the comparison of parameters added during this cycle cannot notice
it: the parameters did not change, the formula did. The version that
wrote a file is now recorded in it, and one from before 1.4.0 is
recomputed and overwritten, with a warning saying why.
The machinery moves to a file of its own on the way, since it is no
longer about collocation analysis alone, and verbose drops out of what a
file records: how loud a query is does not change what it returns.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Change-Id: I8af9eac21ae53fe5d583578c3689b37d140a4af4
diff --git a/man/cacheAs.Rd b/man/cacheAs.Rd
new file mode 100644
index 0000000..ff270d9
--- /dev/null
+++ b/man/cacheAs.Rd
@@ -0,0 +1,19 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/cacheAs.R
+\name{cacheAs}
+\alias{cacheAs}
+\title{Keeping results in a file of one's own}
+\description{
+The \code{cacheAs} parameter of the query functions is a different thing from the
+\code{cache} parameter of \code{\link[=KorAPConnection]{KorAPConnection()}}. The latter is a transparent
+speed-up: it stores server responses where the package finds them again, and
+throwing it away costs nothing but time. The former stores a finished result
+in a file the caller names and keeps, which is what makes an analysis
+reproducible: KorAP corpora grow, so the same query returns different numbers
+next year, and the scores computed from them may change with the package.
+}
+\details{
+A cache file therefore records what produced it, and is not reused when that
+no longer matches what is being asked for.
+}
+\keyword{internal}
diff --git a/man/collocationAnalysis-KorAPConnection-method.Rd b/man/collocationAnalysis-KorAPConnection-method.Rd
index ac7e7d9..c91867b 100644
--- a/man/collocationAnalysis-KorAPConnection-method.Rd
+++ b/man/collocationAnalysis-KorAPConnection-method.Rd
@@ -100,7 +100,7 @@
\item{vcLabel}{optional label override for the current virtual corpus (used internally when named VC collections are expanded)}
-\item{cacheAs}{path to an RDS file for caching the result. If the file already exists, the cached result is loaded and returned immediately without contacting the server. Otherwise the analysis is run normally and the result is saved to the file before returning. Defaults to \code{NULL} (no caching).
+\item{cacheAs}{path to an RDS file to keep the result in. If the file exists and records the same call, it is read back instead of contacting the server; otherwise the query is run and its result stored there. Unlike the connection's \code{cache}, this file belongs to the caller, which is what keeps an analysis reproducible once the corpus has grown or the scores have changed. Defaults to \code{NULL} (no file).
The analysis parameters are stored alongside the result. If they differ from
those of the current call, the cached result would not be the one that was