dispersionQuery-KorAPConnection-method: Query dispersion across corpus metadata

dispersionQuery,KorAPConnection-methodR Documentation

Query dispersion across corpus metadata

Description

Compute selectable dispersion measures for one or more queries, using exact counts per part or a reproducible metadata sample shared by all partitions.

Usage

## S4 method for signature 'KorAPConnection'
dispersionQuery(
  kco,
  query,
  partitions = NULL,
  scoreFunctions = defaultDispersionFunctions(),
  exactFrequencies = TRUE,
  searchHitsSampleLimit = 20000,
  seed = 7,
  ql = "poliqarp",
  verbose = kco@verbose,
  cacheAs = NULL,
  by = "source",
  regex = NULL,
  vc = ""
)

Arguments

kco

A KorAPConnection() object.

query

Query string or vector of queries.

partitions

Optional corpusPartition() table, or named list of them. If NULL, discover groups using by, as in dispersionAnalysis,KorAPQuery-method. Explicit partitions must have the same base virtual corpus and KorAP instance.

scoreFunctions

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

exactFrequencies

If TRUE (default), request exact counts for each part, without downloading matches. If FALSE, collect match metadata, using at most searchHitsSampleLimit hits. No snippets are requested.

searchHitsSampleLimit

Maximum metadata sample size, default 20000. Inf requests all match metadata. Samples draw complete pages without replacement, so finite limits are rounded down to multiples of 50 and must be at least 50 unless all hits fit below the limit.

seed

Seed for page selection. The caller's random state is restored.

ql

Query language, passed to corpusQuery().

verbose

Whether to print progress.

cacheAs

Optional result file; see frequencyQuery().

by

Metadata field(s) for automatic grouping, default "source".

regex

Optional trailing-suffix grouping rule for automatic grouping.

vc

Base virtual corpus for automatic grouping. With explicit partitions, their base virtual corpus is used instead.

Details

A sample is a simple random sample of result pages, not independent hits. Every hit has the same page-inclusion probability. The returned distribution retains unobserved parts and reports observed and extrapolated hit counts. Ratios of these estimates provide plug-in estimates of dispersion; nonlinear measures can be strongly biased by within-page clustering, even with many sampled hits. Range from a sample is only a lower bound, not an estimate of the number of occupied parts. No confidence bounds are claimed. Missing or unlisted metadata are counted as excluded hits.

Partition sizes come from independent corpus statistics, never from the sample. Failed, incomplete or timed-out requests abort the analysis rather than becoming zeros. exactFrequencies = TRUE never falls back to sampling. Arbitrary parts require a membership classifier for metadata sampling. Reuse a partition only with its original base corpus, server and index revision.

Value

A tibble with one row per query and partition, the requested scores, totalResults (base-corpus hits), sampledHits (metadata rows analyzed), usedHits, excludedHits, nParts, estimated, rangeIsLowerBound, and list columns distribution and sampling. Distributions include corpus-part sizes, observed counts, estimated frequencies, relative frequencies and concordance URLs. sampling records the method, seed, selected pages, inclusion probability, server and index revision.

Examples

## Not run: 
kco <- KorAPConnection()
years <- corpusPartition(kco, "year", 2020:2022)
dispersionQuery(kco, "NutzerInnen", years, scoreFunctions = list(
  evenness = function(frequencies, sizes) 1 - dispersionDP(frequencies, sizes)
))
dispersionQuery(kco, "NutzerInnen", years, exactFrequencies = FALSE,
                searchHitsSampleLimit = 10000, seed = 7)

## End(Not run)

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