Merge pull request #256 from ropensci/add-topics

"topics" as an entity

DESCRIPTION

@@ -2,7 +2,7 @@ Type: Package
 Package: openalexR
 Title: Getting Bibliographic Records from 'OpenAlex' Database Using 'DSL'
     API
-Version: 1.3.1
+Version: 1.4.0
 Authors@R: c(
     person(given = "Massimo",
            family = "Aria",

NAMESPACE

@@ -21,5 +21,6 @@ export(show_authors)
 export(show_works)
 export(snowball2df)
 export(sources2df)
+export(topics2df)
 export(works2df)
 importFrom(stats,setNames)

NEWS.md

@@ -1,3 +1,6 @@
+# openalexR 1.4.0
+* "topics" are now available in oa_fetch
+
 # openalexR 1.3.1
 * solved bug in au_affiliation_raw in PR#241
 

R/oa2df.R

@@ -6,7 +6,7 @@
 #' @param data List. Output of \code{oa_request}.
 #' @param entity Character. Scholarly entity of the search.
 #' The argument can be one of
-#' c("works", "authors", "institutions", "concepts", "funders", "sources", "publishers").
+#' c("works", "authors", "institutions", "concepts", "funders", "sources", "publishers", "topics").
 #' @param abstract Logical. If TRUE, the function returns also the abstract of each item.
 #' Ignored if entity is different from "works". Defaults to TRUE.
 #' @param verbose Logical.
@@ -75,6 +75,7 @@ oa2df <- function(data, entity, options = NULL, count_only = FALSE, group_by = N
     funders = funders2df(data, verbose),
     sources = sources2df(data, verbose),
     publishers = publishers2df(data, verbose),
+    topics = topics2df(data, verbose),
     snowball = snowball2df(data)
   )
 }
@@ -843,6 +844,90 @@ publishers2df <- function(data, verbose = TRUE,
 }
 
 
+#' Convert OpenAlex collection of topics' records from list format to data frame
+#'
+#' It converts collection of topics' records gathered from the OpenAlex database.
+#' The function converts a list of topics' records obtained using \code{oa_request} into a data frame/tibble.
+#'
+#' @inheritParams works2df
+#'
+#' @return a data.frame.
+#'
+#' For more extensive information about OpenAlex API, please visit: <https://docs.openalex.org>
+#'
+#'
+#' @examples
+#' \dontrun{
+#'
+#' # Query to search information about all Italian educational institutions
+#'
+#'
+#' query_inst <- oa_query(
+#'   entity = "topics",
+#'   display_name.search = "electrodynamics"
+#' )
+#'
+#' res <- oa_request(
+#'   query_url = query_inst,
+#'   count_only = FALSE,
+#'   verbose = FALSE
+#' )
+#'
+#' df <- oa2df(res, entity = "topics")
+#'
+#' df
+#' }
+#'
+#' @export
+topics2df <- function(data, verbose = TRUE,
+                        pb = if (verbose) oa_progress(length(data)) else NULL) {
+  topic_process <- tibble::tribble(
+    ~type, ~field,
+    "identical", "id",
+    "identical", "display_name",
+    "identical", "description",
+    "flat", "ids",
+    "identical", "relevance_score",
+    "identical", "works_count",
+    "identical", "cited_by_count",
+    "identical", "updated_date",
+    "identical", "created_date",
+    "rbind_df", "siblings",
+    "flat", "keywords"
+  )
+
+  n <- length(data)
+  list_df <- vector(mode = "list", length = n)
+
+  for (i in seq.int(n)) {
+    if (verbose) pb$tick()
+
+    item <- data[[i]]
+    fields <- topic_process[topic_process$field %in% names(item), ]
+    sim_fields <- mapply(
+      function(x, y) subs_na(item[[x]], type = y),
+      fields$field,
+      fields$type,
+      SIMPLIFY = FALSE
+    )
+    domains <- unlist(item[c("subfield", "field", "domain")], recursive = FALSE)
+    domains <- as.data.frame(do.call(cbind, domains))
+    names(domains) <- gsub("\\.", "_", names(domains))
+    list_df[[i]] <- c(sim_fields, domains)
+  }
+
+  col_order <- c(
+    "id", "display_name", "description", "keywords", "ids",
+    "subfield_id", "subfield_display_name", "field_id", "field_display_name",
+    "domain_id", "domain_display_name", "siblings", "relevance_score",
+    "works_count", "cited_by_count", "updated_date", "created_date"
+  )
+
+  out_df <- rbind_oa_ls(list_df)
+  out_df[, intersect(col_order, names(out_df))]
+}
+
+
 
 #' Flatten snowball result
 #'

R/oa_fetch.R

@@ -7,7 +7,7 @@
 oa_entities <- function() {
   c(
     "works", "authors", "institutions", "concepts",
-    "funders", "sources", "publishers"
+    "funders", "sources", "publishers", "topics"
   )
 }
 
@@ -461,7 +461,7 @@ get_next_page <- function(paging, i, res = NULL) {
 #' See more at <https://docs.openalex.org/how-to-use-the-api/get-single-entities#the-openalex-id>.
 #' @param entity Character. Scholarly entity of the search.
 #' The argument can be one of
-#' c("works", "authors", "institutions", "concepts", "funders", "sources", "publishers").
+#' c("works", "authors", "institutions", "concepts", "funders", "sources", "publishers", "topics").
 #' If not provided, `entity` is guessed from `identifier`.
 #' @param options List. Additional parameters to add in the query. For example:
 #'

R/utils.R

@@ -58,6 +58,7 @@ id_type <- function(identifier) {
     S = "sources",
     P = "publishers",
     `F` = "funders",
+    `T` = "topics",
     NA
   )
 }

tests/testthat/test-oa_fetch.R

@@ -299,11 +299,13 @@ test_that("oa_fetch other entities works", {
   random_sources <- oa_fetch(entity = "sources", options = list(sample = 20))
   random_concepts <- oa_fetch(entity = "concepts", options = list(sample = 20))
   random_institutions <- oa_fetch(entity = "institutions", options = list(sample = 20))
+  random_topics <- oa_fetch(entity = "topics", options = list(sample = 20))
 
   expect_equal(nrow(random_authors), 20)
   expect_equal(nrow(random_sources), 20)
   expect_equal(nrow(random_concepts), 20)
   expect_equal(nrow(random_institutions), 20)
+  expect_equal(nrow(random_topics), 20)
 })
 
 test_that("paging works with sample", {

vignettes/articles/Filters.Rmd

@@ -15,7 +15,7 @@ Available arguments/filters for each entity and associated example values are in
 
 **Note**: `x_concepts.id` in all entities are experimental.
 
-See the [original documentation](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/filter-entity-lists) from Open Alex.
+See the [OpenAlex documentation](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/filter-entity-lists) for the latest list of valid filters. 
 
 ## Available arguments by entity