Readme: say what a cacheAs file is good for besides speed
The passage introducing cacheAs framed it as a way around slow collocation
analyses, which is still its main use and now more so, since comparing
them across virtual corpora multiplies the waiting. But the parameter is
no longer collocationAnalysis' alone, and for the quick functions that
reason does not apply: a kept file holds the numbers a text was written
about, which KorAP answers differently once the corpus has grown, and it
lets a script run again with no server at all - which was checked against
a connection whose requests all fail.
That a file is not reused for a call it was not written for is worth
saying too, since the alternative would be silently wrong numbers. And
since it is not, keeping one under version control next to the document
is worth suggesting, with cacheAsInfo() to read back what it rests on,
blessCacheAs() to vouch for a file that is sound all the same, and
withCachedResults() for when there is no time to recompute anything.
Also documents that a named vc vector labels the rows of corpusStats(),
frequencyQuery() and collocationScoreQuery(), which so far only
collocationAnalysis() was said to do. The connection's cache now points
at cacheAs, the two being easy to confuse.
Change-Id: I03e1b9cada8ad76cf7aeacb68d285315c8ab1499
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
diff --git a/Readme.md b/Readme.md
index 50468d9..b7208dd 100644
--- a/Readme.md
+++ b/Readme.md
@@ -48,6 +48,8 @@
clearCache() # discard all locally cached responses
```
+This cache is a transparent speed-up that you can throw away at any time. To keep a finished result in a file of your own instead, see the `cacheAs` parameter described further below.
+
Please note that, in the case of DeReKo, authorized queries behave differently inside and outside the IDS, because of the special license situation. Cached results do not record from where a request was issued, so if you get unexpected results after changing networks, use `clearCache()` or `cache = FALSE`.
### Frequencies over time and domains using ggplot2
@@ -116,6 +118,12 @@
in 253,752,552 sentences in 13,857,981 documents.
```
+Passing a *named* vector of virtual corpora returns one row per corpus, labelled by the names you chose for them in a `label` column. `frequencyQuery` and `collocationScoreQuery` label their results the same way:
+
+```r
+corpusStats(kco, vc = c(before = "pubDate until 2009", since = "pubDate since 2010"), as.df = TRUE)
+```
+
With `as.df = TRUE` you get a one row data frame with `tokens`, `sentences`, `paragraphs` and `documents` columns instead, which makes it easy to compare several virtual corpora.
### Metadata of a text
@@ -188,13 +196,25 @@
|[in Marsch setzen](https://korap.ids-mannheim.de/?q=Marsch%20focus%28in%20%5btt%2fp%3dNN%5d%20%7b%5btt%2fl%3dsetzen%5d%7d%29&ql=poliqarp) | 6.87| 9.27| 22041.63|
|[in Klammern setzen](https://korap.ids-mannheim.de/?q=Klammern%20focus%28in%20%5btt%2fp%3dNN%5d%20%7b%5btt%2fl%3dsetzen%5d%7d%29&ql=poliqarp) | 6.55| 10.08| 15643.27|
-Collocation analyses can take a while. With the `cacheAs` parameter you can have the result stored in an RDS file of your choice, so that repeated calls – when re-knitting a document, for example – return the cached result immediately instead of querying the server again:
+Collocation analyses can take a while, and comparing them across virtual corpora, as shown below, multiplies that. With the `cacheAs` parameter you can have the result stored in an RDS file of your choice, so that repeated calls – when re-knitting a document, for example – return the cached result immediately instead of querying the server again:
```r
KorAPConnection(verbose = TRUE) |> auth() |>
collocationAnalysis("Ameisenplage", cacheAs = "ameisenplage-ca.rds")
```
+`frequencyQuery`, `corpusStats`, `collocationScoreQuery` and `textMetadata` take the parameter as well, where it is less about time: the file keeps the numbers a text was written about, which KorAP would answer differently once the corpus has grown, and it lets the script run again without a server at all. A file is only reused for the call that produced it – a changed parameter, a different KorAP instance, or a version of RKorAPClient whose scores differ has it recomputed and overwritten, with a warning saying why.
+
+Consider keeping such a file under version control next to the document that uses it, so that the analysis travels with the text. `cacheAsInfo()` reads back what produced it: parameters, KorAP instance, index revision and package version.
+
+When a file is refused although you know it to be sound – one written by a development version that already had the current scores, say – `blessCacheAs("klima.rds")` vouches for it once and for good. And when there is no time to recompute anything at all, `withCachedResults({ ... })` takes the files as they are for the code inside it, with `mode = "offline"` refusing to query the server even for a file that is missing:
+
+```r
+withCachedResults(mode = "offline", {
+ ca <- kco |> collocationAnalysis("Klima", cacheAs = "klima-ca.rds")
+})
+```
+
### Comparing collocates across virtual corpora (experimental)
If you pass a *named* vector of virtual corpora as `vc`, `collocationAnalysis` compares the collocates of the node between them and adds a set of comparison columns, labelled with the names you provided: