CiTO Reference Annotation Tools

The characterization or ‘typing’ of bibliographic citations is the provision of annotations that detail the reason or reasons why the author of the citing paper cites a particular cited paper listed in the citing paper’s reference list.

Such annotation is facilitated by the use of CiTO, the Citations Typing Ontology, that provides a vocabulary of 39 properties, including the basic property cito:cites, to characterise the nature of such citations.  The ontology also contains the inverse properties, that can be used reciprocally to explain why a paper is cited by another.  Further details about CiTO are given in [1].

However, until recently, with the exception of Martin Fenner’s CiTO plugin for WordPress, previously described in this blog post, and Egon Willighagen’s use of CiTO in CiteULike, previously described in this other blog post, no good tools have previously been developed to ease the task of creating such annotations.

Thanks to the creativity of Tanya Gray, that situation has now changed.  Recently, with funding from the JISC Open Citations Extension Project, Tanya has been working with me to build two tools that permit the creation of CiTO-defined annotations of references in article reference lists.  These tools enable the author, or a reader of the article, to provide answers to the question “Why does this article cite that reference?”

The CiTO JavaScript Reference Annotation Tool

The first tool, which works for any modern Web browser, is the CiTO JavaScript Reference Annotation Tool.  This inserts a CiTO Properties choice box after every reference in an article’s reference list, thereby permitting users to choose the CiTO properties that best explain why the Citing Article cites the Cited Article.

Five exemplar journal articles have been enhanced by having the functionality of the CiTO JavaScript Reference Annotation Tool embedded in them, from the following journals/sources:

• PLOS Currents
• eLife
• PubMed Central
• ZooKeys
• Our semantically enhanced version of an article by Reis et al. in PLoS Neglected Tropical Diseases, doi:10.1371/journal.pntd.0000228.x001.

Details of how to view these exemplar articles are given in the documentation file.

Functionality

After each reference in the reference list of each exemplar article, the user will see the following CiTO Annotation Box, presenting the eleven most common CiTO citation annotation properties:

Hovering with the mouse over one of these properties will cause its button to change to a light blue, and will cause a pop-up to appear, displaying the definition of this property drawn from the Citation Typing Ontology, as shown:

Clicking on one of the CiTO property buttons will cause its appearance to change from blue to green, to indicate that it has been selected.  The property definition pop-up will remain visible for as long as the mouse continues to hover over the property, and the green colour will persist after the mouse has been moved away, as shown in the following figure:

The user is free to choose as many CiTO properties for any one reference as apply.

Re-clicking on a green button that has been selected will de-select that property, reverting the button appearance from green to grey (or light blue while still hovering over it).

If none of the eleven displayed CiTO property choices are appropriate, clicking the SHOW OTHER REASONS button will display the other 28 CiTO properties, as shown in the following figure, which can be selected in the same manner.

Clicking HIDE OTHER REASONS will hide these additional options, but will not negate any selections that have been made from among them.

The user may continue making choices for this and other references in the reference list, and may stop making citation annotation activity at any time.

How the citation annotations are saved

If the annotated article is saved with a different filename as an .html file in the same directory as the CiTO-Tools-enabled .html file of the original article, alongside the javascript directory containing the cito.js and cito.css files, these annotations will be saved with the article and will be visible when the annotated article is re-opened in a browser.

Additionally, every time a CiTO property is selected or deselected, that choice is recorded both locally and centrally in our CiTO Tools Annotations Database.

When a user clicks on a CiTO property that was previously unselected, a key-value pair is stored in the browser’s web storage facility, the key being set to a value created by concatenating the browser window’s URI and the unique identifier for the HTML that forms the CiTO property ‘button’ in the web page, and the selection value being set to ‘1’.  Additionally, an AJAX request is sent that inserts a record into our CiTO Tools Annotations Database hosted at http://www.miidi.org with the following fields:

• unique id for database record (auto-increment)
• userid – unique opaque identifier for user
• timestamp – when the action was taken
• action = ‘add’
• subject – URI for the citing journal article
• predicate – URI for the CiTO property
• object – URI for the cited journal article (or citation text parsed from the reference, if URI not available)

The reference in the reference list that is the object of this annotation, and the cited paper that is referenced, are both defined by the last property.

Format

UniqueOpaqueUserID|DateTime|operation|CitingPaper|CiTOProperty|CitedPaper

Record example

|294|KDYXFJ4IM2RIAUBYRYUWPWO37BLNSD|Fri, 04 Jan 2013 17:25:34 GMT|add|<http://dx.doi.org/10.1093/nar/gkp850>|<http://purl.org/spar/cito/obtainsBackgroundFrom>|<http://dx.doi.org/10.1128/IAI.00105-07>

The last three items in each record are easily transformed into an RDF triple (in Turtle format):

<http://dx.doi.org/10.1093/nar/gkp850> ;
     <http://purl.org/spar/cito/obtainsBackgroundFrom> ;
     <http://dx.doi.org/10.1128/IAI.00105-07> .

When a user clicks on a CiTO property that was previously selected, in order to de-select it, exactly the same things happen, except that the local selection value is set to “0” and the database action is set to “remove”

Obtaining the CiTO annotation data

The CiTO Tools Annotations Database accumulates and stores all the CiTO annotation choices made by all users of this JavaScript Reference Annotation Tool and also of the CiTO Chrome Extension described below, for all annotated papers.  These data are openly available, and can be obtained by visiting http://www.miidi.org/metaquery/cito and downloading the text file called cito containing the accumulated annotation records in the format given above.

Using the CiTO annotation data

It is anticipated that aggregation of citation annotations in this way may open the way to crowd-sourcing of CiTO citation typing, although it is recognized that the only person who can authoritatively say why a reference has been cited is the author who created it.  For this reason, provenance of these CiTO annotations will be crucial.  Ideally the ability for authors to annotate reference lists at the time of creating the article will become a feature of on-line authoring tools such as PLoS Currents and the Pensoft Writing Tool.

Implementing this functionality as part of normal article publication

To achieve the CiTO JavaScript Reference Annotation Tool functionality for journal articles as part of the normal publishing pipeline, three lines of JavaScript code needs to be inserted into each article before it is published, and the appropriate cito.js and cito.css files need to be present in a javascript directory alongside the directory containing the .html file for the article, as explained in the documentation.

Adaption of this CiTO JavaScript Annotation Tool for articles in other journals that use a different DTD, or that use a different method of mapping the NLM-DTD v3.0 to HTML than that used by PubMed Central, requires the addition of two new functions to the cito.js file, one to identify the HTML for the reference list, and another to extract a DOI, a URI or a textual bibliographic citation for the reference, that would then be used as the object of the bibliographic citation. The code is not complicated, but its modification requires someone with an understanding of JavaScript.

Since all our code is available under an open license from our GitHub Repository, this puts the implementation of such citation typing functionality within the grasp of every publisher that wishes to implement it.

The CiTO Chrome Extension

The second CiTO Tool, closely related in functionality to the first, is the CiTO Chrome Extension, that inserts additional code after each reference in HTML-format articles from PubMed Central, eLife and PLoS Currents without the need to modify each article individually.

This extension works only for the Chrome Browser, and is available free from the Chrome WebStore here.  The software for this Chrome extension is also stored in the chrome-extension folder of the CiTO GitHub Repository.

The following figure shows a screen shot of the tool as it appears in the Chrome WebStore.  The included image shows the user functionality, resembling that of the JavaScript examples shown above.

We welcome the involvement of developers in the community who would be interested working with our code to create and maintain similar extensions / add-ons / plug-ins for other browsers.

Reference

[1]  Peroni S and Shotton D (2012). FaBiO and CiTO: ontologies for describing bibliographic resources and citations. Web Semantics: Science, Services and Agents on the World Wide Web. 17: 33-34. doi:10.1016/j.websem.2012.08.001.

Advertisement