From 3530cef317ed43ec8d31715485837729b5420c8a Mon Sep 17 00:00:00 2001 From: Mikhail Popov Date: Fri, 28 Apr 2017 11:31:28 -0700 Subject: [PATCH] Fixes #3 and prepares for v0.1.1 submission to CRAN * Updated documentation to use Markdown thanks to roxygen2 6.0.0 * Added more links for learning SPARQL in context of Wikidata (see `help("WDQS", package = "WikidataQueryServiceR")`) * Fixed a bug with JSON-formatted results (#3) --- DESCRIPTION | 7 +++--- NEWS.md | 13 +++++++++++ R/query.R | 50 ++++++++++++------------------------------- R/utils.R | 6 +++--- R/wdqs.R | 31 +++++++++++++++------------ README.md | 28 +++++++++++------------- cran-comments.md | 35 +++--------------------------- man/WDQS-package.Rd | 31 +++++++++++++++------------ man/query_wikidata.Rd | 48 +++++++++++------------------------------ man/scrape_example.Rd | 5 ++--- 10 files changed, 99 insertions(+), 155 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index 2757712..d11b13d 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,7 +1,7 @@ Package: WikidataQueryServiceR Title: API Client Library for 'Wikidata Query Service' -Version: 0.1.0 -Date: 2017-01-17 +Version: 0.1.1 +Date: 2017-04-28 Authors@R: c( person("Mikhail", "Popov", email = "mikhail@wikimedia.org", role = c("aut", "cre"), comment = "@bearloga on Twitter"), @@ -23,4 +23,5 @@ BugReports: https://github.com/bearloga/WikidataQueryServiceR/issues License: MIT + file LICENSE Encoding: UTF-8 LazyData: true -RoxygenNote: 5.0.1 +Roxygen: list(markdown = TRUE) +RoxygenNote: 6.0.1 diff --git a/NEWS.md b/NEWS.md index 10b0afa..2352872 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,3 +1,16 @@ +WikidataQueryServiceR 0.1.1 +--------------------------- + +## Changes + +* Updated documentation to use Markdown thanks to [roxygen2 6.0.0](https://blog.rstudio.org/2017/02/01/roxygen2-6-0-0/) +* Added more links for learning SPARQL in context of Wikidata + (see `help("WDQS", package = "WikidataQueryServiceR")`) + +## Bug fixes + +* Fixed a bug with JSON-formatted results ([#3](https://github.com/bearloga/WikidataQueryServiceR/issues/3)) + WikidataQueryServiceR 0.1.0 --------------------------- diff --git a/R/query.R b/R/query.R index 5047df4..d4ffc44 100644 --- a/R/query.R +++ b/R/query.R @@ -3,44 +3,23 @@ #' @param sparql_query SPARQL query (can be a vector of queries) #' @param format "simple" uses CSV and returns pure character data frame, while #' "smart" fetches JSON-formatted data and returns a data frame with datetime -#' columns converted to POSIXlt -#' @param ... Additional parameters to supply to \code{\link[httr]{GET}} -#' @return A data.frame +#' columns converted to `POSIXlt` +#' @param ... Additional parameters to supply to [httr::GET()] +#' @return A `data.frame` #' @examples -#' # Cats on Wikidata: -#' sparql_query <- 'SELECT ?item ?itemLabel -#' WHERE -#' { -#' ?item wdt:P31 wd:Q146 . -#' SERVICE wikibase:label { bd:serviceParam wikibase:language "en" } -#' } -#' LIMIT 10' +#' # 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{ -#' sparql_query <- "#Recent Events -#' SELECT ?event ?eventLabel ?date -#' WHERE -#' { -#' # find events -#' ?event wdt:P31/wdt:P279* wd:Q1190554. -#' # with a point in time or start date -#' OPTIONAL { ?event wdt:P585 ?date. } -#' OPTIONAL { ?event wdt:P580 ?date. } -#' # but at least one of those -#' FILTER(BOUND(?date) && DATATYPE(?date) = xsd:dateTime). -#' # not in the future, and not more than 31 days ago -#' BIND(NOW() - ?date AS ?distance). -#' FILTER(0 <= ?distance && ?distance < 31). -#' # and get a label as well -#' OPTIONAL { -#' ?event rdfs:label ?eventLabel. -#' FILTER(LANG(?eventLabel) = \"en\"). -#' } -#' } -#' # limit to 10 results so we don't timeout -#' LIMIT 10" -#' #' # "smart" format converts all datetime columns to POSIXlt #' query_wikidata(sparql_query, format = "smart") #' } @@ -77,9 +56,8 @@ query_wikidata <- function(sparql_query, format = c("simple", "smart"), ...) { ) httr::stop_for_status(response) if (httr::http_type(response) == "application/sparql-results+json") { - temp <- jsonlite::read_json(httr::content(response, as = "text", encoding = "UTF-8")) + temp <- jsonlite::fromJSON(httr::content(response, as = "text", encoding = "UTF-8"), simplifyVector = FALSE) } - httr::stop_for_status(response) if (length(temp$results$bindings) > 0) { df <- as.data.frame(dplyr::bind_rows(lapply(temp$results$bindings, function(x) { return(lapply(x, function(y) { return(y$value) })) diff --git a/R/utils.R b/R/utils.R index 947101a..d538e5a 100644 --- a/R/utils.R +++ b/R/utils.R @@ -1,11 +1,11 @@ #' @title Scrape an example SPARQL query from Wikidata -#' @description Scrapes \href{https://www.wikidata.org/wiki/Wikidata:SPARQL_query_service/queries/examples}{SPARQL query service examples page} +#' @description Scrapes [SPARQL query service examples page](https://www.wikidata.org/wiki/Wikidata:SPARQL_query_service/queries/examples) #' for specified example(s). Requires rvest and urltools packages. #' @details If you are planning on scraping multiple examples, please provide #' all the names as a single vector. #' @param example_name The names of the examples as they appear on -#' \href{https://www.wikidata.org/wiki/Wikidata:SPARQL_query_service/queries/examples}{this page} -#' @param ... Additional \code{httr} configurations passed to \code{rvest} +#' [this page](https://www.wikidata.org/wiki/Wikidata:SPARQL_query_service/queries/examples) +#' @param ... Additional `httr` configurations passed to `rvest` #' @return The SPARQL query as a character vector. #' @examples #' \dontrun{ diff --git a/R/wdqs.R b/R/wdqs.R index 9a3486d..0b5b2c3 100644 --- a/R/wdqs.R +++ b/R/wdqs.R @@ -1,20 +1,23 @@ #' @title WikidataQueryServiceR: An R Wrapper For Wikidata Query Service API #' @description This is an R wrapper for the -#' \href{https://www.wikidata.org/wiki/Wikidata:SPARQL_query_service}{Wikidata Query Service} +#' [Wikidata Query Service](https://www.wikidata.org/wiki/Wikidata:SPARQL_query_service) #' (WDQS) which provides a way for tools to query Wikidata via -#' \href{https://en.wikipedia.org/wiki/SPARQL}{SPARQL}. -#' @details \href{https://www.mediawiki.org/wiki/Wikidata_query_service}{Wikidata Query Service} -#' is maintained by Wikimedia Foundation's \href{https://www.mediawiki.org/wiki/Wikimedia_Discovery}{Discovery} -#' Department. -#' @references \itemize{ -#' \item \href{https://www.mediawiki.org/wiki/Wikidata_query_service/User_Manual}{WDQS User Manual} -#' \item \href{https://www.wikidata.org/wiki/Wikidata:SPARQL_query_service/queries/examples}{SPARQL Query Examples} for WDQS -#' \item \href{http://programminghistorian.org/lessons/graph-databases-and-SPARQL}{Using SPARQL to access Linked Open Data} -#' by Matthew Lincoln -#' \item Interesting or illustrative \href{https://www.wikidata.org/wiki/Wikidata:SPARQL_query_service/queries}{SPARQL queries} -#' for Wikidata -#' \item Wikidata \href{https://www.wikidata.org/wiki/Wikidata:SPARQL_query_service/2016_SPARQL_Workshop}{2016 SPARQL Workshop} -#' } +#' [SPARQL](https://en.wikipedia.org/wiki/SPARQL). +#' @details [Wikidata Query Service](https://www.mediawiki.org/wiki/Wikidata_query_service) +#' is maintained by [Wikimedia Foundation](https://wikimediafoundation.org/). +#' @references +#' - [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](http://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) #' @aliases WDQS #' @docType package #' @name WDQS-package diff --git a/README.md b/README.md index 808dd1e..f46d74a 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,19 @@ __Author:__ Mikhail Popov (Wikimedia Foundation)
__License:__ [MIT](http://opensource.org/licenses/MIT)
__Status:__ Active +## Installation + +```R +install.packages("WikidataQueryServiceR") +``` + +To install the development version: + +```R +# install.packages(c("devtools", "httr", "dplyr", "jsonlite")) +devtools::install_github("bearloga/WikidataQueryServiceR") +``` + ## Example In this example, we find 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)), get its genres ([P136](https://www.wikidata.org/wiki/Property:P136)), and then use [WDQS label service](https://www.mediawiki.org/wiki/Wikidata_query_service/User_Manual#Label_service) to return the genre labels. @@ -102,21 +115,6 @@ results$`Largest cities with female mayor` |http://www.wikidata.org/entity/Q1563 |Havana |http://www.wikidata.org/entity/Q6774124 |Marta Hernández Romero | |http://www.wikidata.org/entity/Q19660 |Bucharest |http://www.wikidata.org/entity/Q16593781 |Gabriela Fireaa | -## Installation - -This R package depends on [httr](https://cran.r-project.org/package=httr), [dplyr](https://cran.r-project.org/package=dplyr), and [jsonlite](https://cran.r-project.org/package=jsonlite) R packages (and their dependencies). - -```R -install.packages("WikidataQueryServiceR") -``` - -To install the development version: - -```R -# install.packages(c("devtools", "httr", "dplyr", "jsonlite")) -devtools::install_github("bearloga/WikidataQueryServiceR") -``` - ## Additional Information Please note that this project is released with a [Contributor Code of Conduct](https://github.com/bearloga/WikidataQueryServiceR/blob/master/CONDUCT.md). By participating in this project you agree to abide by its terms. diff --git a/cran-comments.md b/cran-comments.md index 729a6da..a24634d 100644 --- a/cran-comments.md +++ b/cran-comments.md @@ -1,8 +1,8 @@ -WikidataQueryServiceR 0.1.0 +WikidataQueryServiceR 0.1.1 --------------------------- ## Test environments -* local OS X install, R 3.3.2 +* local macOS install, R 3.4.0 * win-builder (devel and release) ## R CMD check results @@ -12,35 +12,6 @@ There were no ERRORs or WARNINGs and 1 NOTE: * checking CRAN incoming feasibility ... NOTE Maintainer: 'Mikhail Popov ' -New submission - Possibly mis-spelled words in DESCRIPTION: - API (2:8, 9:17) - -Found the following (possibly) invalid URLs: - URL: https://cran.r-project.org/package=WikidataQueryServiceR - From: README.md - Status: 404 - Message: Not Found -``` - -## R-hub Builder results -Platforms: -* Windows Server 2008 R2 SP1, R-devel, 32/64 bit -* Fedora Linux, R-devel, clang, gfortran -* Ubuntu Linux 16.04 LTS, R-release, GCC - -There were no ERRORs or WARNINGs and 1 NOTE: - -``` -N checking CRAN incoming feasibility - Maintainer: 'Mikhail Popov ' - - New submission - - License components with restrictions and base license permitting such: - MIT + file LICENSE - File 'LICENSE': - YEAR: 2016 - COPYRIGHT HOLDER: Wikimedia Foundation + API (2:8, 10:17) ``` diff --git a/man/WDQS-package.Rd b/man/WDQS-package.Rd index 49a777f..f91f4ac 100644 --- a/man/WDQS-package.Rd +++ b/man/WDQS-package.Rd @@ -2,29 +2,32 @@ % Please edit documentation in R/wdqs.R \docType{package} \name{WDQS-package} -\alias{WDQS} \alias{WDQS-package} +\alias{WDQS} \title{WikidataQueryServiceR: An R Wrapper For Wikidata Query Service API} \description{ This is an R wrapper for the - \href{https://www.wikidata.org/wiki/Wikidata:SPARQL_query_service}{Wikidata Query Service} - (WDQS) which provides a way for tools to query Wikidata via - \href{https://en.wikipedia.org/wiki/SPARQL}{SPARQL}. +\href{https://www.wikidata.org/wiki/Wikidata:SPARQL_query_service}{Wikidata Query Service} +(WDQS) which provides a way for tools to query Wikidata via +\href{https://en.wikipedia.org/wiki/SPARQL}{SPARQL}. } \details{ \href{https://www.mediawiki.org/wiki/Wikidata_query_service}{Wikidata Query Service} - is maintained by Wikimedia Foundation's \href{https://www.mediawiki.org/wiki/Wikimedia_Discovery}{Discovery} - Department. +is maintained by \href{https://wikimediafoundation.org/}{Wikimedia Foundation}. } \references{ \itemize{ - \item \href{https://www.mediawiki.org/wiki/Wikidata_query_service/User_Manual}{WDQS User Manual} - \item \href{https://www.wikidata.org/wiki/Wikidata:SPARQL_query_service/queries/examples}{SPARQL Query Examples} for WDQS - \item \href{http://programminghistorian.org/lessons/graph-databases-and-SPARQL}{Using SPARQL to access Linked Open Data} - by Matthew Lincoln - \item Interesting or illustrative \href{https://www.wikidata.org/wiki/Wikidata:SPARQL_query_service/queries}{SPARQL queries} - for Wikidata - \item Wikidata \href{https://www.wikidata.org/wiki/Wikidata:SPARQL_query_service/2016_SPARQL_Workshop}{2016 SPARQL Workshop} +\item \href{https://www.wikidata.org/wiki/Wikidata:A_beginner-friendly_course_for_SPARQL}{A beginner-friendly course for SPARQL} +\item Building a SPARQL query: \href{https://www.wikidata.org/wiki/Help:SPARQL/Building_a_query/Museums_on_Instagram}{Museums on Instagram} +\item \href{https://www.wikidata.org/wiki/Wikidata:SPARQL_query_service/queries/examples}{SPARQL Query Examples} for WDQS +\item \href{http://programminghistorian.org/lessons/graph-databases-and-SPARQL}{Using SPARQL to access Linked Open Data} +by Matthew Lincoln +\item Interesting or illustrative \href{https://www.wikidata.org/wiki/Wikidata:SPARQL_query_service/queries}{SPARQL queries} +for Wikidata +\item Wikidata \href{https://www.wikidata.org/wiki/Wikidata:SPARQL_query_service/2016_SPARQL_Workshop}{2016 SPARQL Workshop} +\item \href{https://www.youtube.com/watch?v=1jHoUkj_mKw}{Wikidata SPARQL Query video tutorial} +by Navino Evans +\item \emph{\href{http://www.learningsparql.com/}{Learning SPARQL}} by Bob DuCharme +\item \href{https://www.mediawiki.org/wiki/Wikidata_query_service/User_Manual}{WDQS User Manual} } } - diff --git a/man/query_wikidata.Rd b/man/query_wikidata.Rd index e889b34..9536a82 100644 --- a/man/query_wikidata.Rd +++ b/man/query_wikidata.Rd @@ -11,53 +11,31 @@ query_wikidata(sparql_query, format = c("simple", "smart"), ...) \item{format}{"simple" uses CSV and returns pure character data frame, while "smart" fetches JSON-formatted data and returns a data frame with datetime -columns converted to POSIXlt} +columns converted to \code{POSIXlt}} -\item{...}{Additional parameters to supply to \code{\link[httr]{GET}}} +\item{...}{Additional parameters to supply to \code{\link[httr:GET]{httr::GET()}}} } \value{ -A data.frame +A \code{data.frame} } \description{ Makes a GET request to Wikidata Query Service SPARQL endpoint. } \examples{ -# Cats on Wikidata: -sparql_query <- 'SELECT ?item ?itemLabel -WHERE -{ - ?item wdt:P31 wd:Q146 . - SERVICE wikibase:label { bd:serviceParam wikibase:language "en" } -} -LIMIT 10' +# 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{ -sparql_query <- "#Recent Events -SELECT ?event ?eventLabel ?date -WHERE -{ - # find events - ?event wdt:P31/wdt:P279* wd:Q1190554. - # with a point in time or start date - OPTIONAL { ?event wdt:P585 ?date. } - OPTIONAL { ?event wdt:P580 ?date. } - # but at least one of those - FILTER(BOUND(?date) && DATATYPE(?date) = xsd:dateTime). - # not in the future, and not more than 31 days ago - BIND(NOW() - ?date AS ?distance). - FILTER(0 <= ?distance && ?distance < 31). - # and get a label as well - OPTIONAL { - ?event rdfs:label ?eventLabel. - FILTER(LANG(?eventLabel) = \\"en\\"). - } -} -# limit to 10 results so we don't timeout -LIMIT 10" - # "smart" format converts all datetime columns to POSIXlt query_wikidata(sparql_query, format = "smart") } } - diff --git a/man/scrape_example.Rd b/man/scrape_example.Rd index 3cf1f2d..5cf7618 100644 --- a/man/scrape_example.Rd +++ b/man/scrape_example.Rd @@ -17,11 +17,11 @@ The SPARQL query as a character vector. } \description{ Scrapes \href{https://www.wikidata.org/wiki/Wikidata:SPARQL_query_service/queries/examples}{SPARQL query service examples page} - for specified example(s). Requires rvest and urltools packages. +for specified example(s). Requires rvest and urltools packages. } \details{ If you are planning on scraping multiple examples, please provide - all the names as a single vector. +all the names as a single vector. } \examples{ \dontrun{ @@ -35,4 +35,3 @@ cat(sparql_query) query_wikidata(sparql_query) } } -