Many documentation improvements

Author: antaldaniel

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: wbdataset
 Title: Making Datasets Truly Interoperable and Reusable in R with Wikibase
-Version: 0.1.1052
-Date: 2024-06-02
+Version: 0.1.1053
+Date: 2024-06-06
 Authors@R: 
     c(person(given="Daniel", family="Antal", 
            email= "[email protected]", 
@@ -25,6 +25,7 @@ Suggests:
     httptest2,
     keyring,
     knitr,
+    mockery,
     rmarkdown,
     spelling,
     testthat (>= 3.0.0)
@@ -42,6 +43,7 @@ Imports:
     jsonlite,
     magrittr,
     purrr,
+    tibble,
     utils
 Language: en-US
 VignetteBuilder: knitr

NAMESPACE

@@ -27,6 +27,7 @@ importFrom(dataset,dataset_df)
 importFrom(dataset,defined)
 importFrom(dataset,dublincore)
 importFrom(dplyr,bind_rows)
+importFrom(dplyr,everything)
 importFrom(dplyr,filter)
 importFrom(dplyr,left_join)
 importFrom(dplyr,mutate)
@@ -43,3 +44,4 @@ importFrom(magrittr,"%>%")
 importFrom(purrr,safely)
 importFrom(tibble,tibble)
 importFrom(utils,person)
+importFrom(utils,write.table)

R/copy_wikidata_item.R

@@ -87,6 +87,9 @@ copy_wikidata_item <- function(
     csrf = NULL,
     wikibase_session = NULL) {
 
+  if (is.null(qid_equivalence_property)) qid_equivalence_property <- NA_character_
+  validated_action <- "copy_wikidata_item()"
+
   language <- resolve_from_session("language", language, wikibase_session)
   data_curator <- resolve_from_session("data_curator", data_curator, wikibase_session)
   log_file_name <- resolve_from_session("log_file_name", log_file_name, wikibase_session)
@@ -108,11 +111,10 @@ copy_wikidata_item <- function(
     equivalence_id = NA_character_,
     csrf = csrf,
     data_curator = data_curator,
-    validated_action = "copy_wikidata_property()"
+    validated_action = validated_action
   )
 
-  if (is.null(qid_equivalence_property)) qid_equivalence_property <- NA_character_
-
+  # Case when multiple items need to be copied ------------
   if (length(qid_on_wikidata) > 1) {
     return_log_file <- copy_wikidata_items(
       qid_on_wikidata = qid_on_wikidata,
@@ -143,15 +145,13 @@ copy_wikidata_item <- function(
     log_file_name <- ""
   }
 
-
-  # Assert that qid_on_wikidata looks like a QID
+  # Assert that qid_on_wikidata looks like a QID ----------------------
   qid_on_wikidata <- as.character(qid_on_wikidata)
   assert_that(is_qid(qid_on_wikidata),
     msg = "qid_on_wikidata must start with Q followed by digits."
   )
 
   # Getting the data ---------------------------------------------------------
-
   claim_body <- list(
     action = "wbgetentities",
     ids = qid_on_wikidata,
@@ -162,6 +162,7 @@ copy_wikidata_item <- function(
   # it saves various error exceptions when using httr::POST
   safely_post <- purrr::safely(httr::POST, NULL)
 
+  # The data is always received from Wikidata -------------------
   get_claim <- safely_post(
     "https://www.wikidata.org/w/api.php",
     body = claim_body,
@@ -540,10 +541,15 @@ copy_wikidata_item <- function(
   )
 
   if (!is.null(log_file_name) && nchar(log_file_name) > 0) {
-    write_csv(return_dataframe,
+    write.table(
+      return_dataframe,
       file = log_file_name,
+      sep = ",",
+      row.names = FALSE,
+      col.names = !file.exists(log_file_name),
       na = "NA",
-      append = TRUE
+      append = TRUE,
+      quote = TRUE
     )
   }
   return_ds

R/copy_wikidata_property.R

@@ -54,7 +54,7 @@
 #'   useful in interactive workflows or scripts where the same context is
 #'   reused.
 #' @importFrom assertthat assert_that
-#' @importFrom utils person
+#' @importFrom utils person write.table
 #' @return Returns a \code{\link[dataset]{dataset_df}} object. The columns
 #'   are:\cr
 #' \describe{
@@ -548,10 +548,15 @@ copy_wikidata_property <- function(
   )
 
   if (!is.null(log_file_name) && nchar(log_file_name) > 0) {
-    write_csv(return_dataframe,
+    write.table(
+      return_dataframe,
       file = log_file_name,
+      sep = ",",
+      row.names = FALSE,
+      col.names = !file.exists(log_file_name),
       na = "NA",
-      append = TRUE
+      append = TRUE,
+      quote = TRUE
     )
   }
 

R/create_item.R

@@ -56,6 +56,7 @@
 #'   useful in interactive workflows or scripts where the same context is
 #'   reused.
 #' @export
+#' @importFrom utils write.table
 #' @return Returns a \code{\link[dataset]{dataset_df}} object.
 #' The columns are:\cr
 #' \describe{
@@ -392,10 +393,15 @@ create_item <- function(label,
   )
 
   if(!is.null(log_file_name) && nchar(log_file_name)>0 ) {
-    write_csv(return_dataframe,
-              file = log_file_name,
-              na = "NA",
-              append = TRUE
+    write.table(
+      return_dataframe,
+      file = log_file_name,
+      sep = ",",
+      row.names = FALSE,
+      col.names = !file.exists(log_file_name),
+      na = "NA",
+      append = TRUE,
+      quote = TRUE
     )
   }
 

R/create_property.R

@@ -61,6 +61,7 @@
 #'   useful in interactive workflows or scripts where the same context is
 #'   reused.
 #' @export
+#' @importFrom utils write.table
 #' @return Returns a \code{\link[dataset]{dataset_df}} object.
 #' The columns are:\cr
 #' \describe{
@@ -388,10 +389,15 @@ create_property <- function(label,
   )
 
   if(!is.null(log_file_name) && nchar(log_file_name)>0 ) {
-    write_csv(return_dataframe,
-              file = log_file_name,
-              na = "NA",
-              append = TRUE
+    write.table(
+      return_dataframe,
+      file = log_file_name,
+      sep = ",",
+      row.names = FALSE,
+      col.names = !file.exists(log_file_name),
+      na = "NA",
+      append = TRUE,
+      quote = TRUE
     )
   }
 

R/get_claim.R

@@ -49,11 +49,13 @@
 #'
 #' @export
 
-get_claim <- function(qid = "Q528626",
-                      pid = "P625",
-                      wikibase_api_url = "https://www.wikidata.org/w/api.php",
-                      csrf = NULL,
-                      first = TRUE) {
+get_claim <- function(
+    qid = "Q528626",
+    pid = "P625",
+    wikibase_api_url = "https://www.wikidata.org/w/api.php",
+    csrf = NULL,
+    first = TRUE) {
+
   if (!is_qid(qid)) {
     stop(sprintf("Invalid QID: '%s'. QIDs must begin with 'Q' followed by digits (e.g., 'Q42').", qid))
   }
@@ -158,19 +160,16 @@ get_claim <- function(qid = "Q528626",
 #' @title Deprecated: retrieve a claim from a Wikidata item
 #'
 #' @description
-#' \strong{Deprecated.} This function has been replaced by \code{\link{get_claim}}.
+#' \strong{Deprecated.} This function has been replaced by
+#' \code{\link{get_claim}}.
 #'
 #' @details
 #' \code{get_claims()} was used to retrieve a claim (statement) for a specific property from
 #' a Wikidata or Wikibase item. This function is now deprecated and will be removed in a
 #' future release. Please use \code{\link{get_claim}} instead, which provides more robust
 #' functionality and better support for modern data types.
 #'
-#' @param qid A character string giving the QID of the item.
-#' @param property A character string giving the property ID.
-#' @param wikibase_api_url The full URL of the Wikibase API endpoint (must end with \code{api.php}).
-#' @param csrf (Optional) A CSRF token, not used in this read-only function.
-#'
+#' @param ... Any parameters.
 #' @return A data frame or list depending on implementation. For updated behaviour, use \code{get_claim()}.
 #'
 #' @seealso \code{\link{get_claim}}

R/get_wikidata_item.R

@@ -12,10 +12,22 @@
 #'   By default, the function retrieves metadata in multiple languages,
 #'   including English, French, German, Italian, and Spanish.
 #'
+#' @param title The title of the returned (log) dataset.
+#' @param prefix The prefix to be used as a namespace for downloaded items.
 #' @param qid_on_wikidata A character vector of Wikidata QIDs (e.g.,
 #'   \code{"Q42"}).
+#' @param language Defaults to \code{c("en")}. A character string of
+#'   the languages in which the users wants to receive the labels and
+#'   descriptions of the property. The vector of languages must use \href{https://en.wikipedia.org/wiki/IETF_language_tag}{BCP
+#'   47}-compliant language tags (e.g., "en" for English, and "hu"
+#'   for Hungarian.)
 #' @param wikibase_api_url The full URL of the Wikibase API endpoint (must end
 #'   with \code{api.php}).
+#' @param data_curator The name of the data curator who runs the function and
+#'   creates the log file, created with \link[utils]{person}.
+#'   It is either given as a parameter or resolved from
+#'   \code{wikibase_session}. If no curator is given, then filled with
+#'   \code{person("Unknown", "Curator")}.
 #' @param fallback_language A BCP 47 language code (e.g., "en") used as a fallback
 #'   when no label is available in the requested language(s). If a label is missing
 #'   in one or more specified languages, this fallback will be used instead when available.
@@ -28,8 +40,10 @@
 #' @seealso \code{\link{get_claim}} to retrieve claims (properties) for Wikidata
 #'   items.
 #' @importFrom dplyr select mutate filter bind_rows relocate left_join
+#' @importFrom dplyr everything
 #' @importFrom tibble tibble
 #' @importFrom dataset dataset_df defined dublincore
+#' @importFrom utils write.table
 #' @examples
 #' \dontrun{
 #' get_wikidata_item("Q42", language = c("hu"), fallback_language = "en")

R/handle_search_term_ambiguity.R

@@ -4,8 +4,9 @@
 #' @param search_results A list of search results from the Wikibase API.
 #' @param search_term The original search term used in the query.
 #' @param language The language code used in the search.
-#' @param prefer_first Logical; if TRUE, returns the first match when multiple
-#'   matches are found.
+#' @param strategy If \code{return_null} than a NULL value is returned if
+#' there are ambiguous results, if \code{return_first} then the first result
+#' is returned.
 #' @return A single search result or NULL if ambiguity cannot be resolved.
 #' @keywords internal
 handle_search_term_ambiguity <- function(search_results,

R/left_join_column.R

@@ -73,7 +73,7 @@ left_join_column <- function(
   result_df <- dplyr::bind_rows(result_df)
 
   if (property %in% names(ds)) {
-    ds <- ds |>
+    ds <- ds %>%
       dplyr::select(-dplyr::all_of(property))
   }