frequencyQuery-KorAPConnection-method: Query frequencies of search expressions in virtual corpora

frequencyQuery,KorAPConnection-methodR Documentation

Query frequencies of search expressions in virtual corpora

Description

frequencyQuery combines corpusQuery(), corpusStats() and ci() to compute a tibble with the absolute and relative frequencies and confidence intervals of one or multiple search terms across one or multiple virtual corpora.

Usage

## S4 method for signature 'KorAPConnection'
frequencyQuery(
  kco,
  query,
  vc = "",
  conf.level = 0.95,
  as.alternatives = FALSE,
  cacheAs = NULL,
  dispersionBy = NULL,
  dispersionFunctions = defaultDispersionFunctions(),
  dispersionExactFrequencies = TRUE,
  searchHitsSampleLimit = 20000,
  seed = 7,
  ...
)

Arguments

kco

KorAPConnection() object (obtained e.g. from KorAPConnection())

query

corpus query string(s) (can be a vector). The query language depends on the ql parameter. Either query must be provided or KorAPUrl.

vc

virtual corpus definition(s) (can be a vector)

conf.level

confidence level of the returned confidence interval (passed through ci() to prop.test()).

as.alternatives

LOGICAL that specifies if the query terms should be treated as alternatives. If as.alternatives is TRUE, the sum over all query hits, instead of the respective vc token sizes is used as total for the calculation of relative frequencies.

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 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 NULL (no file).

dispersionBy

Optional corpusPartition() table or named list of tables. Adds a dispersion list column computed by dispersionQuery(). Each partition's base corpus must match the frequency row's vc.

dispersionFunctions

Named list of replaceable dispersion functions; see defaultDispersionFunctions().

dispersionExactFrequencies

Use exact part counts for the optional dispersion analysis; FALSE uses metadata sampling.

searchHitsSampleLimit

Maximum number of metadata hits to download for the optional dispersion analysis; see dispersionQuery().

seed

Seed for optional dispersion sampling.

...

further arguments passed to or from other methods (see corpusQuery()), most notably expand, a logical that decides if query and vc parameters are expanded to all of their combinations. It defaults to TRUE, if query and vc have different lengths, and to FALSE otherwise.

Value

A tibble, with each row containing the following result columns for query and vc combinations:

  • query: the query string used for the frequency analysis.

  • variant: query-vector names, when supplied, for display labels.

  • as.alternatives: denominator mode, retained for plotting helpers.

  • totalResults: absolute frequency of query matches in the vc.

  • vc: virtual corpus used for the query.

  • queryDuration: client-side duration of the request in seconds.

  • webUIRequestUrl: URL of the corresponding web UI request with respect to query and vc.

  • total: total number of words in vc.

  • f: relative frequency of query matches in the vc.

  • conf.low: lower bound of the confidence interval for the relative frequency, given conf.level.

  • conf.high: upper bound of the confidence interval for the relative frequency, given conf.level.

Slow queries

Complex queries can take minutes on large corpora, especially on DeLiKo@DNB (⁠https://korap.dnb.de⁠), or exceed the time limit of the server, which leaves the results incomplete. As long as KorAP does not offer sampling by itself, a workaround is to restrict vc to a pseudo-random sample of texts, selected by the last digit of their sigle: "textSigle = /.*5/" selects about a tenth, "textSigle = /.*[0-4]/" about half of the texts. Combine the sample with other conditions using &, e.g. "textType = /.*Krimi.*/ & textSigle = /.*5/". Relative frequencies, and association scores that do not depend on the corpus size, such as logDice, remain estimates for the whole (virtual) corpus, whereas absolute frequencies, and with them log-likelihood scores, shrink with the sample. A sample saves about as much time as it leaves out if the server has recently read the index of the query terms, e.g. for the same query on another virtual corpus, but hardly any time otherwise, when most of the time goes into reading the index from disk. It thus pays off in series of queries on the same terms, such as a frequencyQuery() over many years or a collocationAnalysis(). Repeating a query on the same vc takes no time anyway, as its result comes from the local cache (see the cache parameter of KorAPConnection()). Queries that are fast anyway do not get faster, because selecting the sample takes some time itself.

Examples

## Not run: 

KorAPConnection(verbose = TRUE) |>
  frequencyQuery(c("Mücke", "Schnake"), paste0("pubDate in ", 2000:2003))

## End(Not run)


RKorAPClient documentation built on Nov. 12, 2026, 5:11 p.m.