Many improvements for the new version

Author: antaldaniel

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: wbdataset
 Title: Making Datasets Truly Interoperable and Reusable in R with Wikibase
 Version: 0.1.1034
-Date: 2024-03-26
+Date: 2024-03-30
 Authors@R: 
     c(person(given="Daniel", family="Antal", 
            email= "daniel.antal@dataobservatory.eu", 
@@ -38,9 +38,9 @@ Imports:
     glue,
     here,
     httr,
+    jsonlite,
     magrittr,
     purrr,
-    readr,
     utils
 Language: en-US
 VignetteBuilder: knitr

NAMESPACE

@@ -4,7 +4,6 @@ export("%>%")
 export(add_id_statement)
 export(add_item_statement)
 export(add_statement)
-export(add_wikibase_url_statement)
 export(check_existing_item)
 export(check_existing_property)
 export(copy_wikidata_item)

NEWS.md

@@ -1,12 +1,17 @@
 # wbdataset
 
-# 0.1.1023
-* check_existing_item, check_existing_property
+# 0.1.1034
+* Remove the unnecessary `log_path` parameter from the create and copy function 
+families.
+* Many corrections in the formatting and the contents of the function reference.
+ 
+# wbdataset 0.1.1023
+* [check_existing_item()], [check_existing_property()]
 
-# 0.1.1014
+# wbdataset 0.1.1014
 * copy_wikidata_item, copy_wikidata_property works with one or several items/properties
 
-# 0.1.1
+# wbdataset 0.1.1
 * 0.1.0003: first long-form article, package website.
 * 0.1.1: MediaWiki API vignette and functions.
 

R/add_id_statement.R

@@ -1,13 +1,27 @@
 #' @rdname add_statement
-#' @inheritParams add_statement
+#' @description See
+#' \link[https://www.wikidata.org/w/api.php?action=help&modules=wbcreateclaim]{MediaWiki
+#' API help}
+#' @param qid The QID of the item in the Wikibase instance that you use.
+#' @param pid The PID of the equivalent Wikidata (or reference Wikibase) URI.
+#' @param o The object of the semantic statement.
 #' @param wikibase_type Defaults to \code{"external-id"}.
+#' @param wikibase_api_url The full URL of the Wikibase API, which is the
+#'   address that the \code{wbdataset} R client sends requests to when
+#'   interacting with the knowledge base. For example,
+#'   \code{'https://reprexbase.eu/demowiki/api.php'}. The URL must end with
+#'   api.php.
+#' @param csrf The CSRF token of your session, received with
+#'   \code{\link{get_csrf}}.
 #' @importFrom httr POST content
 #' @importFrom glue glue
 #' @export
-add_id_statement <- function(qid, pid, o,
-                             wikibase_type = "external-id",
-                             wikibase_api_url = "https://reprexbase.eu/jekyll/api.php",
-                             csrf) {
+add_id_statement <- function(
+    qid, pid, o,
+    wikibase_type = "external-id",
+    wikibase_api_url = "https://reprexbase.eu/demowiki/api.php",
+    csrf) {
+
   datavalue <- paste0('"', o, '"')
   datavalue
 

R/add_item_statement.R

@@ -1,7 +1,8 @@
 #' @rdname add_statement
-#' @inheritParams add_statement
-#' @param wikibase_type Defaults to \code{'item'}.
-#' @param o The item to be added to the statement as an object in the semantic triple.
+#' @param qid The QID of the item in the Wikibase instance that you use.
+#' @param pid The PID of the equivalent Wikidata (or reference Wikibase) URI.
+#' @param o The object of the semantic statement.
+#' @param wikibase_type It must be \code{'item'}.
 #' @export
 
 add_item_statement <- function(qid, pid, o,

R/add_statement.R

@@ -1,22 +1,29 @@
 #' @title Add statements
-#' @description
-#' See \link[https://www.wikidata.org/w/api.php?action=help&modules=wbcreateclaim]{MediaWiki API help}
-#'
+#' @description See
+#' \link[https://www.wikidata.org/w/api.php?action=help&modules=wbcreateclaim]{MediaWiki
+#' API help}
 #' @param qid The QID of the item in the Wikibase instance that you use.
 #' @param pid The PID of the equivalent Wikidata (or reference Wikibase) URI.
 #' @param o The object of the semantic statement.
 #' @param wikibase_type A \code{'item'}, \code{'numeric'}, or \code{'string'}.
-#' @param wikibase_api_url \code{\link{"https://reprexbase.eu/demowiki/api.php"}}.
-#' @param csrf The CSRF token of your session, received with \code{\link{get_csrf}}.
+#' @param wikibase_api_url The full URL of the Wikibase API, which is the
+#'   address that the \code{wbdataset} R client sends requests to when
+#'   interacting with the knowledge base. For example,
+#'   \code{'https://reprexbase.eu/demowiki/api.php'}. The URL must end with
+#'   api.php.
+#' @param csrf The CSRF token of your session, received with
+#'   \code{\link{get_csrf}}.
 #' @return A data.frame with four columns:
 #' \code{id} containing the statement ID, \code{qid} with the QID,
 #' \code{o} with the PID, and \code{p} with the  wikidata_uri.
 #' @export
 
-add_statement <- function(qid, pid, o,
-                          wikibase_type,
-                          wikibase_api_url = "https://reprexbase.eu/demowiki/api.php",
-                          csrf) {
+add_statement <- function(
+    qid, pid, o,
+    wikibase_type,
+    wikibase_api_url = "https://reprexbase.eu/demowiki/api.php",
+    csrf) {
+
   if (wikibase_type == "string") {
     add_item_statement(
       qid = qid, pid = pid, o = o,
@@ -35,59 +42,3 @@ add_statement <- function(qid, pid, o,
     stop("Error in add_statement(..., wikibase_type): '", wikibase_type, "' is not recognised (yet).")
   }
 }
-
-#' @rdname add_statement
-#' @inheritParams add_statement
-#' @param wikidata_uri The QID on Wikidata (or a reference Wikibase).
-#' @export
-
-add_wikibase_url_statement <- function(qid,
-                                       pid,
-                                       wikibase_url,
-                                       wikibase_api_url = "https://reprexbase.eu/demowiki/api.php",
-                                       csrf_token) {
-  datavalue <- gsub(
-    "changeuri", wikibase_url,
-    '{"claims":[{"mainsnak":{"snaktype":"value","property":"pid","datavalue":{"value":"changeuri","type":"string"}},"type":"statement","rank":"normal"}]}'
-  )
-
-  datavalue
-  datavalue <- gsub("pid", pid, datavalue)
-
-  claim_body <- list(
-    action = "wbeditentity",
-    id = qid, # in the new wikibase
-    property = pid, # in the wikibase where you write
-    data = datavalue,
-    # data = '{"claims":[{"mainsnak":{"snaktype":"value","property":"P1","datavalue":{"value":"https://www.wikidata.org/wiki/Q43878","type":"string"}},"type":"statement","rank":"normal"}]}',
-    token = csrf_token,
-    format = "json"
-  )
-
-  new_claim <- httr::POST(
-    wikibase_api_url,
-    body = claim_body,
-    encode = "form",
-    handle = response_csrf
-  )
-
-  response <- content(new_claim)
-  response
-
-  if ("error" %in% names(response)) {
-    return(data.frame(
-      statement_id = NA_character_,
-      wikibase_qid = qid,
-      pid = NA_character_,
-      url = NA_character_
-    ))
-  }
-  if (response$success == 1) {
-    data.frame(
-      statement_id = l[[1]]$id,
-      wikibase_qid = response$entity$id,
-      pid          = pid,
-      url          = l[[1]]$mainsnak$datavalue$value
-    )
-  }
-}

R/check_existing_item.R

@@ -14,7 +14,6 @@
 check_existing_item <- function(action = "create_item",
                                 search_term,
                                 language,
-                                action_timestamp = NULL,
                                 equivalence_property = NA_character_,
                                 equivalence_id = NA_character_,
                                 classification_property = NA_character_,

R/check_existing_property.R

@@ -6,6 +6,10 @@
 #' \href{https://www.wikidata.org/w/api.php?action=help&modules=wbsearchentities}{MediaWiki
 #' action=wbsearchentities}.
 #' @param action Defaults to \code{"create_property"}.
+#' @param classification_property The instance of, or subclass of, or superclass
+#'   of property. Defaults to \code{NA_character} when not used.
+#' @param classification_id The QID of the class. Defaults to
+#'   \code{NA_character} when not used.
 #' @param search_term A label in the given language, for example, "Estonia".
 #' @inheritParams create_property
 #' @return A data.frame or NULL.
@@ -15,7 +19,6 @@ check_existing_property <- function(
     action = "create_property",
     search_term,
     language,
-    action_timestamp = NULL,
     equivalence_property = NA_character_,
     equivalence_id = NA_character_,
     classification_property = NA_character_,
@@ -24,6 +27,7 @@ check_existing_property <- function(
     data_curator = person("Unknown", "Person"),
     wikibase_api_url,
     csrf) {
+
   action_timestamp <- action_timestamp_create()
   action_time <- Sys.time()
 

R/copy_wikidata_item.R

@@ -14,24 +14,28 @@
 #'   replaces the more general \code{equivalence_id}, because we must use QID
 #'   for identification in an other Wikibase instance.
 #' @param qid_on_wikidata The QID of the item to be copied to your Wikibase. A
-#' single valid QID or a vector of several QIDs.
+#'   single valid QID or a vector of several QIDs.
 #' @param qid_equivalence_property The QID in Wikibase that records the
 #'   equivalent Wikidata QID as an external ID.
-#' @param language A vector of language codes, for example, \code{c("en",
-#'   "et")}.
+#' @param language Defaults to \code{c("en", "nl", "hu")}. 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, "nl" for Dutch and "hu"
+#'   for Hungarian.)
 #' @param classification_property The instance of, or subclass of, or superclass
 #'   of property. Defaults to \code{NA_character} when not used.
 #' @param classification_id The QID of the class. Defaults to
 #'   \code{NA_character} when not used.
-#' @param wikibase_api_url For example,
-#'   \code{'https://reprexbase.eu/demowiki/api.php'}.
+#' @param wikibase_api_url The full URL of the Wikibase API, which is the
+#'   address that the \code{wbdataset} R client sends requests to when
+#'   interacting with the knowledge base. For example,
+#'   \code{'https://reprexbase.eu/demowiki/api.php'}. The URL must end with
+#'   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}.
-#' @param log_path A path to save the log file. Defaults to the return value of
-#'   \code{\link{tempdir()}}.
-#' @param log_file An explicitly stated full path to a possible CSV log file,
-#' defaults to \code{NULL}. If the value is \code{NULL}, no log file will be
-#' created.
+#'   creates the log file, created with \link[utils]{person}.
+#' @param log_file_name An explicitly stated full path to a possible CSV log
+#'   file, defaults to \code{NULL}. If the value is \code{NULL}, no log file
+#'   will be created.
 #' @param csrf The CSRF token of your session, received with
 #'   \code{\link{get_csrf}}.
 #' @param wikibase_session An optional list that contains any of the values of
@@ -40,24 +44,25 @@
 #'   \code{csrf} (for repeated use in a session.)
 #' @importFrom assertthat assert_that
 #' @importFrom utils person
-#' @return Returns a dataset_df object. The columns are:
-#' \itemize{
-#'  \item{"rowid"}{ A row identifier. }
-#'  \item{"action"}{ The create_item() function name. }
-#'  \item{"id_on_target"}{ The new item identifier (QID) on the targeted Wikibase.}
-#'  \item{"label"}{ The propery label}
-#'  \item{"description"}{ The description label}
-#'  \item{"language"}{ The language code of the label.}
-#'  \item{"datatype"}{ The datatype of the property, for example, `string`}
-#'  \item{"wikibase_api_url"}{ The MediaWiki API URL where the new property is created.}
-#'  \item{"equivalence_property"}{ The PID that connects an equivalence ID to the property.}
-#'  \item{"equivalence_id"}{ The ID of an equivalent property defined elsewhere.}
-#'  \item{"classification_property"}{ The PID that connects the item to a superclass, or class.}
-#'  \item{"classification_id"}{ The QID of a class, subclass or superclass.}
-#'  \item{"success"}{ TRUE if successfully created, FALSE if there was an error.}
-#'  \item{"comment"}{ A summary of the error messages(s), if success is FALSE.}
-#'  \item{"time"}{ The time when the action started.}
-#'  \item{"logfile"}{ The name of the CSV logfile.}
+#' @return Returns a \code{\link[dataset]{dataset_df}} object.
+#' The columns are:\cr
+#' \describe{
+#'  \item{\code{rowid}}{A row identifier. }
+#'  \item{\code{action}}{\code{copy_wikidata_item}}
+#'  \item{\code{id_on_target}}{The new item identifier (QID) on the targeted Wikibase.}
+#'  \item{\code{label}}{The propery label}
+#'  \item{\code{description}}{The description label}
+#'  \item{\code{language}}{The language code of the label.}
+#'  \item{\code{datatype}}{The datatype of the property, for example, `string`}
+#'  \item{\code{wikibase_api_url}}{The MediaWiki API URL where the new property is created.}
+#'  \item{\code{equivalence_property}}{The PID that connects an equivalence ID to the property.}
+#'  \item{\code{equivalence_id}}{The ID of an equivalent property defined elsewhere.}
+#'  \item{\code{classification_property}}{The PID that connects the item to a superclass, or class.}
+#'  \item{\code{classification_id}}{The QID of a class, subclass or superclass.}
+#'  \item{\code{success}}{TRUE if successfully created, FALSE if there was an error.}
+#'  \item{\code{comment}}{A summary of the error messages(s), if success is FALSE.}
+#'  \item{\code{time}}{The time when the action started.}
+#'  \item{\code{logfile}}{The name of the CSV logfile.}
 #' }
 #' The number of rows corresponds to the length of the qid_on_wikidata vector.
 #' @export
@@ -70,7 +75,6 @@ copy_wikidata_item <- function(
     classification_id = NA_character_,
     wikibase_api_url = "https://reprexbase.eu/jekyll/api.php",
     data_curator = NULL,
-    log_path = tempdir(),
     log_file_name = NULL,
     csrf,
     wikibase_session = NULL) {
@@ -99,10 +103,6 @@ copy_wikidata_item <- function(
       wikibase_api_url <- wikibase_session$wikibase_api_url
     }
 
-    if (!is.null(wikibase_session$log_path)) {
-      log_path <- wikibase_session$log_path
-    }
-
     if (!is.null(wikibase_session$log_file_name)) {
       log_file_name <- wikibase_session$log_file_name
     }
@@ -115,7 +115,6 @@ copy_wikidata_item <- function(
   # Assertions for correct inputs ------------------------------------------------
 
   if (is.null(data_curator)) data_curator <- person("Jane", "Doe")
-  if (is.null(log_path)) log_path <- tempdir()
 
   assertthat::assert_that(
     inherits(data_curator, "person"),
@@ -133,7 +132,6 @@ copy_wikidata_item <- function(
       language = language,
       wikibase_api_url = wikibase_api_url,
       data_curator = data_curator,
-      log_path = log_path,
       csrf = csrf,
       wikibase_session = wikibase_session
     )
@@ -251,7 +249,6 @@ copy_wikidata_item <- function(
     action = "copy_item",
     search_term = default_label,
     language = "en",
-    action_timestamp = action_timestamp,
     equivalence_property = qid_equivalence_property,
     equivalence_id = qid_on_wikidata,
     classification_property = classification_property,
@@ -572,7 +569,6 @@ copy_wikidata_items <- function(qid_on_wikidata,
                                 language,
                                 wikibase_api_url,
                                 data_curator,
-                                log_path,
                                 csrf,
                                 wikibase_session) {
   # Ensure that QIDs are used in the loop ----------------------------
@@ -605,10 +601,6 @@ copy_wikidata_items <- function(qid_on_wikidata,
       wikibase_api_url <- wikibase_session$wikibase_api_url
     }
 
-    if (!is.null(wikibase_session$log_path)) {
-      log_path <- wikibase_session$log_path
-    }
-
     if (!is.null(wikibase_session$csrf)) {
       csrf <- wikibase_session$csrf
     }
@@ -624,7 +616,6 @@ copy_wikidata_items <- function(qid_on_wikidata,
         language = language,
         wikibase_api_url = wikibase_api_url,
         data_curator = data_curator,
-        log_path = log_path,
         csrf = csrf
       )
     }