fetchSamplePages-KorAPQuery-method: Fetch a reproducible sample of result pages

fetchSamplePages,KorAPQuery-methodR Documentation

Fetch a reproducible sample of result pages

Description

Select complete result pages without replacement. This is a page (cluster) sample, not a simple random sample of individual hits. Hits within a selected page remain in Lucene index order. A single randomly selected page therefore does not provide independently sampled hits. If all results fit within the limit, all pages are fetched in index order and no sample is drawn.

Usage

## S4 method for signature 'KorAPQuery'
fetchSamplePages(
  kqo,
  maxHits = 2000,
  seed = 7,
  verbose = kqo@korapConnection@verbose,
  warn = TRUE
)

## S4 method for signature 'data.frame'
fetchSamplePages(kqo, maxHits = 2000, seed = 7, verbose = NULL, warn = TRUE)

Arguments

kqo

A corpusQuery() result, for one or several queries.

maxHits

Maximum hits to retrieve per query. Complete pages are used, so a finite limit is rounded down to a multiple of 50. At least 50 is required unless the complete result fits within maxHits. Inf fetches all results.

seed

Seed for choosing pages; the caller's random state is restored.

verbose

Whether to print progress.

warn

Emit the page-sampling warning, or an informational message if all hits are fetched. Defaults to TRUE; the procedure remains recorded in the result even when this is explicitly disabled.

Details

Unlike taking the first hits, pages are selected from the entire result set. If several pages are available, even one page can be selected at random. Within-page ordering and clustering remain; this distinction matters when interpreting estimates and uncertainty. The actual row count can be below maxHits, particularly when the last, shorter page is selected.

Call fetchAll() to replace a page sample with the complete result. A page sample is not a sequential prefix, so fetchNext() and fetchRest() cannot safely continue it. Call fetchSamplePages() again to draw a new sample.

Value

Updated query object(s), with hits in collectedMatches and page sampling provenance in the korapSampling attribute. dispersionAnalysis() uses this exact sample and its inclusion probability without drawing again. Single-valued metadata columns are atomic vectors, with NA for missing values; genuinely multivalued columns remain lists.

Examples

## Not run: 
KorAPConnection() |>
  corpusQuery("Gendern") |>
  fetchSamplePages(maxHits = 2000, seed = 7) |>
  dispersionAnalysis(by = "source")

## End(Not run)

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