From a77283fbc46430d842504d62fc635cb12d7957c6 Mon Sep 17 00:00:00 2001 From: Scott Chamberlain Date: Wed, 28 Mar 2018 12:48:16 -0700 Subject: [PATCH] readme update, and update docs with api key notes and update url for where to get it --- R/evaluate.R | 7 ++-- R/graph_search.R | 3 +- R/microdemic-package.R | 25 ++++++++++-- R/similarity.R | 19 +++++---- README.Rmd | 7 +++- README.md | 85 ++++++++++++++++++++------------------- man/ma_abstract.Rd | 7 ++-- man/ma_calchist.Rd | 7 ++-- man/ma_evaluate.Rd | 7 ++-- man/ma_graph_search.Rd | 3 +- man/ma_interpret.Rd | 3 +- man/ma_search.Rd | 7 ++-- man/ma_similarity.Rd | 15 +++---- man/microdemic-package.Rd | 24 +++++++++-- 14 files changed, 137 insertions(+), 82 deletions(-) diff --git a/R/evaluate.R b/R/evaluate.R index b3252df..60980e4 100644 --- a/R/evaluate.R +++ b/R/evaluate.R @@ -8,9 +8,10 @@ #' @param atts (character) fields to return, in a character vector. See #' #' for details. -#' @param model (character) Name of the model that you wish to query. One of 'latest' -#' or 'beta-2015'. Default: latest -#' @param key (character) microsoft academic API key, see Details. +#' @param model (character) Name of the model that you wish to query. One +#' of 'latest' or 'beta-2015'. Default: latest +#' @param key (character) microsoft academic API key, see the `Authentication` +#' section in [microdemic-package] #' @param ... curl options passed on to [crul::HttpClient] #' @return a list of length two, with `expr` (character) and #' `entities` (data.frame) diff --git a/R/graph_search.R b/R/graph_search.R index ebf9340..e2ddff6 100644 --- a/R/graph_search.R +++ b/R/graph_search.R @@ -3,7 +3,8 @@ #' @export #' @param query (character) query terms #' @param mode (character) json (default) or lambda -#' @param key (character) microsoft academic API key, see Details. +#' @param key (character) microsoft academic API key, see the `Authentication` +#' section in [microdemic-package] #' @param ... curl options passed on to [crul::HttpClient] #' @references #' diff --git a/R/microdemic-package.R b/R/microdemic-package.R index a6c1cef..303f9f1 100644 --- a/R/microdemic-package.R +++ b/R/microdemic-package.R @@ -3,7 +3,7 @@ #' @section Links: #' #' * web interface: -#' * API docs: +#' * API docs: #' #' @section Package API: #' @@ -16,8 +16,27 @@ #' * [ma_graph_search()] #' #' @section Authentication: -#' See to get -#' an API key +#' See to get +#' an API key. Make sure you enable Academic Knowledge and. They should +#' give you two API keys - use either one. You can always pass your API +#' key as a parameter to functions in `microdemic`, but we strongly +#' encourage you to set an environment variable, named `MICROSOFT_ACADEMIC_KEY` +#' +#' To set the environment variable for the current R session only, +#' run `Sys.setenv(MICROSOFT_ACADEMIC_KEY = "yourkey")`. Then `microdemic` +#' will pick up this key and you do not have to pass your key as a +#' parameter to the functions. +#' +#' Even better, save your environment variable in the file that R will use +#' to read in environment variables like `MICROSOFT_ACADEMIC_KEY=yourkey`. +#' This may vary by system and machine. +#' See `?Startup` for details. It's likely your `.Renviron` file that +#' is stored in your home directory. Or could be another environment +#' variable holding file like `.zshrc` or `.bash_profile`. After saving the +#' file, make sure to quit R, source that file like `source .Renviron`, +#' then start R again. Or restart your RStudio session or similar for +#' other R scenarios. +#' #' #' @section Rate limits: #' diff --git a/R/similarity.R b/R/similarity.R index 9423a43..2193afd 100644 --- a/R/similarity.R +++ b/R/similarity.R @@ -3,14 +3,15 @@ #' @export #' @param s1,s2 (character) strings 1 and 2. required #' @param method (character) one of GET (default) or POST -#' @param model (character) Name of the model that you wish to query. One of 'latest' -#' or 'beta-2015'. Default: latest -#' @param key (character) microsoft academic API key, see [microdemic] +#' @param model (character) Name of the model that you wish to query. One of +#' 'latest' or 'beta-2015'. Default: latest +#' @param key (character) microsoft academic API key, see the `Authentication` +#' section in [microdemic-package] #' @param ... curl options passed on to [crul::HttpClient] -#' @return a single value representing the cosine similarity of the text inputs of -#' s1 and s2. The output is represented by a floating point between -1.0 and +1.0. -#' The similarity API evaluates the strings base on their academic concepts, -#' with +1.0 being the most similar and -1.0 being the least similar. +#' @return a single value representing the cosine similarity of the text inputs +#' of s1 and s2. The output is represented by a floating point between -1.0 +#' and +1.0. The similarity API evaluates the strings base on their academic +#' concepts, with +1.0 being the most similar and -1.0 being the least similar. #' @examples \dontrun{ #' s1 <- "Using complementary priors, we derive a fast greedy algorithm that #' can learn deep directed belief networks one layer at a time, provided the @@ -24,7 +25,9 @@ #' #' ma_similarity(s1, s2, method = "POST") #' } -ma_similarity <- function(s1, s2, method = "GET", model = "latest", key = NULL, ...) { +ma_similarity <- function(s1, s2, method = "GET", model = "latest", + key = NULL, ...) { + if (!method %in% c("GET", "POST")) stop("'method' must be one of GET or POST") assert(model, "character") diff --git a/README.Rmd b/README.Rmd index e9cca5a..aca367f 100644 --- a/README.Rmd +++ b/README.Rmd @@ -13,13 +13,14 @@ knitr::opts_chunk$set( [![Project Status: WIP – Initial development is in progress, but there has not yet been a stable, usable release suitable for the public.](http://www.repostatus.org/badges/latest/wip.svg)](http://www.repostatus.org/#wip) [![Build Status](https://travis-ci.org/ropensci/microdemic.svg?branch=master)](https://travis-ci.org/ropensci/microdemic) [![codecov](https://codecov.io/gh/ropensci/microdemic/branch/master/graph/badge.svg)](https://codecov.io/gh/ropensci/microdemic) +[![rstudio mirror downloads](https://cranlogs.r-pkg.org/badges/microdemic)](https://github.com/metacran/cranlogs.app) [![cran version](https://www.r-pkg.org/badges/version/microdemic)](https://cran.r-project.org/package=microdemic) `microdemic` - Microsoft Academic Client -API docs: +API docs: -Get a API key at +Get a API key at ## install @@ -109,3 +110,5 @@ ma_graph_search(query = x) * License: MIT * Get citation information for `microdemic` in R doing `citation(package = 'microdemic')` * Please note that this project is released with a [Contributor Code of Conduct](CONDUCT.md). By participating in this project you agree to abide by its terms. + +[![ropensci_footer](https://ropensci.org/public_images/github_footer.png)](https://ropensci.org) diff --git a/README.md b/README.md index a9df072..c8601e1 100644 --- a/README.md +++ b/README.md @@ -6,13 +6,14 @@ microdemic [![Project Status: WIP – Initial development is in progress, but there has not yet been a stable, usable release suitable for the public.](http://www.repostatus.org/badges/latest/wip.svg)](http://www.repostatus.org/#wip) [![Build Status](https://travis-ci.org/ropensci/microdemic.svg?branch=master)](https://travis-ci.org/ropensci/microdemic) [![codecov](https://codecov.io/gh/ropensci/microdemic/branch/master/graph/badge.svg)](https://codecov.io/gh/ropensci/microdemic) +[![rstudio mirror downloads](https://cranlogs.r-pkg.org/badges/microdemic)](https://github.com/metacran/cranlogs.app) [![cran version](https://www.r-pkg.org/badges/version/microdemic)](https://cran.r-project.org/package=microdemic) `microdemic` - Microsoft Academic Client -API docs: +API docs: -Get a API key at +Get a API key at ## install @@ -50,18 +51,18 @@ res <- ma_interpret(query = "papers by jaime'...") ```r ma_evaluate(expr) #> # A tibble: 10 x 8 -#> logprob Id Ti Y CC AA E J.JN -#> * -#> 1 -14.9 2337454357 inten… 1998 13261 2 -17.8 2122159856 agata… 2012 139 3 -18.0 2567424265 regre… 2016 79 4 -18.2 2018655931 effec… 1995 812 5 -18.3 1507854122 the u… 2002 413 6 -18.6 2066093376 inter… 2008 205 7 -18.7 2035651919 diffe… 2005 243 8 -18.8 2049816406 surfa… 1996 457 9 -18.9 2038399305 from … 2008 65 10 -19.0 2165320653 a pha… 2006 248 logprob Id Ti Y CC AA E J.JN +#> * +#> 1 -14.9 2337454357. inten… 1998 13281 2 -17.8 2122159856. agata… 2012 140 3 -17.9 2567424265. regre… 2016 90 4 -18.2 2018655931. effec… 1995 811 5 -18.3 1507854122. the u… 2002 412 6 -18.6 2066093376. inter… 2008 207 7 -18.7 2035651919. diffe… 2005 242 8 -18.8 2049816406. surfa… 1996 458 9 -19.0 2038399305. from … 2008 65 10 -19.0 2125111321. isola… 2011 85 # A tibble: 10 x 8 -#> logprob Id Ti Y CC AA E J.JN -#> * -#> 1 -13.1 2144634347 molec… 1989 125571 -#> 2 -13.6 2596886333 diagn… 1994 88682 -#> 3 -13.8 2339804494 fuzzy… 1996 36075 -#> 4 -13.8 2156909104 the n… 1995 27342 5 -13.9 2158714788 gappe… 1997 52865 6 -13.9 1856219842 stand… 1992 56992 -#> 7 -14.1 2132905138 crc h… 1990 37155 -#> 8 -14.2 2623205651 quant… 1993 15172 -#> 9 -14.2 2152195021 parti… 1995 26464 -#> 10 -14.2 2148603752 stati… 1998 18218 +#> logprob Id Ti Y CC AA E J.JN +#> * +#> 1 -13.1 2144634347. molec… 1989 126083 +#> 2 -13.6 2596886333. diagn… 1994 89916 +#> 3 -13.8 2339804494. fuzzy… 1996 36215 +#> 4 -13.8 2156909104. the n… 1995 27504 5 -13.9 2158714788. gappe… 1997 53035 6 -13.9 1856219842. stand… 1992 57527 +#> 7 -14.1 2132905138. crc h… 1990 37782 +#> 8 -14.2 2623205651. quant… 1993 15322 +#> 9 -14.2 2152195021. parti… 1995 26555 +#> 10 -14.2 2148603752. stati… 1998 18273 ``` ## Calchistogram @@ -93,24 +94,24 @@ res <- ma_calchist(query = "And(Composite(AA.AuN=='jaime teevan'),Y>2012)", res$histograms$histogram #> [[1]] #> value logprob count -#> 1 2013 -17.060 19 -#> 2 2014 -17.273 13 -#> 3 2016 -17.918 16 -#> 4 2015 -17.998 13 -#> 5 2017 -18.562 11 +#> 1 2013 -17.105 18 +#> 2 2014 -17.315 13 +#> 3 2015 -17.961 13 +#> 4 2016 -18.016 16 +#> 5 2017 -19.015 11 #> #> [[2]] #> value logprob count -#> 1 computer science -16.172 56 -#> 2 data mining -16.833 25 -#> 3 search engine -17.220 13 -#> 4 crowdsourcing -17.299 19 -#> 5 information retrieval -17.326 14 -#> 6 crowd -17.416 16 -#> 7 human computer interaction -17.639 18 -#> 8 multimedia -17.783 13 -#> 9 world wide web -18.070 5 -#> 10 search analytics -18.072 5 +#> 1 computer science -16.227 55 +#> 2 data mining -16.779 26 +#> 3 crowdsourcing -17.163 20 +#> 4 search engine -17.218 13 +#> 5 information retrieval -17.363 13 +#> 6 human computer interaction -17.656 18 +#> 7 multimedia -17.810 13 +#> 8 search analytics -18.091 5 +#> 9 world wide web -18.096 5 +#> 10 social network -18.244 5 ``` ## Similarity @@ -173,3 +174,5 @@ ma_graph_search(query = x) * License: MIT * Get citation information for `microdemic` in R doing `citation(package = 'microdemic')` * Please note that this project is released with a [Contributor Code of Conduct](CONDUCT.md). By participating in this project you agree to abide by its terms. + +[![ropensci_footer](https://ropensci.org/public_images/github_footer.png)](https://ropensci.org) diff --git a/man/ma_abstract.Rd b/man/ma_abstract.Rd index 04bde62..8cef7a9 100644 --- a/man/ma_abstract.Rd +++ b/man/ma_abstract.Rd @@ -16,10 +16,11 @@ ma_abstract(query, count = 10, offset = 0, orderby = NULL, \item{orderby}{(logical) column by which to order. default: none} -\item{model}{(character) Name of the model that you wish to query. One of 'latest' -or 'beta-2015'. Default: latest} +\item{model}{(character) Name of the model that you wish to query. One +of 'latest' or 'beta-2015'. Default: latest} -\item{key}{(character) microsoft academic API key, see Details.} +\item{key}{(character) microsoft academic API key, see the \code{Authentication} +section in \link{microdemic-package}} \item{...}{curl options passed on to \link[crul:HttpClient]{crul::HttpClient}} } diff --git a/man/ma_calchist.Rd b/man/ma_calchist.Rd index 0312a6e..c440152 100644 --- a/man/ma_calchist.Rd +++ b/man/ma_calchist.Rd @@ -18,10 +18,11 @@ ma_calchist(query, count = 10, offset = 0, atts = c("Id", "AA.AuN", \url{https://docs.microsoft.com/en-us/azure/cognitive-services/academic-knowledge/entityattributes} for details.} -\item{model}{(character) Name of the model that you wish to query. One of 'latest' -or 'beta-2015'. Default: latest} +\item{model}{(character) Name of the model that you wish to query. One +of 'latest' or 'beta-2015'. Default: latest} -\item{key}{(character) microsoft academic API key, see Details.} +\item{key}{(character) microsoft academic API key, see the \code{Authentication} +section in \link{microdemic-package}} \item{...}{curl options passed on to \link[crul:HttpClient]{crul::HttpClient}} } diff --git a/man/ma_evaluate.Rd b/man/ma_evaluate.Rd index 90d85aa..d9415bd 100644 --- a/man/ma_evaluate.Rd +++ b/man/ma_evaluate.Rd @@ -21,10 +21,11 @@ ma_evaluate(query, count = 10, offset = 0, orderby = NULL, \url{https://docs.microsoft.com/en-us/azure/cognitive-services/academic-knowledge/entityattributes} for details.} -\item{model}{(character) Name of the model that you wish to query. One of 'latest' -or 'beta-2015'. Default: latest} +\item{model}{(character) Name of the model that you wish to query. One +of 'latest' or 'beta-2015'. Default: latest} -\item{key}{(character) microsoft academic API key, see Details.} +\item{key}{(character) microsoft academic API key, see the \code{Authentication} +section in \link{microdemic-package}} \item{...}{curl options passed on to \link[crul:HttpClient]{crul::HttpClient}} } diff --git a/man/ma_graph_search.Rd b/man/ma_graph_search.Rd index e422071..2e76519 100644 --- a/man/ma_graph_search.Rd +++ b/man/ma_graph_search.Rd @@ -11,7 +11,8 @@ ma_graph_search(query, mode = "json", key = NULL, ...) \item{mode}{(character) json (default) or lambda} -\item{key}{(character) microsoft academic API key, see Details.} +\item{key}{(character) microsoft academic API key, see the \code{Authentication} +section in \link{microdemic-package}} \item{...}{curl options passed on to \link[crul:HttpClient]{crul::HttpClient}} } diff --git a/man/ma_interpret.Rd b/man/ma_interpret.Rd index 1e8d5fc..d87d36f 100644 --- a/man/ma_interpret.Rd +++ b/man/ma_interpret.Rd @@ -17,7 +17,8 @@ ma_interpret(query, count = 10, offset = 0, complete = TRUE, key = NULL, \item{complete}{(logical) \code{TRUE} means that auto-completion suggestions are generated based on the grammar and graph data. default: \code{TRUE}} -\item{key}{(character) microsoft academic API key, see Details.} +\item{key}{(character) microsoft academic API key, see the \code{Authentication} +section in \link{microdemic-package}} \item{...}{curl options passed on to \link[crul:HttpClient]{crul::HttpClient}} } diff --git a/man/ma_search.Rd b/man/ma_search.Rd index 67e8459..223ee27 100644 --- a/man/ma_search.Rd +++ b/man/ma_search.Rd @@ -21,10 +21,11 @@ ma_search(query, count = 10, offset = 0, orderby = NULL, atts = c("Id", \url{https://docs.microsoft.com/en-us/azure/cognitive-services/academic-knowledge/entityattributes} for details.} -\item{model}{(character) Name of the model that you wish to query. One of 'latest' -or 'beta-2015'. Default: latest} +\item{model}{(character) Name of the model that you wish to query. One +of 'latest' or 'beta-2015'. Default: latest} -\item{key}{(character) microsoft academic API key, see Details.} +\item{key}{(character) microsoft academic API key, see the \code{Authentication} +section in \link{microdemic-package}} \item{...}{curl options passed on to \link[crul:HttpClient]{crul::HttpClient}} } diff --git a/man/ma_similarity.Rd b/man/ma_similarity.Rd index 04d39df..63c215c 100644 --- a/man/ma_similarity.Rd +++ b/man/ma_similarity.Rd @@ -11,18 +11,19 @@ ma_similarity(s1, s2, method = "GET", model = "latest", key = NULL, ...) \item{method}{(character) one of GET (default) or POST} -\item{model}{(character) Name of the model that you wish to query. One of 'latest' -or 'beta-2015'. Default: latest} +\item{model}{(character) Name of the model that you wish to query. One of +'latest' or 'beta-2015'. Default: latest} -\item{key}{(character) microsoft academic API key, see \link{microdemic}} +\item{key}{(character) microsoft academic API key, see the \code{Authentication} +section in \link{microdemic-package}} \item{...}{curl options passed on to \link[crul:HttpClient]{crul::HttpClient}} } \value{ -a single value representing the cosine similarity of the text inputs of -s1 and s2. The output is represented by a floating point between -1.0 and +1.0. -The similarity API evaluates the strings base on their academic concepts, -with +1.0 being the most similar and -1.0 being the least similar. +a single value representing the cosine similarity of the text inputs +of s1 and s2. The output is represented by a floating point between -1.0 +and +1.0. The similarity API evaluates the strings base on their academic +concepts, with +1.0 being the most similar and -1.0 being the least similar. } \description{ Similarity API diff --git a/man/microdemic-package.Rd b/man/microdemic-package.Rd index c9b5d5f..ee48df1 100644 --- a/man/microdemic-package.Rd +++ b/man/microdemic-package.Rd @@ -12,7 +12,7 @@ Microsoft Academic Client \itemize{ \item web interface: \url{https://academic.microsoft.com/} -\item API docs: \url{https://www.microsoft.com/cognitive-services/en-us/Academic-Knowledge-API/documentation/overview} +\item API docs: \url{https://dev.labs.cognitive.microsoft.com/docs/services/56332331778daf02acc0a50b/operations/565d9001ca73072048922d97} } } @@ -31,8 +31,26 @@ Microsoft Academic Client \section{Authentication}{ -See \url{https://azure.microsoft.com/en-us/try/cognitive-services/} to get -an API key +See \url{https://labs.cognitive.microsoft.com/en-us/subscriptions} to get +an API key. Make sure you enable Academic Knowledge and. They should +give you two API keys - use either one. You can always pass your API +key as a parameter to functions in \code{microdemic}, but we strongly +encourage you to set an environment variable, named \code{MICROSOFT_ACADEMIC_KEY} + +To set the environment variable for the current R session only, +run \code{Sys.setenv(MICROSOFT_ACADEMIC_KEY = "yourkey")}. Then \code{microdemic} +will pick up this key and you do not have to pass your key as a +parameter to the functions. + +Even better, save your environment variable in the file that R will use +to read in environment variables like \code{MICROSOFT_ACADEMIC_KEY=yourkey}. +This may vary by system and machine. +See \code{?Startup} for details. It's likely your \code{.Renviron} file that +is stored in your home directory. Or could be another environment +variable holding file like \code{.zshrc} or \code{.bash_profile}. After saving the +file, make sure to quit R, source that file like \code{source .Renviron}, +then start R again. Or restart your RStudio session or similar for +other R scenarios. } \section{Rate limits}{