R/derekovecs.R

#' syntagmaticNeighbours
#'
#' Get the syntagmatic neighbours of a word from the predictive derekovecs model.
#' @param word The word to get the syntagmatic neighbours for.
#' @param ... Additional parameters to pass to the API.
#'
#' @return Data frame syntagmatic neighbours of a word from the predictive derekovecs model.
#' @export
syntagmaticNeighbours <- function(word = "Test", ...) {
  derekovecsApiCall("", word = word, json = 1, ...)$collocators
}

#' countbasedCollocates
#'
#' Get the collocates of a word in the count-based dereko model.
#'
#' @param w The word to get the collocates for.
#' @param ... Additional parameters to pass to the API.
#'
#' @return  A data fram with the most salient collcates and their association scores.
#' @export
countbasedCollocates <- function(w = "Test", ...) {
  derekovecsApiCall(method = "/getClassicCollocators", w = w, ...)$collocates
}

#' paradigmaticNeighbours
#'
#' Get the paradigmatic neighbours of a word in the derekovecs model.
#'
#' @param word  The word to get the paradigmatic neighbours for.
#' @param ... Additional parameters to pass to the API.
#' @return  A list of words with their similarity scores.
#' @export
#'
paradigmaticNeighbours <- function(word = "Test", ...) {
  derekovecsApiCall("", word = word, json = 1, ...)$list[[1]]
}

#' collocationScores
#'
#' Calculate the association scores between a node (target word) and words in a window around the it.
#'
#' @param w The target word/node.
#' @param c The collocate.
#' @param ... Additional parameters to pass to the API.
#'
#' @return  A one row data frame with collocate and its association scores.
#' @export
#'
collocationScores <- function(w, c, ...) {
  derekovecsApiCall("/getCollocationAssociation",
                 w = w, c = c, ...)$collocates
}

#' cosineSimilarity
#'
#' @param w1 The first word.
#' @param w2  The second word.
#' @param ... Additional parameters to pass to the API.
#'
#' @return The cosine similarity between the two words.
#' @export
#'
#' @description Calculate the cosine similarity between two words in the derekovecs model.
cosineSimilarity <- function(w1, w2, ...) {
  derekovecsApiCall("/getSimilarity", w1 = w1, w2 = w2, ...)
}

#' DeReKoVecsServer
#'
#' @return The URL of the DeReKoVecs API server.
#' @export
#'
derekovecsServer <- function() {
  api_server <- Sys.getenv("DEREKOVECS_SERVER")
  if (!identical(api_server, "")) {
    return(api_server)
  }
  'https://corpora.ids-mannheim.de/openlab/derekovecs/'
}

#' DeReKoVecsCall
#'
#' Call the DeReKoVecs API.
#'
#' @param method The method to call.
#' @param ... The parameters to pass to the method.
#' @return The result of the call.
#' @importFrom httr2 request req_url_path_append req_url_query req_perform resp_body_json
#'
#' @include utils-pipe.R
#'
derekovecsApiCall <- function(method = "", ...) {
  httr2::request(derekovecsServer()) %>%
    httr2::req_url_path_append(method) %>%
    httr2::req_url_query(...) %>%
    httr2::req_perform() %>%
    httr2::resp_body_json(simplifyVector = TRUE)
}