R Client for KorAP Corpus Analysis Platform

Description

RKorAPClient provides programmatic access to KorAP corpus analysis platform instances, enabling corpus linguistic research on large corpora like DeReKo, CoRoLa, DeLiKo@DNB.

Main Functions

Connection

KorAPConnection(), auth(), persistAccessToken()

Search

corpusQuery(), fetchAll(), fetchNext()

Analysis

corpusStats(), frequencyQuery(), collocationAnalysis()

Quick Start

library(RKorAPClient)
# Connect and search
kcon <- KorAPConnection()
query <- corpusQuery(kcon, "Ameisenplage")
results <- fetchAll(query)

# Access results
results@collectedMatches
results@totalResults

Common Workflows

Basic Search:

kcon <- KorAPConnection()
kcon |> corpusQuery("search term") |> fetchAll()

Frequency Analysis:

frequencyQuery(kcon, c("term1", "term2"), vc="pubDate in 2020")

Corpus Statistics:

corpusStats(kcon, vc="textType=Zeitung", as.df=TRUE)

Author(s)

Maintainer: Marc Kupietz kupietz@ids-mannheim.de

Other contributors:

• Nils Diewald diewald@ids-mannheim.de [contributor]

• Leibniz Institute for the German Language [copyright holder, funder]

References

Kupietz, Marc / Diewald, Nils / Margaretha, Eliza (2020): RKorAPClient: An R package for accessing the German Reference Corpus DeReKo via KorAP. In: Calzolari, Nicoletta, Frédéric Béchet, Philippe Blache, Khalid Choukri, Christopher Cieri, Thierry Declerck, Sara Goggi, Hitoshi Isahara, Bente Maegaard, Joseph Mariani, Hélène Mazo, Asuncion Moreno, Jan Odijk, Stelios Piperidis (eds.): Proceedings of The 12th Language Resources and Evaluation Conference (LREC 2020) Marseille: European Language Resources Association (ELRA), 7017-7023. http://www.lrec-conf.org/proceedings/lrec2020/pdf/2020.lrec-1.867.pdf

See Also

Useful links:

• https://github.com/KorAP/RKorAPClient/

• https://korap.ids-mannheim.de/

• https://www.ids-mannheim.de/digspra/kl/projekte/korap

• Report bugs at https://github.com/KorAP/RKorAPClient/issues

Connect to KorAP Server

Description

KorAPConnection() creates a connection to a KorAP server for corpus queries. This is your starting point for all corpus analysis tasks.

Arguments

kco <- KorAPConnection(accessToken="<access token>")

persistAccessToken(kco)

Details

Use KorAPConnection() to connect, then corpusQuery() to search, and fetchAll() to retrieve results. For authorized access to restricted corpora, use auth() or provide an accessToken.

The KorAPConnection object contains various configuration slots for advanced users: KorAPUrl (server URL), apiVersion, accessToken (OAuth2 token), timeout (request timeout), verbose (logging), cache (local caching), and other technical parameters. Most users can ignore these implementation details.

Value

KorAPConnection() object that can be used e.g. with corpusQuery()

Basic Workflow

# Connect to KorAP
kcon <- KorAPConnection()

# Search for a term
query <- corpusQuery(kcon, "Ameisenplage")

# Get all results
results <- fetchAll(query)

Authorization

For access to restricted corpora, authorize your connection:

kcon <- KorAPConnection() |> auth()

See Also

Other initialization functions: auth,KorAPConnection-method, clearAccessToken,KorAPConnection-method, persistAccessToken,KorAPConnection-method

KorAPCorpusStats class (internal)

Description

Internal class for corpus statistics storage. Users work with corpusStats() function instead.

Usage

## S4 method for signature 'KorAPCorpusStats'
show(object)

Arguments

KorAPQuery class (internal)

Description

Internal class for query state management. Users work with corpusQuery(), fetchAll(), and fetchNext() instead.

Usage

buildWebUIRequestUrlFromString(KorAPUrl, query, vc = "", ql = "poliqarp")

buildWebUIRequestUrl(
  kco,
  query = if (missing(KorAPUrl)) {
    
    stop("At least one of the parameters query and KorAPUrl must be specified.", call. =
    FALSE)
 } else {
     httr2::url_parse(KorAPUrl)$query$q
 },
  vc = if (missing(KorAPUrl)) "" else httr2::url_parse(KorAPUrl)$query$cq,
  KorAPUrl,
  ql = if (missing(KorAPUrl)) "poliqarp" else httr2::url_parse(KorAPUrl)$query$ql
)

## S3 method for class 'KorAPQuery'
format(x, ...)

## S4 method for signature 'KorAPQuery'
show(object)

Arguments

Internal API call method

Description

Internal API call method

Usage

## S4 method for signature 'KorAPConnection'
apiCall(
  kco,
  url,
  json = TRUE,
  getHeaders = FALSE,
  cache = kco@cache,
  timeout = kco@timeout
)

Arguments

Association score functions

Description

Functions to calculate different collocation association scores between a node (target word) and words in a window around the it. The functions are primarily used by collocationScoreQuery().

pmi: pointwise mutual information

mi2: pointwise mutual information squared (Daille 1994), also referred to as mutual dependency (Thanopoulos et al. 2002)

mi3: pointwise mutual information cubed (Daille 1994), also referred to as log-frequency biased mutual dependency) (Thanopoulos et al. 2002)

logDice: log-Dice coefficient, a heuristic measure that is popular in lexicography (Rychlý 2008)

ll: log-likelihood (Dunning 1993) using Stefan Evert's (2004) simplified implementation

Usage

defaultAssociationScoreFunctions()

pmi(O1, O2, O, N, E, window_size)

mi2(O1, O2, O, N, E, window_size)

mi3(O1, O2, O, N, E, window_size)

logDice(O1, O2, O, N, E, window_size)

ll(O1, O2, O, N, E, window_size)

Arguments

Value

         association score

References

Daille, B. (1994): Approche mixte pour l’extraction automatique de terminologie: statistiques lexicales et filtres linguistiques. PhD thesis, Université Paris 7.

Thanopoulos, A., Fakotakis, N., Kokkinakis, G. (2002): Comparative evaluation of collocation extraction metrics. In: Proc. of LREC 2002: 620–625.

Rychlý, Pavel (2008): A lexicographer-friendly association score. In Proceedings of Recent Advances in Slavonic Natural Language Processing, RASLAN, 6–9. https://www.fi.muni.cz/usr/sojka/download/raslan2008/13.pdf.

Dunning, T. (1993): Accurate methods for the statistics of surprise and coincidence. Comput. Linguist. 19, 1 (March 1993), 61-74.

Evert, Stefan (2004): The Statistics of Word Cooccurrences: Word Pairs and Collocations. PhD dissertation, IMS, University of Stuttgart. Published in 2005, URN urn:nbn:de:bsz:93-opus-23714. Free PDF available from https://purl.org/stefan.evert/PUB/Evert2004phd.pdf

See Also

Other collocation analysis functions: collocationAnalysis,KorAPConnection-method, collocationScoreQuery,KorAPConnection-method, synsemanticStopwords()

Examples

## Not run: 

KorAPConnection(verbose = TRUE) %>%
collocationScoreQuery("Perlen", c("verziertes", "Säue"),
  scoreFunctions = append(defaultAssociationScoreFunctions(),
     list(localMI = function(O1, O2, O, N, E, window_size) {
                       O * log2(O/E)
                    })))

## End(Not run)

Authorize RKorAPClient

Description

Authorize RKorAPClient to make KorAP queries and download results on behalf of the user.

Usage

## S4 method for signature 'KorAPConnection'
auth(
  kco,
  app_id = generic_kor_app_id,
  app_secret = NULL,
  scope = kco@oauthScope
)

Arguments

Value

KorAPConnection object with access token set in ⁠@accessToken⁠.

See Also

persistAccessToken(), clearAccessToken()

Other initialization functions: KorAPConnection-class, clearAccessToken,KorAPConnection-method, persistAccessToken,KorAPConnection-method

Examples

## Not run: 
kco <- KorAPConnection(verbose = TRUE) %>% auth()
df <- collocationAnalysis(kco, "focus([marmot/p=ADJA] {Ameisenplage})",
  leftContextSize = 1, rightContextSize = 0
)

## End(Not run)

Calculate and format ETA for batch operations

Description

Helper function to calculate estimated time of arrival based on elapsed time and progress through a batch operation.

Usage

calculate_eta(current_item, total_items, start_time)

Arguments

Value

character string with formatted ETA and completion time or empty string if not calculable

Calculate sophisticated ETA using median of recent non-cached times

Description

Advanced ETA calculation that excludes cached responses and uses median of recent timing data for more stable estimates. This is particularly useful for operations where some responses may be cached and much faster.

Usage

calculate_sophisticated_eta(
  individual_times,
  current_item,
  total_items,
  cache_threshold = 0.1,
  window_size = 5
)

Arguments

Value

list with eta_seconds, estimated_completion_time, and is_cached flag

Add confidence interval and relative frequency variables

Description

Using prop.test(), ci adds three columns to a data frame:

1. relative frequency (f)

2. lower bound of a confidence interval (ci.low)

3. upper bound of a confidence interval

Convenience function for converting frequency tables to instances per million.

Convenience function for converting frequency tables of alternative variants (generated with as.alternatives=TRUE) to percent.

Converts a vector of query or vc strings to typically appropriate legend labels by clipping off prefixes and suffixes that are common to all query strings.

Experimental convenience function for plotting typical frequency by year graphs with confidence intervals using ggplot2. Warning: This function may be moved to a new package.

Usage

ci(df, x = totalResults, N = total, conf.level = 0.95)

ipm(df)

percent(df)

queryStringToLabel(data, pubDateOnly = FALSE, excludePubDate = FALSE)

geom_freq_by_year_ci(mapping = aes(ymin = conf.low, ymax = conf.high), ...)

Arguments

Details

Given a table with columns f, conf.low, and conf.high, ipm ads a ⁠column ipm⁠ und multiplies conf.low and conf.high with 10^6.

Value

original table with additional column ipm and converted columns conf.low and conf.high

original table with converted columns f, conf.low and conf.high

string or vector of strings with clipped off common prefixes and suffixes

See Also

ci is already included in frequencyQuery()

Examples

## Not run: 

library(ggplot2)
kco <- KorAPConnection(verbose=TRUE)
expand_grid(year=2015:2018, alternatives=c("Hate Speech", "Hatespeech")) %>%
  bind_cols(corpusQuery(kco, .$alternatives, sprintf("pubDate in %d", .$year))) %>%
  mutate(total=corpusStats(kco, vc=vc)$tokens) %>%
  ci() %>%
  ggplot(aes(x=year, y=f, fill=query, color=query, ymin=conf.low, ymax=conf.high)) +
    geom_point() + geom_line() + geom_ribbon(alpha=.3)

## End(Not run)
## Not run: 

KorAPConnection() %>% frequencyQuery("Test", paste0("pubDate in ", 2000:2002)) %>% ipm()

## End(Not run)
## Not run: 

KorAPConnection() %>%
    frequencyQuery(c("Tollpatsch", "Tolpatsch"),
    vc=paste0("pubDate in ", 2000:2002),
    as.alternatives = TRUE) %>%
  percent()

## End(Not run)
queryStringToLabel(paste("textType = /Zeit.*/ & pubDate in", c(2010:2019)))
queryStringToLabel(c("[marmot/m=mood:subj]", "[marmot/m=mood:ind]"))
queryStringToLabel(c("wegen dem [tt/p=NN]", "wegen des [tt/p=NN]"))

## Not run: 
library(ggplot2)
kco <- KorAPConnection(verbose=TRUE)

expand_grid(condition = c("textDomain = /Wirtschaft.*/", "textDomain != /Wirtschaft.*/"),
            year = (2005:2011)) %>%
  cbind(frequencyQuery(kco, "[tt/l=Heuschrecke]",
                            paste0(.$condition," & pubDate in ", .$year)))  %>%
  ipm() %>%
  ggplot(aes(year, ipm, fill = condition, color = condition)) +
  geom_freq_by_year_ci()

## End(Not run)

Clear access token from keyring and KorAPConnection object

Description

Clear access token from keyring and KorAPConnection object

Usage

## S4 method for signature 'KorAPConnection'
clearAccessToken(kco)

Arguments

Value

KorAPConnection object with access token set to NULL.

See Also

persistAccessToken()

Other initialization functions: KorAPConnection-class, auth,KorAPConnection-method, persistAccessToken,KorAPConnection-method

Examples

## Not run: 
kco <- KorAPConnection()
kco <- clearAccessToken(kco)

## End(Not run)

Clear local cache

Description

Clears the local cache of API responses for the current RKorAPClient version. Useful when you want to force fresh data retrieval or free up disk space.

Usage

## S4 method for signature 'KorAPConnection'
clearCache(kco)

Arguments

Value

Invisible NULL (function called for side effects)

Examples

## Not run: 
kco <- KorAPConnection()
clearCache(kco)

## End(Not run)

Collocation analysis

Description

Performs a collocation analysis for the given node (or query) in the given virtual corpus.

Usage

## S4 method for signature 'KorAPConnection'
collocationAnalysis(
  kco,
  node,
  vc = "",
  lemmatizeNodeQuery = FALSE,
  minOccur = 5,
  leftContextSize = 5,
  rightContextSize = 5,
  topCollocatesLimit = 200,
  searchHitsSampleLimit = 20000,
  ignoreCollocateCase = FALSE,
  withinSpan = ifelse(exactFrequencies, "base/s=s", ""),
  exactFrequencies = TRUE,
  stopwords = append(RKorAPClient::synsemanticStopwords(), node),
  seed = 7,
  expand = length(vc) != length(node),
  maxRecurse = 0,
  addExamples = FALSE,
  thresholdScore = "logDice",
  threshold = 2,
  localStopwords = c(),
  collocateFilterRegex = "^[:alnum:]+-?[:alnum:]*$",
  ...
)

Arguments

Details

The collocation analysis is currently implemented on the client side, as some of the functionality is not yet provided by the KorAP backend. Mainly for this reason it is very slow (several minutes, up to hours), but on the other hand very flexible. You can, for example, perform the analysis in arbitrary virtual corpora, use complex node queries, and look for expression-internal collocates using the focus function (see examples and demo).

To increase speed at the cost of accuracy and possible false negatives, you can decrease searchHitsSampleLimit and/or topCollocatesLimit and/or set exactFrequencies to FALSE.

Note that some outdated non-DeReKo back-ends might not yet support returning tokenized matches (warning issued). In this case, the client library will fall back to client-side tokenization which might be slightly less accurate. This might lead to false negatives and to frequencies that differ from corresponding ones acquired via the web user interface.

Value

Tibble with top collocates, association scores, corresponding URLs for web user interface queries, etc.

See Also

Other collocation analysis functions: association-score-functions, collocationScoreQuery,KorAPConnection-method, synsemanticStopwords()

Examples

## Not run: 

# Find top collocates of "Packung" inside and outside the sports domain.
KorAPConnection(verbose = TRUE) |>
  collocationAnalysis("Packung",
    vc = c("textClass=sport", "textClass!=sport"),
    leftContextSize = 1, rightContextSize = 1, topCollocatesLimit = 20
  ) |>
  dplyr::filter(logDice >= 5)

## End(Not run)

## Not run: 

# Identify the most prominent light verb construction with "in ... setzen".
# Note that, currently, the use of focus function disallows exactFrequencies.
KorAPConnection(verbose = TRUE) |>
  collocationAnalysis("focus(in [tt/p=NN] {[tt/l=setzen]})",
    leftContextSize = 1, rightContextSize = 0, exactFrequencies = FALSE, topCollocatesLimit = 20
  )

## End(Not run)

Query frequencies of a node and a collocate and calculate collocation association scores

Description

Computes various collocation association scores based on frequencyQuery()s for a target word and a collocate.

Usage

## S4 method for signature 'KorAPConnection'
collocationScoreQuery(
  kco,
  node,
  collocate,
  vc = "",
  lemmatizeNodeQuery = FALSE,
  lemmatizeCollocateQuery = FALSE,
  leftContextSize = 5,
  rightContextSize = 5,
  scoreFunctions = defaultAssociationScoreFunctions(),
  smoothingConstant = 0.5,
  observed = NA,
  ignoreCollocateCase = FALSE,
  withinSpan = "base/s=s"
)

Arguments

Value

tibble with query KorAP web request URL, all observed values and association scores

See Also

Other collocation analysis functions: association-score-functions, collocationAnalysis,KorAPConnection-method, synsemanticStopwords()

Examples

## Not run: 

KorAPConnection(verbose = TRUE) |>
  collocationScoreQuery("Grund", "triftiger")

## End(Not run)

## Not run: 

KorAPConnection(verbose = TRUE) |>
collocationScoreQuery("Grund", c("guter", "triftiger"),
   scoreFunctions = list(localMI = function(O1, O2, O, N, E, window_size) { O * log2(O/E) }) )

## End(Not run)

## Not run: 

library(highcharter)
library(tidyr)
KorAPConnection(verbose = TRUE) |>
  collocationScoreQuery("Team", "agil", vc = paste("pubDate in", c(2014:2018)),
                        lemmatizeNodeQuery = TRUE, lemmatizeCollocateQuery = TRUE) |>
                         pivot_longer(14:last_col(), names_to = "measure", values_to = "score") |>
  hchart(type="spline", hcaes(label, score, group=measure)) |>
  hc_add_onclick_korap_search()

## End(Not run)

Search corpus for query terms

Description

corpusQuery performs a corpus query via a connection to a KorAP-API-server

Usage

## S4 method for signature 'KorAPConnection'
corpusQuery(
  kco,
  query = if (missing(KorAPUrl)) {
    
    stop("At least one of the parameters query and KorAPUrl must be specified.", call. =
    FALSE)
 } else {
     httr2::url_parse(KorAPUrl)$query$q
 },
  vc = if (missing(KorAPUrl)) "" else httr2::url_parse(KorAPUrl)$query$cq,
  KorAPUrl,
  metadataOnly = TRUE,
  ql = if (missing(KorAPUrl)) "poliqarp" else httr2::url_parse(KorAPUrl)$query$ql,
  fields = c("corpusSigle", "textSigle", "pubDate", "pubPlace", "availability",
    "textClass", "snippet", "tokens"),
  accessRewriteFatal = TRUE,
  verbose = kco@verbose,
  expand = length(vc) != length(query),
  as.df = FALSE,
  context = NULL
)

Arguments

Value

Depending on the as.df parameter, a tibble or a KorAPQuery() object that, among other information, contains the total number of results in ⁠@totalResults⁠. The resulting object can be used to fetch all query results (with fetchAll()) or the next page of results (with fetchNext()). A corresponding URL to be used within a web browser is contained in ⁠@webUIRequestUrl⁠ Please make sure to check ⁠$collection$rewrites⁠ to see if any unforeseen access rewrites of the query's virtual corpus had to be performed.

References

https://ids-pub.bsz-bw.de/frontdoor/index/index/docId/9026

See Also

KorAPConnection(), fetchNext(), fetchRest(), fetchAll(), corpusStats()

Other corpus search functions: fetchAll,KorAPQuery-method, fetchNext,KorAPQuery-method

Examples

## Not run: 

# Fetch basic metadata for "Ameisenplage"
KorAPConnection() |>
  corpusQuery("Ameisenplage") |>
  fetchAll()

# Fetch specific metadata fields for bibliographic analysis
query <- KorAPConnection() |>
  corpusQuery("Ameisenplage",
              fields = c("textSigle", "author", "title", "pubDate", "pubPlace", "textType"))
results <- fetchAll(query)
results@collectedMatches

## End(Not run)

## Not run: 

# Use the copy of a KorAP-web-frontend URL for an API query of "Ameise" in a virtual corpus
# and show the number of query hits (but don't fetch them).

KorAPConnection(verbose = TRUE) |>
  corpusQuery(
    KorAPUrl =
      "https://korap.ids-mannheim.de/?q=Ameise&cq=pubDate+since+2017&ql=poliqarp"
  )

## End(Not run)

## Not run: 

# Plot the time/frequency curve of "Ameisenplage"
KorAPConnection(verbose = TRUE) |>
  {
    . ->> kco
  } |>
  corpusQuery("Ameisenplage") |>
  fetchAll() |>
  slot("collectedMatches") |>
  mutate(year = lubridate::year(pubDate)) |>
  dplyr::select(year) |>
  group_by(year) |>
  summarise(Count = dplyr::n()) |>
  mutate(Freq = mapply(function(f, y) {
    f / corpusStats(kco, paste("pubDate in", y))@tokens
  }, Count, year)) |>
  dplyr::select(-Count) |>
  complete(year = min(year):max(year), fill = list(Freq = 0)) |>
  plot(type = "l")

## End(Not run)

Get corpus size and statistics

Description

Retrieve information about corpus size (documents, tokens, sentences, paragraphs) for the entire corpus or a virtual corpus subset.

Usage

## S4 method for signature 'KorAPConnection'
corpusStats(kco, vc = "", verbose = kco@verbose, as.df = FALSE)

Arguments

Value

Object containing corpus statistics with the following information:

vc

Virtual corpus definition used (empty string for entire corpus)

documents

Total number of documents in the (virtual) corpus

tokens

Total number of word tokens in the (virtual) corpus

sentences

Total number of sentences in the (virtual) corpus

paragraphs

Total number of paragraphs in the (virtual) corpus

webUIRequestUrl

URL to view this corpus subset in KorAP web interface

When as.df=TRUE, returns a data frame with these columns. When as.df=FALSE (default), returns a KorAPCorpusStats object with these values as slots.

Usage

# Get statistics for entire corpus
kcon <- KorAPConnection()
stats <- corpusStats(kcon)

# Get statistics for a specific time period
stats <- corpusStats(kcon, "pubDate in 2020")

# Access the number of tokens
stats@tokens

Examples

## Not run: 

kco <- KorAPConnection()

# Get statistics for entire corpus (returns S4 object)
stats <- corpusStats(kco)
stats@tokens  # Access number of tokens

# Get statistics for newspaper texts from 2017 (as data frame)
df <- corpusStats(kco, "pubDate in 2017 & textType=/Zeitung.*/", as.df = TRUE)
df$documents  # Access number of documents

# Compare corpus sizes across years
years <- 2015:2020
sizes <- sapply(years, function(y) {
  corpusStats(kco, paste("pubDate in", y))@tokens
})

## End(Not run)

Fetch all results of a KorAP query.

Description

fetchAll fetches all results of a KorAP query.

Usage

## S4 method for signature 'KorAPQuery'
fetchAll(kqo, verbose = kqo@korapConnection@verbose, ...)

Arguments

Value

The updated kqo object with all results in ⁠@collectedMatches⁠

See Also

Other corpus search functions: corpusQuery,KorAPConnection-method, fetchNext,KorAPQuery-method

Examples

## Not run: 
# Fetch all metadata of every query hit for "Ameisenplage" and show a summary
q <- KorAPConnection() |>
  corpusQuery("Ameisenplage") |>
  fetchAll()
q@collectedMatches

# Fetch also all KWICs
q <- KorAPConnection() |> auth() |>
 corpusQuery("Ameisenplage", metadataOnly = FALSE) |>
 fetchAll()
q@collectedMatches

# Retrieve title and text sigle metadata of all texts published on 1958-03-12
q <- KorAPConnection() |>
 corpusQuery("<base/s=t>", # this matches each text once
    vc = "pubDate in 1958-03-12",
    fields = c("textSigle", "title"),
) |>
 fetchAll()
q@collectedMatches

## End(Not run)

Fetch the next bunch of results of a KorAP query.

Description

fetchNext fetches the next bunch of results of a KorAP query.

Usage

## S4 method for signature 'KorAPQuery'
fetchNext(
  kqo,
  offset = kqo@nextStartIndex,
  maxFetch = maxResultsPerPage,
  verbose = kqo@korapConnection@verbose,
  randomizePageOrder = FALSE
)

Arguments

Value

The kqo input object with updated slots collectedMatches, apiResponse, nextStartIndex, hasMoreMatches

References

https://ids-pub.bsz-bw.de/frontdoor/index/index/docId/9026

See Also

Other corpus search functions: corpusQuery,KorAPConnection-method, fetchAll,KorAPQuery-method

Examples

## Not run: 

q <- KorAPConnection() |>
  corpusQuery("Ameisenplage") |>
  fetchNext()
q@collectedMatches

## End(Not run)

Fetches the remaining results of a KorAP query.

Description

Fetches the remaining results of a KorAP query.

Usage

## S4 method for signature 'KorAPQuery'
fetchRest(kqo, verbose = kqo@korapConnection@verbose, ...)

Arguments

Value

The updated kqo object with remaining results in ⁠@collectedMatches⁠

Examples

## Not run: 

q <- KorAPConnection() |>
  corpusQuery("Ameisenplage") |>
  fetchRest()
q@collectedMatches

## End(Not run)

Format duration in seconds to human-readable format

Description

Converts a duration in seconds to a formatted string with days, hours, minutes, and seconds. Used for ETA calculations and progress reporting.

Usage

format_duration(seconds)

Arguments

Value

character string with formatted duration

Examples

## Not run: 
format_duration(3661) # "01h 01m 01s"
format_duration(86461) # "1d 00h 01m 01s"

## End(Not run)

Format ETA information for display

Description

Helper function to format ETA information consistently across different methods.

Usage

format_eta_display(eta_seconds, estimated_completion_time)

Arguments

Value

character string with formatted ETA or empty string if NA

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 ore 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,
  ...
)

Arguments

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.

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

• vc: virtual corpus used for the query.

• 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.

Examples

## Not run: 

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

## End(Not run)

Get cache indicator string

Description

Helper function to generate cache indicator for logging.

Usage

get_cache_indicator(is_cached, cache_threshold = 0.1)

Arguments

Value

character string with cache indicator or empty string

Add KorAP search click events to highchart plots

Description

Adds on-click events to data points of highcharts that were constructed with frequencyQuery() or collocationScoreQuery(). Clicks on data points then launch KorAP web UI queries for the given query term and virtual corpus in a separate tab.

Usage

hc_add_onclick_korap_search(hc)

Arguments

Value

The input highchart object with added on-click events.

See Also

Other highcharter-helpers: hc_freq_by_year_ci()

Examples

## Not run: 

library(highcharter)
library(tidyr)

KorAPConnection(verbose = TRUE) %>%
  collocationScoreQuery("Team", "agil", vc = paste("pubDate in", c(2014:2018)),
                        lemmatizeNodeQuery = TRUE, lemmatizeCollocateQuery = TRUE) %>%
                         pivot_longer(c("O", "E")) %>%
  hchart(type="spline", hcaes(label, value, group=name)) %>%
  hc_add_onclick_korap_search()

## End(Not run)

Plot interactive frequency curves with confidence intervals

Description

Convenience function for plotting typical frequency by year graphs with confidence intervals using highcharter.

Warning: This function may be moved to a new package.

Usage

hc_freq_by_year_ci(
  df,
  as.alternatives = FALSE,
  ylabel = if (as.alternatives) "%" else "ipm",
  smooth = FALSE,
  ...
)

Arguments

Value

A highchart htmlwidget object containing the frequency plot.

See Also

Other highcharter-helpers: hc_add_onclick_korap_search()

Examples

## Not run: 

year <- c(1990:2018)
alternatives <- c("macht []{0,3} Sinn", "ergibt []{0,3} Sinn")
KorAPConnection(verbose = TRUE) %>%
  frequencyQuery(query = alternatives,
                 vc = paste("textType = /Zeit.*/ & pubDate in", year),
                 as.alternatives = TRUE) %>%
  hc_freq_by_year_ci(as.alternatives = TRUE)


kco <- KorAPConnection(verbose = TRUE)
expand_grid(
  condition = c("textDomain = /Wirtschaft.*/", "textDomain != /Wirtschaft.*/"),
  year = (2005:2011)
) %>%
  cbind(frequencyQuery(
    kco,
    "[tt/l=Heuschrecke]",
    paste0(.$condition, " & pubDate in ", .$year)
  ))  %>%
  hc_freq_by_year_ci()

## End(Not run)

Initialize KorAPConnection object

Description

Initialize KorAPConnection object

Usage

## S4 method for signature 'KorAPConnection'
initialize(
  .Object,
  KorAPUrl = if (is.null(Sys.getenv("KORAP_URL")) | Sys.getenv("KORAP_URL") == "") {
    
    "https://korap.ids-mannheim.de/"
 } else {
     Sys.getenv("KORAP_URL")
 },
  apiVersion = "v1.0",
  apiUrl,
  accessToken = getAccessToken(KorAPUrl),
  oauthClient = NULL,
  oauthScope = "search match_info",
  authorizationSupported = TRUE,
  userAgent = "R-KorAP-Client",
  timeout = 240,
  verbose = FALSE,
  cache = TRUE
)

Initialize KorAPQuery object

Description

Initialize KorAPQuery object

Usage

## S4 method for signature 'KorAPQuery'
initialize(
  .Object,
  korapConnection = NULL,
  request = NULL,
  vc = "",
  totalResults = 0,
  nextStartIndex = 0,
  fields = c("corpusSigle", "textSigle", "pubDate", "pubPlace", "availability",
    "textClass", "snippet", "tokens"),
  requestUrl = "",
  webUIRequestUrl = "",
  apiResponse = NULL,
  hasMoreMatches = FALSE,
  collectedMatches = NULL
)

Arguments

Logging utilities for RKorAPClient

Description

This module provides centralized logging functions used throughout the package for progress reporting and ETA calculations. Log informational messages with optional coloring

Usage

log_info(v, ...)

Arguments

Merge duplicate collocate rows and re-calculate association scores and URLs. Useful if collocation analyses were performed separately for collocates on the left and right side of a node.

Description

Merge duplicate collocate rows and re-calculate association scores and URLs. Useful if collocation analyses were performed separately for collocates on the left and right side of a node.

Usage

mergeDuplicateCollocates(..., smoothingConstant = 0.5)

Arguments

Value

tibble with unique collocate rows

Persist current access token in keyring

Description

Persist current access token in keyring

Usage

## S4 method for signature 'KorAPConnection'
persistAccessToken(kco, accessToken = kco@accessToken)

Arguments

Value

KorAPConnection object.

See Also

clearAccessToken(), auth()

Other initialization functions: KorAPConnection-class, auth,KorAPConnection-method, clearAccessToken,KorAPConnection-method

Examples

## Not run: 
kco <- KorAPConnection(accessToken = "e739u6eOzkwADQPdVChxFg")
persistAccessToken(kco)

kco <- KorAPConnection() %>%
  auth(app_id = "<my application id>") %>%
  persistAccessToken()

## End(Not run)

Objects exported from other packages

Description

These objects are imported from other packages. Follow the links below to see their documentation.

broom

tidy

dplyr

bind_cols, group_by, mutate, n, select, summarise

lubridate

year

magrittr

%>%

tibble

as_tibble

tidyr

complete, expand_grid

Display KorAPConnection object

Description

Display KorAPConnection object

Usage

## S4 method for signature 'KorAPConnection'
show(object)

Arguments

Preliminary synsemantic stopwords function

Description

Preliminary synsemantic stopwords function to be used in collocation analysis.

Usage

synsemanticStopwords(...)

Arguments

Details

Currently only suitable for German. See stopwords package for other languages.

Value

Vector of synsemantic stopwords.

See Also

Other collocation analysis functions: association-score-functions, collocationAnalysis,KorAPConnection-method, collocationScoreQuery,KorAPConnection-method

Retrieve metadata for a text, identified by its sigle (id)

Description

Retrieves metadata for a text, identified by its sigle (id) using the corresponding KorAP API (see Kustvakt Wiki). To retrieve the metadata for every text in a virtual corpus, use corpusQuery() with ⁠<base/s=t>⁠ as query, instead.

Usage

## S4 method for signature 'KorAPConnection'
textMetadata(kco, textSigle, verbose = kco@verbose)

Arguments

Value

Tibble with columns for each metadata property. In case of errors, such as non-existing texts/sigles, the tibble will also contain a column called errors. If there are metadata columns you cannot make sense of, please ignore them. The function simply returns all the metadata it gets from the server.

Examples

## Not run: 
KorAPConnection() |> textMetadata(c("WUD17/A97/08542", "WUD17/B96/57558", "WUD17/A97/08541"))

## End(Not run)