First working package
Change-Id: I7f011864775a0486d6dd985b93e4473574956fa7
diff --git a/.Rbuildignore b/.Rbuildignore
index 91114bf..21ae968 100644
--- a/.Rbuildignore
+++ b/.Rbuildignore
@@ -1,2 +1,5 @@
^.*\.Rproj$
^\.Rproj\.user$
+LICENSE.md
+Readme.md
+Changelog.md
diff --git a/DESCRIPTION b/DESCRIPTION
index 8c28566..14ed37f 100644
--- a/DESCRIPTION
+++ b/DESCRIPTION
@@ -1,11 +1,29 @@
Package: rderekovecs
Type: Package
-Title: What the Package Does (Title Case)
+Title: DeReKoVecs API Client Package
Version: 0.1.0
-Author: Who wrote it
-Maintainer: The package maintainer <yourself@somewhere.net>
-Description: More about what it does (maybe more than one line)
- Use four spaces when indenting paragraphs within the Description.
-License: What license is it under?
+Authors@R:
+ c(person(given = "Marc",
+ family = "Kupietz",
+ role = c("aut", "cre"),
+ email = "kupietz@ids-mannheim.de"))
+Description: A client package that makes the 'DeReKoVecs'
+ web service API accessible from R.
+Depends: R (>= 3.5.0)
+Language: en-US
+License: BSD_2_clause + file LICENSE
+URL: https://korap.ids-mannheim.de/gerrit/plugins/gitiles/ids-kl/derekovecs,
+ https://corpora.ids-mannheim.de/openlab/derekovecs
Encoding: UTF-8
LazyData: true
+RoxygenNote: 7.2.3
+Imports:
+ httr2,
+ magrittr
+Suggests:
+ lifecycle,
+ testthat
+Collate:
+ 'utils-pipe.R'
+ 'derekovecs.R'
+Roxygen: list(markdown = TRUE)
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..fbcd1f2
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,2 @@
+YEAR: 2023
+COPYRIGHT HOLDER: Leibniz Institute for the German Language
diff --git a/LICENSE.md b/LICENSE.md
new file mode 100644
index 0000000..357eee7
--- /dev/null
+++ b/LICENSE.md
@@ -0,0 +1,25 @@
+# BSD-2-Clause License
+
+Copyright (c) 2020 Leibniz Institute for the German Language
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+ this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+ this list of conditions and the following disclaimer in the documentation
+ and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
+GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
+DAMAGE.
diff --git a/NAMESPACE b/NAMESPACE
index d75f824..0ac2973 100644
--- a/NAMESPACE
+++ b/NAMESPACE
@@ -1 +1,15 @@
-exportPattern("^[[:alpha:]]+")
+# Generated by roxygen2: do not edit by hand
+
+export("%>%")
+export(collocationScores)
+export(cosineSimilarity)
+export(countbasedCollocates)
+export(derekovecsServer)
+export(paradigmaticNeighbours)
+export(syntagmaticNeighbours)
+importFrom(httr2,req_perform)
+importFrom(httr2,req_url_path_append)
+importFrom(httr2,req_url_query)
+importFrom(httr2,request)
+importFrom(httr2,resp_body_json)
+importFrom(magrittr,"%>%")
diff --git a/R/derekovecs.R b/R/derekovecs.R
index 24b6d89..2b0d492 100644
--- a/R/derekovecs.R
+++ b/R/derekovecs.R
@@ -1,32 +1,99 @@
-library(httr2)
-library(tidyverse)
-
-derekovecs_server = 'https://corpora.ids-mannheim.de/openlab/derekovecs/'
-
-DeReKoVecsCall <- function(method="", ...) {
- request(derekovecs_server) %>%
- req_url_path_append(method) %>%
- req_url_query(...) %>%
- req_perform() %>%
- resp_body_json(simplifyVector = TRUE)
-}
-
+#' 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", ...) {
- DeReKoVecsCall("", word=word, json=1, ...)$collocators
+ 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", ...) {
- DeReKoVecsCall(method = "/getClassicCollocators", w = w, ...)$collocates
+ 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", ...) {
- DeReKoVecsCall("", word=word, json=1, ...)$list[[1]]
+ 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, ...) {
- DeReKoVecsCall("/getCollocationAssociation", w=w, c=c, ...)$collocates
+ 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, ...) {
- DeReKoVecsCall("/getSimilarity", w1=w1, w2=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)
}
diff --git a/R/utils-pipe.R b/R/utils-pipe.R
new file mode 100644
index 0000000..fd0b1d1
--- /dev/null
+++ b/R/utils-pipe.R
@@ -0,0 +1,14 @@
+#' Pipe operator
+#'
+#' See \code{magrittr::\link[magrittr:pipe]{\%>\%}} for details.
+#'
+#' @name %>%
+#' @rdname pipe
+#' @keywords internal
+#' @export
+#' @importFrom magrittr %>%
+#' @usage lhs \%>\% rhs
+#' @param lhs A value or the magrittr placeholder.
+#' @param rhs A function call using the magrittr semantics.
+#' @return The result of calling `rhs(lhs)`.
+NULL
diff --git a/Readme.md b/Readme.md
new file mode 100644
index 0000000..9b08f58
--- /dev/null
+++ b/Readme.md
@@ -0,0 +1,9 @@
+# rderekovecs
+
+A client package that makes the DeReKoVecs web service API accessible from R.
+
+## Installation
+
+```bash
+devtools::install_git("https://korap.ids-mannheim.de/gerrit/IDS-Mannheim/rderekovecs")
+```
diff --git a/man/collocationScores.Rd b/man/collocationScores.Rd
new file mode 100644
index 0000000..b206e18
--- /dev/null
+++ b/man/collocationScores.Rd
@@ -0,0 +1,21 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/derekovecs.R
+\name{collocationScores}
+\alias{collocationScores}
+\title{collocationScores}
+\usage{
+collocationScores(w, c, ...)
+}
+\arguments{
+\item{w}{The target word/node.}
+
+\item{c}{The collocate.}
+
+\item{...}{Additional parameters to pass to the API.}
+}
+\value{
+A one row data frame with collocate and its association scores.
+}
+\description{
+Calculate the association scores between a node (target word) and words in a window around the it.
+}
diff --git a/man/cosineSimilarity.Rd b/man/cosineSimilarity.Rd
new file mode 100644
index 0000000..5b30c89
--- /dev/null
+++ b/man/cosineSimilarity.Rd
@@ -0,0 +1,21 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/derekovecs.R
+\name{cosineSimilarity}
+\alias{cosineSimilarity}
+\title{cosineSimilarity}
+\usage{
+cosineSimilarity(w1, w2, ...)
+}
+\arguments{
+\item{w1}{The first word.}
+
+\item{w2}{The second word.}
+
+\item{...}{Additional parameters to pass to the API.}
+}
+\value{
+The cosine similarity between the two words.
+}
+\description{
+Calculate the cosine similarity between two words in the derekovecs model.
+}
diff --git a/man/countbasedCollocates.Rd b/man/countbasedCollocates.Rd
new file mode 100644
index 0000000..c3f153f
--- /dev/null
+++ b/man/countbasedCollocates.Rd
@@ -0,0 +1,19 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/derekovecs.R
+\name{countbasedCollocates}
+\alias{countbasedCollocates}
+\title{countbasedCollocates}
+\usage{
+countbasedCollocates(w = "Test", ...)
+}
+\arguments{
+\item{w}{The word to get the collocates for.}
+
+\item{...}{Additional parameters to pass to the API.}
+}
+\value{
+A data fram with the most salient collcates and their association scores.
+}
+\description{
+Get the collocates of a word in the count-based dereko model.
+}
diff --git a/man/derekovecsApiCall.Rd b/man/derekovecsApiCall.Rd
new file mode 100644
index 0000000..a84757f
--- /dev/null
+++ b/man/derekovecsApiCall.Rd
@@ -0,0 +1,19 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/derekovecs.R
+\name{derekovecsApiCall}
+\alias{derekovecsApiCall}
+\title{DeReKoVecsCall}
+\usage{
+derekovecsApiCall(method = "", ...)
+}
+\arguments{
+\item{method}{The method to call.}
+
+\item{...}{The parameters to pass to the method.}
+}
+\value{
+The result of the call.
+}
+\description{
+Call the DeReKoVecs API.
+}
diff --git a/man/derekovecsServer.Rd b/man/derekovecsServer.Rd
new file mode 100644
index 0000000..4ef9089
--- /dev/null
+++ b/man/derekovecsServer.Rd
@@ -0,0 +1,14 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/derekovecs.R
+\name{derekovecsServer}
+\alias{derekovecsServer}
+\title{DeReKoVecsServer}
+\usage{
+derekovecsServer()
+}
+\value{
+The URL of the DeReKoVecs API server.
+}
+\description{
+DeReKoVecsServer
+}
diff --git a/man/paradigmaticNeighbours.Rd b/man/paradigmaticNeighbours.Rd
new file mode 100644
index 0000000..225dae7
--- /dev/null
+++ b/man/paradigmaticNeighbours.Rd
@@ -0,0 +1,19 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/derekovecs.R
+\name{paradigmaticNeighbours}
+\alias{paradigmaticNeighbours}
+\title{paradigmaticNeighbours}
+\usage{
+paradigmaticNeighbours(word = "Test", ...)
+}
+\arguments{
+\item{word}{The word to get the paradigmatic neighbours for.}
+
+\item{...}{Additional parameters to pass to the API.}
+}
+\value{
+A list of words with their similarity scores.
+}
+\description{
+Get the paradigmatic neighbours of a word in the derekovecs model.
+}
diff --git a/man/pipe.Rd b/man/pipe.Rd
new file mode 100644
index 0000000..a648c29
--- /dev/null
+++ b/man/pipe.Rd
@@ -0,0 +1,20 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/utils-pipe.R
+\name{\%>\%}
+\alias{\%>\%}
+\title{Pipe operator}
+\usage{
+lhs \%>\% rhs
+}
+\arguments{
+\item{lhs}{A value or the magrittr placeholder.}
+
+\item{rhs}{A function call using the magrittr semantics.}
+}
+\value{
+The result of calling \code{rhs(lhs)}.
+}
+\description{
+See \code{magrittr::\link[magrittr:pipe]{\%>\%}} for details.
+}
+\keyword{internal}
diff --git a/man/syntagmaticNeighbours.Rd b/man/syntagmaticNeighbours.Rd
new file mode 100644
index 0000000..6278606
--- /dev/null
+++ b/man/syntagmaticNeighbours.Rd
@@ -0,0 +1,19 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/derekovecs.R
+\name{syntagmaticNeighbours}
+\alias{syntagmaticNeighbours}
+\title{syntagmaticNeighbours}
+\usage{
+syntagmaticNeighbours(word = "Test", ...)
+}
+\arguments{
+\item{word}{The word to get the syntagmatic neighbours for.}
+
+\item{...}{Additional parameters to pass to the API.}
+}
+\value{
+Data frame syntagmatic neighbours of a word from the predictive derekovecs model.
+}
+\description{
+Get the syntagmatic neighbours of a word from the predictive derekovecs model.
+}