Add files via upload

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: eurlex
 Type: Package
 Title: Retrieve Data on European Union Law
-Version: 0.3.1
+Version: 0.3.2
 Authors@R: c(person(given = "Michal",
              family = "Ovadek",
              role = c("aut", "cre", "cph"),

NEWS.md

@@ -1,3 +1,15 @@
+# eurlex 0.3.2
+
+## Major changes
+
+- improvement to legal basis harvesting thanks to help from Eur-Lex insiders
+- legal basis results are now slightly more comprehensive and correct
+- legal basis results now include a new column detailing the "suffix" (paragraph, subparagraph, etc.) in string form
+
+## Minor changes
+
+- minor updates to documentation
+
 # eurlex 0.3.1
 
 ## Minor changes

R/elx_council_votes.R

@@ -3,6 +3,8 @@
 #' Executes a SPARQL query to the Council's endpoint.
 #'
 #' @importFrom rlang .data
+#' @return
+#' A data frame with Council votes on EU acts.
 #' @export
 #' @examples
 #' \donttest{

R/elx_curia_list.R

@@ -5,7 +5,8 @@
 #'
 #' @param data Data to be scraped from four separate lists of cases maintained by Curia, defaults to "all"
 #' which contains cases from Court of Justice, General Court and Civil Service Tribunal.
-#'
+#' @return
+#' A data frame containing case identifiers and information as character columns.
 #' @importFrom rlang .data
 #' @export
 #' @examples

R/elx_fetch_data.R

@@ -2,12 +2,14 @@
 #'
 #' Wraps httr::GET with pre-specified headers to retrieve data.
 #'
-#' @param url A valid url based on a resource identifier such as CELEX or Cellar URI.
+#' @param url A valid url as character vector of length one based on a resource identifier such as CELEX or Cellar URI.
 #' @param type The type of data to be retrieved. When type = "text", the returned list contains named elements reflecting the source of each text.
 #' @param language_1 The priority language in which the data will be attempted to be retrieved, in ISO 639 2-char code
 #' @param language_2 If data not available in `language_1`, try `language_2`
 #' @param language_3 If data not available in `language_2`, try `language_3`
 #' @param include_breaks If TRUE, text includes tags showing where pages ("---pagebreak---", for pdfs) and documents ("---documentbreak---") were concatenated
+#' @return
+#' A character vector of length one containing the result.
 #' @export
 #' @examples
 #' \donttest{

R/elx_label_eurovoc.R

@@ -5,6 +5,8 @@
 #' @param uri_eurovoc Character vector with valid EuroVoc URIs
 #' @param alt_labels If `TRUE`, results include comma-separated alternative labels in addition to the preferred label
 #' @param language Language in which to return the labels, in ISO 639 2-char code
+#' @return
+#' A `tibble` containing EuroVoc unique concept identifiers and labels.
 #' @export
 #' @examples
 #' elx_label_eurovoc(uri_eurovoc = "http://eurovoc.europa.eu/5760", alt_labels = TRUE, language = "fr")

R/elx_make_query.R

@@ -19,6 +19,8 @@
 #' @param include_eurovoc If `TRUE`, results include EuroVoc descriptors of subject matter
 #' @param order Order results by ids
 #' @param limit Limit the number of results, for testing purposes mainly
+#' @return
+#' A character string containing the SPARQL query
 #' @export
 #' @examples
 #' elx_make_query(resource_type = "directive", include_date = TRUE, include_force = TRUE)
@@ -45,6 +47,7 @@ elx_make_query <- function(resource_type = c("directive","regulation","decision"
   }
 
   query <- "PREFIX cdm: <http://publications.europa.eu/ontology/cdm#>
+  PREFIX annot: <http://publications.europa.eu/ontology/annotation#>
   PREFIX skos:<http://www.w3.org/2004/02/skos/core#>
   PREFIX dc:<http://purl.org/dc/elements/1.1/>
   PREFIX xsd:<http://www.w3.org/2001/XMLSchema#>
@@ -88,7 +91,7 @@ elx_make_query <- function(resource_type = c("directive","regulation","decision"
       stop("Legal basis variable incompatible with requested resource type", call. = TRUE)
     }
 
-    query <- paste(query, "?lbs ?lbcelex", sep = " ")
+    query <- paste(query, "?lbs ?lbcelex ?lbsuffix", sep = " ")
 
   }
 
@@ -267,8 +270,12 @@ elx_make_query <- function(resource_type = c("directive","regulation","decision"
 
   if (include_lbs == TRUE & resource_type!="caselaw"){
 
-    query <- paste(query, "?work cdm:resource_legal_based_on_resource_legal ?lbs.
-                   ?lbs cdm:resource_legal_id_celex ?lbcelex.",
+    query <- paste(query, "OPTIONAL{?work cdm:resource_legal_based_on_resource_legal ?lbs.
+    ?lbs cdm:resource_legal_id_celex ?lbcelex.
+    OPTIONAL{?bn owl:annotatedSource ?work.
+    ?bn owl:annotatedProperty <http://publications.europa.eu/ontology/cdm#resource_legal_based_on_resource_legal>.
+    ?bn owl:annotatedTarget ?lbs.
+    ?bn annot:comment_on_legal_basis ?lbsuffix}}",
                    sep = " ")
 
   }

R/elx_run_query.R

@@ -5,6 +5,9 @@
 #'
 #' @param query A valid SPARQL query specified by `elx_make_query` or manually
 #' @param endpoint SPARQL endpoint
+#' @return
+#' A data frame containing the results of the SPARQL query.
+#' Column `work` contains the Cellar URI of the resource. Rows with even one missing variable are dropped.
 #' @export
 #' @examples
 #' \donttest{

README.md

@@ -17,7 +17,7 @@ The `eurlex` package currently envisions the typical use-case to consist of gett
 
 The function `elx_make_query` takes as its first argument the type of resource to be retrieved (such as "directive") from the semantic database that powers Eur-Lex (and other publications) called Cellar. If you are familiar with SPARQL, you can always specify your own queries and execute them with `elx_run_query()`.
 
-`elx_run_query()` executes SPARQL queries on a pre-specified endpoint of the EU Publication Office. It outputs a `data.frame` where each column corresponds to one of the requested variables, while the rows accumulate observations of the resource type satisfying the query criteria. Obviously, the more data is to be returned, the longer the execution time, varying from a few seconds to several minutes, depending also on your connection. The first column always contains the unique URI of a "work" (legislative act or court judgment) which identifies each resource in Cellar. Several human-readable identifiers are normally associated with each "work" but the most useful one is CELEX, retrieved by default.
+`elx_run_query()` executes SPARQL queries on a pre-specified endpoint of the EU Publication Office. It outputs a `data.frame` where each column corresponds to one of the requested variables, while the rows accumulate observations of the resource type satisfying the query criteria. Obviously, the more data is to be returned, the longer the execution time, varying from a few seconds to several minutes, depending also on your connection. The first column always contains the unique URI of a "work" (legislative act or court judgment) which identifies each resource in Cellar. Several human-readable identifiers are normally associated with each "work" but the most useful one is [CELEX](https://eur-lex.europa.eu/content/tools/TableOfSectors/types_of_documents_in_eurlex.html), retrieved by default.
 
 For the moment, it is recommended to retrieve metadata one variable at a time. For example, if you wish to obtain the legal bases of directives and the date of transposition, you should run separate calls: