Archive for May, 2014

Foundry bits: @PublicationReference Annotation

May 28th, 2014 Comments off

The Foundry has lots of  interesting bits of code that can be helpful for doing algorithmic work in Java (or more broadly in JVM languages). Lets dig into one such example…

When you are implementing algorithms for research or to build a system, you may often find yourself referring to specific papers, articles, book chapters, web pages, etc. about an algorithm or some aspect of its implementation. Often these references can help provide more background on the algorithm, how it works, or explain some of the notation used in the code. To help document these dependencies and give attribution to where algorithms or implementation approaches come from, we came up with a simple Java annotation, @PublicationReference. This annotation makes it easy to trace from an implementation class back to reference materials that may provide more insight and background.

As an annotation, the @PublicationReference acts similarly to a reference in a paper by referring to some published article. The annotation has the following fields:

  • author (required): The authors of the article. Typically, each author name is a separate String in an array.
  • title (required): The title of the article.
  • type (required): The type of article. For example: Journal, Conference, Book, WebPage, … See PublicationType.
  • year (required): The year of publication.
  • publication: The title of the larger publication for the article. May be a journal, book, conference proceedings, etc.
  • pages: The range of pages for the article.  Typically an array of two values like {10, 15}.
  • url: A URL where the publication can be found. This is not required but strongly recommended to help others find the information.
  • notes: Any other notes regarding the reference.

Here is an example annotation for the Online Passive-Aggressive Perceptron algorithm:

    author={"Koby Crammer", "Ofer Dekel", "Joseph Keshet", 
        "Shai Shalev-Shwartz", "Yoram Singer"},
    title="Online Passive-Aggressive Algorithms",
    publication="Journal of Machine Learning Research",
    pages={551, 585},

As you can see, the reference is similar to a simplified BibTex entry. We most often use the annotation on classes, but it can also be used on methods, fields, or wherever annotations are allowed. We also provide a multiple-value container, the @PublicationReferences annotation, to combine together multiple @PublicationReference annotations. The Foundry also has other reference annotations like  @ModelingApproximation and  @SoftwareReference, though we find the publication reference to be the most useful.

Using the annotations allows for a good amount of information about a reference to be kept in a nice, structured form. This makes it easy to do things like generate a simple bibliography for your code, have references show up in the JavaDoc, or use reflection to create a set of references for a specific algorithm configuration. We have found that having these references is extremely handy when someone asks a question about the code, an algorithm, or it is time to write a paper: the reference, often with the URL, is right there in the code. In this way, the @PublicationReference has helped standardize the way we link code to relevant reference material and we wanted to highlight it with the hope that others may find it useful as well.

Categories: Bits Tags: