New Upstream Snapshot - r-cran-wikidatar
Ready changes
Summary
Merged new upstream version: 2.3.3+git20171223.1.647d2af (was: 2.3.3).
Resulting package
Built on 2023-01-19T06:07 (took 7m1s)
The resulting binary packages can be installed (if you have the apt repository enabled) by running one of:
apt install -t fresh-snapshots r-cran-wikidatar
Lintian Result
Diff
diff --git a/DESCRIPTION b/DESCRIPTION
index 0a1cacd..e70f7aa 100644
--- a/DESCRIPTION
+++ b/DESCRIPTION
@@ -1,40 +1,19 @@
Package: WikidataR
Type: Package
-Title: Read-Write API Client Library for Wikidata
-Version: 2.3.3
-Date: 2021-11-16
-Authors@R: c(
- person("Thomas", "Shafee", role = c("aut", "cre"), email = "T.Shafee@latrobe.edu.au", comment = c(ORCID = "0000-0002-2298-7593")),
- person("Os", "Keyes", role = "aut", comment = c(ORCID = "0000-0001-5196-609X")),
- person("Serena", "Signorelli", role = "aut"),
- person("Alex", "Lum", role = "ctb", comment = c(ORCID = "0000-0002-9295-9053")),
- person("Christian", "Graul", role = "ctb"),
- person("Mikhail", "Popov", role = "ctb", comment = c(ORCID = "0000-0003-0145-8948"))
- )
-Description: Read from, interogate, and write to Wikidata <https://www.wikidata.org> -
- the multilingual, interdisciplinary, semantic knowledgebase. Includes functions to:
- read from wikidata (single items, properties, or properties); query wikidata (retrieving
- all items that match a set of criterial via Wikidata SPARQL query service); write to
- Wikidata (adding new items or statements via QuickStatements); and handle and manipulate
- Wikidata objects (as lists and tibbles). Uses the Wikidata and Quickstatements APIs.
-BugReports: https://github.com/TS404/WikidataR/issues
-URL: https://github.com/TS404/WikidataR
+Title: API Client Library for 'Wikidata'
+Version: 1.4.0
+Date: 2017-09-21
+Author: Oliver Keyes [aut, cre], Serena Signorelli [aut, cre],
+ Christian Graul [ctb], Mikhail Popov [ctb]
+Maintainer: Oliver Keyes <ironholds@gmail.com>
+Description: An API client for the Wikidata <http://wikidata.org/> store of
+ semantic data.
+BugReports: https://github.com/Ironholds/WikidataR/issues
+URL: https://github.com/Ironholds/WikidataR/issues
License: MIT + file LICENSE
-Imports: httr, jsonlite, WikipediR, WikidataQueryServiceR, tibble,
- dplyr, stringr, Hmisc, progress, pbapply, stats, readr, crayon,
- utils
-Suggests: markdown, testthat, tidyverse, knitr, pageviews
-RoxygenNote: 7.1.1
-Encoding: UTF-8
-Depends: R (>= 3.5.0)
+Imports: httr, jsonlite, WikipediR (>= 1.4.0), utils
+Suggests: testthat, knitr, pageviews
+VignetteBuilder: knitr
+RoxygenNote: 6.0.1
NeedsCompilation: no
-Packaged: 2021-11-16 11:48:41 UTC; thoma
-Author: Thomas Shafee [aut, cre] (<https://orcid.org/0000-0002-2298-7593>),
- Os Keyes [aut] (<https://orcid.org/0000-0001-5196-609X>),
- Serena Signorelli [aut],
- Alex Lum [ctb] (<https://orcid.org/0000-0002-9295-9053>),
- Christian Graul [ctb],
- Mikhail Popov [ctb] (<https://orcid.org/0000-0003-0145-8948>)
-Maintainer: Thomas Shafee <T.Shafee@latrobe.edu.au>
-Repository: CRAN
-Date/Publication: 2021-11-16 13:00:06 UTC
+Packaged: 2023-01-19 06:03:59 UTC; root
diff --git a/LICENSE b/LICENSE
index bec4cd5..ebbb227 100644
--- a/LICENSE
+++ b/LICENSE
@@ -1,2 +1,2 @@
-YEAR: 2014
+YEAR: 2014
COPYRIGHT HOLDER: Oliver Keyes
\ No newline at end of file
diff --git a/MD5 b/MD5
deleted file mode 100644
index 2e93eb2..0000000
--- a/MD5
+++ /dev/null
@@ -1,60 +0,0 @@
-790e3888e447fa9a7cbcc4d63a96b73d *DESCRIPTION
-e327f9c01b333b34d5f1a7df9f173d5a *LICENSE
-edc3fe338aaa0a05a77de0419855160a *NAMESPACE
-cddf305289a1e1a3ef6ebf883c837099 *NEWS
-e434dc5488a1f4c6a1a329f28081e92e *R/WikidataR.R
-4427c2b2674e6691ce8bce8eca7c3201 *R/data.R
-b5dd335b1351459def84bbee4a4c7fbf *R/disambiguators.R
-eda7a783d092d2fe5ddef012b2f97aa7 *R/geo.R
-edb3a4badb64a5e8090f9317b0df9950 *R/gets.R
-3a59c9490177b80be8f70bd0d885aed1 *R/prints.R
-c926dcca2171eac71df0ce33805b6c32 *R/queries.R
-0afb790db53229f7c7ced84e8c1a6660 *R/schol.R
-2e515ebb78ab420087651f1d336c1692 *R/sysdata.rda
-6e5b17a1dbb375f035e75f017ef3de83 *R/utils.R
-506a63c3a3139139b13846f2b8088103 *R/writes.R
-bca3ae5e8073b1446ef1e5a094793c79 *R/zzz.R
-d0767f261839cda82c31e07ef225b78f *README.md
-7b80f30bc55674afdc5d922f57c5beec *inst/extdata/WD.globalvar.RDS
-6860eea8ad3721e4908e2b502b3c3377 *man/WD.globalvar.Rd
-4a2caab720ab4e94b699fe3a94df9a10 *man/WikidataR.Rd
-0361847cf40b847a86ce83b36c53c412 *man/as_pid.Rd
-7b4b40dce6e03e8b6463c3d637b44d47 *man/as_qid.Rd
-3357c8e90b7f2690477d86473b762aac *man/as_quot.Rd
-531097258c237c46b236e2b53d25e2e6 *man/as_sid.Rd
-cddc41eea6eaa0e969bbbbd081e39638 *man/check_input.Rd
-2c66c01974d576fbf99367ad1dfcbc9c *man/createrows.Rd
-cd291c37840b51a97ac0a71cca7753cb *man/createrows.tidy.Rd
-8fe82fbcd237a91657fdce38c5670aba *man/disambiguate_QIDs.Rd
-33c8946335d2d0b1565fe105ba0cd9cd *man/extract_claims.Rd
-d112f271f0b87e8cef2dec363d850d08 *man/extract_para.Rd
-e0030038b4df6950f409be20eab80eb7 *man/filter_qids.Rd
-f2cc8655e1ba912968b179de7e9e9dbd *man/find_item.Rd
-f875fadb7f30a3d35b12231407537947 *man/get_example.Rd
-ee011e5fc7af618b1b550f41d56a4b29 *man/get_geo_box.Rd
-1c0a2897ecae8d1461995400d2f35ccb *man/get_geo_entity.Rd
-d3e0400de3aeab4a298388b1d7afc723 *man/get_item.Rd
-6e11fe213d4462d36f1d688d35cced46 *man/get_names_from_properties.Rd
-9031d5dda3632005d8c399c9d349b23f *man/get_random.Rd
-280815e5921db5a91fdaa23095917333 *man/identifier_from_identifier.Rd
-9ca4ffe38247b0677dfcab081ae687cf *man/initials.Rd
-a06f92081d2c3e1ebf3ef9180861af4f *man/list_properties.Rd
-44c26e612f3e769d6c900ba002988c64 *man/print.find_item.Rd
-6ecc3a748e722646dee1af7c8412486c *man/print.find_property.Rd
-183c6117fd084489ac06b9e9abdf14c4 *man/print.wikidata.Rd
-fa760b5c26963fa55e7cc0efef5de4e1 *man/qid_from_DOI.Rd
-bbe2fc3a9e1b2ad52363a1701e1b79f8 *man/qid_from_ORCID.Rd
-e4bd57eb112c64daa8c70dfa7eeb87e5 *man/qid_from_identifier.Rd
-c89910c2f09ba27bfda77af169aad79c *man/qid_from_name.Rd
-b3e9f1a3feac2408792ade21a573f736 *man/query_wikidata.Rd
-54839ca3cc109f0f1552f7d10dea1dc4 *man/searcher.Rd
-b04adb27fcb15281dde99d1a3d2dbd45 *man/sparql_query.Rd
-3b0fadfe82ab967a623565ef1760a910 *man/unspecial.Rd
-9490a2332a673b27ede31f6b9a13776c *man/url_to_id.Rd
-be43e60ae24e7dfa179dc5cb71b51048 *man/wd_query.Rd
-3f905ae62e3178a2481a7840c28bc02b *man/wd_rand_query.Rd
-57403c2a9da6f93453029ab09ae5ea88 *man/write_wikidata.Rd
-6802883083c1500ce37088c6349f4652 *tests/testthat.R
-aae0d0411ae5b12ac04c1e77e9874f85 *tests/testthat/test_geo.R
-c6d0feb03de5a1ecc904e7acd6d41736 *tests/testthat/test_gets.R
-b8ced9b08d59231a6b29fdcfb5ccbc85 *tests/testthat/test_search.R
diff --git a/NAMESPACE b/NAMESPACE
index 2f0b1bc..a40769d 100644
--- a/NAMESPACE
+++ b/NAMESPACE
@@ -3,57 +3,17 @@
S3method(print,find_item)
S3method(print,find_property)
S3method(print,wikidata)
-export(as_pid)
-export(as_qid)
-export(as_quot)
-export(as_sid)
-export(check_input)
-export(createrows)
-export(createrows.tidy)
-export(disambiguate_QIDs)
export(extract_claims)
-export(extract_para)
-export(filter_qids)
export(find_item)
export(find_property)
-export(get_example)
export(get_geo_box)
export(get_geo_entity)
export(get_item)
-export(get_names_from_properties)
export(get_property)
export(get_random_item)
export(get_random_property)
-export(identifier_from_identifier)
-export(initials)
-export(list_properties)
-export(qid_from_DOI)
-export(qid_from_ORCID)
-export(qid_from_identifier)
-export(qid_from_name)
-export(query_wikidata)
-export(searcher)
-export(sparql_query)
-export(unspecial)
-export(url_to_id)
-export(wd_query)
-export(wd_rand_query)
-export(write_wikidata)
-import(WikidataQueryServiceR)
-import(crayon)
-import(dplyr)
-import(pbapply)
-import(progress)
-import(stringr)
-import(tibble)
-import(utils)
importFrom(WikipediR,page_content)
importFrom(WikipediR,query)
importFrom(WikipediR,random_page)
-importFrom(dplyr,bind_cols)
importFrom(httr,user_agent)
importFrom(jsonlite,fromJSON)
-importFrom(readr,format_delim)
-importFrom(readr,format_tsv)
-importFrom(stats,cor)
-importFrom(stats,var)
diff --git a/NEWS b/NEWS
index cde719e..84e9813 100644
--- a/NEWS
+++ b/NEWS
@@ -1,61 +1,33 @@
-2.3.0
-=================================================
-* New disambiguate_QIDs() function for manual item-by-item disambiguation
-
-2.2.1
-=================================================
-* Outputs as tibbles by default with vector options where relevant
-
-2.2.0
-=================================================
-* Additional 'website' output format option for write_wikidata() to submit to Quickstatements website
-* Patches to make writing wikidata statements with dates more reliable
-
-2.1.5
-=================================================
-* Updated release on CRAN
-* Expected property values and constraints from 2.1.0 now just stored as a data file, since onAttach function caused issues
-
-2.1.0
-=================================================
-* Upon loading the package, it will check whether property values are expected to be strings, numbers, dates or QIDs
-
-2.0.0
-=================================================w
-* Write_wikidata() allows you to write to wikidata via the 'quickstatements' format
-* Outputs as tibbles where relevant
-* Switch maintatiner to Thomas Shafee
-
-1.4.0
-=================================================
-* First release on CRAN!
-* Extract_claims() allows you to, well, extract claims.
-* SPARQL syntax bug with some geo queries now fixed (thanks to Mikhail Popov)
-
-1.3.0
-=================================================
-* Vectorisation of get_*() functions
-
-1.2.0
-=================================================
-* Geographic data for entities that exist relative to other Wikidata items can now be retrieved
- with get_geo_entity and get_geo_box, courtesy of excellent Serena Signorelli's excellent
- QueryWikidataR package.
-* A bug in printing returned objects is now fixed.
-
-1.1.0
-=================================================
-* You can now retrieve multiple random properties or items with get_random_item and get_random_property
-
-1.0.1
-=================================================
-* Various documentation and metadata improvements.
-
-1.0.0
-=================================================
-* Fix a bug in get_* functions due to a parameter name mismatch
-* Print methods added by Christian Graul
-
-0.5.0
-=================================================
-* This is the initial release! See the explanatory vignettes.
+1.4.0
+=================================================
+* extract_claims() allows you to, well, extract claims.
+* SPARQL syntax bug with some geo queries now fixed (thanks to Mikhail Popov)
+
+1.3.0
+=================================================
+* get_* functions are now vectorised
+
+1.2.0
+=================================================
+* geographic data for entities that exist relative to other Wikidata items can now be retrieved
+with get_geo_entity and get_geo_box, courtesy of excellent Serena Signorelli's excellent
+QueryWikidataR package.
+
+* A bug in printing returned objects is now fixed.
+
+1.1.0
+=================================================
+* You can now retrieve multiple random properties or items with get_random_item and get_random_property
+
+1.0.1
+=================================================
+* Various documentation and metadata improvements.
+
+1.0.0
+=================================================
+* Fix a bug in get_* functions due to a parameter name mismatch
+* Print methods added by Christian Graul
+
+0.5.0
+=================================================
+* This is the initial release! See the explanatory vignettes.
diff --git a/R/WikidataR.R b/R/WikidataR.R
index 3eb18f3..9614e67 100644
--- a/R/WikidataR.R
+++ b/R/WikidataR.R
@@ -1,29 +1,15 @@
-#' @title API client library for Wikidata
-#' @description This package serves as an API client for reading and writing
-#' to and from \href{https://www.wikidata.org/wiki/Wikidata:Main_Page}{Wikidata}, (including
-#' via the \href{https://quickstatements.toolforge.org/}{QuickStatements} format),
-#' as well as for reading from \href{https://www.wikipedia.org}{Wikipedia}.
-#' @name WikidataR
-#' @docType package
-#' @seealso \code{\link{get_random}} for selecting a random item or property,
-#' \code{\link{get_item}} for a /specific/ item or property, or \code{\link{find_item}}
-#' for using search functionality to pull out item or property IDs where the descriptions
-#' or aliases match a particular search term.
-#' @import WikidataQueryServiceR
-#' @import tibble
-#' @import dplyr
-#' @import stringr
-#' @import pbapply
-#' @import progress
-#' @import crayon
-#' @import utils
-#' @importFrom readr format_tsv
-#' @importFrom readr format_delim
-#' @importFrom dplyr bind_cols
-#' @importFrom stats var
-#' @importFrom stats cor
-#' @importFrom WikipediR page_content random_page query
-#' @importFrom httr user_agent
-#' @importFrom jsonlite fromJSON
-#' @aliases WikidataR WikidataR-package
+#' @title API client library for Wikidata
+#' @description This package serves as an API client for \href{Wikidata}{https://www.wikidata.org}.
+#' See the accompanying vignette for more details.
+#'
+#' @name WikidataR
+#' @docType package
+#'@seealso \code{\link{get_random}} for selecting a random item or property,
+#'\code{\link{get_item}} for a /specific/ item or property, or \code{\link{find_item}}
+#'for using search functionality to pull out item or property IDs where the descriptions
+#'or aliases match a particular search term.
+#' @importFrom WikipediR page_content random_page query
+#' @importFrom httr user_agent
+#' @importFrom jsonlite fromJSON
+#' @aliases WikidataR WikidataR-package
NULL
\ No newline at end of file
diff --git a/R/data.R b/R/data.R
deleted file mode 100644
index 87e046c..0000000
--- a/R/data.R
+++ /dev/null
@@ -1,18 +0,0 @@
-#' @name WD.globalvar
-#'
-#' @title Global variables for Wikidata properties
-#'
-#' @description A dataset of Wikidata global variables.
-#'
-#' @format A list of tibbles documenting key property constraints from wikidata
-#' \describe{
-#' \item{SID.valid}{valid reference source properties}
-#' \item{PID.datatype}{required data type for each property}
-#' \item{PID.constraint}{expected regex match for each property}
-#' \item{lang.abbrev}{language abbreviations}
-#' \item{lang.abbrev.wiki}{language abbreviations for current wikis}
-#' \item{abbrev.wiki}{Wikimedia abbreviations for current wikis}
-#' ...
-#' }
-
-utils::globalVariables(c("WD.globalvar"))
\ No newline at end of file
diff --git a/R/disambiguators.R b/R/disambiguators.R
deleted file mode 100644
index 3bce992..0000000
--- a/R/disambiguators.R
+++ /dev/null
@@ -1,366 +0,0 @@
-# -------- Disambiguator functions --------
-#
-#'@title Disambiguate QIDs
-#'@description Interactive function that presents alternative possible QID matches for a list of text
-#'strings and provides options for choosing between alternatives, rejecting all presented alternatives,
-#'or creating new items. Useful in cases where a list of text strings may have either missing wikidata items
-#'or multiple alternative potential matches that need to be manually disambuguated. Can also used on
-#'lists of lists (see examples). For long lists of items, the process can be stopped partway through and
-#'the returned vector will indicate where the process was stopped.
-#'@param list a list or vector of text strings to find potential QID matches to.
-#' Can also be a list of lists (see examples)
-#'@param variablename type of items in the list that are being disambiguated (used in messages)
-#'@param variableinfo additional information about items that are being disambiguated (used in messages)
-#'@param filter_property property to filter on (e.g. "P31" to filter on "instance of")
-#'@param filter_variable values of that property to use to filter out (e.g. "Q571" to filter out books)
-#'@param filter_firsthit apply filter to the first match presented or only if alternatives requested?
-#' (default = FALSE, note: true is slower if filter not needed on most matches)
-#'@param limit number of alternative possible wikidata items to present if multiple potential matches
-#'@return a vector of:
-#' \describe{
-#' \item{QID}{Selected QID (for when an appropriate Wikidata match exists)}
-#' \item{CREATE}{Mark that a new Wikidata item should be created (for when no appropriate Wikidata match yet exists)}
-#' \item{NA}{Mark that no Wikidata item is needed}
-#' \item{STOP}{Mark that the process was halted at this point (so that output can be used as input to the function later)}
-#' }
-#'@examples
-#'\dontrun{
-#'#Disambiguating possible QID matches for these music genres
-#'#Results should be:
-#'# "Q22731" as the first match
-#'# "Q147538" as the first match
-#'# "Q3947" as the second alternative match
-#'disambiguate_QIDs(list=c("Rock","Pop","House"),
-#' variablename="music genre")
-#'
-#'#Disambiguating possible QID matches for these three words, but not the music genres
-#'#This will take longer as the filtering step is slower
-#'#Results should be:
-#'# "Q22731" (the material) as the first match
-#'# "Q147538" (the soft drink) as the second alternative match
-#'# "Q3947" (the building) as the first match
-#'disambiguate_QIDs(list=c("Rock","Pop","House"),
-#' filter_property="instance of",
-#' filter_variable="music genre",
-#' filter_firsthit=TRUE,
-#' variablename="concept, not the music genre")
-#'
-#'#Disambiguating possible QID matches for the multiple expertise of
-#'#these three people as list of lists
-#'disambiguate_QIDs(list=list(alice=list("physics","chemistry","maths"),
-#' barry=list("history"),
-#' clair=list("law","genetics","ethics")),
-#' variablename="expertise")
-#'}
-#'@export
-disambiguate_QIDs <- function(list,
- variablename="variables",
- variableinfo=NULL,
- filter_property=NULL,
- filter_variable=NULL,
- filter_firsthit=FALSE,
- limit=10){
- #make list is formatted as a list (e.g. if vector)
- if(!all(class(list)=="list")){list <- as.list(list)}
- if(!is.null(filter_property)){filter_property <- as_pid(filter_property)[[1]][1]}
- if(!is.null(filter_variable)){filter_variable <- as_qid(filter_variable)[[1]][1]}
-
- #is the list the outut from a previous half-done run?
- if(any(unlist(lapply(list,function(x) x=="STOP")),na.rm = TRUE)){
- item_to_start_from <- which(unlist(lapply(list,function(x) any(x=="STOP"))))
- subitem_to_start_from <- first(which(list == "STOP"))
- output <- list
- }else{
- item_to_start_from <- 1
- subitem_to_start_from <- 1
- output <- blank_output_list(list)
- }
-
- #create output
- pb_main <- progress_bar$new(total = sum(unlist(output,recursive = TRUE)==""|unlist(output,recursive = TRUE)=="STOP"),
- format = ":bar :percent eta::eta \n",
- current = "|",
- width = 90,
- show_after = 0)
- for(item in item_to_start_from:length(list)){
- for(subitem in subitem_to_start_from:length(list[[item]])){
- #check item to search
- tosearch <- list[[item]][subitem]
- if(is.na(tosearch)){break} #skip NAs
- if(tosearch=="STOP"|tosearch==""){tosearch<-names(tosearch)} #use name for items not done in previous run (stored as "STOP" and "")
- if(grepl("^[Qq][0-9]+$",tosearch)){break} #skip if already a QID
- if(is.null(tosearch)){break} #skip nulls or empty items with no name (usually errors)
- list[[item]][subitem] <- tosearch #if no skips, place that text back in the list
-
- #announce choice to be made
- message_header(list,item,subitem,variablename,variableinfo)
- pb_main$tick()
- #execute search and record choice
- if(filter_firsthit){
- first_hit_qid <- firsthit(list[[item]][subitem],filter_property,filter_variable)
- }else{
- first_hit_qid <- firsthit(list[[item]][subitem])
- }
- choice <- makechoice(qid = first_hit_qid,
- text= names(first_hit_qid),
- filter_property=filter_property,
- filter_variable=filter_variable,
- limit=limit)
- output[[item]][[subitem]] <- choice
- names(output[[item]])[[subitem]] <- names(choice)
-
- #check if stop request made
- if(!is.na(output[[item]][[subitem]])){if(output[[item]][[subitem]]=="STOP"){
- done_so_far <- item
- message_stop(done_so_far,total = length(list))
- break
- }}
- }
- subitem_to_start_from <- 1 # reset the subitem to start from if completed a full item
- if(!is.na(output[[item]][[subitem]])){if(output[[item]][[subitem]]=="STOP"){break}}
- }
- return(output)
-}
-
-# When provided with a QID, interactively make a decision on whether the output should be that qid or some other value
-makechoice <- function(qid=NULL,
- text=NULL,
- table=NULL,
- filter_property=NULL,
- filter_variable=NULL,
- limit=10){
- if(is.null(text)){
- text <- names(qid)
- }
-
- # announce item for disambig
- suppressWarnings(invisible(selection <- readline()))
- if (selection=="s"|selection=="stop"){ #s = stop
- output <- "STOP"
- names(output) <- text
-
- }else if(selection=="y"|selection=="yes"){ #y = accept
- output <- qid
- names(output) <- text
-
- }else if(selection=="n"|selection=="no"|selection==""){ #n = reject
- output <- NA
- names(output) <- text
-
- }else if(selection=="c"|selection=="create"){ #c = create
- output <- "CREATE"
- names(output) <- text
-
- }else if(selection=="?"){ #? = loop up in browser
- browseURL(paste0("https://www.wikidata.org/wiki/",qid))
- output <- makechoice(qid,text,table,filter_property,filter_variable,limit)
-
- }else if(grepl("^[Qq][0-9]+$",selection)){ #Q123 = id
- output <- selection
- names(output) <- paste0("-> ",selection)
-
- }else if(grepl("^[Qq][0-9]+?$",selection)){ #Q123? = search that id
- browseURL(paste0("https://www.wikidata.org/wiki/",
- gsub("\\?","",selection)))
- output <- makechoice(qid,text,table,filter_property,filter_variable,limit)
-
- }else if(grepl("^[0-9]+$",selection) & !is.null(table)){ #number = select row
- output <- table$qid[as.numeric(selection)]
- label <- table$label[as.numeric(selection)]
-
- }else if(grepl("^[0-9]+\\?$",selection)& !is.null(table)){ #number? = loop up row in browser
- browseURL(paste0("https://www.wikidata.org/wiki/",
- table$qid[as.numeric(gsub("\\?","",selection))]))
- output <- makechoice(qid,text,table,filter_property,filter_variable,limit)
- label <- table$label[as.numeric(selection)]
-
- }else if((selection=="a"|selection=="alt") & !is.null(text)){ #a = alternative
- table <- choices_alt(text,filter_property,filter_variable,limit)
- output <- makechoice(qid,text,table,filter_property,filter_variable,limit)
- if(!is.null(names(output)) & !is.null(text)){if(names(output)!=text){
- names(output) <- paste0(text," -> ",names(output))
- }}
-
- }else{ #freetext = freetext to search
- table <- choices_alt(selection,filter_property,filter_variable,limit)
- output <- makechoice(qid,selection,table,filter_property,filter_variable,limit)
- if(!is.null(names(output)) & !is.null(text)){if(names(output)!=text){
- names(output) <- paste0(text," -> ",names(output))
- }}
- }
-
- return(output)
-}
-
-# -------- Messages --------
-
-# Clear console and show standard header for
-message_header <- function(list,
- i,
- j,
- variablename=NULL,
- variableinfo=NULL){
- list <- as.list(list)
- name <- bold$cyan(names(list)[[i]])
- variables <- list[[i]]
- variables[j] <- bold$white$underline(variables[j])
- variables <- paste(variables,collapse = " | ")
- if(!is.null(variablename)){
- variablename <- paste0("the ",variablename," of ")
- }else{
- variablename <- NULL
- }
- if(!is.null(variableinfo)){
- variableinfo <- paste0(variableinfo,"\n")
- }else{
- variableinfo <- NULL
- }
- message("\014",
- "--------------------------------------------------------------------------- \n",
- "Let's disambiguate ",variablename,
- name, ": \n",
- variableinfo,
- variables)
-}
-
-message_choices <- function(){
- message(bold(" y "),"-> accept the presented match \n",
- bold(" n "),"-> reject the presented match and move on to the next \n",
- bold(" a "),"-> request alternative possible matches \n",
- bold(" Q123 "),"-> use this as the wikidata QID \n",
- bold(" text "),"-> try this text as alternative search term \n",
- bold(" c "),"-> create a new item for this later \n",
- bold(" s "),"-> stop here, save those done so far and come back later \n",
- bold(" ? "),"-> check the presented match in your browser")
-}
-
-message_choices_na <- function(){
- message(bold(" y/n "),"-> leave as 'NA' \n",
- bold(" Q123 "),"-> use this as the wikidata QID \n",
- bold(" text "),"-> try this text as alternative search term \n",
- bold(" c "),"-> create a new item for this later \n",
- bold(" s "),"-> stop here, save those done so far and come back later")
-}
-
-message_choices_alt <- function(table){
- message("Are any of these appropriate?")
- print(data.frame(table),right=FALSE)
- message(bold(" number "),"-> select one of the matches presented (include ",bold("?")," to check an item in your browser) \n",
- bold(" Q123 "),"-> use this as the wikidata QID \n",
- bold(" text "),"-> try this text as alternative search term \n",
- bold(" c "),"-> create a new item for this later \n",
- bold(" s "),"-> stop here, save those done so far and come back later")
-}
-
-message_stop <- function(done_so_far,total){
- message("Stopping. You've completed ",
- bold$white(done_so_far - 1),
- " so far (",
- bold$white(total - done_so_far + 1),
- " remaining). \n",
- "To restart from where you left off, use the output from this function as the list for disambiguate_QIDs()")
-}
-
-
-# -------- Misc. support --------
-
-# pulling and formatting the first hit from wikidata
-# and presenting appropriate choice text options in prep for makechoice()
-firsthit <- function(text,
- filter_property=NULL,
- filter_variable=NULL,
- limit=10){
- if(!is.null(filter_property) & !is.null(filter_variable)){
- filtered_items <- filter_qids(ids=sapply(find_item(text,limit = limit),"[[",1),
- property=filter_property,
- filter=filter_variable,
- message="Checking for item that doesn't match the filter ")
- if(!is.na(filtered_items$qid[1])){
- qid <- filtered_items$qid[1]
- label <- filtered_items$label[1]
- desc <- filtered_items$desc[1]
- message(white(qid," ",label," ",desc,sep=""))
- message_choices()
- }else{
- qid <- NA
- message(white("No good match found that matches filters"))
- message_choices_na()
- }
- }else{
- item <- find_item(text,limit = 1)
- if(length(item)>0){
- if(is.null(item[[1]]$description)){
- desc <- "no description"
- }else{
- desc <- item[[1]]$description
- }
- if(is.null(item[[1]]$label)){
- label <- "no label"
- }else{
- label <- item[[1]]$label
- }
- qid <- item[[1]]$id
- message(white(qid," ",label," ",desc,sep=""))
- message_choices()
- }else{
- qid <- NA
- message(white("No good match found"))
- message_choices_na()
- }
- }
- names(qid) <- text
- return(qid)
-}
-
-blank_output_list <- function(list){
- make_attr_names <- function(x){
- x1 <- list[[x]]
- attr(x1, 'names') <- x1
- x1
- }
- if(all(is.null(names(list)))){
- output <- list
- names(output) <- list
- }else{
- output <- lapply(names(list), make_attr_names)
- names(output) <- names(list)
- }
- output <- rapply(output,function(x) ifelse(is.na(x),NA,""),how = 'replace')
- return(output)
-}
-
-
-restarted_output_list <- function(list){
- make_attr_names_rev <- function(x){
- x1 <- list[[x]]
- x1 <- attr(x1, 'names')
- x1
- }
- listnames <- lapply(names(list), make_attr_names_rev)
- output <- rapply(output,function(x) ifelse(is.na(x),NA,""),how = 'replace')
- return(output)
-}
-
-choices_alt <- function(selection,filter_property,filter_variable,limit){
- altqids <- unlist(lapply(find_item(selection,limit=limit),function(x) x$id))
- if(is.null(altqids)){
- message("Searching for ",bold$white(selection)," as an alternative term")
- results <- tibble(qid=NA,
- label=NA,
- desc="No current matching Wikidata item")
- }else{
- message("Searching for ",bold$white(selection)," as an alternative term")
- results <- filter_qids(ids = altqids,
- property = filter_property,
- filter = filter_variable)
- }
- if(all(is.na(results$qid))){
- message(white("No good match found"))
- message_choices_na()
- return(NULL)
- }else{
- message_choices_alt(results)
- names(results$qid) <- results$label
- return(results)
- }
-}
diff --git a/R/geo.R b/R/geo.R
index a993fa6..37efdff 100644
--- a/R/geo.R
+++ b/R/geo.R
@@ -1,189 +1,182 @@
-#'@title Retrieve geographic information from Wikidata
-#'@description \code{get_geo_entity} retrieves the item ID, latitude
-#'and longitude of any object with geographic data associated with \emph{another}
-#'object with geographic data (example: all the locations around/near/associated with
-#'a city).
-#'
-#'@param entity a Wikidata item (\code{Q...}) or series of items, to check
-#'for associated geo-tagged items.
-#'
-#'@param language the two-letter language code to use for the name
-#'of the item. "en" by default, because we're imperialist
-#'anglocentric westerners.
-#'
-#'@param radius optionally, a radius (in kilometers) around \code{entity}
-#'to restrict the search to.
-#'
-#'@param limit the maximum number of results to return.
-#'
-#'@param \\dots further arguments to pass to httr's GET.
-#'
-#'@return a data.frame of 5 columns:
-#'\itemize{
-#' \item{item}{ the Wikidata identifier of each object associated with
-#' \code{entity}.}
-#' \item{name}{ the name of the item, if available, in the requested language. If it
-#' is not available, \code{NA} will be returned instead.}
-#' \item{latitude}{ the latitude of \code{item}}
-#' \item{longitude}{ the longitude of \code{item}}
-#' \item{entity}{ the entity the item is associated with (necessary for multi-entity
-#' queries).}
-#'}
-#'
-#'@examples
-#'# All entities
-#'\donttest{sf_locations <- get_geo_entity("Q62")}
-#'
-#'# Entities with French, rather than English, names
-#'\donttest{sf_locations <- get_geo_entity("Q62", language = "fr")}
-#'
-#'# Entities within 1km
-#'\donttest{sf_close_locations <- get_geo_entity("Q62", radius = 1)}
-#'
-#'# Multiple entities
-#'\donttest{multi_entity <- get_geo_entity(entity = c("Q62", "Q64"))}
-#'
-#'@seealso \code{\link{get_geo_box}} for using a bounding box
-#'rather than an unrestricted search or simple radius.
-#'
-#'@export
-get_geo_entity <- function(entity, language = "en", radius = NULL, limit=100, ...){
-
- entity <- check_input(entity, "Q")
-
- if(is.null(radius)){
- query <- paste0("SELECT DISTINCT ?item ?name ?coord ?propertyLabel WHERE {
- ?item wdt:P131* wd:", entity, ". ?item wdt:P625 ?coord .
- SERVICE wikibase:label {
- bd:serviceParam wikibase:language \"", language, "\" .
- ?item rdfs:label ?name
- }
- }
- ORDER BY ASC (?name)
- LIMIT ", limit)
- } else {
- query <- paste0("SELECT ?item ?name ?coord
- WHERE {
- wd:", entity, " wdt:P625 ?mainLoc .
- SERVICE wikibase:around {
- ?item wdt:P625 ?coord .
- bd:serviceParam wikibase:center ?mainLoc .
- bd:serviceParam wikibase:radius \"", radius,
- "\" .
- }
- SERVICE wikibase:label {
- bd:serviceParam wikibase:language \"", language, "\" .
- ?item rdfs:label ?name
- }
- } ORDER BY ASC (?name)
- LIMIT ",limit)
- }
-
- if(length(query) > 1){
- return(do.call("rbind", mapply(function(query, entity, ...){
- output <- clean_geo(sparql_query(query, ...)$results$bindings)
- output$entity <- entity
- return(output)
- }, query = query, entity = entity, SIMPLIFY = FALSE, ...)))
- }
- output <- clean_geo(sparql_query(query)$results$bindings)
- if(length(output)==0){warning("Query timeout. Possibly try again with lower 'limit='")}
- output$entity <- entity
- return(output)
-}
-
-#'@title Get geographic entities based on a bounding box
-#'@description \code{get_geo_box} retrieves all geographic entities in
-#'Wikidata that fall between a bounding box between two existing items
-#'with geographic attributes (usually cities).
-#'
-#'@param first_city_code a Wikidata item, or series of items, to use for
-#'one corner of the bounding box.
-#'
-#'@param first_corner the direction of \code{first_city_code} relative
-#'to \code{city} (eg "NorthWest", "SouthEast").
-#'
-#'@param second_city_code a Wikidata item, or series of items, to use for
-#'one corner of the bounding box.
-#'
-#'@param second_corner the direction of \code{second_city_code} relative
-#'to \code{city} (eg "NorthWest", "SouthEast").
-#'
-#'@param language the two-letter language code to use for the name
-#'of the item. "en" by default.
-#'
-#'@param \\dots further arguments to pass to httr's GET.
-#'
-#'@return a data.frame of 5 columns:
-#'\itemize{
-#' \item{item}{ the Wikidata identifier of each object associated with
-#' \code{entity}.}
-#' \item{name}{ the name of the item, if available, in the requested language. If it
-#' is not available, \code{NA} will be returned instead.}
-#' \item{latitude}{ the latitude of \code{item}}
-#' \item{longitude}{ the longitude of \code{item}}
-#' \item{entity}{ the entity the item is associated with (necessary for multi-entity
-#' queries).}
-#'}
-#'
-#'@examples
-#'# Simple bounding box
-#'\donttest{bruges_box <- get_geo_box("Q12988", "NorthEast", "Q184287", "SouthWest")}
-#'
-#'# Custom language
-#'\donttest{bruges_box_fr <- get_geo_box("Q12988", "NorthEast", "Q184287", "SouthWest",
-#' language = "fr")}
-#'
-#'@seealso \code{\link{get_geo_entity}} for using an unrestricted search or simple radius,
-#'rather than a bounding box.
-#'
-#'@export
-get_geo_box <- function(first_city_code, first_corner, second_city_code, second_corner,
- language = "en", ...){
-
- # Input checks
- first_city_code <- check_input(first_city_code, "Q")
- second_city_code <- check_input(second_city_code, "Q")
-
- # Construct query
- query <- paste0("SELECT ?item ?name ?coord WHERE {
- wd:", first_city_code, " wdt:P625 ?Firstloc .
- wd:", second_city_code, " wdt:P625 ?Secondloc .
- SERVICE wikibase:box {
- ?item wdt:P625 ?coord .
- bd:serviceParam wikibase:corner", first_corner, " ?Firstloc .
- bd:serviceParam wikibase:corner", second_corner, " ?Secondloc .
- }
- SERVICE wikibase:label {
- bd:serviceParam wikibase:language \"", language, "\" .
- ?item rdfs:label ?name
- }
- }ORDER BY ASC (?name)")
-
- # Vectorise if necessary, or not if not!
- if(length(query) > 1){
- return(do.call("rbind", mapply(function(query, ...){
- output <- clean_geo(sparql_query(query, ...)$results$bindings)
- return(output)
- }, query = query, ..., SIMPLIFY = FALSE)))
- }
- output <- clean_geo(sparql_query(query)$results$bindings)
- return(output)
-}
-
-
-# Cleanup function
-clean_geo <- function(results){
- do.call("rbind", lapply(results, function(item){
- point <- unlist(strsplit(gsub(x = item$coord$value, pattern = "(Point\\(|\\))", replacement = ""),
- " "))
- wd_id <- gsub(x = item$item$value, pattern = "http://www.wikidata.org/entity/",
- replacement = "", fixed = TRUE)
- return(data.frame(item = wd_id,
- name = ifelse(item$name$value == wd_id, NA, item$name$value),
- latitutde = as.numeric(point[1]),
- longitude = as.numeric(point[2]),
- stringsAsFactors = FALSE))
-
- }))
-}
+clean_geo <- function(results){
+ do.call("rbind", lapply(results, function(item){
+ point <- unlist(strsplit(gsub(x = item$coord$value, pattern = "(Point\\(|\\))", replacement = ""),
+ " "))
+ wd_id <- gsub(x = item$item$value, pattern = "http://www.wikidata.org/entity/",
+ replacement = "", fixed = TRUE)
+ return(data.frame(item = wd_id,
+ name = ifelse(item$name$value == wd_id, NA, item$name$value),
+ latitutde = as.numeric(point[1]),
+ longitude = as.numeric(point[2]),
+ stringsAsFactors = FALSE))
+
+ }))
+}
+
+#'@title Retrieve geographic information from Wikidata
+#'@description \code{get_geo_entity} retrieves the item ID, latitude
+#'and longitude of any object with geographic data associated with \emph{another}
+#'object with geographic data (example: all the locations around/near/associated with
+#'a city).
+#'
+#'@param entity a Wikidata item (\code{Q...}) or series of items, to check
+#'for associated geo-tagged items.
+#'
+#'@param language the two-letter language code to use for the name
+#'of the item. "en" by default, because we're imperialist
+#'anglocentric westerners.
+#'
+#'@param radius optionally, a radius (in kilometers) around \code{entity}
+#'to restrict the search to.
+#'
+#'@param ... further arguments to pass to httr's GET.
+#'
+#'@return a data.frame of 5 columns:
+#'\itemize{
+#' \item{item}{ the Wikidata identifier of each object associated with
+#' \code{entity}.}
+#' \item{name}{ the name of the item, if available, in the requested language. If it
+#' is not available, \code{NA} will be returned instead.}
+#' \item{latitude}{ the latitude of \code{item}}
+#' \item{longitude}{ the longitude of \code{item}}
+#' \item{entity}{ the entity the item is associated with (necessary for multi-entity
+#' queries).}
+#'}
+#'
+#'@examples
+#'# All entities
+#'sf_locations <- get_geo_entity("Q62")
+#'
+#'# Entities with French, rather than English, names
+#'sf_locations <- get_geo_entity("Q62", language = "fr")
+#'
+#'# Entities within 1km
+#'sf_close_locations <- get_geo_entity("Q62", radius = 1)
+#'
+#'# Multiple entities
+#'multi_entity <- get_geo_entity(entity = c("Q62", "Q64"))
+#'
+#'@seealso \code{\link{get_geo_box}} for using a bounding box
+#'rather than an unrestricted search or simple radius.
+#'
+#'@export
+get_geo_entity <- function(entity, language = "en", radius = NULL, ...){
+
+ entity <- check_input(entity, "Q")
+
+ if(is.null(radius)){
+ query <- paste0("SELECT DISTINCT ?item ?name ?coord ?propertyLabel WHERE {
+ ?item wdt:P131* wd:", entity, ". ?item wdt:P625 ?coord .
+ SERVICE wikibase:label {
+ bd:serviceParam wikibase:language \"", language, "\" .
+ ?item rdfs:label ?name
+ }
+ }
+ ORDER BY ASC (?name)")
+ } else {
+ query <- paste0("SELECT ?item ?name ?coord
+ WHERE {
+ wd:", entity, " wdt:P625 ?mainLoc .
+ SERVICE wikibase:around {
+ ?item wdt:P625 ?coord .
+ bd:serviceParam wikibase:center ?mainLoc .
+ bd:serviceParam wikibase:radius \"", radius,
+ "\" .
+ }
+ SERVICE wikibase:label {
+ bd:serviceParam wikibase:language \"", language, "\" .
+ ?item rdfs:label ?name
+ }
+ } ORDER BY ASC (?name)")
+ }
+
+ if(length(query) > 1){
+ return(do.call("rbind", mapply(function(query, entity, ...){
+ output <- clean_geo(sparql_query(query, ...)$results$bindings)
+ output$entity <- entity
+ return(output)
+ }, query = query, entity = entity, ..., SIMPLIFY = FALSE)))
+ }
+ output <- clean_geo(sparql_query(query)$results$bindings)
+ output$entity <- entity
+ return(output)
+}
+
+#'@title Get geographic entities based on a bounding box
+#'@description \code{get_geo_box} retrieves all geographic entities in
+#'Wikidata that fall between a bounding box between two existing items
+#'with geographic attributes (usually cities).
+#'
+#'@param first_city_code a Wikidata item, or series of items, to use for
+#'one corner of the bounding box.
+#'
+#'@param first_corner the direction of \code{first_city_code} relative
+#'to \code{city} (eg "NorthWest", "SouthEast").
+#'
+#'@param second_city_code a Wikidata item, or series of items, to use for
+#'one corner of the bounding box.
+#'
+#'@param second_corner the direction of \code{second_city_code} relative
+#'to \code{city} (eg "NorthWest", "SouthEast").
+#'
+#'@param language the two-letter language code to use for the name
+#'of the item. "en" by default.
+#'
+#'@param ... further arguments to pass to httr's GET.
+#'
+#'@return a data.frame of 5 columns:
+#'\itemize{
+#' \item{item}{ the Wikidata identifier of each object associated with
+#' \code{entity}.}
+#' \item{name}{ the name of the item, if available, in the requested language. If it
+#' is not available, \code{NA} will be returned instead.}
+#' \item{latitude}{ the latitude of \code{item}}
+#' \item{longitude}{ the longitude of \code{item}}
+#' \item{entity}{ the entity the item is associated with (necessary for multi-entity
+#' queries).}
+#'}
+#'
+#'@examples
+#'# Simple bounding box
+#'bruges_box <- WikidataR:::get_geo_box("Q12988", "NorthEast", "Q184287", "SouthWest")
+#'
+#'# Custom language
+#'bruges_box_fr <- WikidataR:::get_geo_box("Q12988", "NorthEast", "Q184287", "SouthWest",
+#' language = "fr")
+#'
+#'@seealso \code{\link{get_geo_entity}} for using an unrestricted search or simple radius,
+#'rather than a bounding box.
+#'
+#'@export
+get_geo_box <- function(first_city_code, first_corner, second_city_code, second_corner,
+ language = "en", ...){
+
+ # Input checks
+ first_city_code <- check_input(first_city_code, "Q")
+ second_city_code <- check_input(second_city_code, "Q")
+
+ # Construct query
+ query <- paste0("SELECT ?item ?name ?coord WHERE {
+ wd:", first_city_code, " wdt:P625 ?Firstloc .
+ wd:", second_city_code, " wdt:P625 ?Secondloc .
+ SERVICE wikibase:box {
+ ?item wdt:P625 ?coord .
+ bd:serviceParam wikibase:corner", first_corner, " ?Firstloc .
+ bd:serviceParam wikibase:corner", second_corner, " ?Secondloc .
+ }
+ SERVICE wikibase:label {
+ bd:serviceParam wikibase:language \"", language, "\" .
+ ?item rdfs:label ?name
+ }
+ }ORDER BY ASC (?name)")
+
+ # Vectorise if necessary, or not if not!
+ if(length(query) > 1){
+ return(do.call("rbind", mapply(function(query, ...){
+ output <- clean_geo(sparql_query(query, ...)$results$bindings)
+ return(output)
+ }, query = query, ..., SIMPLIFY = FALSE)))
+ }
+ output <- clean_geo(sparql_query(query)$results$bindings)
+ return(output)
+}
\ No newline at end of file
diff --git a/R/gets.R b/R/gets.R
index 4ec01b9..2a9c5ce 100644
--- a/R/gets.R
+++ b/R/gets.R
@@ -1,205 +1,127 @@
-# -------- Gets --------
-
-#'@title Retrieve specific Wikidata items or properties
-#'@description \code{get_item} and \code{get_property} allow you to retrieve the data associated
-#'with individual Wikidata items and properties, respectively. As with
-#'other \code{WikidataR} code, custom print methods are available; use \code{\link{str}}
-#'to manipulate and see the underlying structure of the data.
-#'
-#'@param id the ID number(s) of the item or property you're looking for. This can be in
-#'various formats; either a numeric value ("200"), the full name ("Q200") or
-#'even with an included namespace ("Property:P10") - the function will format
-#'it appropriately. This function is vectorised and will happily accept
-#'multiple IDs.
-#'
-#'@param \\dots further arguments to pass to httr's GET.
-#'
-#'@seealso \code{\link{get_random}} for selecting a random item or property,
-#'or \code{\link{find_item}} for using search functionality to pull out
-#'item or property IDs where the descriptions or aliases match a particular
-#'search term.
-#'
-#'@examples
-#'
-#'#Retrieve a specific item
-#'adams_metadata <- get_item("42")
-#'
-#'#Retrieve a specific property
-#'object_is_child <- get_property("P40")
-#'
-#'@aliases get_item get_property
-#'@rdname get_item
-#'@export
-get_item <- function(id, ...){
- id <- check_input(id, "Q")
- output <- (lapply(id, wd_query, ...))
- class(output) <- "wikidata"
- return(output)
-}
-
-#'@rdname get_item
-#'@export
-get_property <- function(id, ...){
- has_grep <- grepl("^P(?!r)",id, perl = TRUE)
- id[has_grep] <- paste0("Property:", id[has_grep])
- id <- check_input(id, "Property:P")
-
- output <- (lapply(id, wd_query, ...))
- class(output) <- "wikidata"
- return(output)
-}
-
-#'@title Retrieve randomly-selected Wikidata items or properties
-#'@description \code{get_random_item} and \code{get_random_property} allow you to retrieve the data
-#'associated with randomly-selected Wikidata items and properties, respectively. As with
-#'other \code{WikidataR} code, custom print methods are available; use \code{\link{str}}
-#'to manipulate and see the underlying structure of the data.
-#'
-#'@param limit how many random items to return. 1 by default, but can be higher.
-#'
-#'@param \\dots arguments to pass to httr's GET.
-#'
-#'@seealso \code{\link{get_item}} for selecting a specific item or property,
-#'or \code{\link{find_item}} for using search functionality to pull out
-#'item or property IDs where the descriptions or aliases match a particular
-#'search term.
-#'
-#'@examples
-#'\dontrun{
-#'#Random item
-#'random_item <- get_random_item()
-#'
-#'#Random property
-#'random_property <- get_random_property()
-#'}
-#'@aliases get_random get_random_item get_random_property
-#'@rdname get_random
-#'@export
-get_random_item <- function(limit = 1, ...){
- return(wd_rand_query(ns = 0, limit = limit, ...))
-}
-
-#'@rdname get_random
-#'@export
-get_random_property <- function(limit = 1, ...){
- return(wd_rand_query(ns = 120, limit = limit, ...))
-}
-
-
-#' @title Get an example SPARQL query from Wikidata
-#' @description Gets the specified example(s) from
-#' [SPARQL query service examples page](https://www.wikidata.org/wiki/Wikidata:SPARQL_query_service/queries/examples)
-#' using [Wikidata's MediaWiki API](https://www.wikidata.org/w/api.php).
-#' @details If you are planning on extracting multiple examples, please provide
-#' all the names as a single vector for efficiency.
-#' @param example_name the names of the examples as they appear on
-#' [this page](https://www.wikidata.org/wiki/Wikidata:SPARQL_query_service/queries/examples)
-#' @return The SPARQL query as a character vector.
-#' @examples
-#' \dontrun{
-#' sparql_query <- extract_example(c("Cats", "Horses"))
-#' query_wikidata(sparql_query)
-#' # returns a named list with two data frames
-#' # one called "Cats" and one called "Horses"
-#' sparql_query <- extract_example("Largest cities with female mayor")
-#' cat(sparql_query)
-#' query_wikidata(sparql_query)
-#' }
-#' @seealso [query_wikidata]
-#' @export
-get_example <- function(example_name){
- content <- WikipediR::page_content(
- domain = "www.wikidata.org",
- page_name = "Wikidata:SPARQL query service/queries/examples",
- as_wikitext = TRUE
- )
- wiki <- strsplit(content$parse$wikitext$`*`, "\n")[[1]]
- wiki <- wiki[wiki != ""]
- return(vapply(example_name, function(example_name){
- heading_line <- which(grepl(paste0("^===\\s?", example_name, "\\s?===$"), wiki, fixed = FALSE))
- start_line <- which(grepl("{{SPARQL", wiki[(heading_line + 1):length(wiki)], fixed = TRUE))[1]
- end_line <- which(grepl("}}", wiki[(heading_line + start_line + 1):length(wiki)], fixed = TRUE))[1]
- query <- paste0(wiki[(heading_line + start_line):(heading_line + start_line + end_line - 1)], collapse = "\n")
- return(sub("^\\s*\\{\\{SPARQL2?\\n?\\|query\\=", "", query))
- }, ""))
-}
-
-
-# -------- Finds --------
-
-#'@title Search for Wikidata items or properties that match a search term
-#'@description \code{find_item} and \code{find_property} allow you to retrieve a set
-#'of Wikidata items or properties where the aliase or descriptions match a particular
-#'search term. As with other \code{WikidataR} code, custom print methods are available;
-#'use \code{\link{str}} to manipulate and see the underlying structure of the data.
-#'
-#'@param search_term a term to search for.
-#'
-#'@param language the language to return the labels and descriptions in; this should
-#'consist of an ISO language code. Set to "en" by default.
-#'
-#'@param limit the number of results to return; set to 10 by default.
-#'
-#'@param \\dots further arguments to pass to httr's GET.
-#'
-#'@seealso \code{\link{get_random}} for selecting a random item or property,
-#'or \code{\link{get_item}} for selecting a specific item or property.
-#'
-#'@examples
-#'
-#'#Check for entries relating to Douglas Adams in some way
-#'adams_items <- find_item("Douglas Adams")
-#'
-#'#Check for properties involving the peerage
-#'peerage_props <- find_property("peerage")
-#'
-#'@aliases find_item find_property
-#'@rdname find_item
-#'@export
-find_item <- function(search_term, language = "en", limit = 10, ...){
- res <- searcher(search_term, language, limit, "item")
- class(res) <- "find_item"
- return(res)
-}
-
-#'@rdname find_item
-#'@export
-find_property <- function(search_term, language = "en", limit = 10){
- res <- searcher(search_term, language, limit, "property")
- class(res) <- "find_property"
- return(res)
-}
-
-#Generic, direct access to Wikidata's search functionality.
-#'@title Convert an input to a item QID
-#'@description Convert an input string to the most likely item QID
-#'@param search_term a term to search for.
-#'@param language the language to return the labels and descriptions in; this should
-#'consist of an ISO language code. Set to "en" by default.
-#'@param limit the number of results to return; set to 10 by default.
-#'@param type type of wikidata object to return (default = "item")
-#'@param \\dots Additional parameters to supply to [httr::POST]
-#'@return If the inputted string matches an item label, return its QID.
-#'If the inputted string matches multiple labels of multiple items, return the QID of the first hit.
-#'If the inputted string is already a QID, return the string.
-#'@examples
-#'# if input string is a valid QID
-#'as_qid("Q42")
-#'# if input string matches multiple item labels
-#'as_qid("Douglas Adams")
-#'# if input string matches a single unique label
-#'as_qid("Douglas Adams and the question of arterial blood pressure in mammals")
-#'@export
-searcher <- function(search_term, language, limit, type, ...){
- result <- WikipediR::query(url = "https://www.wikidata.org/w/api.php", out_class = "list", clean_response = FALSE,
- query_param = list(
- action = "wbsearchentities",
- type = type,
- language = language,
- limit = limit,
- search = search_term
- ),
- ...)
- result <- result$search
- return(result)
-}
+#'@title Retrieve specific Wikidata items or properties
+#'@description \code{get_item} and \code{get_property} allow you to retrieve the data associated
+#'with individual Wikidata items and properties, respectively. As with
+#'other \code{WikidataR} code, custom print methods are available; use \code{\link{str}}
+#'to manipulate and see the underlying structure of the data.
+#'
+#'@param id the ID number(s) of the item or property you're looking for. This can be in
+#'various formats; either a numeric value ("200"), the full name ("Q200") or
+#'even with an included namespace ("Property:P10") - the function will format
+#'it appropriately. This function is vectorised and will happily accept
+#'multiple IDs.
+#'
+#'@param ... further arguments to pass to httr's GET.
+#'
+#'@seealso \code{\link{get_random}} for selecting a random item or property,
+#'or \code{\link{find_item}} for using search functionality to pull out
+#'item or property IDs where the descriptions or aliases match a particular
+#'search term.
+#'
+#'@examples
+#'
+#'#Retrieve a specific item
+#'adams_metadata <- get_item("42")
+#'
+#'#Retrieve a specific property
+#'object_is_child <- get_property("P40")
+#'
+#'@aliases get_item get_property
+#'@rdname get_item
+#'@export
+get_item <- function(id, ...){
+ id <- check_input(id, "Q")
+ output <- (lapply(id, wd_query, ...))
+ class(output) <- "wikidata"
+ return(output)
+}
+
+#'@rdname get_item
+#'@export
+get_property <- function(id, ...){
+ has_grep <- grepl("^P(?!r)",id, perl = TRUE)
+ id[has_grep] <- paste0("Property:", id[has_grep])
+ id <- check_input(id, "Property:P")
+
+ output <- (lapply(id, wd_query, ...))
+ class(output) <- "wikidata"
+ return(output)
+}
+
+#'@title Retrieve randomly-selected Wikidata items or properties
+#'@description \code{get_random_item} and \code{get_random_property} allow you to retrieve the data
+#'associated with randomly-selected Wikidata items and properties, respectively. As with
+#'other \code{WikidataR} code, custom print methods are available; use \code{\link{str}}
+#'to manipulate and see the underlying structure of the data.
+#'
+#'@param limit how many random items to return. 1 by default, but can be higher.
+#'
+#'@param ... arguments to pass to httr's GET.
+#'
+#'@seealso \code{\link{get_item}} for selecting a specific item or property,
+#'or \code{\link{find_item}} for using search functionality to pull out
+#'item or property IDs where the descriptions or aliases match a particular
+#'search term.
+#'
+#'@examples
+#'
+#'#Random item
+#'random_item <- get_random_item()
+#'
+#'#Random property
+#'random_property <- get_random_property()
+#'
+#'@aliases get_random get_random_item get_random_property
+#'@rdname get_random
+#'@export
+get_random_item <- function(limit = 1, ...){
+ return(wd_rand_query(ns = 0, limit = limit, ...))
+}
+
+#'@rdname get_random
+#'@export
+get_random_property <- function(limit = 1, ...){
+ return(wd_rand_query(ns = 120, limit = limit, ...))
+}
+
+#'@title Search for Wikidata items or properties that match a search term
+#'@description \code{find_item} and \code{find_property} allow you to retrieve a set
+#'of Wikidata items or properties where the aliase or descriptions match a particular
+#'search term. As with other \code{WikidataR} code, custom print methods are available;
+#'use \code{\link{str}} to manipulate and see the underlying structure of the data.
+#'
+#'@param search_term a term to search for.
+#'
+#'@param language the language to return the labels and descriptions in; this should
+#'consist of an ISO language code. Set to "en" by default.
+#'
+#'@param limit the number of results to return; set to 10 by default.
+#'
+#'@param ... further arguments to pass to httr's GET.
+#'
+#'@seealso \code{\link{get_random}} for selecting a random item or property,
+#'or \code{\link{get_item}} for selecting a specific item or property.
+#'
+#'@examples
+#'
+#'#Check for entries relating to Douglas Adams in some way
+#'adams_items <- find_item("Douglas Adams")
+#'
+#'#Check for properties involving the peerage
+#'peerage_props <- find_property("peerage")
+#'
+#'@aliases find_item find_property
+#'@rdname find_item
+#'@export
+find_item <- function(search_term, language = "en", limit = 10, ...){
+ res <- searcher(search_term, language, limit, "item")
+ class(res) <- "find_item"
+ return(res)
+}
+
+#'@rdname find_item
+#'@export
+find_property <- function(search_term, language = "en", limit = 10){
+ res <- searcher(search_term, language, limit, "property")
+ class(res) <- "find_property"
+ return(res)
+}
diff --git a/R/prints.R b/R/prints.R
index 070c3a9..261287d 100644
--- a/R/prints.R
+++ b/R/prints.R
@@ -1,125 +1,125 @@
-#'@title Print method for find_item
-#'
-#'@description print found items.
-#'
-#'@param x find_item object with search results
-#'@param \dots Arguments to be passed to methods
-#'
-#'@method print find_item
-#'@export
-print.find_item <- function(x, ...) {
- cat("\n\tWikidata item search\n\n")
-
- # number of results
- num_results <- length(x)
- cat("Number of results:\t", num_results, "\n\n")
-
- # results
- if(num_results > 0) {
- cat("Results:\n")
- for(i in 1:num_results) {
- if(is.null(x[[i]]$description)){
- desc <- "\n"
- }
- else {
- desc <- paste("-", x[[i]]$description, "\n")
- }
- cat(i, "\t", x[[i]]$label, paste0("(", x[[i]]$id, ")"), desc)
- }
- }
-}
-
-#'@title Print method for find_property
-#'
-#'@description print found properties.
-#'
-#'@param x find_property object with search results
-#'@param \dots Arguments to be passed to methods
-#'
-#'@method print find_property
-#'@export
-print.find_property <- function(x, ...) {
- cat("\n\tWikidata property search\n\n")
-
- # number of results
- num_results <- length(x)
- cat("Number of results:\t", num_results, "\n\n")
-
- # results
- if(num_results > 0) {
- cat("Results:\n")
- for(i in seq_len(num_results)) {
- if(is.null(x[[i]]$description)){
- desc <- "\n"
- }
- else {
- desc <- paste("-", x[[i]]$description, "\n")
- }
- cat(i, "\t", x[[i]]$label, paste0("(", x[[i]]$id, ")"), desc)
- }
- }
-}
-
-wd_print_base <- function(x, ...){
-
- cat("\n\tWikidata", x$type, x$id, "\n\n")
-
- # labels
- num.labels <- length(x$labels)
- if(num.labels>0) {
- lbl <- x$labels[[1]]$value
- if(num.labels==1) cat("Label:\t\t", lbl, "\n")
- else {
- if(!is.null(x$labels$en)) lbl <- x$labels$en$value
- cat("Label:\t\t", lbl, paste0("\t[", num.labels-1, " other languages available]\n"))
- }
- }
-
- # aliases
- num_aliases <- length(x$aliases)
- if(num_aliases > 0) {
- al <- unique(unlist(lapply(x$aliases, function(xl){return(xl$value)})))
- cat("Aliases:\t", paste(al, collapse = ", "), "\n")
- }
-
- # descriptions
- num_desc <- length(x$descriptions)
- if(num_desc > 0) {
- desc <- x$descriptions[[1]]$value
- if(num_desc == 1){
- cat("Description:", desc, "\n")
- }
- else {
- if(!is.null(x$descriptions$en)){
- desc <- x$descriptions$en$value
- }
- cat("Description:", desc, paste0("\t[", (num_desc - 1), " other languages available]\n"))
- }
- }
-
- # num claims
- num_claims <- length(x$claims)
- if(num_claims > 0){
- cat("Claims:\t\t", num_claims, "\n")
- }
-
- # num sitelinks
- num_links <- length(x$sitelinks)
- if(num_links > 0){
- cat("Sitelinks:\t", num_links, "\n")
- }
-}
-
-#'@title Print method for Wikidata objects
-#'
-#'@description print found objects generally.
-#'
-#'@param x wikidata object from get_item, get_random_item, get_property or get_random_property
-#'@param \dots Arguments to be passed to methods
-#'@seealso get_item, get_random_item, get_property or get_random_property
-#'@method print wikidata
-#'@export
-print.wikidata <- function(x, ...){
- lapply(x, wd_print_base, ...)
- return(invisible())
+#'@title Print method for find_item
+#'
+#'@description print found items.
+#'
+#'@param x find_item object with search results
+#'@param \dots Arguments to be passed to methods
+#'
+#'@method print find_item
+#'@export
+print.find_item <- function(x, ...) {
+ cat("\n\tWikidata item search\n\n")
+
+ # number of results
+ num_results <- length(x)
+ cat("Number of results:\t", num_results, "\n\n")
+
+ # results
+ if(num_results > 0) {
+ cat("Results:\n")
+ for(i in 1:num_results) {
+ if(is.null(x[[i]]$description)){
+ desc <- "\n"
+ }
+ else {
+ desc <- paste("-", x[[i]]$description, "\n")
+ }
+ cat(i, "\t", x[[i]]$label, paste0("(", x[[i]]$id, ")"), desc)
+ }
+ }
+}
+
+#'@title Print method for find_property
+#'
+#'@description print found properties.
+#'
+#'@param x find_property object with search results
+#'@param \dots Arguments to be passed to methods
+#'
+#'@method print find_property
+#'@export
+print.find_property <- function(x, ...) {
+ cat("\n\tWikidata property search\n\n")
+
+ # number of results
+ num_results <- length(x)
+ cat("Number of results:\t", num_results, "\n\n")
+
+ # results
+ if(num_results > 0) {
+ cat("Results:\n")
+ for(i in seq_len(num_results)) {
+ if(is.null(x[[i]]$description)){
+ desc <- "\n"
+ }
+ else {
+ desc <- paste("-", x[[i]]$description, "\n")
+ }
+ cat(i, "\t", x[[i]]$label, paste0("(", x[[i]]$id, ")"), desc)
+ }
+ }
+}
+
+wd_print_base <- function(x, ...){
+
+ cat("\n\tWikidata", x$type, x$id, "\n\n")
+
+ # labels
+ num.labels <- length(x$labels)
+ if(num.labels>0) {
+ lbl <- x$labels[[1]]$value
+ if(num.labels==1) cat("Label:\t\t", lbl, "\n")
+ else {
+ if(!is.null(x$labels$en)) lbl <- x$labels$en$value
+ cat("Label:\t\t", lbl, paste0("\t[", num.labels-1, " other languages available]\n"))
+ }
+ }
+
+ # aliases
+ num_aliases <- length(x$aliases)
+ if(num_aliases > 0) {
+ al <- unique(unlist(lapply(x$aliases, function(xl){return(xl$value)})))
+ cat("Aliases:\t", paste(al, collapse = ", "), "\n")
+ }
+
+ # descriptions
+ num_desc <- length(x$descriptions)
+ if(num_desc > 0) {
+ desc <- x$descriptions[[1]]$value
+ if(num_desc == 1){
+ cat("Description:", desc, "\n")
+ }
+ else {
+ if(!is.null(x$descriptions$en)){
+ desc <- x$descriptions$en$value
+ }
+ cat("Description:", desc, paste0("\t[", (num_desc - 1), " other languages available]\n"))
+ }
+ }
+
+ # num claims
+ num_claims <- length(x$claims)
+ if(num_claims > 0){
+ cat("Claims:\t\t", num_claims, "\n")
+ }
+
+ # num sitelinks
+ num_links <- length(x$sitelinks)
+ if(num_links > 0){
+ cat("Sitelinks:\t", num_links, "\n")
+ }
+}
+
+#'@title Print method for Wikidata objects
+#'
+#'@description print found objects generally.
+#'
+#'@param x wikidata object from get_item, get_random_item, get_property or get_random_property
+#'@param \dots Arguments to be passed to methods
+#'@seealso get_item, get_random_item, get_property or get_random_property
+#'@method print wikidata
+#'@export
+print.wikidata <- function(x, ...){
+ lapply(x, wd_print_base, ...)
+ return(invisible())
}
\ No newline at end of file
diff --git a/R/queries.R b/R/queries.R
deleted file mode 100644
index ba27784..0000000
--- a/R/queries.R
+++ /dev/null
@@ -1,167 +0,0 @@
-#Generic queryin' function for direct Wikidata calls. Wraps around WikipediR::page_content. - Ironholds
-#'@title Download a Wikidata item
-#'@description Utility wrapper for wikidata API to download item.
-#'Used by \code{get_item} and \code{get_property}
-#'@param title the wikidata item or property as a string
-#'@param \\dots Additional parameters to supply to [httr::POST]
-#'@return a download of the full wikidata object (item or property) formatted as a nested json list
-#'@export
-wd_query <- function(title, ...){
- result <- WikipediR::page_content(domain = "wikidata.org", page_name = title, as_wikitext = TRUE,
- httr::user_agent("WikidataR - https://github.com/TS404/WikidataR"),
- ...)
- output <- jsonlite::fromJSON(result$parse$wikitext[[1]])
- return(output)
-}
-
-# Query for a random item in "namespace" (ns). Essentially a wrapper around WikipediR::random_page. - Ironholds
-#'@title Download random Wikidata items
-#'@description Utility wrapper for wikidata API to download random items. Used by \code{random_item}
-#'@param ns string indicating namespace, most commonly "Main" for QID items, "Property" for PID properties
-#'@param limit how many random objesct to return
-#'@param \\dots Additional parameters to supply to [httr::POST]
-#'@return a download of the full wikidata objects (items or properties) formatted as nested json lists
-#'@export
-wd_rand_query <- function(ns, limit, ...){
- result <- WikipediR::random_page(domain = "wikidata.org", as_wikitext = TRUE, namespaces = ns,
- httr::user_agent("WikidataR - https://github.com/TS404/WikidataR"),
- limit = limit, ...)
- output <- lapply(result, function(x){jsonlite::fromJSON(x$wikitext[[1]])})
- class(output) <- "wikidata"
- return(output)
-}
-
-#sparql query function for direct Wikidata calls.
-#'@title Download full Wikidata items matching a sparql query
-#'@description Utility wrapper for wikidata spargle endpoint to download items.
-#'Used by \code{get_geo_entity} and \code{get_geo_box}
-#'@param query the sparql query as a string
-#'@param \\dots Additional parameters to supply to [httr::POST]
-#'@return a download of the full wikidata objects formatted as a nested json list
-#'@export
-sparql_query <- function(query, ...){
- result <- httr::GET("https://query.wikidata.org/bigdata/namespace/wdq/sparql",
- query = list(query = query),
- httr::user_agent("WikidataR - https://github.com/TS404/WikidataR"),
- ...)
- httr::stop_for_status(result)
- return(httr::content(result, as = "parsed", type = "application/json"))
-}
-
-#Wrapper around WikidataQueryServiceR::query_wikidata
-#' @title Send one or more SPARQL queries to WDQS
-#' @description Makes a POST request to Wikidata Query Service SPARQL endpoint.
-#' @param sparql_query SPARQL query (can be a vector of queries)
-#' @param format
-#' `tibble` (default) returns a pure character data frame,
-#' `simple` returns a pure character vector, while
-#' `smart` fetches JSON-formatted data and returns a tibble with datetime
-#' columns converted to `POSIXct`
-#' @param \\dots Additional parameters to supply to [httr::POST]
-#' @return A `tibble` or `vector`. Note: QID values will be returned as QIDs, rather than URLs.
-#' @section Query limits:
-#' There is a hard query deadline configured which is set to 60 seconds. There
-#' are also following limits:
-#' - One client (user agent + IP) is allowed 60 seconds of processing time each
-#' 60 seconds
-#' - One client is allowed 30 error queries per minute
-#' See [query limits section](https://www.mediawiki.org/wiki/Wikidata_Query_Service/User_Manual#Query_limits)
-#' in the WDQS user manual for more information.
-#' @examples
-#' # R's versions and release dates:
-#' sparql_query <- 'SELECT DISTINCT
-#' ?softwareVersion ?publicationDate
-#' WHERE {
-#' BIND(wd:Q206904 AS ?R)
-#' ?R p:P348 [
-#' ps:P348 ?softwareVersion;
-#' pq:P577 ?publicationDate
-#' ] .
-#' }'
-#' query_wikidata(sparql_query)
-#'
-#' \dontrun{
-#' # "smart" format converts all datetime columns to POSIXct
-#' query_wikidata(sparql_query, format = "smart")
-#' }
-#' @export
-query_wikidata <- function(sparql_query,format="tibble",...) {
- if(format=="simple"){simplify<-TRUE}else{simplify<-FALSE}
- if(format=="tibble"){format<-"simple"}
- output <- WikidataQueryServiceR::query_wikidata(sparql_query=sparql_query,format=format,...)
- output <- suppressWarnings(mapply(url_to_id,data.frame(output),SIMPLIFY=simplify))
- output <- tibble(data.frame(output))
- if(nrow(output)==0){output<-tibble(value=NA)}
- output
-}
-
-#' @title QID from identifier
-#' @description convert unique identifiers to QIDs (for items in wikidata).
-#' @param property the identifier property to search (for caveats, see \code{as_pid})
-#' @param value the identifier value to match
-#' @return vector of QIDs corresponding to identifiers submitted
-#' @examples
-#' qid_from_identifier('ISBN-13','978-0-262-53817-6')
-#' @export
-qid_from_identifier <- function(property = 'DOI',
- value = c('10.15347/WJM/2019.001','10.15347/WJM/2020.002')){
-
- property <- as_pid(property)
-
- qid_from_property1 <- function(value,property){out <- paste('SELECT ?value WHERE {?value wdt:',
- property,
- ' "',
- value,
- '"}',
- sep='')
- names(out)<-value
- return(out)}
-
- qid_from_property2 <- function(x){out <- as.character(query_wikidata(x)[[1]])
- names(out) <- names(x)
- return(out)}
-
- sparql_query <- lapply(value,property,FUN=qid_from_property1)
- if(length(value)>1){
- output <- unlist(pblapply(sparql_query,qid_from_property2))
- }else{
- output <- as.character(unlist(lapply(sparql_query,FUN=query_wikidata)))
- names(output) <- value
- }
- if(length(value)!=length(output)){message("Caution! Some supplied values returned more than one QID.")}
- return(output)
-}
-
-#' @title identifier from identifier
-#' @description convert unique identifiers to other unique identifiers
-#' @param property the identifier property to search (for caveats, see \code{as_pid})
-#' @param return the identifier property to convert to
-#' @param value the identifier value to match
-#' @return vector of identifiers corresponding to identifiers submitted
-#' @examples
-#' identifier_from_identifier('ORCID iD','IMDb ID',c('0000-0002-7865-7235','0000-0003-1079-5604'))
-#' @export
-identifier_from_identifier <- function(property = 'ORCID iD',
- return = 'IMDb ID',
- value = "0000-0002-7865-7235"){
-
- property <- as_pid(property)
- return <- as_pid(return)
-
- qid_from_property1 <- function(value,return,property){paste('SELECT ?return WHERE { ?value wdt:',
- property,
- ' "',
- value,
- '". ?value wdt:',
- return,
- ' ?return.}',
- sep='')}
- sparql_query <- lapply(value,return,property,FUN=qid_from_property1)
- output <- if(length(value)>1){
- unlist(pbapply::pblapply(sparql_query,function(x) as.character(query_wikidata(x)[[1]])))
- }else{
- as.character(unlist(lapply(sparql_query,FUN=query_wikidata)))
- }
- names(output) <- value
- return(output)
-}
diff --git a/R/schol.R b/R/schol.R
deleted file mode 100644
index 84f9d4b..0000000
--- a/R/schol.R
+++ /dev/null
@@ -1,39 +0,0 @@
-#' @title QID from DOI
-#' @description simple converter from DOIs to QIDs (for items in wikidata)
-#' @param DOI digital object identifiers submitted as strings
-#' @return vector of QIDs corresponding to DOIs submitted
-#' @export
-qid_from_DOI <- function(DOI = '10.15347/WJM/2019.001'){
- article.qid <- qid_from_identifier(property = 'P356',value = DOI)
- return(article.qid)
-}
-
-#' @title QID from label name
-#' @description simple converter from label names to QIDs (for items in wikidata).
-#' Essentially a simplification of \code{find_item}
-#' @param name name labels submitted as strings
-#' @param limit if multiple QIDs match each submitted name, how many to return
-#' @param format output format ('vector' to return a simple vector, or 'list' to return a nested list)
-#' @return vector of QIDs corresponding to names submitted. Note: some names may return multiple QIDs.
-#' @export
-qid_from_name <- function(name = "Thomas Shafee",
- limit = 100,
- format = "vector"){
- qid_from_name_nest1 <- function(x){lapply(x,"[[","id")}
- item.qs <- lapply(name,find_item, limit=limit)
- item.qid <- lapply(item.qs,qid_from_name_nest1)
- names(item.qid) <- name
- if(format=="vector"){item.qid <- unlist(item.qid)}
- if(format=="list") {item.qid <- item.qid}
- return(item.qid)
-}
-
-#' @title QID from ORCID
-#' @description simple converter from ORCIDs to QIDs (for items in wikidata)
-#' @param ORCID digital object identifiers submitted as strings
-#' @return vector of QIDs corresponding to ORCIDs submitted
-#' @export
-qid_from_ORCID <- function(ORCID = '0000-0002-2298-7593'){
- author.qid <- qid_from_identifier(property = 'P496',value = ORCID)
- return(author.qid)
-}
diff --git a/R/sysdata.rda b/R/sysdata.rda
deleted file mode 100644
index 50d313b..0000000
Binary files a/R/sysdata.rda and /dev/null differ
diff --git a/R/utils.R b/R/utils.R
index dc58e4c..ffde3cc 100644
--- a/R/utils.R
+++ b/R/utils.R
@@ -1,549 +1,90 @@
-# -------- Format checkers --------
-# Simple tests of strings for whether they adhere to common wikidata formats
-is.qid <- function(x){grepl("^[Qq][0-9]+$",x)}
-is.pid <- function(x){gsub("S","P",x) %in% as.matrix(WD.globalvar$PID.datatype$property)}
-is.sid <- function(x){gsub("S","P",x) %in% as.matrix(WD.globalvar$SID.valid$Wikidata_property_to_indicate_a_source)}
-is.date <- function(x){grepl("[0-9]{1,4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}",x)}
-is.quot <- function(x){grepl("^\".+\"$",x)}
-is.empty <- function(x){x==""}
-is.coord <- function(x){grepl("@-?([1-8]?\\d(\\.\\d+)?|90(\\.0+)?)/-?(180(\\.0+)?|((1[0-7]\\d)|([1-9]?\\d))(\\.\\d+)?)$",x)}
-is.wdURL <- function(x){grepl("http://www.wikidata.org/entity/[PpQq][0-9]+$",x)}
-is.create <- function(x){grepl("^CREATE",x)}
-is.createx <- function(x){grepl("^CREATE.+",x)}
-is.last <- function(x){grepl("^LAST$",x)}
-is.special <- function(x){
- if(grepl("^[LAD]",x)){
- substr(x,2,100) %in% as.matrix(WD.globalvar$lang.abbrev)
- }else if(grepl("^S",x)){
- substr(x,2,100) %in% as.matrix(WD.globalvar$abbrev.wiki)
- }else{
- FALSE
- }
-}
-
-check.PID.WikibaseItem <- function(x){
- x %in% WD.globalvar$PID.datatype$property[WD.globalvar$PID.datatype$wbtype=="WikibaseItem"]}
-
-check.PID.constraint <- function(x){
- check.PID.constraint.nest1 <- function(x){
- out <- as.character(WD.globalvar$PID.constraint$fmt[WD.globalvar$PID.constraint$Wikidata_property==x])
- if(length(out)!=0){out}else{NA}
- }
- sapply(x,check.PID.constraint.nest1)
-}
-
-#'@title Extract an identifier from a wikidata URL
-#'@description Convert a URL ending in an identifier (returned by SPARQL queries) to just
-#'the plain identifier (QID or PID).
-#'@param x a strings representing a wikidata URL
-#'@return if the URL ends in a QID or PID, return that PID or QID, else return the original string
-#'@examples
-#'url_to_id("http://www.wikidata.org/entity/42")
-#'@export
-url_to_id <- function (x){
- if(is.wdURL(x)){x <- sapply(sapply(x,pattern = "/",stringr::str_split),tail,1)}
- output <- x
- output
-}
-
-#Generic input checker. Needs additional stuff for property-based querying
-#because namespaces are weird, yo. - Ironholds
-#'@title Generic input checker
-#'@description Utility function to handle namespaces. Used by \code{get_item} and \code{get_property}
-#'@param input string to check
-#'@param substitution string for what's been looked for
-#'@return boolian indicating whether the checked string contains a match for the substitution string
-#'@export
-check_input <- function(input, substitution){
- in_fit <- grepl("^\\d+$",input)
- if(any(in_fit)){
- input[in_fit] <- paste0(substitution, input[in_fit])
- }
- return(input)
-}
-
-
-# -------- Format converters --------
-# Simple functions to convert plain text descriptions into their most likely QID/PIDs
-#'@title Convert an input to a item QID
-#'@description Convert an input string to the most likely item QID
-#'@param x a vector, data frame, or tibble of strings representaing wikidata items
-#'@return if the inputted string is a valid QID, return the string.
-#'If the inputted string matches an item label, return its QID.
-#'If the inputted string matches multiple labels of multiple items, return the QID of the first hit.
-#'@examples
-#'# if input string is a valid QID
-#'as_qid("Q42")
-#'# if input string matches multiple item labels
-#'as_qid("Douglas Adams")
-#'# if input string matches a single unique label
-#'as_qid("Douglas Adams and the question of arterial blood pressure in mammals")
-#'@export
-as_qid <- function(x){
- as_qid_nest1 <- function(x){
- as_qid_nest2 <- function(x){
- if(is.qid(x)|is.date(x)|is.quot(x)|is.na(x)|is.null(x)|is.empty(x)|is.createx(x)|is.create(x)|is.last(x)){
- x
- }else{
- temp <- find_item(x,limit = 100)
- if(length(temp)==0){
- out <- NA
- message (paste0("no sufficiently close match for \"",x,"\". Returned \"NA\"."))
- }else{
- toinclude <- sapply(temp,function(temp,x){temp$label==x},x)
- toinclude[1] <- TRUE
- temp <- temp[toinclude]
- out <- temp[[1]]$id
- names(out) <- temp[[1]]$label
- if(x!=temp[[1]]$label){message(paste0(
- "Inexact match for \"",x,
- "\", closest match = ",temp[[1]]$label,
- " (",out,") "))}
- if(length(temp)>1){
- message(paste0(
- "Multiple exact matches for \"",x,"\""))
- message(paste0(
- " match ",1:length(temp),
- " = (",sapply(temp,function(temp){temp$id}),
- ") ",sapply(temp,function(temp){temp$description}),
- "\n"))}
- }
- out
- }
- }
- out <- unlist(lapply(x,as_qid_nest2))
- out
- }
- output <- bind_cols(lapply(tibble(x),as_qid_nest1))
- return(output)
-}
-
-#'@title Convert an input to a property PID
-#'@description Convert an input string to the most likely property PID
-#'@param x a vector, data frame, or tibble of strings representaing wikidata properties
-#'@return if the inputted string is a valid PID, return the string.
-#'If the inputted string matches a property label, return its PID.
-#'If the inputted string matches multiple labels of multiple properties, return the PID of the first hit.
-#'@examples
-#'# if input string is a valid PID
-#'as_pid("P50")
-#'# if input string matches multiple item labels
-#'as_pid("author")
-#'# if input string matches a single unique label
-#'as_pid("Scopus author ID")
-#'@export
-as_pid <- function(x){
- as_pid_nest1 <- function(x){
- as_pid_nest2 <- function(x){
- if(is.pid(x)|is.date(x)|is.quot(x)|is.na(x)|is.null(x)|is.empty(x)|is.special(x)){
- x
- }else{
- temp <- find_property(x,limit = 2)
- if(length(temp)==0){
- out <- NA
- message (paste0("no sufficiently close match for \"",x,"\". Returned \"NA\"."))
- }else{
- out <- temp[[1]]$id
- names(out) <- temp[[1]]$label
- if(x!=temp[[1]]$label){message(paste0(
- "Inexact match for \"",x,
- "\", closest match = ",temp[[1]]$label,
- " (",out,")."))}
- }
- out
- }
- }
- out <- unlist(lapply(x,as_pid_nest2))
- out
- }
- output <- bind_cols(lapply(tibble(x),as_pid_nest1))
- return(output)
-}
-
-#'@title Convert an input to a source property SID
-#'@description Convert an input string to the most likely source SID (equivalent to PID)
-#'@param x a vector, data frame, or tibble of strings representaing wikidata source properties
-#'@return if the inputted string is a valid SID, return the string.
-#'If the inputted string matches a property label, return its SID
-#'If the inputted string matches multiple labels of multiple properties, return the SID of the first hit.
-#'@examples
-#'# if input string is a valid SID
-#'as_pid("S854")
-#'# if input string matches multiple item labels
-#'as_pid("URL")
-#'# if input string matches a single unique label
-#'as_pid("Reference URL")
-#'@export
-as_sid <- function(x){
- as_sid_nest1 <- function(x){
- as_sid_nest2 <- function(x){
- if(is.sid(x)|is.date(x)|is.quot(x)|is.na(x)|is.null(x)|is.empty(x)){
- x
- }else if(all(is.pid(x))){
- gsub("P","S",x,ignore.case = 1)
- }else{
- gsub("P","S",find_property(x)[[1]]$id)
- }
- }
- out <- unlist(lapply(x,as_sid_nest2))
- out
- }
- output <- bind_cols(lapply(tibble(x),as_sid_nest1))
- return(output)
-}
-
-#'@title Add quotations marks
-#'@description Add escaped quotation marks around strings that need them ready for submision to an API
-#'@param x a vector, data frame, or tibble of strings
-#'@param format either "tibble" / "csv" to use plain quotation marks (default), or "api" / "website" to use '\%22'
-#'@return tibble of items inside of escaped quotation marks
-#'unless they are already in escaped quotation marks, is a QID, (in which chase it is returned unchanged)
-#'@examples
-#'as_quot("text")
-#'@export
-as_quot <- function(x,format="tibble"){
- if(is.null(x)){
- return(NULL)
- }else if(format=="api"|format=="website"){
- q_mark <- '%22'
- }else if(format=="tibble"|format=="csv"){
- q_mark <- '"'
- }
- as_quot_nest1 <- function(x){
- as_quot_nest2 <- function(x){
- if(!(is.qid(x)|is.quot(x)|is.date(x)|is.na(x)|is.empty(x)|is.numeric(x)))
- {paste0(q_mark,x,q_mark)}
- else
- {x}
- }
- out <- unlist(lapply(x,as_quot_nest2))
- out
- }
- output <- bind_cols(lapply(tibble(x),as_quot_nest1))
- return(output)
-}
-
-#'@title Extract an identifier from a wikidata URL
-#'@description Convert a URL ending in an identifier (returned by SPARQL queries)
-#'to just the plan identifier (QID or PID).
-#'@param x a vector of strings representing wikidata URLs
-#'@return QID or PID
-#'@examples
-#'url_to_id("http://www.wikidata.org/Q42")
-#'@export
-url_to_id <- function(x){
- sapply(sapply(x,pattern = "/|:",stringr::str_split),tail,1)
-}
-
-
-# -------- Wikidata object manipulation --------
-#'@title Extract Claims from Returned Item Data
-#'@description extract claim information from data returned using
-#'\code{\link{get_item}}.
-#'@param items a list of one or more Wikidata items returned with
-#'\code{\link{get_item}}.
-#'@param claims a vector of claims (in the form "P321", "P12") to look for
-#'and extract.
-#'@return a list containing one sub-list for each entry in \code{items},
-#'and (below that) the found data for each claim. In the event a claim
-#'cannot be found for an item, an \code{NA} will be returned
-#'instead.
-#'@examples
-#'# Get item data
-#'adams_data <- get_item("42")
-#'# Get claim data
-#'claims <- extract_claims(adams_data, "P31")
-#'@export
-extract_claims <- function (items,
- claims){
- claims <- sapply(claims,as_pid)
- output <- lapply(items, function(x, claims){
- return(lapply(claims, function(claim, obj){
- which_match <- which(names(obj$claims) == claim)
- if (!length(which_match)){
- return(NA)
- }
- return(obj$claims[[which_match[1]]])
- }, obj = x))
- }, claims = claims)
- return(output)
-}
-
-#'@title List properties of a Wikidata item
-#'@description for a downloaded wikidata item, list the properties of all statements
-#'@param item a list of one or more Wikidata items returned with
-#'\code{\link{get_item}}.
-#'@param names a boolian for whether to return property names, or just P numbers
-#'and extract.
-#'@return a list containing one sub-list for each entry in \code{items},
-#'and (below that) the found data for each claim. In the event a claim
-#'cannot be found for an item, an \code{NA} will be returned
-#'instead.
-#'@examples
-#'# Get item data
-#'adams_data <- get_item("42")
-#'# Get claim data
-#'claims <- extract_claims(adams_data, "P31")
-#'@export
-list_properties <- function (item,
- names=FALSE){
- properties.p <- lapply(lapply(item,"[[","claims"),names)
- if(names){
- if(length(item)==1){
- names(properties.p) <- unlist(lapply(lapply(lapply(get_property(properties.p),"[[","labels"),"[[","en"),"[[","value"))
- }
- }
- return(properties.p)
-}
-
-#Note: This one isn't very well named. not really the property names, more the predicate names, but you get the idea
-#'@title Get names of properties
-#'@description For a claim or set of claims, return the names of the properties
-#'@param properties a claims list from \code{extract_claims}
-#'@return tibble of labels for each property for a set of claims
-#'@export
-get_names_from_properties <- function(properties){
- get_names_from_properties_nest1 <- function(x){
- out <- lapply(lapply(lapply(lapply(x,"[[","mainsnak"),"[[","datavalue"),"[[","value"),"[[","id")
- names(out) <- lapply(lapply(lapply(x,"[[","mainsnak"),"[[","property"),"[[",1)
- return(out)
- }
- get_names_from_properties_nest2 <- function(x){
- out <- lapply(x,get_item)
- return(out)
- }
- get_names_from_properties_nest3.1 <- function(x){
- out <- lapply(lapply(lapply(x,"[[","labels"),"[[","en"),"[[","value")
- names(out) <- lapply(x,"[[","id")
- return(out)
- }
- get_names_from_properties_nest3 <- function(x){
- out <- lapply(x,get_names_from_properties_nest3.1)
- return(out)
- }
-
- property_values.qid <- lapply(properties,get_names_from_properties_nest1)
- property_values.q <- lapply(property_values.qid,get_names_from_properties_nest2)
- property_names <- lapply(property_values.q, get_names_from_properties_nest3)
- property_names <- lapply(lapply(property_names,unlist),enframe,name = "QID")
- return(property_names)
-}
-
-
-#'@title Filter QIDs
-#'@description For a QID or vector of QIDs, remove ones that match a particular statement
-#'(e.g. remove all that are instances of academic publications or books).
-#'@param ids QIDs to check
-#'@param property property to check (default = P31 to filter on "instance of")
-#'@param filter values of that property to use to filter out
-#'(default = Q737498, Q5633421, Q7725634, Q13442814, and Q18918145 to remove academic
-#'publications or books)
-#'@param message message to return (useful for disambiguate_QIDs function)
-#'@return a vector of QIDs that do not match the property filter
-#'@examples
-#' \dontrun{
-#' # Filter three items called "Earth Science" to show only those that aren't
-#' # books, journals or journal articles
-#' filter_qids(ids = c("Q96695546","Q8008","Q58966429"),
-#' property = "P31",
-#' filter = c("Q737498","Q5633421","Q7725634","Q13442814","Q18918145"))
-#' }
-#'@export
-filter_qids <- function (ids,
- property = "P31",
- filter = c("Q737498",
- "Q5633421",
- "Q7725634",
- "Q13442814",
- "Q18918145"),
- message=NULL){
- out <- NULL
- pb <- progress_bar$new(total = length(ids),
- format = paste0(message,":bar :percent eta::eta"),
- width = 75,
- show_after = 0)
- if(is.null(property)|is.null(filter)){
- for (i in 1:length(ids)){
- pb$tick()
- qid <- ids[i]
- item <- find_item(qid,limit=1)
- label <- item[[1]]$label
- if(length(item[[1]]$description)>0){
- if(!is.null(item[[1]]$description)){
- desc <- item[[1]]$description
- }else{
- desc <- item[[1]]$description
- }
- }else{
- desc <- "no description"
- }
- out <- bind_rows(out,tibble(qid=qid,label=label,desc=desc))
- }
- }else{
- for (i in 1:length(ids)){
- pb$tick()
- qid <- ids[i]
- item <- get_item(qid)
- P31 <- item[[1]]$claims[[property]]$mainsnak$datavalue$value$id
- if(all(is.null(P31))){P31<-"other"}
- if(!any(P31 %in% filter)){
- label <- item[[1]]$labels[[1]]$value
- if(length(item[[1]]$descriptions)>0){
- if(!is.null(item[[1]]$descriptions$en$value)){
- desc <- item[[1]]$descriptions$en$value
- }else{
- desc <- item[[1]]$descriptions[[1]]$value
- }
- }else{
- desc <- "no description"
- }
- if(length(item[[1]]$labels)>0){
- if(!is.null(item[[1]]$labels$en$value)){
- label <- item[[1]]$labels$en$value
- }else{
- label <- item[[1]]$labels[[1]]$value
- }
- }else{
- label <- "no label"
- }
- out <- bind_rows(out,tibble(qid=qid,label=label,desc=desc))
- }
- }
- }
- if(is.null(out)){
- out <- tibble(qid=NA,
- label=NA,
- desc="No current matching Wikidata item")
- }
- return(out)
-}
-
-
-# -------- Misc. string manipulation --------
-#'@title Format short form person names
-#'@description Converting names into first initial and surname, or just initials
-#'@param x a vector of people's names as strings
-#'@param format a vector of strings of either "FLast" or "FL" to indicate the output format
-#'@return the inputted name strings with first names shortened based on the
-#'selected format.
-#'@export
-initials <- function(x,format="FLast"){
- if (format=="FLast"){
- gsub("^([A-Za-z]).* ([A-Za-z]*)", "\\1 \\2", x)
- }else{
- gsub("(.)\\S* *", "\\1", x)
- }
-}
-
-#'@title Remove special characters
-#'@description Special characters can otherwise mess up wikidata read-writes
-#'@param x a vector of strings to check for special characters
-#'@return the inputted strings with special characters replaced with
-#'closest match plan characters.
-#'@export
-unspecial <- function(x){
- out <- x
- for(i in 1:ncol(x)){
- out[[i]] <- iconv(x[[i]],to = 'ASCII//TRANSLIT')
- if(Hmisc::all.is.numeric(x[[i]])){
- out[[i]] <- as.numeric(out[[i]])
- }else{
- out[[i]] <- as.factor(out[[i]])
- }
- }
- return(as_tibble(out))
-}
-
-#'@title Extract a paragraph of text
-#'@description Return the nth paragraph of a section of text
-#'Useful for extracting information from wikipedia or other wikimarkup text
-#'@param text the input text as a string
-#'@param para number indicating which paragraph(s) to return (default=1)
-#'@param templ an optional string specifying a mediawikitemplate within
-#'which to restrict the search restrict search
-#'@return the nth paragraph of the input text.
-#'@export
-extract_para <- function(text,
- para=1,
- templ=NULL){
- extract_para_nest1 <- function(x,y){
- out <- lapply(x,gsub,pattern=".*= *| *\\|",replacement="")
- names(out) <- y
- return(out)
- }
- templ <- gsub(" ","_",templ)
- tosearch <- gsub("( |\\\\n|\\\\t)+"," ",text)
- if(!is.null(templ)){
- templates <- regmatches(tosearch, gregexpr("\\{(?:[^{}]+|(?R))*+\\}",
- tosearch, perl=TRUE, ignore.case=TRUE))[[1]]
- name_lens <- regexpr(" *\\|| *\\}",templates) - 1
- templates <- paste0(gsub(" ","_",substr(templates,1,regexpr(" *\\|| *\\}",templates)-1)),
- substr(templates,regexpr("*\\||*\\}",templates),nchar(templates)))
-
- tosearch <- unlist(str_extract_all(templates,
- paste0("(?i)\\{\\{ *?",templ,".*?\\}\\}")))
- names(tosearch) <- paste0(templ,"_",1:length(tosearch))
- }
-
- match_paras <- lapply(tosearch,
- str_extract_all,
- paste0("\\| *?",para," *?=.*?\\|"))
-
- match_exact <- lapply(match_paras,extract_para_nest1,para)
-
- return(match_exact)
-}
-
-#'@title "CREATE" rows
-#'@description Add in empty lines for QuickStatements CREATE rows that mint new QIDs.
-#'This is a slightly messy quirk of the QuickStatements format that mints new QIDs via a line
-#'containing only "CREATE", so this function is a way to approximate that bevaviour in a tibble
-#'@param items a vector, data frame or tibble of items (which may or may not contain the keyword "CREATE")
-#'@param vector a vector of properties or values which may be expanded based on the items vector
-#'@return if the vector is NULL, return NULL. Otherwise, if the "CREATE" keyword appears in the
-#'items vector, insert blank strings at those positions in the vector.
-#'@export
-createrows <- function(items,vector){
- if(is.null(vector)){
- return(NULL)
- }
- if(any(items=="CREATE",na.rm = 1)){
- #expand vector to full length if just intending to repeat a single value
- if(length(unlist(vector))==1){
- vector <- rep(vector,sum(items!="CREATE"))
- }
- vector <- tibble(vector)
-
- newQID <- which(items=="CREATE")
- val <- bind_rows(vector,tibble(data.frame(array("",dim=c(length(newQID),ncol(vector)),dimnames = list(NULL,colnames(vector))))))
- id <- c(1:nrow(vector), newQID-seq_along(newQID)+0.5)
- out <- tibble(val[order(id),])
- return(out)
- }else{
- return(tibble(vector))
- }
-}
-
-#'@title "CREATE" rows from tidy format
-#'@description Add in QuickStatements CREATE rows that mint new QIDs from tidy input data.
-#'New items are created by any item starting that starts with the text "CREATE" followed
-#'by any unique ID.
-#'@param QS.tib a tibble of items, values and properties (optionally qualifiers and sources).
-#'@return a tibble, with items that start with "CREATE" followed by any unique text causing the
-#'addition of a "Create" line above, being replaced with "LAST" in the Quickstatemnts format
-#'to create new QIDs.
-#'@export
-createrows.tidy <- function(QS.tib){
- #insert 'CREATE' blankrows above first instance of 'CREATExyz'
- newQID <- which(!duplicated(QS.tib[,1])&sapply(QS.tib[,1],is.createx))
- val <- rbind(QS.tib, array("",dim=c(length(newQID),ncol(QS.tib)),dimnames = list(newQID,names(QS.tib))) )
- id <- c(seq_along(t(QS.tib)[1,]), newQID-0.5)
- out <- val[order(id),]
-
- #replace 'CREATEXYZ' with 'LAST'
- out[sapply(out[,1],is.createx),1] <- "LAST"
-
- #replace new empty rows with 'CREATE' row
- out[apply(is.empty(out),all,MARGIN=1),1] <- "CREATE"
- return(out)
-}
+#Generic queryin' function for direct Wikidata calls. Wraps around WikipediR::page_content.
+wd_query <- function(title, ...){
+ result <- WikipediR::page_content(domain = "wikidata.org", page_name = title, as_wikitext = TRUE,
+ httr::user_agent("WikidataR - https://github.com/Ironholds/WikidataR"),
+ ...)
+ output <- jsonlite::fromJSON(result$parse$wikitext[[1]])
+ return(output)
+}
+
+#Query for a random item in "namespace" (ns). Essentially a wrapper around WikipediR::random_page.
+wd_rand_query <- function(ns, limit, ...){
+ result <- WikipediR::random_page(domain = "wikidata.org", as_wikitext = TRUE, namespaces = ns,
+ httr::user_agent("WikidataR - https://github.com/Ironholds/WikidataR"),
+ limit = limit, ...)
+ output <- lapply(result, function(x){jsonlite::fromJSON(x$wikitext[[1]])})
+ class(output) <- "wikidata"
+ return(output)
+
+}
+
+#Generic input checker. Needs additional stuff for property-based querying
+#because namespaces are weird, yo.
+check_input <- function(input, substitution){
+ in_fit <- grepl("^\\d+$",input)
+ if(any(in_fit)){
+ input[in_fit] <- paste0(substitution, input[in_fit])
+ }
+ return(input)
+}
+
+#Generic, direct access to Wikidata's search functionality.
+searcher <- function(search_term, language, limit, type, ...){
+ result <- WikipediR::query(url = "https://www.wikidata.org/w/api.php", out_class = "list", clean_response = FALSE,
+ query_param = list(
+ action = "wbsearchentities",
+ type = type,
+ language = language,
+ limit = limit,
+ search = search_term
+ ),
+ ...)
+ result <- result$search
+ return(result)
+}
+
+sparql_query <- function(params, ...){
+ result <- httr::GET("https://query.wikidata.org/bigdata/namespace/wdq/sparql",
+ query = list(query = params),
+ httr::user_agent("WikidataR - https://github.com/Ironholds/WikidataR"),
+ ...)
+ httr::stop_for_status(result)
+ return(httr::content(result, as = "parsed", type = "application/json"))
+}
+
+#'@title Extract Claims from Returned Item Data
+#'@description extract claim information from data returned using
+#'\code{\link{get_item}}.
+#'
+#'@param items a list of one or more Wikidata items returned with
+#'\code{\link{get_item}}.
+#'
+#'@param claims a vector of claims (in the form "P321", "P12") to look for
+#'and extract.
+#'
+#'@return a list containing one sub-list for each entry in \code{items},
+#'and (below that) the found data for each claim. In the event a claim
+#'cannot be found for an item, an \code{NA} will be returned
+#'instead.
+#'
+#'@examples
+#'# Get item data
+#'adams_data <- get_item("42")
+#'
+#'# Get claim data
+#'claims <- extract_claims(adams_data, "P31")
+#'
+#'@export
+extract_claims <- function(items, claims){
+ output <- lapply(items, function(x, claims){
+ return(lapply(claims, function(claim, obj){
+ which_match <- which(names(obj$claims) == claim)
+ if(!length(which_match)){
+ return(NA)
+ }
+ return(obj$claims[[which_match[1]]])
+ }, obj = x))
+ }, claims = claims)
+
+ return(output)
+}
diff --git a/R/writes.R b/R/writes.R
deleted file mode 100644
index 37a7f62..0000000
--- a/R/writes.R
+++ /dev/null
@@ -1,235 +0,0 @@
-# -------- Writes --------
-
-#'@title Write statements to Wikidata
-#'@description Upload data to wikidata, including creating items,
-#'adding statements to existing items (via the quickstatements format and API).
-#'
-#'@param items a vector of strings indicating the items to which to add statements (as QIDs or labels).
-#'Note: if labels are provided, and multiple items match, the first matching item will be used
-#'(see \code{as_qid} function), so use with caution.
-#'New QIDs can be created by using the "CREATE_xyz", where "_xyz" is any unique string.
-#'Using the same id will add additional statemnts to those new items
-#'@param properties a vector of strings indicating the properties to add as statements (as PIDs or labels).
-#'Note: if labels are provided, and multiple items match, the first matching item will be used
-#'(see \code{as_pid} function), so use with caution.
-#'Four special properties can also be used: labels, aliases, descriptions and sitelinks.
-#'See [this link](https://www.wikidata.org/wiki/Help:QuickStatements#Adding_labels,_aliases,_descriptions_and_sitelinks) for the syntax.
-#'@param values a vector of strings indicating the values to add as statements (as QIDs or strings).
-#'Note: if strings are provided, they will be treated as plain text.
-#'@param qual.properties a vector, data frame, or tibble of strings indicating the properties to add as qualifiers to statements (as PIDs or labels).
-#'Note: if labels are provided, and multiple items match, the first matching item will be used
-#'(see \code{as_pid} function), so use with caution.
-#'@param qual.values a vector, data frame, or tibble of strings indicating the values to add as statements (as QIDs or strings).
-#'Note: if strings are provided, they will be treated as plain text.
-#'@param src.properties a vector, data frame, or tibble of strings indicating the properties to add as reference sources to statements (as SIDs or labels).
-#'Note: if labels are provided, and multiple items match, the first matching item will be used
-#'(see \code{as_sid} function), so use with caution.
-#'@param src.values a vector, data frame, or tibble of strings indicating the values to add reference sources to statements (as QIDs or strings).
-#'Note: if strings are provided, they will be treated as plain text.
-#'@param remove a vector of boolians for each statemnt indicating whether it should
-#'be removed from the item rather than added (default = FALSE)
-#'@param format output format as a string. Options include:
-#' \describe{
-#' \item{tibble}{easiest format to further manuipulation in R}
-#' \item{csv}{can be copy-pasted to [the QuickStatements website](https://quickstatements.toolforge.org/) (or manipulated in a spreadsheet programs)}
-#' \item{api}{a url that can be copy-pasted into a web browser, or automatically submitted (see \code{api.submit} parameter)}
-#' \item{website}{open a [QuickStatements](https://quickstatements.toolforge.org/) web browser window summarising the edits to be made to Wikidata)}
-#' }
-#'@param api.username a string indicating your wikimedia username
-#'@param api.token a string indicating your api token (the unique identifier that you can find listed at [your user page](https://quickstatements.toolforge.org/#/user))
-#'@param api.format a string indicateing which version of the quickstatement format used to submit the api (default = "v1")
-#'@param api.batchname a string create a named batch (listed at [your batch history page](https://quickstatements.toolforge.org/#/batches)) and tag in the edit summaries
-#'@param api.submit boolian indicating whether to submit instruction directly to wikidata (else returns the URL that can be copy-pasted into a web browser)
-#'
-#'@return data formatted to upload to wikidata (via quickstatemsnts),
-#'optionally also directly uploded to wikidata (see \code{format} parameter).
-#'
-#'@examples
-#'# Add a statement to the "Wikidata sandbox" item (Q4115189)
-#'# to say that it is an "instance of" (P31) of Q1 (the universe).
-#'# The instruction will submit directly to wikidata via the API
-#'# (if you include your wikimedia username and token)
-#'
-#' \donttest{write_wikidata(items = "Wikidata Sandbox",
-#' properties = "instance of",
-#' values = "Q1",
-#' format = "api",
-#' api.username = "myusername",
-#' api.token = , #REDACTED#
-#' )}
-#'#note:
-#'
-#'@export
-
-write_wikidata <- function(items,
- properties = NULL,
- values = NULL,
- qual.properties = NULL,
- qual.values = NULL,
- src.properties = NULL,
- src.values = NULL,
- remove = FALSE,
- format = "tibble",
- api.username = NULL,
- api.token = NULL, # Find yours from [your user page](https://tools.wmflabs.org/quickstatements/#/user)
- api.format = "v1",
- api.batchname = NULL,
- api.submit = TRUE
-){
-
- # Check if username and token provided
- if(format=="api"){
- if(is.null(api.username)){stop("Enter your Wikimedia username")}
- if(is.null(api.token)) {stop("Enter your api.token (Find yours at https://tools.wmflabs.org/quickstatements/#/user)")}
- }
-
- # Place all the quickstatements variables into a list
- QS <- list(items = items,
- properties = properties,
- values = values,
- qual.properties = qual.properties,
- qual.values = qual.values,
- src.properties = src.properties,
- src.values = src.values)
- QS <- lapply(QS,function(x){if(!is.null(x)){tibble(x)}})
-
- # If new QIDs are being created via the "CREATE" keyword, need to insert blank lines across the other parameters to align correctly into rows
- # This is the most similar to the standard quickstatements method, though the "CREATExyz" method is preferred (see createrows.tidy function later)
- QS$properties <- createrows(QS$items,QS$properties)
- QS$values <- createrows(QS$items,QS$values)
- QS$qual.properties <- createrows(QS$items,QS$qual.properties)
- QS$qual.values <- createrows(QS$items,QS$qual.values)
- QS$src.properties <- createrows(QS$items,QS$src.properties)
- QS$src.values <- createrows(QS$items,QS$src.values)
-
- # If same number of rows as the rowmax, do nothing
- # If only one row, repeat it rowmax times
- # If wrong number of rows, stop with an error message
- rowcount <- unlist(lapply(QS,nrow))
- rowmax <- max(rowcount)
- stoprun <- FALSE
-
- if(var(unlist(rowcount))!=0){
- for (x in 1:length(QS)){
- if(nrow(QS[[x]])==rowmax){
- QS[[x]] <- QS[[x]]
- }else if (nrow(QS[[x]])==1){
- QS[[x]] <- slice(QS[[x]],rep(1:n(), each=rowmax))
- }else{
- stoprun<-TRUE
- warning(paste0("Not all quickstatement columns have equal rows: ",
- nrow(QS$items)," items (including ",
- sum(is.create(unlist(QS$items)))," new QIDs to CREATE) were provided, but ",
- names(QS)[x],
- " has ",
- nrow(QS[[x]]),
- " rows (expecting ",
- nrow(QS$items),
- ")."))
- }
- }
- }
- if(stoprun){stop("Therefore stopping")}
-
- # Convert values to QIDs where possible and identify which (if any) to remove
- QS$items <- as_qid(QS$items)
- QS$items[remove,] <- paste0("-",unlist(QS$items[remove,]))
-
- # Convert properties to PIDs where possible, unless special functions (such as lables and aliases)
- QS$properties <- as_pid(QS$properties)
-
- # Convert values to QIDs where possible, unless property is expecting a string
- QS$values <- tibble(QS$values)
- if(any(sapply(QS$properties,check.PID.WikibaseItem))){
- QS$values[sapply(QS$properties,check.PID.WikibaseItem),] <- as_qid(QS$values[sapply(QS$properties,check.PID.WikibaseItem),])
- }
- QS$values <- as_quot(QS$values,format)
-
- # Convert first three columns into tibble (tibbulate?)
- colnames(QS$items) <- "Item"
- colnames(QS$properties) <- "Prop"
- colnames(QS$values) <- "Value"
-
- QS.tib <- bind_cols(QS$items,
- QS$properties,
- QS$values)
-
- # optionally, append columns for qualifier properties and qualifier values for those statements
- if(!is.null(QS$qual.properties)|!is.null(QS$qual.values)){
- QS$qual.properties <- as_pid(QS$qual.properties)
- QS$qual.values <- as_quot(QS$qual.values,format)
-
- colnames(QS$qual.properties) <- paste0("Qual.prop.",1:ncol(QS$qual.properties))
- colnames(QS$qual.values) <- paste0("Qual.value.",1:ncol(QS$qual.values))
-
- QSq <- list(QS$qual.properties,
- QS$qual.values)
- QSq.check <- var(sapply(c(QS,QSq),function(x){if(is.null(dim(x))){length(x)}else{nrow(x)}}))==0
- if(!QSq.check){stop("Incorrect number of qualifiers provided. If no qualifers needed for a statement, use NA or \"\".")}
-
- QS.qual.tib <- as_tibble(cbind(QSq[[1]],QSq[[2]])[,c(rbind(1:ncol(QSq[[1]]),ncol(QSq[[1]])+1:ncol(QSq[[2]])))])
-
- QS.tib <- tibble(QS.tib,
- QS.qual.tib)
- }
-
- # optionally, append columns for source properties and source values for those statements
- if(!is.null(src.properties)|!is.null(src.values)){
- QS$src.properties <- as_sid(QS$src.properties)
- QS$src.values <- as_quot(QS$src.values,format)
-
- colnames(QS$src.properties) <- paste0("Src.prop.",1:ncol(QS$src.properties))
- colnames(QS$src.values) <- paste0("Src.values.",1:ncol(QS$src.values))
-
- QSs <- list(QS$src.properties,
- QS$src.values)
- QSs.check <- var(sapply(c(QS,QSs),function(x){if(is.null(dim(x))){length(x)}else{nrow(x)}}))==0
- if(!QSs.check){stop("incorrect number of sources provided")}
-
- QS.src.tib <- as_tibble(cbind(QSs[[1]],QSs[[2]])[,c(rbind(1:ncol(QSs[[1]]),ncol(QSs[[1]])+1:ncol(QSs[[2]])))])
-
- QS.tib <- tibble(QS.tib,
- QS.src.tib)
- }
-
- # if new QIDs are being created via tidy "CREATExyz" keywords, need to insert CREATE lines above and replace subsequent "CREATExyz" with "LAST"
- QS.tib <- createrows.tidy(QS.tib)
-
- # output
- if (format=="csv"){
- write.table(QS.tib,quote = FALSE,row.names = FALSE,sep = ",")
- }
- # format up the output
- if (format=="tibble"){
- return(QS.tib)
- }
- if (format=="api"|format=="website"){
- api.temp1 <- format_tsv(QS.tib, col_names = FALSE)
- api.temp2 <- gsub("\t", "%7C",api.temp1) # Replace TAB with "%7C"
- api.temp3 <- gsub("\n", "%7C%7C",api.temp2) # Replace end-of-line with "%7C%7C"
- api.temp4 <- gsub(" ", "%20",api.temp3) # Replace space with "%20"
- api.temp5 <- gsub("\\+","%2B",api.temp4) # Replace plus with "%2B"
- api.data <- gsub("/", "%2F",api.temp5) # Replace slash with "%2F"
-
- if (format=="api"){
- if (is.null(api.token)){stop("API token needed. Find yours at https://quickstatements.toolforge.org/#/user")}
- url <- paste0("https://tools.wmflabs.org/quickstatements/api.php",
- "?action=", "import",
- "&submit=", "1",
- "&format=", api.format,
- "&batchname=",api.batchname,
- "&username=", api.username,
- "&token=", api.token,
- "&data=", api.data)
- }
- if (format=="website"){
- url <- paste0("https://quickstatements.toolforge.org/#/v1=",
- "&data=", api.data)
- }
- if(api.submit){
- browseURL(url)
- }else{
- return(url)
- }
- }
-}
diff --git a/R/zzz.R b/R/zzz.R
deleted file mode 100644
index 65056d4..0000000
--- a/R/zzz.R
+++ /dev/null
@@ -1,89 +0,0 @@
-# # ----------- Validation checks -----------
-#
-# # Below are the queries used to generate sysdata.rda within the R package
-# # Ideally run these on startup or something? The parameters will change not frequently.
-# # Useful for checking whether quickstatements inputs will be valid to warn early.
-#
-# .onAttach <- function(){
-#
-# message('Updating key variables from wikidata (estimated time <1 min)')
-#
-# # Valid reference source properties
-# message(' ... Checking valid reference source properties')
-# sparql_query <- 'SELECT ?Wikidata_property_to_indicate_a_source ?Wikidata_property_to_indicate_a_sourceLabel WHERE {
-# SERVICE wikibase:label { bd:serviceParam wikibase:language "[AUTO_LANGUAGE],en". }
-# ?Wikidata_property_to_indicate_a_source wdt:P31 wd:Q18608359.
-# }'
-# SID.valid <- query_wikidata(sparql_query)
-#
-# # The required data type for each property
-# message(' ... Checking required data type for each property')
-# sparql_query <- 'SELECT ?property ?propertyLabel ?wbtype WHERE {
-# SERVICE wikibase:label { bd:serviceParam wikibase:language "[AUTO_LANGUAGE],en". }
-# ?property rdf:type wikibase:Property.
-# ?property wikibase:propertyType ?wbtype.
-# }'
-# PID.datatype <- query_wikidata(sparql_query)
-# PID.datatype$wbtype <- gsub("ontology#","",PID.datatype$wbtype)
-#
-# # The expected regex match for each property
-# message(' ... Checking expected regex match for each property')
-# # Those with a 'format as a regular expression' (P1793) listed as a qualifier of their 'property constraint' (P2302)
-# sparql_query1 <- 'SELECT DISTINCT ?Wikidata_property ?Wikidata_propertyLabel ?fmt WHERE {
-# SERVICE wikibase:label { bd:serviceParam wikibase:language "[AUTO_LANGUAGE],en". }
-# ?Wikidata_property wdt:P31/wdt:P279* wd:Q18616576.
-# ?Wikidata_property p:P2302 [pq:P1793 ?fmt].
-# }'
-# # Those with a 'format as a regular expression' (P1793) only listed as a property statement
-# sparql_query2 <- 'SELECT DISTINCT ?Wikidata_property ?Wikidata_propertyLabel ?fmt WHERE {
-# SERVICE wikibase:label { bd:serviceParam wikibase:language "[AUTO_LANGUAGE],en". }
-# ?Wikidata_property wdt:P31/wdt:P279* wd:Q18616576.
-# ?Wikidata_property wdt:P1793 ?fmt
-# MINUS{?Wikidata_property p:P2302 [pq:P1793 ?fmtmain]}.
-# }'
-# PID.constraint <- add_row(query_wikidata(sparql_query1),
-# query_wikidata(sparql_query2))
-#
-#
-# # Language abbreviations
-# message(' ... Checking language abbreviations')
-# sparql_query <- 'SELECT ?abbrev WHERE {
-# ?language wdt:P305 ?abbrev.
-# }'
-# lang.abbrev <- query_wikidata(sparql_query)
-#
-# # Language abbreviations for current wikis
-# message(' ... Checking language abbreviations for current wikis')
-# sparql_query <- 'SELECT ?abbrev WHERE {
-# ?Wikipedia_language_edition wdt:P31 wd:Q10876391.
-# ?Wikipedia_language_edition wdt:P424 ?abbrev.
-# }'
-# lang.abbrev.wiki <- query_wikidata(sparql_query)
-#
-# # Wikimedia abbreviations for current wikis
-# message(' ... Checking Wikimedia abbreviations for current wikis')
-# sparql_query <- 'SELECT ?abbrev WHERE {
-# ?Wiki_edition wdt:P1800 ?abbrev.
-# }'
-# abbrev.wiki <- query_wikidata(sparql_query)
-#
-# # #example
-# # grep(as.matrix(PID.constraint[PID.constraint$Wikidata_property=="P968","fmt"]),
-# # "mailto:t.shafee@gmail.com",
-# # perl=TRUE)
-# assign(x = "WD.globalvar",
-# envir = .GlobalEnv,
-# value = list(SID.valid = SID.valid,
-# PID.datatype = PID.datatype,
-# PID.constraint = PID.constraint,
-# lang.abbrev = lang.abbrev,
-# lang.abbrev.wiki = lang.abbrev.wiki,
-# abbrev.wiki = abbrev.wiki)
-# )
-#
-# message('Update complete (data saved as WD.globalvar)')
-# }
-
-
-# # Below used to save as system data within an R package
-# save(list="WD.globalvar",file="R//sysdata.rda", compress = "xz")
\ No newline at end of file
diff --git a/README.md b/README.md
index dbe8aa2..e38a002 100644
--- a/README.md
+++ b/README.md
@@ -1,201 +1,38 @@
-WikidataR
-=========
-
-An combined R package for reading, writing and handling Wikidata semantic data (via APIs).
-
-__Authors:__ [Thomas Shafee](https://github.com/TS404) (aut., maint.), [Os Keys](https://github.com/Ironholds) (aut., cre.)
-__License:__ [MIT](https://opensource.org/licenses/MIT)
-__Status:__ Stable
-
-Description
-======
-WikidataR includes functions to:
-- read from wikidata (single items, properties, or properties)
-- query wikidata (retrieving all items that match a set of criterial via [Wikidata SPARQL query service](https://query.wikidata.org))
-- write to Wikidata (adding new items or statements via [QuickStatements](https://tools.wmflabs.org/quickstatements))
-- Handle and manipulate Wikidata objects (as lists and tibbles)
-For details on how to best use it, see the examples below.
-
-Installation
-======
-
-To download WikidataR from CRAN:
-
- install.packages("WikidataR","WikidataQueryServiceR")
-
-To get the current development version from github:
-
- install.packages("devtools")
- devtools::install_github("r-lib/httr")
-
-Examples
-======
-### Search Wikidata to see if an item exists (example: pharmaceuticals)
-For cases where you don't already know the QID of an item or the PID of a property, you can search wikidata by name. Note that some search terms will return multiple possible items. You can also specify a language (defaults to Engligh).
-
-``` r
-find_item("Paracetamol")
-find_property("medical condition treated")
-```
-Which returns the lists:
-
-```
- acetaminophen (Q57055) - common drug for pain and fever
- Paracetamol (Q36716177) - scientific article published on July 1980
- Paracetamol (Q54982056) - musical group
- ...
-```
-
-and
-```
- medical condition treated (P2175) - disease that this pharmaceutical drug, procedure, or therapy is used to treat
-```
-Elements within those lists include basic information from wikidata (ID, description, labels). The QID or PID can then be used to get the full data for the item (see below).
-
-### Convert between identifiers
-Wikidata is an excellent thesaurus for different identifiers. For example it's possible to convert from any identifier to wikidata QIDs or between different identifiers
-``` r
-qid_from_identifier('ISBN-13','978-0-262-53817-6')
-identifier_from_identifier('ORCID iD','IMDb ID',c('0000-0002-7865-7235','0000-0003-1079-5604'))
-```
-Which returns the lists:
-```
- 978-0-262-53817-6 Q102035721 Wikipedia @ 20: Stories of an Incomplete Revolution
-```
-and
-```
- # A tibble: 2 x 2
- value return
- <chr> <fct>
- 1 0000-0002-7865-7235 nm2118834
- 2 0000-0003-1079-5604 nm1821217
-```
-
-### Get full items from Wikidata (example: journal articles)
-In this example, we search for three articles using their DOIs ([P356](https://www.wikidata.org/wiki/Property:P356)), find their QIDs, download their full wikidata entries, and then extract the "main topics" (note PID didn't have to be used).
-
-``` r
-article.qid <- qid_from_DOI(c('10.15347/WJM/2017.007','10.15347/WJM/2019.001','10.15347/WJM/2019.007'))
-article.q <- get_item(article.qid)
-article.topics.p <- extract_claims(article.q, "main topic")
-get_names_from_properties(article.topics.p)
-```
-Which returns a tibble for each of the journal articles, listing the main topics of each and their QIDs.
-```
- $`10.15347/WJM/2017.007`
- # A tibble: 1 x 2
- QID value
- <chr> <chr>
- 1 P921.Q164778 rotavirus
-
- $`10.15347/WJM/2019.001`
- # A tibble: 2 x 2
- QID value
- <chr> <chr>
- 1 P921.Q15989108 Western African Ebola virus epidemic
- 2 P921.Q10538943 Ebola virus
-
- $`10.15347/WJM/2019.007`
- # A tibble: 2 x 2
- QID value
- <chr> <chr>
- 1 P921.Q1820650 readability
- 2 P921.Q16235120 health information on Wikipedia
-```
-
-### Query Wikidata with complex searches (example: movie genres)
-
-In this example, we search Wikidata for any items that are an "instance of" ([P31](https://www.wikidata.org/wiki/Property:P31)) "film" ([Q11424](https://www.wikidata.org/wiki/Q11424)) that has the label "The Cabin in the Woods" ([Q45394](https://www.wikidata.org/wiki/Q45394)), and ask for the item's genres ([P136](https://www.wikidata.org/wiki/Property:P136)).
-
-``` r
-query_wikidata('SELECT DISTINCT
- ?genre ?genreLabel
-WHERE {
- ?film wdt:P31 wd:Q11424.
- ?film rdfs:label "The Cabin in the Woods"@en.
- ?film wdt:P136 ?genre.
- SERVICE wikibase:label { bd:serviceParam wikibase:language "en". }
-}')
-```
-Which returns a tibble:
-```
- # A tibble: 6 x 2
- genre genreLabel
- <chr> <chr>
- 1 http://www.wikidata.org/entity/Q3072049 zombie film
- 2 http://www.wikidata.org/entity/Q471839 science fiction film
- 3 http://www.wikidata.org/entity/Q859369 comedy-drama
- 4 http://www.wikidata.org/entity/Q1342372 monster film
- 5 http://www.wikidata.org/entity/Q853630 slasher film
- 6 http://www.wikidata.org/entity/Q224700 comedy horror
-```
-
-For more example SPARQL queries, see [this page](https://www.wikidata.org/wiki/Wikidata:SPARQL_query_service/queries/examples) on [Wikidata](https://www.wikidata.org/wiki/Wikidata:Main_Page).
-
-`query_wikidata()` can accept multiple queries, returning a (potentially named) list of data frames. If the vector of SPARQL queries is named, the results will inherit those names.
-
-#### Links for learning SPARQL
-
-- [A beginner-friendly course for SPARQL](https://www.wikidata.org/wiki/Wikidata:A_beginner-friendly_course_for_SPARQL)
-- Building a SPARQL query: [Museums on Instagram](https://www.wikidata.org/wiki/Help:SPARQL/Building_a_query/Museums_on_Instagram)
-- [SPARQL Query Examples](https://www.wikidata.org/wiki/Wikidata:SPARQL_query_service/queries/examples) for WDQS
-- [Using SPARQL to access Linked Open Data](https://programminghistorian.org/lessons/graph-databases-and-SPARQL) by Matthew Lincoln
-- Interesting or illustrative [SPARQL queries](https://www.wikidata.org/wiki/Wikidata:SPARQL_query_service/queries) for Wikidata
-- Wikidata [2016 SPARQL Workshop](https://www.wikidata.org/wiki/Wikidata:SPARQL_query_service/2016_SPARQL_Workshop)
-- [Wikidata SPARQL Query video tutorial](https://www.youtube.com/watch?v=1jHoUkj_mKw) by Navino Evans
-- *[Learning SPARQL](http://www.learningsparql.com/)* by Bob DuCharme
-- [WDQS User Manual](https://www.mediawiki.org/wiki/Wikidata_query_service/User_Manual)
-
-### Write to Wikidata (example: paintings)
-In this example we'll write directly to wikidata via the [QuickStatements](https://tools.wmflabs.org/quickstatements) format.
-``` r
-write_wikidata(items = c("Q4115189","Q13406268"),
- properties = "author",
- values = c("Q762","Q41406"),
- format = "api",
- api.username = "myusername", # Enter your Wikimedia username here
- api.token = "" #REDACTED# Find yours from https://tools.wmflabs.org/quickstatements/#/user
- )
-```
-Results in the statements being directly added to wikidata under your username via the API.
-> The Mona Lisa (Q12418) has the Creator (P170) of Leonardo da Vinci (Q762)
-> The Scream (Q471379) has the Creator (P170) of Edvard Munch (Q41406)
-
-Alternatively, you can print via <code>format=tibble</code> and paste into the [QuickStatements](https://tools.wmflabs.org/quickstatements) website.
-
-### Combining all of the above (example: journal articles)
-The example below finds all articles in a journal, works out the URL for their peer reviews, and writes those URLs into those articles' wikidata items.
-``` r
-sparql_query <- 'SELECT ?Article ?ArticleLabel ?JLabel ?T ?peer_review_URL WHERE {
- SERVICE wikibase:label { bd:serviceParam wikibase:language "[AUTO_LANGUAGE],en". }
- ?Article wdt:P1433 wd:Q24657325.
- OPTIONAL { ?Article wdt:P1433 ?J. }
- OPTIONAL { ?Article wdt:P1476 ?T. }
- OPTIONAL { ?Article wdt:P7347 ?peer_review_URL. }}
-LIMIT 10000'
-articles.qr <- as_tibble(query_wikidata(sparql_query))
-articles.qr <- articles.qr[articles.qr$peer_review_URL=="",] #omit those with review URLs listed
-review.URLs <- paste0('https://en.wikiversity.org/wiki/Talk:',
- articles.qr$JLabel,
- "/",
- articles.qr$T
- )
-review.URLs <- gsub(" ","_",review.URLs)
-
-write_wikidata(items = sapply(sapply(articles.qr$Article,pattern = "/",stringr::str_split),tail,1),
- properties = "Peer review URL",
- values = review.URLs,
- format = "tibble",
- )
-
-write_wikidata(items = sapply(sapply(articles.qr$Article,pattern = "/",stringr::str_split),tail,1),
- properties = "Peer review URL",
- values = review.URLs,
- format = "api",
- api.username = "myusername",
- api.token = , #REDACTED# Find yours from https://tools.wmflabs.org/quickstatements/#/user
- )
-```
-### Acknowledgements
-This package combines and builds on the utilities of Os Keyes' [WikidataR](https://github.com/Ironholds/WikidataR), Christian Graul's
-[rwikidata](https://github.com/chgrl/rwikidata), Mikhail Popov's [WikidataQueryServiceR](https://github.com/wikimedia/WikidataQueryServiceR), and Serena Signorelli's [QueryWikidataR](https://github.com/serenasignorelli/QueryWikidataR) packages. It also uses the Magnus Manske's [QuickStatements](https://github.com/magnusmanske/quickstatements) tool.
+WikidataR
+=========
+
+An R API wrapper for the Wikidata store of semantic data.
+
+__Author:__ Oliver Keyes, Serena Signorelli & Christian Graul<br/>
+__License:__ [MIT](http://opensource.org/licenses/MIT)<br/>
+__Status:__ Stable
+
+[](https://travis-ci.org/Ironholds/WikidataR)
+
+Description
+======
+WikidataR is a wrapper around the Wikidata API. It is written in and for R, and was inspired by Christian Graul's
+[rwikidata](https://github.com/chgrl/rwikidata) project. For details on how to best use it, see the [explanatory
+vignette](https://CRAN.R-project.org/package=WikidataR/vignettes/Introduction.html).
+
+Please note that this project is released with a
+[Contributor Code of Conduct](https://github.com/Ironholds/WikidataR/blob/master/CONDUCT.md).
+By participating in this project you agree to abide by its terms.
+
+Installation
+======
+
+For the most recent CRAN version:
+
+ install.packages("WikidataR")
+
+For the development version:
+
+ library(devtools)
+ devtools::install_github("ironholds/WikidataR")
+
+Dependencies
+======
+* R. Doy.
+* [httr](https://cran.r-project.org/package=httr) and its dependencies.
+* [WikipediR](https://cran.r-project.org/package=WikipediR)
diff --git a/build/vignette.rds b/build/vignette.rds
new file mode 100644
index 0000000..c8401ac
Binary files /dev/null and b/build/vignette.rds differ
diff --git a/debian/changelog b/debian/changelog
index b325a4b..191f922 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -1,8 +1,12 @@
-r-cran-wikidatar (2.3.3-2) UNRELEASED; urgency=medium
+r-cran-wikidatar (2.3.3+git20171223.1.647d2af-1) UNRELEASED; urgency=medium
+ [ Andreas Tille ]
* Disable reprotest
- -- Andreas Tille <tille@debian.org> Sat, 04 Dec 2021 08:27:35 +0100
+ [ Debian Janitor ]
+ * New upstream snapshot.
+
+ -- Andreas Tille <tille@debian.org> Thu, 19 Jan 2023 06:04:03 -0000
r-cran-wikidatar (2.3.3-1) unstable; urgency=medium
diff --git a/inst/doc/Introduction.R b/inst/doc/Introduction.R
new file mode 100644
index 0000000..9761ab4
--- /dev/null
+++ b/inst/doc/Introduction.R
@@ -0,0 +1,36 @@
+## ---- eval=FALSE--------------------------------------------------------------
+# #Retrieve an item
+# item <- get_item(id = 1)
+#
+# #Get information about the property of the first claim it has.
+# first_claim <- get_property(id = names(item$claims)[1])
+# #Do we succeed? Dewey!
+
+## ---- eval=FALSE--------------------------------------------------------------
+# #Retrieve a random item
+# rand_item <- get_random_item()
+#
+# #Retrieve a random property
+# rand_prop <- get_random_property()
+
+## ---- eval=FALSE--------------------------------------------------------------
+# #Retrieve 42 random items
+# rand_item <- get_random_item(limit = 42)
+#
+# #Retrieve 42 random properties
+# rand_prop <- get_random_property(limit = 42)
+
+## ---- eval=FALSE--------------------------------------------------------------
+# #Find item - find defaults to "en" as a language.
+# aarons <- find_item("Aaron Halfaker")
+#
+# #Find a property - also defaults to "en"
+# first_names <- find_property("first name")
+
+## ---- eval=FALSE--------------------------------------------------------------
+# #Find item.
+# all_aarons <- find_item("Aaron Halfaker")
+#
+# #Grab the ID code for the first entry and retrieve the associated item data.
+# first_aaron <- get_item(all_aarons[[1]]$id)
+
diff --git a/inst/doc/Introduction.Rmd b/inst/doc/Introduction.Rmd
new file mode 100644
index 0000000..e22aae2
--- /dev/null
+++ b/inst/doc/Introduction.Rmd
@@ -0,0 +1,82 @@
+<!--
+%\VignetteEngine{knitr::knitr}
+%\VignetteIndexEntry{Introduction to WikidataR}
+-->
+
+# WikidataR: the API client library for Wikidata
+Wikidata is a wonderful and irreplaceable resource for linked data, containing information on pretty much any subject. If there's a Wikipedia article on it, there's almost certainly a Wikidata item for it.
+
+<code>WikidataR</code> - following the naming scheme of [WikipediR](https://github.com/Ironholds/WikipediR#thanks-and-misc) - is an API client library for Wikidata, written in and accessible from R.
+
+## Items and properties
+The two basic component pieces of Wikidata are "items" and "properties". An "item" is a thing - a concept, object or
+topic that exists in the real world, such as "Rush". These items each have statements associated with them - for
+example, "Rush is an instance of: Rock Band". In that statement, "Rock Band" is a property: a class or trait
+that items can hold. Wikidata items are organised as descriptors of the item, in various languages, and references to the properties that that item holds.
+
+## Retrieving specific items or properties
+Items and properties are both identified by numeric IDs, prefaced with "Q" in the case of items,
+and "P" in the case of properties. WikipediR can be used to retrieve items or properties with specific
+ID numbers, using the <code>get\_item</code> and <code>get\_property</code> functions:
+
+```{r, eval=FALSE}
+#Retrieve an item
+item <- get_item(id = 1)
+
+#Get information about the property of the first claim it has.
+first_claim <- get_property(id = names(item$claims)[1])
+#Do we succeed? Dewey!
+```
+
+These functions are capable of accepting various forms for the ID, including (as examples), "Q100" or "100"
+for items, and "Property:P100", "P100" or "100" for properties. They're also vectorised - pass them as many IDs as you want!
+
+## Retrieving randomly-selected items or properties
+As well as retrieving specific items or properties, Wikidata's API also allows for the retrieval of *random*
+elements. With WikidataR, this can be achieved through:
+
+```{r, eval=FALSE}
+#Retrieve a random item
+rand_item <- get_random_item()
+
+#Retrieve a random property
+rand_prop <- get_random_property()
+```
+
+These also allow you to retrieve *sets* of random elements - not just one at a time, but say, 50 at a time - by including the "limit" argument:
+
+```{r, eval=FALSE}
+#Retrieve 42 random items
+rand_item <- get_random_item(limit = 42)
+
+#Retrieve 42 random properties
+rand_prop <- get_random_property(limit = 42)
+```
+
+## Search
+Wikidata's search functionality can also be used, either to find items or to find properties. All you need is
+a search string (which is run over the names and descriptions of items or properties) and a language code
+(since Wikidata's descriptions can be in many languages):
+
+```{r, eval=FALSE}
+#Find item - find defaults to "en" as a language.
+aarons <- find_item("Aaron Halfaker")
+
+#Find a property - also defaults to "en"
+first_names <- find_property("first name")
+```
+
+The resulting search entries have the ID as a key, making it trivial to then retrieve the full corresponding
+items or properties:
+
+```{r, eval=FALSE}
+#Find item.
+all_aarons <- find_item("Aaron Halfaker")
+
+#Grab the ID code for the first entry and retrieve the associated item data.
+first_aaron <- get_item(all_aarons[[1]]$id)
+```
+
+## Other and future functionality
+If you have ideas for other types of useful Wikidata access, the best approach
+is to either [request it](https://github.com/Ironholds/WikidataR/issues) or [add it](https://github.com/Ironholds/WikidataR/pulls)!
diff --git a/inst/doc/Introduction.html b/inst/doc/Introduction.html
new file mode 100644
index 0000000..7c0ebd4
--- /dev/null
+++ b/inst/doc/Introduction.html
@@ -0,0 +1,152 @@
+<!DOCTYPE html>
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
+
+<title>WikidataR: the API client library for Wikidata</title>
+
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.6.0/build/styles/github.min.css">
+<script src="https://cdn.jsdelivr.net/combine/gh/highlightjs/cdn-release@11.6.0/build/highlight.min.js,npm/@xiee/utils/js/load-highlight.js" async></script>
+
+
+
+<style type="text/css">
+body, td {
+ font-family: sans-serif;
+ background-color: white;
+ font-size: 13px;
+}
+body {
+ max-width: 800px;
+ margin: auto;
+ padding: 1em;
+ line-height: 1.5;
+}
+tt, code, pre {
+ font-family: 'DejaVu Sans Mono', 'Droid Sans Mono', 'Lucida Console', Consolas, Monaco, monospace;
+}
+a:visited { color: #80007f; }
+pre, img { max-width: 100%; }
+code {
+ font-size: 92%;
+ border: 1px solid #ccc;
+}
+code[class] { background-color: #F8F8F8; }
+code.language-undefined { background-color: inherit; }
+table {
+ margin: auto;
+ border-top: 1px solid #666;
+ border-bottom: 1px solid #666;
+}
+table thead th { border-bottom: 1px solid #ddd; }
+th, td { padding: 5px; }
+thead, tfoot, tr:nth-child(even) { background: #eee; }
+blockquote {
+ color:#666;
+ margin:0;
+ padding-left: 1em;
+ border-left: 0.5em #eee solid;
+}
+hr { border: 1px #ddd dashed; }
+
+@media print {
+ * {
+ background: transparent !important;
+ color: black !important;
+ filter:none !important;
+ }
+ body {
+ font-size: 12pt;
+ max-width: 100%;
+ }
+ a, a:visited { text-decoration: underline; }
+ hr {
+ visibility: hidden;
+ page-break-before: always;
+ }
+ pre, blockquote {
+ padding-right: 1em;
+ page-break-inside: avoid;
+ }
+ tr, img { page-break-inside: avoid; }
+ img { max-width: 100% !important; }
+ @page :left { margin: 15mm 20mm 15mm 10mm; }
+ @page :right { margin: 15mm 10mm 15mm 20mm; }
+ p, h2, h3 { orphans: 3; widows: 3; }
+ h2, h3 { page-break-after: avoid; }
+}
+</style>
+
+
+
+</head>
+
+<body>
+<!--
+%\VignetteEngine{knitr::knitr}
+%\VignetteIndexEntry{Introduction to WikidataR}
+-->
+<h1>WikidataR: the API client library for Wikidata</h1>
+<p>Wikidata is a wonderful and irreplaceable resource for linked data, containing information on pretty much any subject. If there’s a Wikipedia article on it, there’s almost certainly a Wikidata item for it.</p>
+<p><code>WikidataR</code> - following the naming scheme of <a href="https://github.com/Ironholds/WikipediR#thanks-and-misc">WikipediR</a> - is an API client library for Wikidata, written in and accessible from R.</p>
+<h2>Items and properties</h2>
+<p>The two basic component pieces of Wikidata are “items” and “properties”. An “item” is a thing - a concept, object or
+topic that exists in the real world, such as “Rush”. These items each have statements associated with them - for
+example, “Rush is an instance of: Rock Band”. In that statement, “Rock Band” is a property: a class or trait
+that items can hold. Wikidata items are organised as descriptors of the item, in various languages, and references to the properties that that item holds.</p>
+<h2>Retrieving specific items or properties</h2>
+<p>Items and properties are both identified by numeric IDs, prefaced with “Q” in the case of items,
+and “P” in the case of properties. WikipediR can be used to retrieve items or properties with specific
+ID numbers, using the <code>get_item</code> and <code>get_property</code> functions:</p>
+<pre><code class="language-r">#Retrieve an item
+item <- get_item(id = 1)
+
+#Get information about the property of the first claim it has.
+first_claim <- get_property(id = names(item$claims)[1])
+#Do we succeed? Dewey!
+</code></pre>
+<p>These functions are capable of accepting various forms for the ID, including (as examples), “Q100” or “100”
+for items, and “Property:P100”, “P100” or “100” for properties. They’re also vectorised - pass them as many IDs as you want!</p>
+<h2>Retrieving randomly-selected items or properties</h2>
+<p>As well as retrieving specific items or properties, Wikidata’s API also allows for the retrieval of <em>random</em>
+elements. With WikidataR, this can be achieved through:</p>
+<pre><code class="language-r">#Retrieve a random item
+rand_item <- get_random_item()
+
+#Retrieve a random property
+rand_prop <- get_random_property()
+</code></pre>
+<p>These also allow you to retrieve <em>sets</em> of random elements - not just one at a time, but say, 50 at a time - by including the “limit” argument:</p>
+<pre><code class="language-r">#Retrieve 42 random items
+rand_item <- get_random_item(limit = 42)
+
+#Retrieve 42 random properties
+rand_prop <- get_random_property(limit = 42)
+</code></pre>
+<h2>Search</h2>
+<p>Wikidata’s search functionality can also be used, either to find items or to find properties. All you need is
+a search string (which is run over the names and descriptions of items or properties) and a language code
+(since Wikidata’s descriptions can be in many languages):</p>
+<pre><code class="language-r">#Find item - find defaults to "en" as a language.
+aarons <- find_item("Aaron Halfaker")
+
+#Find a property - also defaults to "en"
+first_names <- find_property("first name")
+</code></pre>
+<p>The resulting search entries have the ID as a key, making it trivial to then retrieve the full corresponding
+items or properties:</p>
+<pre><code class="language-r">#Find item.
+all_aarons <- find_item("Aaron Halfaker")
+
+#Grab the ID code for the first entry and retrieve the associated item data.
+first_aaron <- get_item(all_aarons[[1]]$id)
+</code></pre>
+<h2>Other and future functionality</h2>
+<p>If you have ideas for other types of useful Wikidata access, the best approach
+is to either <a href="https://github.com/Ironholds/WikidataR/issues">request it</a> or <a href="https://github.com/Ironholds/WikidataR/pulls">add it</a>!</p>
+
+
+<script src="https://cdn.jsdelivr.net/combine/npm/@xiee/utils/js/center-img.min.js" async></script>
+</body>
+
+</html>
diff --git a/inst/extdata/WD.globalvar.RDS b/inst/extdata/WD.globalvar.RDS
deleted file mode 100644
index a3e7836..0000000
Binary files a/inst/extdata/WD.globalvar.RDS and /dev/null differ
diff --git a/man/WD.globalvar.Rd b/man/WD.globalvar.Rd
deleted file mode 100644
index 2c65d7e..0000000
--- a/man/WD.globalvar.Rd
+++ /dev/null
@@ -1,20 +0,0 @@
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/data.R
-\name{WD.globalvar}
-\alias{WD.globalvar}
-\title{Global variables for Wikidata properties}
-\format{
-A list of tibbles documenting key property constraints from wikidata
-\describe{
- \item{SID.valid}{valid reference source properties}
- \item{PID.datatype}{required data type for each property}
- \item{PID.constraint}{expected regex match for each property}
- \item{lang.abbrev}{language abbreviations}
- \item{lang.abbrev.wiki}{language abbreviations for current wikis}
- \item{abbrev.wiki}{Wikimedia abbreviations for current wikis}
- ...
-}
-}
-\description{
-A dataset of Wikidata global variables.
-}
diff --git a/man/WikidataR.Rd b/man/WikidataR.Rd
index c21bd17..2ea9768 100644
--- a/man/WikidataR.Rd
+++ b/man/WikidataR.Rd
@@ -1,19 +1,18 @@
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/WikidataR.R
-\docType{package}
-\name{WikidataR}
-\alias{WikidataR}
-\alias{WikidataR-package}
-\title{API client library for Wikidata}
-\description{
-This package serves as an API client for reading and writing
-to and from \href{https://www.wikidata.org/wiki/Wikidata:Main_Page}{Wikidata}, (including
-via the \href{https://quickstatements.toolforge.org/}{QuickStatements} format),
-as well as for reading from \href{https://www.wikipedia.org}{Wikipedia}.
-}
-\seealso{
-\code{\link{get_random}} for selecting a random item or property,
-\code{\link{get_item}} for a /specific/ item or property, or \code{\link{find_item}}
-for using search functionality to pull out item or property IDs where the descriptions
-or aliases match a particular search term.
-}
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/WikidataR.R
+\docType{package}
+\name{WikidataR}
+\alias{WikidataR}
+\alias{WikidataR-package}
+\alias{WikidataR-package}
+\title{API client library for Wikidata}
+\description{
+This package serves as an API client for \href{Wikidata}{https://www.wikidata.org}.
+See the accompanying vignette for more details.
+}
+\seealso{
+\code{\link{get_random}} for selecting a random item or property,
+\code{\link{get_item}} for a /specific/ item or property, or \code{\link{find_item}}
+for using search functionality to pull out item or property IDs where the descriptions
+or aliases match a particular search term.
+}
diff --git a/man/as_pid.Rd b/man/as_pid.Rd
deleted file mode 100644
index 02bbe2b..0000000
--- a/man/as_pid.Rd
+++ /dev/null
@@ -1,27 +0,0 @@
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/utils.R
-\name{as_pid}
-\alias{as_pid}
-\title{Convert an input to a property PID}
-\usage{
-as_pid(x)
-}
-\arguments{
-\item{x}{a vector, data frame, or tibble of strings representaing wikidata properties}
-}
-\value{
-if the inputted string is a valid PID, return the string.
-If the inputted string matches a property label, return its PID.
-If the inputted string matches multiple labels of multiple properties, return the PID of the first hit.
-}
-\description{
-Convert an input string to the most likely property PID
-}
-\examples{
-# if input string is a valid PID
-as_pid("P50")
-# if input string matches multiple item labels
-as_pid("author")
-# if input string matches a single unique label
-as_pid("Scopus author ID")
-}
diff --git a/man/as_qid.Rd b/man/as_qid.Rd
deleted file mode 100644
index b61cb54..0000000
--- a/man/as_qid.Rd
+++ /dev/null
@@ -1,27 +0,0 @@
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/utils.R
-\name{as_qid}
-\alias{as_qid}
-\title{Convert an input to a item QID}
-\usage{
-as_qid(x)
-}
-\arguments{
-\item{x}{a vector, data frame, or tibble of strings representaing wikidata items}
-}
-\value{
-if the inputted string is a valid QID, return the string.
-If the inputted string matches an item label, return its QID.
-If the inputted string matches multiple labels of multiple items, return the QID of the first hit.
-}
-\description{
-Convert an input string to the most likely item QID
-}
-\examples{
-# if input string is a valid QID
-as_qid("Q42")
-# if input string matches multiple item labels
-as_qid("Douglas Adams")
-# if input string matches a single unique label
-as_qid("Douglas Adams and the question of arterial blood pressure in mammals")
-}
diff --git a/man/as_quot.Rd b/man/as_quot.Rd
deleted file mode 100644
index e8a2e1c..0000000
--- a/man/as_quot.Rd
+++ /dev/null
@@ -1,23 +0,0 @@
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/utils.R
-\name{as_quot}
-\alias{as_quot}
-\title{Add quotations marks}
-\usage{
-as_quot(x, format = "tibble")
-}
-\arguments{
-\item{x}{a vector, data frame, or tibble of strings}
-
-\item{format}{either "tibble" / "csv" to use plain quotation marks (default), or "api" / "website" to use '\%22'}
-}
-\value{
-tibble of items inside of escaped quotation marks
-unless they are already in escaped quotation marks, is a QID, (in which chase it is returned unchanged)
-}
-\description{
-Add escaped quotation marks around strings that need them ready for submision to an API
-}
-\examples{
-as_quot("text")
-}
diff --git a/man/as_sid.Rd b/man/as_sid.Rd
deleted file mode 100644
index 6f35584..0000000
--- a/man/as_sid.Rd
+++ /dev/null
@@ -1,27 +0,0 @@
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/utils.R
-\name{as_sid}
-\alias{as_sid}
-\title{Convert an input to a source property SID}
-\usage{
-as_sid(x)
-}
-\arguments{
-\item{x}{a vector, data frame, or tibble of strings representaing wikidata source properties}
-}
-\value{
-if the inputted string is a valid SID, return the string.
-If the inputted string matches a property label, return its SID
-If the inputted string matches multiple labels of multiple properties, return the SID of the first hit.
-}
-\description{
-Convert an input string to the most likely source SID (equivalent to PID)
-}
-\examples{
-# if input string is a valid SID
-as_pid("S854")
-# if input string matches multiple item labels
-as_pid("URL")
-# if input string matches a single unique label
-as_pid("Reference URL")
-}
diff --git a/man/check_input.Rd b/man/check_input.Rd
deleted file mode 100644
index 7ad8499..0000000
--- a/man/check_input.Rd
+++ /dev/null
@@ -1,19 +0,0 @@
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/utils.R
-\name{check_input}
-\alias{check_input}
-\title{Generic input checker}
-\usage{
-check_input(input, substitution)
-}
-\arguments{
-\item{input}{string to check}
-
-\item{substitution}{string for what's been looked for}
-}
-\value{
-boolian indicating whether the checked string contains a match for the substitution string
-}
-\description{
-Utility function to handle namespaces. Used by \code{get_item} and \code{get_property}
-}
diff --git a/man/createrows.Rd b/man/createrows.Rd
deleted file mode 100644
index fa15515..0000000
--- a/man/createrows.Rd
+++ /dev/null
@@ -1,22 +0,0 @@
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/utils.R
-\name{createrows}
-\alias{createrows}
-\title{"CREATE" rows}
-\usage{
-createrows(items, vector)
-}
-\arguments{
-\item{items}{a vector, data frame or tibble of items (which may or may not contain the keyword "CREATE")}
-
-\item{vector}{a vector of properties or values which may be expanded based on the items vector}
-}
-\value{
-if the vector is NULL, return NULL. Otherwise, if the "CREATE" keyword appears in the
-items vector, insert blank strings at those positions in the vector.
-}
-\description{
-Add in empty lines for QuickStatements CREATE rows that mint new QIDs.
-This is a slightly messy quirk of the QuickStatements format that mints new QIDs via a line
-containing only "CREATE", so this function is a way to approximate that bevaviour in a tibble
-}
diff --git a/man/createrows.tidy.Rd b/man/createrows.tidy.Rd
deleted file mode 100644
index 0650bd9..0000000
--- a/man/createrows.tidy.Rd
+++ /dev/null
@@ -1,21 +0,0 @@
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/utils.R
-\name{createrows.tidy}
-\alias{createrows.tidy}
-\title{"CREATE" rows from tidy format}
-\usage{
-createrows.tidy(QS.tib)
-}
-\arguments{
-\item{QS.tib}{a tibble of items, values and properties (optionally qualifiers and sources).}
-}
-\value{
-a tibble, with items that start with "CREATE" followed by any unique text causing the
-addition of a "Create" line above, being replaced with "LAST" in the Quickstatemnts format
-to create new QIDs.
-}
-\description{
-Add in QuickStatements CREATE rows that mint new QIDs from tidy input data.
-New items are created by any item starting that starts with the text "CREATE" followed
-by any unique ID.
-}
diff --git a/man/disambiguate_QIDs.Rd b/man/disambiguate_QIDs.Rd
deleted file mode 100644
index 773938c..0000000
--- a/man/disambiguate_QIDs.Rd
+++ /dev/null
@@ -1,80 +0,0 @@
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/disambiguators.R
-\name{disambiguate_QIDs}
-\alias{disambiguate_QIDs}
-\title{Disambiguate QIDs}
-\usage{
-disambiguate_QIDs(
- list,
- variablename = "variables",
- variableinfo = NULL,
- filter_property = NULL,
- filter_variable = NULL,
- filter_firsthit = FALSE,
- limit = 10
-)
-}
-\arguments{
-\item{list}{a list or vector of text strings to find potential QID matches to.
-Can also be a list of lists (see examples)}
-
-\item{variablename}{type of items in the list that are being disambiguated (used in messages)}
-
-\item{variableinfo}{additional information about items that are being disambiguated (used in messages)}
-
-\item{filter_property}{property to filter on (e.g. "P31" to filter on "instance of")}
-
-\item{filter_variable}{values of that property to use to filter out (e.g. "Q571" to filter out books)}
-
-\item{filter_firsthit}{apply filter to the first match presented or only if alternatives requested?
-(default = FALSE, note: true is slower if filter not needed on most matches)}
-
-\item{limit}{number of alternative possible wikidata items to present if multiple potential matches}
-}
-\value{
-a vector of:
-\describe{
- \item{QID}{Selected QID (for when an appropriate Wikidata match exists)}
- \item{CREATE}{Mark that a new Wikidata item should be created (for when no appropriate Wikidata match yet exists)}
- \item{NA}{Mark that no Wikidata item is needed}
- \item{STOP}{Mark that the process was halted at this point (so that output can be used as input to the function later)}
-}
-}
-\description{
-Interactive function that presents alternative possible QID matches for a list of text
-strings and provides options for choosing between alternatives, rejecting all presented alternatives,
-or creating new items. Useful in cases where a list of text strings may have either missing wikidata items
-or multiple alternative potential matches that need to be manually disambuguated. Can also used on
-lists of lists (see examples). For long lists of items, the process can be stopped partway through and
-the returned vector will indicate where the process was stopped.
-}
-\examples{
-\dontrun{
-#Disambiguating possible QID matches for these music genres
-#Results should be:
-# "Q22731" as the first match
-# "Q147538" as the first match
-# "Q3947" as the second alternative match
-disambiguate_QIDs(list=c("Rock","Pop","House"),
- variablename="music genre")
-
-#Disambiguating possible QID matches for these three words, but not the music genres
-#This will take longer as the filtering step is slower
-#Results should be:
-# "Q22731" (the material) as the first match
-# "Q147538" (the soft drink) as the second alternative match
-# "Q3947" (the building) as the first match
-disambiguate_QIDs(list=c("Rock","Pop","House"),
- filter_property="instance of",
- filter_variable="music genre",
- filter_firsthit=TRUE,
- variablename="concept, not the music genre")
-
-#Disambiguating possible QID matches for the multiple expertise of
-#these three people as list of lists
-disambiguate_QIDs(list=list(alice=list("physics","chemistry","maths"),
- barry=list("history"),
- clair=list("law","genetics","ethics")),
- variablename="expertise")
-}
-}
diff --git a/man/extract_claims.Rd b/man/extract_claims.Rd
index 7a311dc..7f32f98 100644
--- a/man/extract_claims.Rd
+++ b/man/extract_claims.Rd
@@ -1,31 +1,33 @@
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/utils.R
-\name{extract_claims}
-\alias{extract_claims}
-\title{Extract Claims from Returned Item Data}
-\usage{
-extract_claims(items, claims)
-}
-\arguments{
-\item{items}{a list of one or more Wikidata items returned with
-\code{\link{get_item}}.}
-
-\item{claims}{a vector of claims (in the form "P321", "P12") to look for
-and extract.}
-}
-\value{
-a list containing one sub-list for each entry in \code{items},
-and (below that) the found data for each claim. In the event a claim
-cannot be found for an item, an \code{NA} will be returned
-instead.
-}
-\description{
-extract claim information from data returned using
-\code{\link{get_item}}.
-}
-\examples{
-# Get item data
-adams_data <- get_item("42")
-# Get claim data
-claims <- extract_claims(adams_data, "P31")
-}
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/utils.R
+\name{extract_claims}
+\alias{extract_claims}
+\title{Extract Claims from Returned Item Data}
+\usage{
+extract_claims(items, claims)
+}
+\arguments{
+\item{items}{a list of one or more Wikidata items returned with
+\code{\link{get_item}}.}
+
+\item{claims}{a vector of claims (in the form "P321", "P12") to look for
+and extract.}
+}
+\value{
+a list containing one sub-list for each entry in \code{items},
+and (below that) the found data for each claim. In the event a claim
+cannot be found for an item, an \code{NA} will be returned
+instead.
+}
+\description{
+extract claim information from data returned using
+\code{\link{get_item}}.
+}
+\examples{
+# Get item data
+adams_data <- get_item("42")
+
+# Get claim data
+claims <- extract_claims(adams_data, "P31")
+
+}
diff --git a/man/extract_para.Rd b/man/extract_para.Rd
deleted file mode 100644
index a73c51f..0000000
--- a/man/extract_para.Rd
+++ /dev/null
@@ -1,23 +0,0 @@
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/utils.R
-\name{extract_para}
-\alias{extract_para}
-\title{Extract a paragraph of text}
-\usage{
-extract_para(text, para = 1, templ = NULL)
-}
-\arguments{
-\item{text}{the input text as a string}
-
-\item{para}{number indicating which paragraph(s) to return (default=1)}
-
-\item{templ}{an optional string specifying a mediawikitemplate within
-which to restrict the search restrict search}
-}
-\value{
-the nth paragraph of the input text.
-}
-\description{
-Return the nth paragraph of a section of text
-Useful for extracting information from wikipedia or other wikimarkup text
-}
diff --git a/man/filter_qids.Rd b/man/filter_qids.Rd
deleted file mode 100644
index 1d14792..0000000
--- a/man/filter_qids.Rd
+++ /dev/null
@@ -1,40 +0,0 @@
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/utils.R
-\name{filter_qids}
-\alias{filter_qids}
-\title{Filter QIDs}
-\usage{
-filter_qids(
- ids,
- property = "P31",
- filter = c("Q737498", "Q5633421", "Q7725634", "Q13442814", "Q18918145"),
- message = NULL
-)
-}
-\arguments{
-\item{ids}{QIDs to check}
-
-\item{property}{property to check (default = P31 to filter on "instance of")}
-
-\item{filter}{values of that property to use to filter out
-(default = Q737498, Q5633421, Q7725634, Q13442814, and Q18918145 to remove academic
-publications or books)}
-
-\item{message}{message to return (useful for disambiguate_QIDs function)}
-}
-\value{
-a vector of QIDs that do not match the property filter
-}
-\description{
-For a QID or vector of QIDs, remove ones that match a particular statement
-(e.g. remove all that are instances of academic publications or books).
-}
-\examples{
-\dontrun{
-# Filter three items called "Earth Science" to show only those that aren't
-# books, journals or journal articles
-filter_qids(ids = c("Q96695546","Q8008","Q58966429"),
- property = "P31",
- filter = c("Q737498","Q5633421","Q7725634","Q13442814","Q18918145"))
-}
-}
diff --git a/man/find_item.Rd b/man/find_item.Rd
index 92b5b08..d2af2bd 100644
--- a/man/find_item.Rd
+++ b/man/find_item.Rd
@@ -1,40 +1,41 @@
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/gets.R
-\name{find_item}
-\alias{find_item}
-\alias{find_property}
-\title{Search for Wikidata items or properties that match a search term}
-\usage{
-find_item(search_term, language = "en", limit = 10, ...)
-
-find_property(search_term, language = "en", limit = 10)
-}
-\arguments{
-\item{search_term}{a term to search for.}
-
-\item{language}{the language to return the labels and descriptions in; this should
-consist of an ISO language code. Set to "en" by default.}
-
-\item{limit}{the number of results to return; set to 10 by default.}
-
-\item{\\dots}{further arguments to pass to httr's GET.}
-}
-\description{
-\code{find_item} and \code{find_property} allow you to retrieve a set
-of Wikidata items or properties where the aliase or descriptions match a particular
-search term. As with other \code{WikidataR} code, custom print methods are available;
-use \code{\link{str}} to manipulate and see the underlying structure of the data.
-}
-\examples{
-
-#Check for entries relating to Douglas Adams in some way
-adams_items <- find_item("Douglas Adams")
-
-#Check for properties involving the peerage
-peerage_props <- find_property("peerage")
-
-}
-\seealso{
-\code{\link{get_random}} for selecting a random item or property,
-or \code{\link{get_item}} for selecting a specific item or property.
-}
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/gets.R
+\name{find_item}
+\alias{find_item}
+\alias{find_property}
+\alias{find_property}
+\title{Search for Wikidata items or properties that match a search term}
+\usage{
+find_item(search_term, language = "en", limit = 10, ...)
+
+find_property(search_term, language = "en", limit = 10)
+}
+\arguments{
+\item{search_term}{a term to search for.}
+
+\item{language}{the language to return the labels and descriptions in; this should
+consist of an ISO language code. Set to "en" by default.}
+
+\item{limit}{the number of results to return; set to 10 by default.}
+
+\item{...}{further arguments to pass to httr's GET.}
+}
+\description{
+\code{find_item} and \code{find_property} allow you to retrieve a set
+of Wikidata items or properties where the aliase or descriptions match a particular
+search term. As with other \code{WikidataR} code, custom print methods are available;
+use \code{\link{str}} to manipulate and see the underlying structure of the data.
+}
+\examples{
+
+#Check for entries relating to Douglas Adams in some way
+adams_items <- find_item("Douglas Adams")
+
+#Check for properties involving the peerage
+peerage_props <- find_property("peerage")
+
+}
+\seealso{
+\code{\link{get_random}} for selecting a random item or property,
+or \code{\link{get_item}} for selecting a specific item or property.
+}
diff --git a/man/get_example.Rd b/man/get_example.Rd
deleted file mode 100644
index 944831b..0000000
--- a/man/get_example.Rd
+++ /dev/null
@@ -1,38 +0,0 @@
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/gets.R
-\name{get_example}
-\alias{get_example}
-\title{Get an example SPARQL query from Wikidata}
-\usage{
-get_example(example_name)
-}
-\arguments{
-\item{example_name}{the names of the examples as they appear on
-[this page](https://www.wikidata.org/wiki/Wikidata:SPARQL_query_service/queries/examples)}
-}
-\value{
-The SPARQL query as a character vector.
-}
-\description{
-Gets the specified example(s) from
- [SPARQL query service examples page](https://www.wikidata.org/wiki/Wikidata:SPARQL_query_service/queries/examples)
- using [Wikidata's MediaWiki API](https://www.wikidata.org/w/api.php).
-}
-\details{
-If you are planning on extracting multiple examples, please provide
- all the names as a single vector for efficiency.
-}
-\examples{
-\dontrun{
-sparql_query <- extract_example(c("Cats", "Horses"))
-query_wikidata(sparql_query)
-# returns a named list with two data frames
-# one called "Cats" and one called "Horses"
-sparql_query <- extract_example("Largest cities with female mayor")
-cat(sparql_query)
-query_wikidata(sparql_query)
-}
-}
-\seealso{
-[query_wikidata]
-}
diff --git a/man/get_geo_box.Rd b/man/get_geo_box.Rd
index c69c741..899c005 100644
--- a/man/get_geo_box.Rd
+++ b/man/get_geo_box.Rd
@@ -1,64 +1,58 @@
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/geo.R
-\name{get_geo_box}
-\alias{get_geo_box}
-\title{Get geographic entities based on a bounding box}
-\usage{
-get_geo_box(
- first_city_code,
- first_corner,
- second_city_code,
- second_corner,
- language = "en",
- ...
-)
-}
-\arguments{
-\item{first_city_code}{a Wikidata item, or series of items, to use for
-one corner of the bounding box.}
-
-\item{first_corner}{the direction of \code{first_city_code} relative
-to \code{city} (eg "NorthWest", "SouthEast").}
-
-\item{second_city_code}{a Wikidata item, or series of items, to use for
-one corner of the bounding box.}
-
-\item{second_corner}{the direction of \code{second_city_code} relative
-to \code{city} (eg "NorthWest", "SouthEast").}
-
-\item{language}{the two-letter language code to use for the name
-of the item. "en" by default.}
-
-\item{\\dots}{further arguments to pass to httr's GET.}
-}
-\value{
-a data.frame of 5 columns:
-\itemize{
- \item{item}{ the Wikidata identifier of each object associated with
- \code{entity}.}
- \item{name}{ the name of the item, if available, in the requested language. If it
- is not available, \code{NA} will be returned instead.}
- \item{latitude}{ the latitude of \code{item}}
- \item{longitude}{ the longitude of \code{item}}
- \item{entity}{ the entity the item is associated with (necessary for multi-entity
- queries).}
-}
-}
-\description{
-\code{get_geo_box} retrieves all geographic entities in
-Wikidata that fall between a bounding box between two existing items
-with geographic attributes (usually cities).
-}
-\examples{
-# Simple bounding box
-\donttest{bruges_box <- get_geo_box("Q12988", "NorthEast", "Q184287", "SouthWest")}
-
-# Custom language
-\donttest{bruges_box_fr <- get_geo_box("Q12988", "NorthEast", "Q184287", "SouthWest",
- language = "fr")}
-
-}
-\seealso{
-\code{\link{get_geo_entity}} for using an unrestricted search or simple radius,
-rather than a bounding box.
-}
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/geo.R
+\name{get_geo_box}
+\alias{get_geo_box}
+\title{Get geographic entities based on a bounding box}
+\usage{
+get_geo_box(first_city_code, first_corner, second_city_code, second_corner,
+ language = "en", ...)
+}
+\arguments{
+\item{first_city_code}{a Wikidata item, or series of items, to use for
+one corner of the bounding box.}
+
+\item{first_corner}{the direction of \code{first_city_code} relative
+to \code{city} (eg "NorthWest", "SouthEast").}
+
+\item{second_city_code}{a Wikidata item, or series of items, to use for
+one corner of the bounding box.}
+
+\item{second_corner}{the direction of \code{second_city_code} relative
+to \code{city} (eg "NorthWest", "SouthEast").}
+
+\item{language}{the two-letter language code to use for the name
+of the item. "en" by default.}
+
+\item{...}{further arguments to pass to httr's GET.}
+}
+\value{
+a data.frame of 5 columns:
+\itemize{
+ \item{item}{ the Wikidata identifier of each object associated with
+ \code{entity}.}
+ \item{name}{ the name of the item, if available, in the requested language. If it
+ is not available, \code{NA} will be returned instead.}
+ \item{latitude}{ the latitude of \code{item}}
+ \item{longitude}{ the longitude of \code{item}}
+ \item{entity}{ the entity the item is associated with (necessary for multi-entity
+ queries).}
+}
+}
+\description{
+\code{get_geo_box} retrieves all geographic entities in
+Wikidata that fall between a bounding box between two existing items
+with geographic attributes (usually cities).
+}
+\examples{
+# Simple bounding box
+bruges_box <- WikidataR:::get_geo_box("Q12988", "NorthEast", "Q184287", "SouthWest")
+
+# Custom language
+bruges_box_fr <- WikidataR:::get_geo_box("Q12988", "NorthEast", "Q184287", "SouthWest",
+ language = "fr")
+
+}
+\seealso{
+\code{\link{get_geo_entity}} for using an unrestricted search or simple radius,
+rather than a bounding box.
+}
diff --git a/man/get_geo_entity.Rd b/man/get_geo_entity.Rd
index 5b82a7e..ccec09e 100644
--- a/man/get_geo_entity.Rd
+++ b/man/get_geo_entity.Rd
@@ -1,60 +1,58 @@
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/geo.R
-\name{get_geo_entity}
-\alias{get_geo_entity}
-\title{Retrieve geographic information from Wikidata}
-\usage{
-get_geo_entity(entity, language = "en", radius = NULL, limit = 100, ...)
-}
-\arguments{
-\item{entity}{a Wikidata item (\code{Q...}) or series of items, to check
-for associated geo-tagged items.}
-
-\item{language}{the two-letter language code to use for the name
-of the item. "en" by default, because we're imperialist
-anglocentric westerners.}
-
-\item{radius}{optionally, a radius (in kilometers) around \code{entity}
-to restrict the search to.}
-
-\item{limit}{the maximum number of results to return.}
-
-\item{\\dots}{further arguments to pass to httr's GET.}
-}
-\value{
-a data.frame of 5 columns:
-\itemize{
- \item{item}{ the Wikidata identifier of each object associated with
- \code{entity}.}
- \item{name}{ the name of the item, if available, in the requested language. If it
- is not available, \code{NA} will be returned instead.}
- \item{latitude}{ the latitude of \code{item}}
- \item{longitude}{ the longitude of \code{item}}
- \item{entity}{ the entity the item is associated with (necessary for multi-entity
- queries).}
-}
-}
-\description{
-\code{get_geo_entity} retrieves the item ID, latitude
-and longitude of any object with geographic data associated with \emph{another}
-object with geographic data (example: all the locations around/near/associated with
-a city).
-}
-\examples{
-# All entities
-\donttest{sf_locations <- get_geo_entity("Q62")}
-
-# Entities with French, rather than English, names
-\donttest{sf_locations <- get_geo_entity("Q62", language = "fr")}
-
-# Entities within 1km
-\donttest{sf_close_locations <- get_geo_entity("Q62", radius = 1)}
-
-# Multiple entities
-\donttest{multi_entity <- get_geo_entity(entity = c("Q62", "Q64"))}
-
-}
-\seealso{
-\code{\link{get_geo_box}} for using a bounding box
-rather than an unrestricted search or simple radius.
-}
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/geo.R
+\name{get_geo_entity}
+\alias{get_geo_entity}
+\title{Retrieve geographic information from Wikidata}
+\usage{
+get_geo_entity(entity, language = "en", radius = NULL, ...)
+}
+\arguments{
+\item{entity}{a Wikidata item (\code{Q...}) or series of items, to check
+for associated geo-tagged items.}
+
+\item{language}{the two-letter language code to use for the name
+of the item. "en" by default, because we're imperialist
+anglocentric westerners.}
+
+\item{radius}{optionally, a radius (in kilometers) around \code{entity}
+to restrict the search to.}
+
+\item{...}{further arguments to pass to httr's GET.}
+}
+\value{
+a data.frame of 5 columns:
+\itemize{
+ \item{item}{ the Wikidata identifier of each object associated with
+ \code{entity}.}
+ \item{name}{ the name of the item, if available, in the requested language. If it
+ is not available, \code{NA} will be returned instead.}
+ \item{latitude}{ the latitude of \code{item}}
+ \item{longitude}{ the longitude of \code{item}}
+ \item{entity}{ the entity the item is associated with (necessary for multi-entity
+ queries).}
+}
+}
+\description{
+\code{get_geo_entity} retrieves the item ID, latitude
+and longitude of any object with geographic data associated with \emph{another}
+object with geographic data (example: all the locations around/near/associated with
+a city).
+}
+\examples{
+# All entities
+sf_locations <- get_geo_entity("Q62")
+
+# Entities with French, rather than English, names
+sf_locations <- get_geo_entity("Q62", language = "fr")
+
+# Entities within 1km
+sf_close_locations <- get_geo_entity("Q62", radius = 1)
+
+# Multiple entities
+multi_entity <- get_geo_entity(entity = c("Q62", "Q64"))
+
+}
+\seealso{
+\code{\link{get_geo_box}} for using a bounding box
+rather than an unrestricted search or simple radius.
+}
diff --git a/man/get_item.Rd b/man/get_item.Rd
index f9b78ab..830d4f5 100644
--- a/man/get_item.Rd
+++ b/man/get_item.Rd
@@ -1,41 +1,42 @@
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/gets.R
-\name{get_item}
-\alias{get_item}
-\alias{get_property}
-\title{Retrieve specific Wikidata items or properties}
-\usage{
-get_item(id, ...)
-
-get_property(id, ...)
-}
-\arguments{
-\item{id}{the ID number(s) of the item or property you're looking for. This can be in
-various formats; either a numeric value ("200"), the full name ("Q200") or
-even with an included namespace ("Property:P10") - the function will format
-it appropriately. This function is vectorised and will happily accept
-multiple IDs.}
-
-\item{\\dots}{further arguments to pass to httr's GET.}
-}
-\description{
-\code{get_item} and \code{get_property} allow you to retrieve the data associated
-with individual Wikidata items and properties, respectively. As with
-other \code{WikidataR} code, custom print methods are available; use \code{\link{str}}
-to manipulate and see the underlying structure of the data.
-}
-\examples{
-
-#Retrieve a specific item
-adams_metadata <- get_item("42")
-
-#Retrieve a specific property
-object_is_child <- get_property("P40")
-
-}
-\seealso{
-\code{\link{get_random}} for selecting a random item or property,
-or \code{\link{find_item}} for using search functionality to pull out
-item or property IDs where the descriptions or aliases match a particular
-search term.
-}
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/gets.R
+\name{get_item}
+\alias{get_item}
+\alias{get_property}
+\alias{get_property}
+\title{Retrieve specific Wikidata items or properties}
+\usage{
+get_item(id, ...)
+
+get_property(id, ...)
+}
+\arguments{
+\item{id}{the ID number(s) of the item or property you're looking for. This can be in
+various formats; either a numeric value ("200"), the full name ("Q200") or
+even with an included namespace ("Property:P10") - the function will format
+it appropriately. This function is vectorised and will happily accept
+multiple IDs.}
+
+\item{...}{further arguments to pass to httr's GET.}
+}
+\description{
+\code{get_item} and \code{get_property} allow you to retrieve the data associated
+with individual Wikidata items and properties, respectively. As with
+other \code{WikidataR} code, custom print methods are available; use \code{\link{str}}
+to manipulate and see the underlying structure of the data.
+}
+\examples{
+
+#Retrieve a specific item
+adams_metadata <- get_item("42")
+
+#Retrieve a specific property
+object_is_child <- get_property("P40")
+
+}
+\seealso{
+\code{\link{get_random}} for selecting a random item or property,
+or \code{\link{find_item}} for using search functionality to pull out
+item or property IDs where the descriptions or aliases match a particular
+search term.
+}
diff --git a/man/get_names_from_properties.Rd b/man/get_names_from_properties.Rd
deleted file mode 100644
index 12520ee..0000000
--- a/man/get_names_from_properties.Rd
+++ /dev/null
@@ -1,17 +0,0 @@
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/utils.R
-\name{get_names_from_properties}
-\alias{get_names_from_properties}
-\title{Get names of properties}
-\usage{
-get_names_from_properties(properties)
-}
-\arguments{
-\item{properties}{a claims list from \code{extract_claims}}
-}
-\value{
-tibble of labels for each property for a set of claims
-}
-\description{
-For a claim or set of claims, return the names of the properties
-}
diff --git a/man/get_random.Rd b/man/get_random.Rd
index 78a5cda..7edfaf1 100644
--- a/man/get_random.Rd
+++ b/man/get_random.Rd
@@ -1,38 +1,39 @@
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/gets.R
-\name{get_random_item}
-\alias{get_random_item}
-\alias{get_random}
-\alias{get_random_property}
-\title{Retrieve randomly-selected Wikidata items or properties}
-\usage{
-get_random_item(limit = 1, ...)
-
-get_random_property(limit = 1, ...)
-}
-\arguments{
-\item{limit}{how many random items to return. 1 by default, but can be higher.}
-
-\item{\\dots}{arguments to pass to httr's GET.}
-}
-\description{
-\code{get_random_item} and \code{get_random_property} allow you to retrieve the data
-associated with randomly-selected Wikidata items and properties, respectively. As with
-other \code{WikidataR} code, custom print methods are available; use \code{\link{str}}
-to manipulate and see the underlying structure of the data.
-}
-\examples{
-\dontrun{
-#Random item
-random_item <- get_random_item()
-
-#Random property
-random_property <- get_random_property()
-}
-}
-\seealso{
-\code{\link{get_item}} for selecting a specific item or property,
-or \code{\link{find_item}} for using search functionality to pull out
-item or property IDs where the descriptions or aliases match a particular
-search term.
-}
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/gets.R
+\name{get_random_item}
+\alias{get_random_item}
+\alias{get_random}
+\alias{get_random_property}
+\alias{get_random_property}
+\title{Retrieve randomly-selected Wikidata items or properties}
+\usage{
+get_random_item(limit = 1, ...)
+
+get_random_property(limit = 1, ...)
+}
+\arguments{
+\item{limit}{how many random items to return. 1 by default, but can be higher.}
+
+\item{...}{arguments to pass to httr's GET.}
+}
+\description{
+\code{get_random_item} and \code{get_random_property} allow you to retrieve the data
+associated with randomly-selected Wikidata items and properties, respectively. As with
+other \code{WikidataR} code, custom print methods are available; use \code{\link{str}}
+to manipulate and see the underlying structure of the data.
+}
+\examples{
+
+#Random item
+random_item <- get_random_item()
+
+#Random property
+random_property <- get_random_property()
+
+}
+\seealso{
+\code{\link{get_item}} for selecting a specific item or property,
+or \code{\link{find_item}} for using search functionality to pull out
+item or property IDs where the descriptions or aliases match a particular
+search term.
+}
diff --git a/man/identifier_from_identifier.Rd b/man/identifier_from_identifier.Rd
deleted file mode 100644
index a736ccf..0000000
--- a/man/identifier_from_identifier.Rd
+++ /dev/null
@@ -1,28 +0,0 @@
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/queries.R
-\name{identifier_from_identifier}
-\alias{identifier_from_identifier}
-\title{identifier from identifier}
-\usage{
-identifier_from_identifier(
- property = "ORCID iD",
- return = "IMDb ID",
- value = "0000-0002-7865-7235"
-)
-}
-\arguments{
-\item{property}{the identifier property to search (for caveats, see \code{as_pid})}
-
-\item{return}{the identifier property to convert to}
-
-\item{value}{the identifier value to match}
-}
-\value{
-vector of identifiers corresponding to identifiers submitted
-}
-\description{
-convert unique identifiers to other unique identifiers
-}
-\examples{
-identifier_from_identifier('ORCID iD','IMDb ID',c('0000-0002-7865-7235','0000-0003-1079-5604'))
-}
diff --git a/man/initials.Rd b/man/initials.Rd
deleted file mode 100644
index 1fef6f1..0000000
--- a/man/initials.Rd
+++ /dev/null
@@ -1,20 +0,0 @@
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/utils.R
-\name{initials}
-\alias{initials}
-\title{Format short form person names}
-\usage{
-initials(x, format = "FLast")
-}
-\arguments{
-\item{x}{a vector of people's names as strings}
-
-\item{format}{a vector of strings of either "FLast" or "FL" to indicate the output format}
-}
-\value{
-the inputted name strings with first names shortened based on the
-selected format.
-}
-\description{
-Converting names into first initial and surname, or just initials
-}
diff --git a/man/list_properties.Rd b/man/list_properties.Rd
deleted file mode 100644
index 67ae560..0000000
--- a/man/list_properties.Rd
+++ /dev/null
@@ -1,30 +0,0 @@
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/utils.R
-\name{list_properties}
-\alias{list_properties}
-\title{List properties of a Wikidata item}
-\usage{
-list_properties(item, names = FALSE)
-}
-\arguments{
-\item{item}{a list of one or more Wikidata items returned with
-\code{\link{get_item}}.}
-
-\item{names}{a boolian for whether to return property names, or just P numbers
-and extract.}
-}
-\value{
-a list containing one sub-list for each entry in \code{items},
-and (below that) the found data for each claim. In the event a claim
-cannot be found for an item, an \code{NA} will be returned
-instead.
-}
-\description{
-for a downloaded wikidata item, list the properties of all statements
-}
-\examples{
-# Get item data
-adams_data <- get_item("42")
-# Get claim data
-claims <- extract_claims(adams_data, "P31")
-}
diff --git a/man/print.find_item.Rd b/man/print.find_item.Rd
index 62ade1a..0bfbccc 100644
--- a/man/print.find_item.Rd
+++ b/man/print.find_item.Rd
@@ -1,16 +1,16 @@
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/prints.R
-\name{print.find_item}
-\alias{print.find_item}
-\title{Print method for find_item}
-\usage{
-\method{print}{find_item}(x, ...)
-}
-\arguments{
-\item{x}{find_item object with search results}
-
-\item{\dots}{Arguments to be passed to methods}
-}
-\description{
-print found items.
-}
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/prints.R
+\name{print.find_item}
+\alias{print.find_item}
+\title{Print method for find_item}
+\usage{
+\method{print}{find_item}(x, ...)
+}
+\arguments{
+\item{x}{find_item object with search results}
+
+\item{\dots}{Arguments to be passed to methods}
+}
+\description{
+print found items.
+}
diff --git a/man/print.find_property.Rd b/man/print.find_property.Rd
index 23b8c2d..a7f4e4f 100644
--- a/man/print.find_property.Rd
+++ b/man/print.find_property.Rd
@@ -1,16 +1,16 @@
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/prints.R
-\name{print.find_property}
-\alias{print.find_property}
-\title{Print method for find_property}
-\usage{
-\method{print}{find_property}(x, ...)
-}
-\arguments{
-\item{x}{find_property object with search results}
-
-\item{\dots}{Arguments to be passed to methods}
-}
-\description{
-print found properties.
-}
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/prints.R
+\name{print.find_property}
+\alias{print.find_property}
+\title{Print method for find_property}
+\usage{
+\method{print}{find_property}(x, ...)
+}
+\arguments{
+\item{x}{find_property object with search results}
+
+\item{\dots}{Arguments to be passed to methods}
+}
+\description{
+print found properties.
+}
diff --git a/man/print.wikidata.Rd b/man/print.wikidata.Rd
index 7b5232a..8e3b076 100644
--- a/man/print.wikidata.Rd
+++ b/man/print.wikidata.Rd
@@ -1,19 +1,19 @@
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/prints.R
-\name{print.wikidata}
-\alias{print.wikidata}
-\title{Print method for Wikidata objects}
-\usage{
-\method{print}{wikidata}(x, ...)
-}
-\arguments{
-\item{x}{wikidata object from get_item, get_random_item, get_property or get_random_property}
-
-\item{\dots}{Arguments to be passed to methods}
-}
-\description{
-print found objects generally.
-}
-\seealso{
-get_item, get_random_item, get_property or get_random_property
-}
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/prints.R
+\name{print.wikidata}
+\alias{print.wikidata}
+\title{Print method for Wikidata objects}
+\usage{
+\method{print}{wikidata}(x, ...)
+}
+\arguments{
+\item{x}{wikidata object from get_item, get_random_item, get_property or get_random_property}
+
+\item{\dots}{Arguments to be passed to methods}
+}
+\description{
+print found objects generally.
+}
+\seealso{
+get_item, get_random_item, get_property or get_random_property
+}
diff --git a/man/qid_from_DOI.Rd b/man/qid_from_DOI.Rd
deleted file mode 100644
index 67508a2..0000000
--- a/man/qid_from_DOI.Rd
+++ /dev/null
@@ -1,17 +0,0 @@
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/schol.R
-\name{qid_from_DOI}
-\alias{qid_from_DOI}
-\title{QID from DOI}
-\usage{
-qid_from_DOI(DOI = "10.15347/WJM/2019.001")
-}
-\arguments{
-\item{DOI}{digital object identifiers submitted as strings}
-}
-\value{
-vector of QIDs corresponding to DOIs submitted
-}
-\description{
-simple converter from DOIs to QIDs (for items in wikidata)
-}
diff --git a/man/qid_from_ORCID.Rd b/man/qid_from_ORCID.Rd
deleted file mode 100644
index 186f3e2..0000000
--- a/man/qid_from_ORCID.Rd
+++ /dev/null
@@ -1,17 +0,0 @@
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/schol.R
-\name{qid_from_ORCID}
-\alias{qid_from_ORCID}
-\title{QID from ORCID}
-\usage{
-qid_from_ORCID(ORCID = "0000-0002-2298-7593")
-}
-\arguments{
-\item{ORCID}{digital object identifiers submitted as strings}
-}
-\value{
-vector of QIDs corresponding to ORCIDs submitted
-}
-\description{
-simple converter from ORCIDs to QIDs (for items in wikidata)
-}
diff --git a/man/qid_from_identifier.Rd b/man/qid_from_identifier.Rd
deleted file mode 100644
index 11aa2d9..0000000
--- a/man/qid_from_identifier.Rd
+++ /dev/null
@@ -1,25 +0,0 @@
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/queries.R
-\name{qid_from_identifier}
-\alias{qid_from_identifier}
-\title{QID from identifier}
-\usage{
-qid_from_identifier(
- property = "DOI",
- value = c("10.15347/WJM/2019.001", "10.15347/WJM/2020.002")
-)
-}
-\arguments{
-\item{property}{the identifier property to search (for caveats, see \code{as_pid})}
-
-\item{value}{the identifier value to match}
-}
-\value{
-vector of QIDs corresponding to identifiers submitted
-}
-\description{
-convert unique identifiers to QIDs (for items in wikidata).
-}
-\examples{
-qid_from_identifier('ISBN-13','978-0-262-53817-6')
-}
diff --git a/man/qid_from_name.Rd b/man/qid_from_name.Rd
deleted file mode 100644
index d369f2e..0000000
--- a/man/qid_from_name.Rd
+++ /dev/null
@@ -1,22 +0,0 @@
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/schol.R
-\name{qid_from_name}
-\alias{qid_from_name}
-\title{QID from label name}
-\usage{
-qid_from_name(name = "Thomas Shafee", limit = 100, format = "vector")
-}
-\arguments{
-\item{name}{name labels submitted as strings}
-
-\item{limit}{if multiple QIDs match each submitted name, how many to return}
-
-\item{format}{output format ('vector' to return a simple vector, or 'list' to return a nested list)}
-}
-\value{
-vector of QIDs corresponding to names submitted. Note: some names may return multiple QIDs.
-}
-\description{
-simple converter from label names to QIDs (for items in wikidata).
-Essentially a simplification of \code{find_item}
-}
diff --git a/man/query_wikidata.Rd b/man/query_wikidata.Rd
deleted file mode 100644
index 5ad604f..0000000
--- a/man/query_wikidata.Rd
+++ /dev/null
@@ -1,53 +0,0 @@
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/queries.R
-\name{query_wikidata}
-\alias{query_wikidata}
-\title{Send one or more SPARQL queries to WDQS}
-\usage{
-query_wikidata(sparql_query, format = "tibble", ...)
-}
-\arguments{
-\item{sparql_query}{SPARQL query (can be a vector of queries)}
-
-\item{format}{`tibble` (default) returns a pure character data frame,
-`simple` returns a pure character vector, while
-`smart` fetches JSON-formatted data and returns a tibble with datetime
-columns converted to `POSIXct`}
-
-\item{\\dots}{Additional parameters to supply to [httr::POST]}
-}
-\value{
-A `tibble` or `vector`. Note: QID values will be returned as QIDs, rather than URLs.
-}
-\description{
-Makes a POST request to Wikidata Query Service SPARQL endpoint.
-}
-\section{Query limits}{
-
-There is a hard query deadline configured which is set to 60 seconds. There
-are also following limits:
-- One client (user agent + IP) is allowed 60 seconds of processing time each
- 60 seconds
-- One client is allowed 30 error queries per minute
-See [query limits section](https://www.mediawiki.org/wiki/Wikidata_Query_Service/User_Manual#Query_limits)
-in the WDQS user manual for more information.
-}
-
-\examples{
-# R's versions and release dates:
-sparql_query <- 'SELECT DISTINCT
- ?softwareVersion ?publicationDate
- WHERE {
- BIND(wd:Q206904 AS ?R)
- ?R p:P348 [
- ps:P348 ?softwareVersion;
- pq:P577 ?publicationDate
- ] .
-}'
-query_wikidata(sparql_query)
-
-\dontrun{
-# "smart" format converts all datetime columns to POSIXct
-query_wikidata(sparql_query, format = "smart")
-}
-}
diff --git a/man/searcher.Rd b/man/searcher.Rd
deleted file mode 100644
index a486495..0000000
--- a/man/searcher.Rd
+++ /dev/null
@@ -1,36 +0,0 @@
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/gets.R
-\name{searcher}
-\alias{searcher}
-\title{Convert an input to a item QID}
-\usage{
-searcher(search_term, language, limit, type, ...)
-}
-\arguments{
-\item{search_term}{a term to search for.}
-
-\item{language}{the language to return the labels and descriptions in; this should
-consist of an ISO language code. Set to "en" by default.}
-
-\item{limit}{the number of results to return; set to 10 by default.}
-
-\item{type}{type of wikidata object to return (default = "item")}
-
-\item{\\dots}{Additional parameters to supply to [httr::POST]}
-}
-\value{
-If the inputted string matches an item label, return its QID.
-If the inputted string matches multiple labels of multiple items, return the QID of the first hit.
-If the inputted string is already a QID, return the string.
-}
-\description{
-Convert an input string to the most likely item QID
-}
-\examples{
-# if input string is a valid QID
-as_qid("Q42")
-# if input string matches multiple item labels
-as_qid("Douglas Adams")
-# if input string matches a single unique label
-as_qid("Douglas Adams and the question of arterial blood pressure in mammals")
-}
diff --git a/man/sparql_query.Rd b/man/sparql_query.Rd
deleted file mode 100644
index c1eaed9..0000000
--- a/man/sparql_query.Rd
+++ /dev/null
@@ -1,20 +0,0 @@
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/queries.R
-\name{sparql_query}
-\alias{sparql_query}
-\title{Download full Wikidata items matching a sparql query}
-\usage{
-sparql_query(query, ...)
-}
-\arguments{
-\item{query}{the sparql query as a string}
-
-\item{\\dots}{Additional parameters to supply to [httr::POST]}
-}
-\value{
-a download of the full wikidata objects formatted as a nested json list
-}
-\description{
-Utility wrapper for wikidata spargle endpoint to download items.
-Used by \code{get_geo_entity} and \code{get_geo_box}
-}
diff --git a/man/unspecial.Rd b/man/unspecial.Rd
deleted file mode 100644
index e48add0..0000000
--- a/man/unspecial.Rd
+++ /dev/null
@@ -1,18 +0,0 @@
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/utils.R
-\name{unspecial}
-\alias{unspecial}
-\title{Remove special characters}
-\usage{
-unspecial(x)
-}
-\arguments{
-\item{x}{a vector of strings to check for special characters}
-}
-\value{
-the inputted strings with special characters replaced with
-closest match plan characters.
-}
-\description{
-Special characters can otherwise mess up wikidata read-writes
-}
diff --git a/man/url_to_id.Rd b/man/url_to_id.Rd
deleted file mode 100644
index 7e45a55..0000000
--- a/man/url_to_id.Rd
+++ /dev/null
@@ -1,29 +0,0 @@
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/utils.R
-\name{url_to_id}
-\alias{url_to_id}
-\title{Extract an identifier from a wikidata URL}
-\usage{
-url_to_id(x)
-
-url_to_id(x)
-}
-\arguments{
-\item{x}{a vector of strings representing wikidata URLs}
-}
-\value{
-if the URL ends in a QID or PID, return that PID or QID, else return the original string
-
-QID or PID
-}
-\description{
-Convert a URL ending in an identifier (returned by SPARQL queries) to just
-the plain identifier (QID or PID).
-
-Convert a URL ending in an identifier (returned by SPARQL queries)
-to just the plan identifier (QID or PID).
-}
-\examples{
-url_to_id("http://www.wikidata.org/entity/42")
-url_to_id("http://www.wikidata.org/Q42")
-}
diff --git a/man/wd_query.Rd b/man/wd_query.Rd
deleted file mode 100644
index a7481d7..0000000
--- a/man/wd_query.Rd
+++ /dev/null
@@ -1,20 +0,0 @@
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/queries.R
-\name{wd_query}
-\alias{wd_query}
-\title{Download a Wikidata item}
-\usage{
-wd_query(title, ...)
-}
-\arguments{
-\item{title}{the wikidata item or property as a string}
-
-\item{\\dots}{Additional parameters to supply to [httr::POST]}
-}
-\value{
-a download of the full wikidata object (item or property) formatted as a nested json list
-}
-\description{
-Utility wrapper for wikidata API to download item.
-Used by \code{get_item} and \code{get_property}
-}
diff --git a/man/wd_rand_query.Rd b/man/wd_rand_query.Rd
deleted file mode 100644
index a7441e3..0000000
--- a/man/wd_rand_query.Rd
+++ /dev/null
@@ -1,21 +0,0 @@
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/queries.R
-\name{wd_rand_query}
-\alias{wd_rand_query}
-\title{Download random Wikidata items}
-\usage{
-wd_rand_query(ns, limit, ...)
-}
-\arguments{
-\item{ns}{string indicating namespace, most commonly "Main" for QID items, "Property" for PID properties}
-
-\item{limit}{how many random objesct to return}
-
-\item{\\dots}{Additional parameters to supply to [httr::POST]}
-}
-\value{
-a download of the full wikidata objects (items or properties) formatted as nested json lists
-}
-\description{
-Utility wrapper for wikidata API to download random items. Used by \code{random_item}
-}
diff --git a/man/write_wikidata.Rd b/man/write_wikidata.Rd
deleted file mode 100644
index 3d9d4cc..0000000
--- a/man/write_wikidata.Rd
+++ /dev/null
@@ -1,98 +0,0 @@
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/writes.R
-\name{write_wikidata}
-\alias{write_wikidata}
-\title{Write statements to Wikidata}
-\usage{
-write_wikidata(
- items,
- properties = NULL,
- values = NULL,
- qual.properties = NULL,
- qual.values = NULL,
- src.properties = NULL,
- src.values = NULL,
- remove = FALSE,
- format = "tibble",
- api.username = NULL,
- api.token = NULL,
- api.format = "v1",
- api.batchname = NULL,
- api.submit = TRUE
-)
-}
-\arguments{
-\item{items}{a vector of strings indicating the items to which to add statements (as QIDs or labels).
-Note: if labels are provided, and multiple items match, the first matching item will be used
-(see \code{as_qid} function), so use with caution.
-New QIDs can be created by using the "CREATE_xyz", where "_xyz" is any unique string.
-Using the same id will add additional statemnts to those new items}
-
-\item{properties}{a vector of strings indicating the properties to add as statements (as PIDs or labels).
-Note: if labels are provided, and multiple items match, the first matching item will be used
-(see \code{as_pid} function), so use with caution.
-Four special properties can also be used: labels, aliases, descriptions and sitelinks.
-See [this link](https://www.wikidata.org/wiki/Help:QuickStatements#Adding_labels,_aliases,_descriptions_and_sitelinks) for the syntax.}
-
-\item{values}{a vector of strings indicating the values to add as statements (as QIDs or strings).
-Note: if strings are provided, they will be treated as plain text.}
-
-\item{qual.properties}{a vector, data frame, or tibble of strings indicating the properties to add as qualifiers to statements (as PIDs or labels).
-Note: if labels are provided, and multiple items match, the first matching item will be used
-(see \code{as_pid} function), so use with caution.}
-
-\item{qual.values}{a vector, data frame, or tibble of strings indicating the values to add as statements (as QIDs or strings).
-Note: if strings are provided, they will be treated as plain text.}
-
-\item{src.properties}{a vector, data frame, or tibble of strings indicating the properties to add as reference sources to statements (as SIDs or labels).
-Note: if labels are provided, and multiple items match, the first matching item will be used
-(see \code{as_sid} function), so use with caution.}
-
-\item{src.values}{a vector, data frame, or tibble of strings indicating the values to add reference sources to statements (as QIDs or strings).
-Note: if strings are provided, they will be treated as plain text.}
-
-\item{remove}{a vector of boolians for each statemnt indicating whether it should
-be removed from the item rather than added (default = FALSE)}
-
-\item{format}{output format as a string. Options include:
-\describe{
- \item{tibble}{easiest format to further manuipulation in R}
- \item{csv}{can be copy-pasted to [the QuickStatements website](https://quickstatements.toolforge.org/) (or manipulated in a spreadsheet programs)}
- \item{api}{a url that can be copy-pasted into a web browser, or automatically submitted (see \code{api.submit} parameter)}
- \item{website}{open a [QuickStatements](https://quickstatements.toolforge.org/) web browser window summarising the edits to be made to Wikidata)}
-}}
-
-\item{api.username}{a string indicating your wikimedia username}
-
-\item{api.token}{a string indicating your api token (the unique identifier that you can find listed at [your user page](https://quickstatements.toolforge.org/#/user))}
-
-\item{api.format}{a string indicateing which version of the quickstatement format used to submit the api (default = "v1")}
-
-\item{api.batchname}{a string create a named batch (listed at [your batch history page](https://quickstatements.toolforge.org/#/batches)) and tag in the edit summaries}
-
-\item{api.submit}{boolian indicating whether to submit instruction directly to wikidata (else returns the URL that can be copy-pasted into a web browser)}
-}
-\value{
-data formatted to upload to wikidata (via quickstatemsnts),
-optionally also directly uploded to wikidata (see \code{format} parameter).
-}
-\description{
-Upload data to wikidata, including creating items,
-adding statements to existing items (via the quickstatements format and API).
-}
-\examples{
-# Add a statement to the "Wikidata sandbox" item (Q4115189)
-# to say that it is an "instance of" (P31) of Q1 (the universe).
-# The instruction will submit directly to wikidata via the API
-# (if you include your wikimedia username and token)
-
-\donttest{write_wikidata(items = "Wikidata Sandbox",
- properties = "instance of",
- values = "Q1",
- format = "api",
- api.username = "myusername",
- api.token = , #REDACTED#
- )}
-#note:
-
-}
diff --git a/tests/testthat.R b/tests/testthat.R
index e4633de..34fbd73 100644
--- a/tests/testthat.R
+++ b/tests/testthat.R
@@ -1,4 +1,4 @@
-library(testthat)
-library(WikidataR)
-
-test_check("WikidataR")
+library(testthat)
+library(WikidataR)
+
+test_check("WikidataR")
diff --git a/tests/testthat/test_geo.R b/tests/testthat/test_geo.R
index 2192ecd..ac7e88b 100644
--- a/tests/testthat/test_geo.R
+++ b/tests/testthat/test_geo.R
@@ -1,50 +1,48 @@
-testthat::context("Geographic queries")
-# Have had to comment out tests. Wikidata query service having timeout issues that cause tests to fail
-
-
-# testthat::test_that("Simple entity-based geo lookups work", {
-# field_names <- c("item", "name", "latitutde", "longitude", "entity")
-# sf_locations <- get_geo_entity("Q62")
-# testthat::expect_true(is.data.frame(sf_locations))
-# testthat::expect_true(all(field_names == names(sf_locations)))
-# testthat::expect_true(unique(sf_locations$entity) == "Q62")
-# })
-
-# testthat::test_that("Language-variant entity-based geo lookups work", {
-# field_names <- c("item", "name", "latitutde", "longitude", "entity")
-# sf_locations <- get_geo_entity("Q62", language = "fr")
-# testthat::expect_true(is.data.frame(sf_locations))
-# testthat::expect_true(all(field_names == names(sf_locations)))
-# testthat::expect_true(unique(sf_locations$entity) == "Q62")
-# })
-
-# testthat::test_that("Radius restricted entity-based geo lookups work", {
-# field_names <- c("item", "name", "latitutde", "longitude", "entity")
-# sf_locations <- get_geo_entity("Q62", radius = 1)
-# testthat::expect_true(is.data.frame(sf_locations))
-# testthat::expect_true(all(field_names == names(sf_locations)))
-# testthat::expect_true(unique(sf_locations$entity) == "Q62")
-# })
-
-# testthat::test_that("multi-entity geo lookups work", {
-# field_names <- c("item", "name", "latitutde", "longitude", "entity")
-# sf_locations <- get_geo_entity(c("Q62", "Q64"), radius = 1)
-# testthat::expect_true(is.data.frame(sf_locations))
-# testthat::expect_true(all(field_names == names(sf_locations)))
-# testthat::expect_equal(length(unique(sf_locations$entity)), 2)
-# })
-
-# testthat::test_that("Simple bounding lookups work", {
-# field_names <- c("item", "name", "latitutde", "longitude")
-# bruges_box <- get_geo_box("Q12988", "NorthEast", "Q184287", "SouthWest")
-# testthat::expect_true(is.data.frame(bruges_box))
-# testthat::expect_true(all(field_names == names(bruges_box)))
-# })
-
-# testthat::test_that("Language-variant bounding lookups work", {
-# field_names <- c("item", "name", "latitutde", "longitude")
-# bruges_box <- get_geo_box("Q12988", "NorthEast", "Q184287", "SouthWest",
-# language = "fr")
-# testthat::expect_true(is.data.frame(bruges_box))
-# testthat::expect_true(all(field_names == names(bruges_box)))
-# })
\ No newline at end of file
+testthat::context("Geographic queries")
+
+testthat::test_that("Simple entity-based geo lookups work", {
+ field_names <- c("item", "name", "latitutde", "longitude", "entity")
+ sf_locations <- get_geo_entity("Q62")
+ testthat::expect_true(is.data.frame(sf_locations))
+ testthat::expect_true(all(field_names == names(sf_locations)))
+ testthat::expect_true(unique(sf_locations$entity) == "Q62")
+})
+
+testthat::test_that("Language-variant entity-based geo lookups work", {
+ field_names <- c("item", "name", "latitutde", "longitude", "entity")
+ sf_locations <- get_geo_entity("Q62", language = "fr")
+ testthat::expect_true(is.data.frame(sf_locations))
+ testthat::expect_true(all(field_names == names(sf_locations)))
+ testthat::expect_true(unique(sf_locations$entity) == "Q62")
+})
+
+testthat::test_that("Radius restricted entity-based geo lookups work", {
+ field_names <- c("item", "name", "latitutde", "longitude", "entity")
+ sf_locations <- get_geo_entity("Q62", radius = 1)
+ testthat::expect_true(is.data.frame(sf_locations))
+ testthat::expect_true(all(field_names == names(sf_locations)))
+ testthat::expect_true(unique(sf_locations$entity) == "Q62")
+})
+
+testthat::test_that("multi-entity geo lookups work", {
+ field_names <- c("item", "name", "latitutde", "longitude", "entity")
+ sf_locations <- get_geo_entity(c("Q62", "Q64"), radius = 1)
+ testthat::expect_true(is.data.frame(sf_locations))
+ testthat::expect_true(all(field_names == names(sf_locations)))
+ testthat::expect_equal(length(unique(sf_locations$entity)), 2)
+})
+
+testthat::test_that("Simple bounding lookups work", {
+ field_names <- c("item", "name", "latitutde", "longitude")
+ bruges_box <- get_geo_box("Q12988", "NorthEast", "Q184287", "SouthWest")
+ testthat::expect_true(is.data.frame(bruges_box))
+ testthat::expect_true(all(field_names == names(bruges_box)))
+})
+
+testthat::test_that("Language-variant bounding lookups work", {
+ field_names <- c("item", "name", "latitutde", "longitude")
+ bruges_box <- get_geo_box("Q12988", "NorthEast", "Q184287", "SouthWest",
+ language = "fr")
+ testthat::expect_true(is.data.frame(bruges_box))
+ testthat::expect_true(all(field_names == names(bruges_box)))
+})
\ No newline at end of file
diff --git a/tests/testthat/test_gets.R b/tests/testthat/test_gets.R
index e3d6514..2164d4b 100644
--- a/tests/testthat/test_gets.R
+++ b/tests/testthat/test_gets.R
@@ -1,30 +1,30 @@
-context("Direct Wikidata get functions")
-
-test_that("A specific item can be retrieved with an entire item code", {
- expect_true({get_item("Q100");TRUE})
-})
-
-test_that("A specific item can be retrieved with a partial entire item code", {
- expect_true({get_item("100");TRUE})
-})
-
-test_that("A specific property can be retrieved with an entire prop code + namespace", {
- expect_true({get_property("Property:P10");TRUE})
-})
-
-test_that("A specific property can be retrieved with an entire prop code + namespace", {
- expect_true({get_property("P10");TRUE})
-})
-
-
-test_that("A specific property can be retrieved with a partial prop code", {
- expect_true({get_property("10");TRUE})
-})
-
-test_that("A randomly-selected item can be retrieved",{
- expect_true({get_random_item();TRUE})
-})
-
-test_that("A randomly-selected property can be retriveed",{
- expect_true({get_random_property();TRUE})
+context("Direct Wikidata get functions")
+
+test_that("A specific item can be retrieved with an entire item code", {
+ expect_true({get_item("Q100");TRUE})
+})
+
+test_that("A specific item can be retrieved with a partial entire item code", {
+ expect_true({get_item("100");TRUE})
+})
+
+test_that("A specific property can be retrieved with an entire prop code + namespace", {
+ expect_true({get_property("Property:P10");TRUE})
+})
+
+test_that("A specific property can be retrieved with an entire prop code + namespace", {
+ expect_true({get_property("P10");TRUE})
+})
+
+
+test_that("A specific property can be retrieved with a partial prop code", {
+ expect_true({get_property("10");TRUE})
+})
+
+test_that("A randomly-selected item can be retrieved",{
+ expect_true({get_random_item();TRUE})
+})
+
+test_that("A randomly-selected property can be retriveed",{
+ expect_true({get_random_property();TRUE})
})
\ No newline at end of file
diff --git a/tests/testthat/test_search.R b/tests/testthat/test_search.R
index d487170..3588f82 100644
--- a/tests/testthat/test_search.R
+++ b/tests/testthat/test_search.R
@@ -1,13 +1,17 @@
-context("Search functions")
-
-test_that("English-language search works",{
- expect_true({find_item("Wonder Girls", "en");TRUE})
-})
-
-test_that("Non-English-language search works",{
- expect_true({find_item("Wonder Girls", "es");TRUE})
-})
-
-test_that("Property search works",{
- expect_true({find_property("Music", "en");TRUE})
+context("Search functions")
+
+test_that("English-language search works",{
+ expect_true({find_item("Wonder Girls", "en");TRUE})
+})
+
+test_that("Non-English-language search works",{
+ expect_true({find_item("Wonder Girls", "es");TRUE})
+})
+
+test_that("Search with limit modding works",{
+ expect_that(length(find_item("Wonder Girls", "en", 3)), equals(3))
+})
+
+test_that("Property search works",{
+ expect_true({find_property("Music", "en");TRUE})
})
\ No newline at end of file
diff --git a/vignettes/Introduction.Rmd b/vignettes/Introduction.Rmd
new file mode 100644
index 0000000..e22aae2
--- /dev/null
+++ b/vignettes/Introduction.Rmd
@@ -0,0 +1,82 @@
+<!--
+%\VignetteEngine{knitr::knitr}
+%\VignetteIndexEntry{Introduction to WikidataR}
+-->
+
+# WikidataR: the API client library for Wikidata
+Wikidata is a wonderful and irreplaceable resource for linked data, containing information on pretty much any subject. If there's a Wikipedia article on it, there's almost certainly a Wikidata item for it.
+
+<code>WikidataR</code> - following the naming scheme of [WikipediR](https://github.com/Ironholds/WikipediR#thanks-and-misc) - is an API client library for Wikidata, written in and accessible from R.
+
+## Items and properties
+The two basic component pieces of Wikidata are "items" and "properties". An "item" is a thing - a concept, object or
+topic that exists in the real world, such as "Rush". These items each have statements associated with them - for
+example, "Rush is an instance of: Rock Band". In that statement, "Rock Band" is a property: a class or trait
+that items can hold. Wikidata items are organised as descriptors of the item, in various languages, and references to the properties that that item holds.
+
+## Retrieving specific items or properties
+Items and properties are both identified by numeric IDs, prefaced with "Q" in the case of items,
+and "P" in the case of properties. WikipediR can be used to retrieve items or properties with specific
+ID numbers, using the <code>get\_item</code> and <code>get\_property</code> functions:
+
+```{r, eval=FALSE}
+#Retrieve an item
+item <- get_item(id = 1)
+
+#Get information about the property of the first claim it has.
+first_claim <- get_property(id = names(item$claims)[1])
+#Do we succeed? Dewey!
+```
+
+These functions are capable of accepting various forms for the ID, including (as examples), "Q100" or "100"
+for items, and "Property:P100", "P100" or "100" for properties. They're also vectorised - pass them as many IDs as you want!
+
+## Retrieving randomly-selected items or properties
+As well as retrieving specific items or properties, Wikidata's API also allows for the retrieval of *random*
+elements. With WikidataR, this can be achieved through:
+
+```{r, eval=FALSE}
+#Retrieve a random item
+rand_item <- get_random_item()
+
+#Retrieve a random property
+rand_prop <- get_random_property()
+```
+
+These also allow you to retrieve *sets* of random elements - not just one at a time, but say, 50 at a time - by including the "limit" argument:
+
+```{r, eval=FALSE}
+#Retrieve 42 random items
+rand_item <- get_random_item(limit = 42)
+
+#Retrieve 42 random properties
+rand_prop <- get_random_property(limit = 42)
+```
+
+## Search
+Wikidata's search functionality can also be used, either to find items or to find properties. All you need is
+a search string (which is run over the names and descriptions of items or properties) and a language code
+(since Wikidata's descriptions can be in many languages):
+
+```{r, eval=FALSE}
+#Find item - find defaults to "en" as a language.
+aarons <- find_item("Aaron Halfaker")
+
+#Find a property - also defaults to "en"
+first_names <- find_property("first name")
+```
+
+The resulting search entries have the ID as a key, making it trivial to then retrieve the full corresponding
+items or properties:
+
+```{r, eval=FALSE}
+#Find item.
+all_aarons <- find_item("Aaron Halfaker")
+
+#Grab the ID code for the first entry and retrieve the associated item data.
+first_aaron <- get_item(all_aarons[[1]]$id)
+```
+
+## Other and future functionality
+If you have ideas for other types of useful Wikidata access, the best approach
+is to either [request it](https://github.com/Ironholds/WikidataR/issues) or [add it](https://github.com/Ironholds/WikidataR/pulls)!
Debdiff
[The following lists of changes regard files as different if they have different names, permissions or owners.]
Files in second set of .debs but not in first
-rw-r--r-- root/root /usr/lib/R/site-library/WikidataR/Meta/vignette.rds -rw-r--r-- root/root /usr/lib/R/site-library/WikidataR/doc/Introduction.R -rw-r--r-- root/root /usr/lib/R/site-library/WikidataR/doc/Introduction.Rmd -rw-r--r-- root/root /usr/lib/R/site-library/WikidataR/doc/Introduction.html -rw-r--r-- root/root /usr/lib/R/site-library/WikidataR/doc/index.html
Files in first set of .debs but not in second
-rw-r--r-- root/root /usr/lib/R/site-library/WikidataR/R/sysdata.rdb -rw-r--r-- root/root /usr/lib/R/site-library/WikidataR/R/sysdata.rdx -rw-r--r-- root/root /usr/lib/R/site-library/WikidataR/extdata/WD.globalvar.RDS
Control files: lines which differ (wdiff format)
Depends: r-base-core (>= 4.2.2.20221110-1), r-api-4.0, r-cran-httr, r-cran-jsonlite, r-cran-wikipedir, r-cran-wikidataqueryservicer, r-cran-tibble, r-cran-dplyr, r-cran-stringr, r-cran-hmisc, r-cran-progress, r-cran-pbapply, r-cran-readr, r-cran-crayon r-cran-wikipedir (>= 1.4.0)
Suggests: r-cran-markdown, r-cran-tidyverse, r-cran-knitr