hypothesisr

NEWS code{white-space: pre-wrap;} span.smallcaps{font-variant: small-caps;} span.underline{text-decoration: underline;} div.column{display: inline-block; vertical-align: top; width: 50%;} div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;} ul.task-list{list-style: none;} hypothesisr 0.1.1 Minor bux fix to repair a failing test that expected different result column names than it should have. hypothesisr 0.1.0 First CRAN release

README code{white-space: pre-wrap;} span.smallcaps{font-variant: small-caps;} span.underline{text-decoration: underline;} div.column{display: inline-block; vertical-align: top; width: 50%;} div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;} ul.task-list{list-style: none;} pre > code.sourceCode { white-space: pre; position: relative; } pre > code.sourceCode > span { display: inline-block; line-height: 1.25; } pre > code.sourceCode > span:empty { height: 1.2em; } .sourceCode { overflow: visible; } code.sourceCode > span { color: inherit; text-decoration: inherit; } div.sourceCode { margin: 1em 0; } pre.sourceCode { margin: 0; } @media screen { div.sourceCode { overflow: auto; } } @media print { pre > code.sourceCode { white-space: pre-wrap; } pre > code.sourceCode > span { text-indent: -5em; padding-left: 5em; } } pre.numberSource code { counter-reset: source-line 0; } pre.numberSource code > span { position: relative; left: -4em; counter-increment: source-line; } pre.numberSource code > span > a:first-child::before { content: counter(source-line); position: relative; left: -1em; text-align: right; vertical-align: baseline; border: none; display: inline-block; -webkit-touch-callout: none; -webkit-user-select: none; -khtml-user-select: none; -moz-user-select: none; -ms-user-select: none; user-select: none; padding: 0 4px; width: 4em; color: #aaaaaa; } pre.numberSource { margin-left: 3em; border-left: 1px solid #aaaaaa; padding-left: 4px; } div.sourceCode { } @media screen { pre > code.sourceCode > span > a:first-child::before { text-decoration: underline; } } code span.al { color: #ff0000; font-weight: bold; } /* Alert */ code span.an { color: #60a0b0; font-weight: bold; font-style: italic; } /* Annotation */ code span.at { color: #7d9029; } /* Attribute */ code span.bn { color: #40a070; } /* BaseN */ code span.bu { color: #008000; } /* BuiltIn */ code span.cf { color: #007020; font-weight: bold; } /* ControlFlow */ code span.ch { color: #4070a0; } /* Char */ code span.cn { color: #880000; } /* Constant */ code span.co { color: #60a0b0; font-style: italic; } /* Comment */ code span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } /* CommentVar */ code span.do { color: #ba2121; font-style: italic; } /* Documentation */ code span.dt { color: #902000; } /* DataType */ code span.dv { color: #40a070; } /* DecVal */ code span.er { color: #ff0000; font-weight: bold; } /* Error */ code span.ex { } /* Extension */ code span.fl { color: #40a070; } /* Float */ code span.fu { color: #06287e; } /* Function */ code span.im { color: #008000; font-weight: bold; } /* Import */ code span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Information */ code span.kw { color: #007020; font-weight: bold; } /* Keyword */ code span.op { color: #666666; } /* Operator */ code span.ot { color: #007020; } /* Other */ code span.pp { color: #bc7a00; } /* Preprocessor */ code span.sc { color: #4070a0; } /* SpecialChar */ code span.ss { color: #bb6688; } /* SpecialString */ code span.st { color: #4070a0; } /* String */ code span.va { color: #19177c; } /* Variable */ code span.vs { color: #4070a0; } /* VerbatimString */ code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warning */ hypothesisr Interact with the API for hypothes.is , the web annotation service. Allows users to add, search for, and retrieve annotation data. Installation # install.packages("devtools") devtools :: install_github ( "mdlincoln/hypothesisr" ) Usage Search and retrieve annotations library (hypothesisr) ulysses_annotations <- hs_search ( text = "ulysses" ) dim (ulysses_annotations) #> [1] 6 28 names (ulysses_annotations) #> [1] "updated" "group" #> [3] "target" "tags" #> [5] "text" "created" #> [7] "uri" "user" #> [9] "id" "references" #> [11] "links.json" "links.html" #> [13] "links.incontext" "document.link" #> [15] "document.title" "document.favicon" #> [17] "document.twitter.url" "document.twitter.site" #> [19] "document.twitter.card" "document.twitter.title" #> [21] "document.facebook.url" "document.facebook.site_name" #> [23] "document.facebook.type" "document.facebook.title" #> [25] "permissions.read" "permissions.admin" #> [27] "permissions.update" "permissions.delete" ulysses_annotations $ text #> [1] "Pope adds in a footnote: \"Minerva in like manner, during the Battle of Ulysses with the Suitors in Odyss. perches on a beam of the roof to behold it.\"\n\nSource: \n\nPope, Alexander, and Adolphus William Ward. The Poetical Works of Alexander Pope. London: Macmillan, 1907. Print." #> [2] "Reminds me also of the \"Bloomsday\" tradition of reading (gulp) Joyce's *Ulysses* aloud on the calendar day associated with the fictional events of the novel." #> [3] "I wonder if the paperback of *Ulysses* I spilled a Venti iced coffee on in 2009 will make it into one of these displays some day. Probably not, but a girl can dream, right?" #> [4] "Using s sneak attack on Gen, Ulysses S. Grant on the Tennessee river ending in 13,000 people killed and injured on the union, and 10,000 confederates. Knowing that the Union can not take many more loses like this, and something new had to be done. " #> [5] "And Ulysses may be the ideal text to annotate and collaborate with, as Joyce's work itself " #> [6] "What better novel to annotate than Ulysses, a novel full of jokes, references, and puzzles? " You can specify any of the available annotation data fields with a named list using the custom parameter. For example, to find all the annotations on a domain, query the uri.parts field (but don’t include .com , .org , .edu and the like; this currently results in the API returning annotations sharing any of those TLDs.) ph <- hs_search_all ( custom = list ( uri.parts = "programminghistorian" )) library (dplyr) # Display the top 5 most-annotated pages under this domain slice ( count (ph, uri, sort = TRUE ), 1 : 5 ) uri n http://programminghistorian.org/lessons/getting-started-with-markdown 6 http://programminghistorian.org/lessons/graph-databases-and-SPARQL 6 http://programminghistorian.org/lessons/intro-to-the-zotero-api 6 http://programminghistorian.github.io/ph-submissions/lessons/building-static-sites-with-jekyll-github-pages 5 http://programminghistorian.org/lessons/creating-new-items-in-zotero 5 hs_search() will retrieve one page of annotations (up to 200 annotations per page), while hs_search_all() will page through all available annotations until they are all downloaded. Note: running hs_search_all() with no parameters will download all publicly accessible hypothes.is annotations. Create, read, update, and delete annotations To create and delete annotations, you will need to register for an API token at https://hypothes.is/register . At the moment, hpothesisr cannot create annotations targeted to a particular section of a webpage, such as a highlighted line. These annotations will be visible at the page-level. user_token <- "xxxx-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" hs_create ( token = user_token, uri = "https://github.com/mdlincoln/hypothesisr" , user = "acct:mdlincoln@hypothes.is" , tags = c ( "testing" , "R" ), text = "R made me!" ) #> [1] "WFMnSC3FEeaNvLeGkQeJbg" You may also retrieve the data describing individual annotations by id: a <- hs_read ( "WFMnSC3FEeaNvLeGkQeJbg" ) a $ uri #> [1] "https://github.com/mdlincoln/hypothesisr" a $ text #> [1] "R made me!" a $ user #> [1] "acct:mdlincoln@hypothes.is" You can update individual fields of annotations by passing your token, the annotation ID, and one or more fields with replacement values. hs_update (user_token, "WFMnSC3FEeaNvLeGkQeJbg" , text = "Now even more annotate-y!" ) hs_read ( "WFMnSC3FEeaNvLeGkQeJbg" ) $ text #> [1] "Now even more annotate-y!" You can also delete annotations (at least, those for which you have the permissions to delete): hs_delete (user_token, "lDf9rC3EEea6ck-G5kLdXA" ) #> [1] TRUE Other utilities Easily reply to an annotation with hs_reply() , which sends useful defaults to hs_creat

Help for package hypothesisr const macros = { "\\R": "\\textsf{R}", "\\mbox": "\\text", "\\code": "\\texttt"}; function processMathHTML() { var l = document.getElementsByClassName('reqn'); for (let e of l) { katex.render(e.textContent, e, { throwOnError: false, macros }); } return; } Package {hypothesisr} Contents hypothesisr hs_create hs_delete hs_read hs_reply hs_search hs_search_all hs_update open_ Type: Package Title: Wrapper for the 'Hypothes.is' Web Annotation Service Version: 0.1.1 Description: Interact with the application programming interface for the web annotation service 'Hypothes.is' (See http://hypothes.is for more information.) Allows users to download data about public annotations, and create, retrieve, update, and delete their own annotations. Imports: dplyr, httr, jsonlite License: MIT + file LICENSE LazyData: TRUE RoxygenNote: 5.0.1 Suggests: testthat URL: https://github.com/mdlincoln/hypothesisr BugReports: https://github.com/mdlincoln/hypothesisr/issues NeedsCompilation: no Packaged: 2016-07-01 14:07:42 UTC; admin Author: Matthew Lincoln [aut, cre] Maintainer: Matthew Lincoln <matthew.d.lincoln@gmail.com> Repository: CRAN Date/Publication: 2016-07-01 16:33:31 hypothesisr: Wrapper for the Hypothes.is API Description Interact with the API for the web annotation service hypothes.is. Allows users to add, search for, and retrieve annotation data. Create annotations Description Create annotations Usage hs_create(token, uri, user, permissions = list(read = "group:__world__", update = user, delete = user, admin = user), document = NULL, target = NULL, tags = NULL, text, custom = NULL) Arguments token Character. Your account token, which you can generate at https://hypothes.is/register uri Character. The URI to be annotated. user Character. Your user account, normally in the format acct:username@hypothes.is permissions A named list with read, update, delete, and admin permissions. Defaults to setting global read permissions ( group:__world__ ) and setting the user string for update, delete, and admin permissions. document A list describing the document. CURRENTLY IGNORED. target A list describing the highlight position of the annotation. CURRENTLY IGNORED tags Character. (optional) Tags to apply to the annotation. text Character. Text to put in the body of the annotation. This will be coerced into a character vector of length 1 using paste . custom Add arbitrary fields to the JSON object submitted to hypothes.is by means of a named list. Value Upon successful creation, returns a 22-character annotation ID. This ID may be retrieved using hs_read . Source https://h.readthedocs.io/en/latest/api/#create Examples ## Not run: hs_create(token = user_token, uri = "https://github.com/mdlincoln/hypothesisr", user = "acct:mdlincoln@hypothes.is", tags = c("testing", "R"), text = "R made me!") ## End(Not run) Delete an annotation Description Delete an annotation Usage hs_delete(token, id) Arguments token Character. Your account token, which you can generate at https://hypothes.is/register id Character. A hypothes.is annotation id. Value TRUE on successful deletion. Source https://h.readthedocs.io/en/latest/api/#delete Retrieve a single annotation by ID Description Retrieve a single annotation by ID Usage hs_read(id) Arguments id Character. A hypothes.is annotation id. Value A dataframe with the contents of that annotation. Source https://h.readthedocs.io/en/latest/api/#read Examples hs_read("WFMnSC3FEeaNvLeGkQeJbg") Create a reply to a comment Description This is a utility wrapper around hs_create that takes an original comment ID and creates a reply to it by adding the custom references field when constructing the annotation. Normal fields like Usage hs_reply(token, user, id, text, ...) Arguments token Character. Your account token, which you can generate at https://hypothes.is/register user Character. Your user account, normally in the format acct:username@hypothes.is id Character. The annotation ID to reply to. text Character. Text to put in the body of the annotation. This will be coerced into a character vector of length 1 using paste . ... Other arguments to pass to hs_create . Search hypothes.is annotations Description Search hypothes.is annotations. Usage hs_search(limit = NULL, offset = NULL, sort = "updated", order = "asc", uri = NULL, user = NULL, text = NULL, any = NULL, custom = list()) Arguments limit Integer. The maximum number of annotations to return. (Default: 20) offset Integer The minimum number of initial annotations to skip. This is used for pagination. For example if there are 65 annotations matching our search query and we're retrieving up to 30 annotations at a time, then to retrieve the last 5, set offset = 5. (Default = 0) sort Character. Specify which field the annotations should be sorted by: consumer , created , id , text , updated , uri , user . order Character. Specify which order annotations should be sorted by: asc or desc . uri Character. Search for annotations of a particular URI, for example www.example.com . URI searches will also find annotations of equivalent URIs. For example if the HTML document at http://www.example.com/document.html? includes a <link rel="canonical" href="http://www.example.com/canonical_document.html"> then annotations of http://www.example.com/canonical_document.html will also be included in the search results. Other forms of document equivalence that are supported include rel="alternate" links, DOIs, PDF file IDs, and more. user Character. Search for annotations by a particular user. For example, tim will find all annotations by users named tim at any provider, while tim@hypothes.is will only find annotations by tim on hypothes.is text Character. Search for annotations whose body text contains some text, for example: foobar . any Character. Search for annotations whose quote , tags , text , uri.parts or user fields match some query text. custom A named list of any field in the results returned by hypothes.is as a name, and the search text as values. Value A dataframe with annotation data. Note If any vectors are passed to these arguments, only the first values will be used. Source https://h.readthedocs.io/en/latest/api/#search Examples # Search for no more than 5 annotations containing the text "ulysses" hs_search(text = "ulysses", limit = 5) # Search with a custom field for tags hs_search(custom = list(tags = "todo")) # use the 'uri.parts' field to find annotations on a given domain (exclude # the TLD, as this will result in all annotations on sites with, e.g., .org, # as well.) hs_search(custom = list(uri.parts = "programminghistorian")) Retreive all annotation search results as a data frame Description Takes the same arguments as hs_search and pages through all available results, formatting the output as a data.frame. Usage hs_search_all(sort = "updated", order = "asc", uri = NULL, user = NULL, text = NULL, any = NULL, custom = list(), pagesize = 200, progress = interactive()) Arguments sort Character. Specify which field the annotations should be sorted by: consumer , created , id , text , updated , uri , user . order Character. Specify which order annotations should be sorted by: asc or desc . uri Character. Search for annotations of a particular URI, for example www.example.com . URI searches will also find annotations of equivalent URIs. For example if the HTML document at http://www.example.com/document.html? includes a <link rel="canonical" href="http://www.example.com/canonical_document.html"> then annotations of http://www.example.com/canonical_document.html will also be included in the search results. Other forms of document equivalence that are supported include rel="alternate" links, DOIs, PDF file IDs, and more. user Character. Search for annotations by a particular user. For example, tim will find all annotations by users named tim at any provider, while tim@hypothes.is will only find annotations by tim on hypothes.is text Character. Search for annotations whose body tex