dispersionAnalysis-KorAPQuery-method: Calculate dispersion directly from a corpus query

dispersionAnalysis,KorAPQuery-methodR Documentation

Calculate dispersion directly from a corpus query

Description

[Experimental]

Usage

## S4 method for signature 'KorAPQuery'
dispersionAnalysis(
  frequencies,
  by = "source",
  regex = NULL,
  scoreFunctions = defaultDispersionFunctions(),
  exactFrequencies = NULL,
  searchHitsSampleLimit = 20000,
  seed = 7,
  verbose = frequencies@korapConnection@verbose,
  cacheAs = NULL
)

## S4 method for signature 'data.frame'
dispersionAnalysis(
  frequencies,
  by = "source",
  regex = NULL,
  scoreFunctions = defaultDispersionFunctions(),
  exactFrequencies = NULL,
  searchHitsSampleLimit = 20000,
  seed = 7,
  verbose = NULL,
  cacheAs = NULL
)

Arguments

frequencies

A corpusQuery() result for one or several queries.

by

Metadata field or vector of fields. "source" groups DeReKo's annual corpusTitle values into sources automatically; "year" groups pubDate by publication year; "region" uses pubPlaceKey. Automatic grouping of pubDate and creationDate uses calendar-year groups.

regex

Optional regular expression removing a trailing suffix from metadata values, ending in $, e.g. " [0-9]{4}$". For by = "source" this is the default. For custom grouping, use a single field such as by = "corpusTitle". With multiple dimensions, use their default grouping.

scoreFunctions

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

exactFrequencies

By default (NULL), reuse an explicit page sample or complete, unjoined metadata containing the requested fields; otherwise request exact counts per group. TRUE requests exact counts even after a fetch. FALSE permits metadata sampling, controlled by searchHitsSampleLimit.

searchHitsSampleLimit

Maximum metadata sample size; see dispersionQuery().

seed

Seed for random page selection.

verbose

Whether to print progress.

cacheAs

Optional result file; see frequencyQuery().

Details

Ask a corpus question first, then choose the metadata dimension of its dispersion. The library discovers the groups and their sizes, including groups without query hits. No source lists or classification code are needed. The analysis interface and result structure may change in future releases.

An explicit fetchSamplePages() step makes the retrieval scope visible. Recorded pages are reused without drawing again; any missing metadata are retrieved from those same pages. Multiple queries share independently discovered groups and token sizes, seeded by the groups already observed across their fetched metadata. Printing their result shows one column per query variant, labelled by the names of the original query vector.

See the Interpretation section in dispersion-score-functions for what the measures describe, their directions and why they can disagree. Use distribution to examine source counts and token sizes alongside the scores.

by = "year" treats publication years as discrete corpus parts, using each year's token count as its size and retaining positive-sized years without query hits. The built-in measures ignore temporal order and distances; they describe dispersion across year groups, not a trend over time.

Use a metadata-only query (the default of corpusQuery()). A full-text query rewritten to a smaller licensed population is rejected, so that hit counts and corpus-part sizes cannot silently refer to different populations.

All metadata categories are discovered independently of the query hits. The current API does not offer a public distinct-values endpoint, so the library retrieves one representative text's metadata from each remaining group, excluding already known groups until none remain. It does not download the corpus. The resulting partition is cached per server, index revision, virtual corpus, metadata field and grouping rule when connection caching is enabled. Discovery and size queries can take time on the first call, especially for fields with many categories.

regex removes a suffix, rather than selecting which categories are included. It must have a corresponding corpus-query regex: use ordinary groups and character classes, without lookarounds. This makes the metadata grouping and the token denominators agree. Advanced arbitrary groupings remain available through corpusPartition() and dispersionQuery().

Value

A KorAPDispersion tibble. Printing it shows all requested scores. Detailed counts remain in distribution; sampling records whether the scores are estimated. The complete partitions are also retained as the partitions attribute. See dispersionQuery() for the other columns.

Examples

## Not run: 
kco <- KorAPConnection()
q <- corpusQuery(kco, "NutzerInnen", vc = "pubPlaceKey=AT & pubDate in 2022")
dispersionAnalysis(q, by = "source")
# The explicit metadata-field equivalent:
dispersionAnalysis(q, by = "corpusTitle", regex = " [0-9]{4}$")

## End(Not run)

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