Restructure documentation
Change-Id: I2640e68972cb7c5ed67032a3b575a2aec056f592
diff --git a/R/KorAPQuery.R b/R/KorAPQuery.R
index fa84839..b06dea1 100644
--- a/R/KorAPQuery.R
+++ b/R/KorAPQuery.R
@@ -1,12 +1,13 @@
#' Class KorAPQuery
#'
-#' \code{KorAPQuery} objects represent the current state of a query to a KorAP server.
-#' New \code{KorAPQuery} objects are typically created by the \code{\link{corpusQuery}} method.
+#' This class provides methods to perform different kinds of queries on the KorAP API server.
+#' \code{KorAPQuery} objects, which are typically created by the \code{\link{corpusQuery}} method,
+#' represent the current state of a query to a KorAP server.
#'
#' @include KorAPConnection.R
#' @import httr
#'
-#' @include RKorAPClient.R
+#' @include RKorAPClient-package.R
#' @export
KorAPQuery <- setClass("KorAPQuery", slots = c(
@@ -66,17 +67,13 @@
setGeneric("fetchRest", function(kqo, ...) standardGeneric("fetchRest") )
setGeneric("frequencyQuery", function(kco, ...) standardGeneric("frequencyQuery") )
setGeneric("collocationScoreQuery", function(kco, ...) standardGeneric("collocationScoreQuery") )
-setGeneric("collocationScoreQueryNew", function(kco, ...) standardGeneric("collocationScoreQueryNew") )
-
maxResultsPerPage <- 50
## quiets concerns of R CMD check re: the .'s that appear in pipelines
if(getRversion() >= "2.15.1") utils::globalVariables(c("."))
-#' Method corpusQuery
-#'
-#' Perform a corpus query via a connection to a KorAP-API-server.
+#' \bold{\code{corpusQuery}} performs a corpus query via a connection to a KorAP-API-server
#'
#' @param kco \code{\link{KorAPConnection}} object (obtained e.g. from \code{new("KorAPConnection")}
#' @param query string that contains the corpus query. The query language depends on the \code{ql} parameter. Either \code{query} must be provided or \code{KorAPUrl}.
@@ -293,6 +290,8 @@
#' Fetch all results of a KorAP query.
#'
+#' \bold{\code{fetchAll}} fetches allf results of a KorAP query.
+#'
#' @examples
#' \donttest{
#' q <- new("KorAPConnection") %>% corpusQuery("Ameisenplage") %>% fetchAll()
diff --git a/R/RKorAPClient-package.R b/R/RKorAPClient-package.R
new file mode 100644
index 0000000..5c66076
--- /dev/null
+++ b/R/RKorAPClient-package.R
@@ -0,0 +1,7 @@
+#' @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)](http://www.lrec-conf.org/proceedings/lrec2020/LREC-2020.pdf). Marseille: European Language Resources Association (ELRA), 7017-7023. <http://www.lrec-conf.org/proceedings/lrec2020/pdf/2020.lrec-1.867.pdf>
+#'
+#' @keywords internal
+"_PACKAGE"
+#' [1] "_PACKAGE"
+#'
diff --git a/R/RKorAPClient.R b/R/RKorAPClient.R
deleted file mode 100644
index 92fc66e..0000000
--- a/R/RKorAPClient.R
+++ /dev/null
@@ -1,10 +0,0 @@
-#' \code{RKorapClient} package
-#'
-#' R package to access the \href{https://github.com/KorAP/}{KorAP} web service API.
-#'
-#' See the README.md on
-#' \href{https://github.com/KorAP/RKorAPClient/}{github}
-#'
-#' @docType package
-#' @name RKorAPClient
-NULL
diff --git a/R/association-scores.R b/R/association-scores.R
index 494477e..2d9b41e 100644
--- a/R/association-scores.R
+++ b/R/association-scores.R
@@ -1,8 +1,23 @@
-#' Default association score functions
+#' Association score functions
#'
-#' @family association-score-functions
+#' @param O1 observed absolute frequency of node
+#' @param O2 observed absolute frequency of collocate
+#' @param O observed absolute frequency of collocation
+#' @param N corpus size
+#' @param E expected absolute frequency of collocation (already adjusted to window size)
+#' @param window_size total window size around node (left neighbour count + right neighbour count)
#'
-#' @return list of default association score functions
+#' @return association score
+#' @name 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 \code{\link{collocationScoreQuery}}.
+NULL
+#' NULL
+
+#' @rdname association-score-functions
+#'
#' @export
#'
#' @examples
@@ -19,47 +34,26 @@
list(pmi=pmi, mi2=mi2, mi3=mi3, logDice=logDice, ll=ll)
}
-#' Pointwise mutual information
+#' @rdname association-score-functions
#'
-#' @family association-score-functions
-#'
-#' @param O1 observed absolute frequency of node
-#' @param O2 observed absolute frequency of collocate
-#' @param O observed absolute frequency of collocation
-#' @param N corpus size
-#' @param E expected absolute frequency of collocation (already adjusted to window size)
-#' @param window_size total window size around node (left neighbour count + right neighbour count)
-#'
-#' @return association score
#' @export
#'
-
pmi <- function(O1, O2, O, N, E, window_size) {
log2(O / E)
}
-#' Pointwise mutual information squared
+#' @rdname association-score-functions
#'
-#' @family association-score-functions
-#'
-#' @details
-#' Also referenced to as mutual dependency (MD)
-#'
-#' @inheritParams pmi
#' @export
#'
mi2 <- function(O1, O2, O, N, E, window_size) {
log2(O ^ 2 / E)
}
-#' Pointwise mutual information cubed
-#'
+#' @rdname association-score-functions
#' @family association-score-functions
#'
-#' @details
-#' Also referenced to as log-frequency biased mutual dependency (LFMD)
#'
-#' @inheritParams pmi
#' @export
#'
#' @references
@@ -71,16 +65,12 @@
log2(O ^ 3 / E)
}
-#' log-Dice coefficient
-#'
+#' @rdname association-score-functions
#' @family association-score-functions
-#' @inheritParams pmi
#' @export
#'
-#' @examples
-#'
#' @references
-#' Rychlý, Pavel (2008): <a href="http://www.fi.muni.cz/usr/sojka/download/raslan2008/13.pdf">A lexicographer-friendly association score.</a> In Proceedings of Recent Advances in Slavonic Natural Language Processing, RASLAN, 6–9.
+#' Rychlý, Pavel (2008): A lexicographer-friendly association score. In Proceedings of Recent Advances in Slavonic Natural Language Processing, RASLAN, 6–9. <http://www.fi.muni.cz/usr/sojka/download/raslan2008/13.pdf>.
#'
logDice <- function(O1, O2, O, N, E, window_size) {
@@ -90,14 +80,13 @@
#' Log likelihood
#'
+#' @rdname association-score-functions
#' @family association-score-functions
#'
#' @export
#'
#' @importFrom dplyr if_else
#'
-#' @inheritParams pmi
-#'
#' @references
#' Dunning, T. (1993): Accurate methods for the statistics of surprise and coincidence. Comput. Linguist. 19, 1 (March 1993), 61-74.
#'
diff --git a/R/ci.R b/R/ci.R
index 64f7c0a..80c45f1 100644
--- a/R/ci.R
+++ b/R/ci.R
@@ -15,6 +15,8 @@
#' @param conf.level confidence level of the returned confidence interval. Must
#' be a single number between 0 and 1.
#'
+#' @rdname misc-functions
+#'
#' @export
#' @importFrom stats prop.test
#' @importFrom tibble remove_rownames
diff --git a/R/highcharter-helper.R b/R/highcharter-helper.R
index 2b9a557..929ac0a 100644
--- a/R/highcharter-helper.R
+++ b/R/highcharter-helper.R
@@ -1,8 +1,17 @@
+#' Helper functions for producing highcharts
+#'
+#' @param hc highchart
+#'
+#' @name highcharter-helpers
+NULL
+#' NULL
+
#' Experimental: Plot interactive frequency by year graphs with confidence intervals using highcharter
#'
#' Experimental convenience function for plotting typical frequency by year graphs with confidence intervals using highcharter.
#' \bold{Warning:} This function may be moved to a new package.
#'
+#' @rdname highcharter-helpers
#' @import highcharter
#' @importFrom tibble add_column
#' @export
@@ -148,12 +157,11 @@
#'
#' @description
#' Adds on-click events to data points of highcarts that were constructed with
-#' \ref{frequencyQuery} or ref \ref{collocationScoreQuery}. Clicks on data points
+#' \code{\link{frequencyQuery}} or \code{\link{collocationScoreQuery}}. Clicks on data points
#' then launch KorAP web UI queries for the given query term and virtual corpus in
-#' a separate frame.
+#' a separate tab.
#'
-#' @param hc highchart
-#'
+#' @rdname highcharter-helpers
#' @export
#'
#' @examples
diff --git a/R/misc.R b/R/misc.R
index a39ef21..4529d7a 100644
--- a/R/misc.R
+++ b/R/misc.R
@@ -1,3 +1,8 @@
+#' Misc functions
+#'
+#' @name misc-functions
+NULL
+#' NULL
#' Convert corpus frequency table to instances per million.
#'
@@ -12,6 +17,7 @@
#' @return original table with additional column \code{ipm} and converted columns \code{conf.low} and \code{conf.high}
#' @export
#'
+#' @rdname misc-functions
#' @importFrom dplyr .data
#'
#' @examples
@@ -35,6 +41,7 @@
#'
#' @importFrom dplyr .data
#'
+#' @rdname misc-functions
#' @examples
#' \donttest{
#' new("KorAPConnection") %>%
@@ -58,6 +65,8 @@
#' @param excludePubDate discard publication date constraints
#' @return string or vector of strings with clipped off common prefixes and suffixes
#'
+#' @rdname misc-functions
+#'
#' @examples
#' queryStringToLabel(paste("textType = /Zeit.*/ & pubDate in", c(2010:2019)))
#' queryStringToLabel(c("[marmot/m=mood:subj]", "[marmot/m=mood:ind]"))
@@ -97,6 +106,8 @@
#' @param mapping Set of aesthetic mappings created by aes() or aes_(). If specified and inherit.aes = TRUE (the default), it is combined with the default mapping at the top level of the plot. You must supply mapping if there is no plot mapping.
#' @param ... Other arguments passed to geom_ribbon, geom_line, and geom_click_point.
#'
+#' @rdname misc-functions
+#'
#' @examples
#' library(ggplot2)
#' kco <- new("KorAPConnection", verbose=TRUE)
@@ -175,6 +186,8 @@
#' \code{"url"} here.
#' @param ... Other arguments passed to \code{plotly::ggplotly}
#'
+#' @rdname misc-functions
+#'
#' @examples
#' library(ggplot2)
#' kco <- new("KorAPConnection", verbose=TRUE)