rdflib

[cboettig]

Summary

• What does this package do? (explain in 50 words or less):

rdflib is simply a wrapper around two existing ropensci packages: redland and jsonld, which should be a user-friendly complement to the low-level interface already provided by redland for working with RDF (semantic/linked data).

• Paste the full DESCRIPTION file inside a code block below:

Package: rdflib
Title: Tools to Manipulate and Query Semantic Data
Version: 0.0.2
Authors@R: person("Carl", "Boettiger", 
                  email = "cboettig@gmail.com", 
                  role = c("aut", "cre", "cph"),
                  comment=c(ORCID = "http://orcid.org/0000-0002-1642-628X"))
Description: The Resource Description Framework, or 'RDF' is a widely used
             data representation model that forms the cornerstone of the 
             Semantic Web. 'RDF' represents data as a graph rather than 
             the familiar data table or rectangle of relational databases.
             The 'rdflib' package provides a friendly and concise user interface
             for performing common tasks on 'RDF' data, such as reading, writing
             and converting between the various serializations of 'RDF' data,
             including 'rdfxml', 'turtle', 'nquads', 'ntriples', 'trig', and 'json-ld';
             creating new 'RDF' graphs, and performing graph queries using 'SPARQL'.
             This package wraps the low level 'redland' R package which
             provides direct bindings to the 'redland' C library.  Additionally,
             the package supports the newer and more developer friendly
             'JSON-LD' format through the 'jsonld' package. The package
             interface takes inspiration from the Python 'rdflib' library.
Depends: R (>= 3.4.1)
License: MIT + file LICENSE
Encoding: UTF-8
LazyData: true
URL: https://github.com/cboettig/rdflib
BugReports: https://github.com/cboettig/rdflib/issues
Imports: redland,
    jsonld,
    methods,
    utils
RoxygenNote: 6.0.1
Suggests: magrittr,
    covr,
    testthat,
    knitr,
    rmarkdown,
    jsonlite,
    httr,
    xml2,
    jqr,
    readr,
    dplyr,
    lubridate,
    DT
VignetteBuilder: knitr

• URL for the package (the development repository, not a stylized html page):

https://github.com/cboettig/rdflib

• Please indicate which category or categories from our package fit policies this package falls under *and why(? (e.g., data retrieval, reproducibility. If you are unsure, we suggest you make a pre-submission inquiry.):

data extraction, because this package parses scientific data file formats. (specifically, formats already parsed by existing rOpenSci packages). This package also enables graph queries using the SPARQL language, somewhat analogous to the rOpenSci jqr package, but for JSON-LD and other linked data formats.

•   Who is the target audience and what are scientific applications of this package?  

Anyone working with semantic data, including the wide array of scientific ontologies and knowledge-bases. These include reproducibility-focused ontologies like PROV, and a large number of biological ontologies ranging from genes to traits to environmental features.

• Are there other R packages that accomplish the same thing? If so, how does
  yours differ or meet our criteria for best-in-category?

As described above, this package overlaps significantly with the redland package, but should be easier to use.

•   If you made a pre-submission enquiry, please paste the link to the corresponding issue, forum post, or other discussion, or @tag the editor you contacted.

Requirements

Confirm each of the following by checking the box. This package:

• does not violate the Terms of Service of any service it interacts with.
• has a CRAN and OSI accepted license.
• contains a README with instructions for installing the development version.
• includes documentation with examples for all functions.
• contains a vignette with examples of its essential functions and uses.
• has a test suite.
• has continuous integration, including reporting of test coverage, using services such as Travis CI, Coeveralls and/or CodeCov.
• I agree to abide by ROpenSci's Code of Conduct during the review process and in maintaining my package should it be accepted.

Publication options

• Do you intend for this package to go on CRAN?
• Do you wish to automatically submit to the Journal of Open Source Software? If so:
  • The package has an obvious research application according to JOSS's definition.
  • The package contains a paper.md matching JOSS's requirements with a high-level description in the package root or in inst/.
  • The package is deposited in a long-term repository with the DOI: https://doi.org/10.5281/zenodo.1098478
  • (Do not submit your package separately to JOSS)
• Do you wish to submit an Applications Article about your package to Methods in Ecology and Evolution? If so:
  • The package is novel and will be of interest to the broad readership of the journal.
  • The manuscript describing the package is no longer than 3000 words.
  • You intend to archive the code for the package in a long-term repository which meets the requirements of the journal.
  • (Please do not submit your package separately to Methods in Ecology and Evolution)

Detail

• Does R CMD check (or devtools::check()) succeed? Paste and describe any errors or warnings:

• Does the package conform to rOpenSci packaging guidelines? Please describe any exceptions:

• If this is a resubmission following rejection, please explain the change in circumstances:

• If possible, please provide recommendations of reviewers - those with experience with similar packages and/or likely users of your package - and their GitHub user names:

• Scott Chamberlain, @sckott
• Peter Slaughter, @gothub
• Bryce Mecum, @amoeba
• Anna Krystalli, @annakrystalli

[karthik]

👋 @cboettig
Thanks for the submission. Since it would be a COI for any of the four editors to handle your submission, I have asked @lmullen to serve as the ad hoc editor on this one and he has graciously agreed. I will let Lincoln take it from here. 🚀

[lmullen]

Editor checks:

• Fit: The package meets criteria for fit and overlap
• Automated tests: Package has a testing suite and is tested via Travis-CI or another CI service.
• License: The package has a CRAN or OSI accepted license
• Repository: The repository link resolves correctly
• Archive (JOSS only, may be post-review): The repository DOI resolves correctly
• Version (JOSS only, may be post-review): Does the release version given match the GitHub release (v1.0.0)?

---

Editor comments

Passes devtools::check() without issue.

R CMD check results
0 errors | 0 warnings | 0 notes

Here is the result of goodpractice::gp().

It is good practice to

  ✖ write unit tests for all functions, and all
    package code in general. 97% of code lines are covered by
    test cases.

    R/rdf.R:274:NA
    R/rdf.R:275:NA

  ✖ not import packages as a whole, as this can cause
    name clashes between the imported packages. Instead, import
    only the specific functions you need.

97% coverage is excellent.

The advice not to import entire packages is up to the discretion of the reviewers.

Note one misspelling (occured) from devtools::spell_check().

@karthik I am now approaching reviewers.

---

Reviewers:
Due date:

[lmullen]

Two reviewers have agreed to review this package. Reviewers, thanks for being willing, and I'll ask you to have your reviews in within three weeks. Here is the reviewer's guide. Feel free to let me know if you have any questions.

Reviewer: Anna Krystalli, @annakrystalli
Reviewer: Bryce Mecum, @amoeba
Due date: 2018-01-25

@cboettig Could you please add the rOpenSci under review badge to the README for this package? Here is the snippet.

[![](https://badges.ropensci.org/169_status.svg)](https://github.com/ropensci/onboarding/issues/169)

[amoeba]

Package Review

• As the reviewer I confirm that there are no conflicts of interest for me to review this work (If you are unsure whether you are in conflict, please speak to your editor before starting your review).

Documentation

The package includes all the following forms of documentation:

• A statement of need clearly stating problems the software is designed to solve and its target audience in README
• Installation instructions: for the development version of package and any non-standard dependencies in README
• Vignette(s) demonstrating major functionality that runs successfully locally
• Function Documentation: for all exported functions in R help
• Examples for all exported functions in R Help that run successfully locally
• Community guidelines including contribution guidelines in the README or CONTRIBUTING, and DESCRIPTION with URL, BugReports and Maintainer (which may be autogenerated via Authors@R).

For packages co-submitting to JOSS

• The package has an obvious research application according to JOSS's definition

The package contains a paper.md matching JOSS's requirements with:

• A short summary describing the high-level functionality of the software
• Authors: A list of authors with their affiliations
• A statement of need clearly stating problems the software is designed to solve and its target audience.
• References: with DOIs for all those that have one (e.g. papers, datasets, software).

Functionality

• Installation: Installation succeeds as documented.
• Functionality: Any functional claims of the software been confirmed.
• Performance: Any performance claims of the software been confirmed.
• Automated tests: Unit tests cover essential functions of the package
  and a reasonable range of inputs and conditions. All tests pass on the local machine.
• Packaging guidelines: The package conforms to the rOpenSci packaging guidelines

Final approval (post-review)

• The author has responded to my review and made changes to my satisfaction. I recommend approving this package.

Estimated hours spent reviewing: 2

---

Review Comments

This looks like an excellent package for inclusion in the ropensci ecosystem. I have personal experience with the problem this package is trying to solve, namely working with RDF in R from the analysts perspective. The RDF package this package wraps, redland, is intended more for developers to write packages on top of than for end users to do things like run SPARQL queries or manipulate RDF graphs. I would use this package.

The package is laid out in a non-surprising manner, most functions are short and well-scoped, and, overall, the code is very readable. The accompanying test suite is reasonable and provides 100% coverage, and the single vignette is well-written and useful.

I did find the documentation could use some polish in some places (see comments below). I suspect a pass or two by the author would make some good improvements without much work.

I have left two checkboxes unchecked due to the following issues:

• Community guidelines are missing in README.md
• README.md missing citation section recommended by packaging guide
• NEWS.md file doesn't quite conform to packaging guide

but I otherwise found everything else to be in order.

Higher level

• How are you dealing with differentiating between resource, literal, and blank nodes in rdf_add? As far as I can see, it looks I can't create a new triple with a resource or blank node as the subject:

  > rdf_add(x, "test", "test", "test")
  > x
  <test> <test> "test" .

• I'd like to see more usage of the RDF capabilities of rdflib in the vignette. At current it's centered around JSON-LD

Lower level

These were written out as I went through the checklist:

• Documentation could benefit from a general pass for capitalization just to make things look nicer

• \link{}s in docs for rdf_serialize and rdf_query link to wrong version of the parse function

• Noticed funky encoding issues from vita.json.
  "Fernández" => "Fern\u00E1ndez"
  Not sure if this is an rdflib problem or a redland one.

• I think any mentions of "RDF+XML" outside of MIME types should be "RDF/XML", not "RDF+XML"

• I thought arg doc in rdf_serialize could be path instead as it's a little more clear.

• I'm generally not a fan of arguments named x, though it feels warranted in some cases. Could a more descriptive name be used in these instances? For example, rdf_query has a first arg of x which could, instead, be rdf.

• Perhaps a little more error checking...
  If I send a malformed query, I get useful but a bit cryptic response from rdf_query:

  > coi <- vita %>% rdf_query(sparql)
  librdf error  - syntax error, unexpected a
  rdf_query_results.c:100: (librdf_query_results_finished) assertion failed: object pointer of type librdf_query_results is NULL.
  rdf_query_results.c:100: (librdf_query_results_finished) assertion failed: object pointer of type librdf_query_results is NULL.

  This is caused by failing to cath an error to the call to redland::executeQuery.

  queryResult <- redland::executeQuery(queryObj, x$model)

• browseVignettes(package = "rdflib") doesn't return any vignettes. I'm not that familiar with this functionality so I didn't debug it.

• Noticed the test "we can parse from a url" calls out to the web but the skip_on_cran() guard is commented out. Should it not be commented out?

• Found documentation for rdf() to be too terse and terse by comparison to other functions in the package

• rdf_parse() mentions the return is an 'rdf S3 object'. I might just call it an 'object' and omit the class system it was defined in

• Verbage in rdf_serialize 'Serialize RDF docs' maybe should be 'Serialize an RDF Documnet' (no plural)

• In rdf_serialize, I wonder if the return should not be the raw numeric return code from redland but either a logical or the document path itself (the latter would allow for piping)

• rdf_query states the return type is 'a list of all query results' when it actually appears to be a 'data.frame' from what I can tell

• What the common argument 'x' is documented as across functions varies. "rdf graph object" "rdf object". Please use common language for these

• RE: JOSS submission: I wonder if they won't find this package to simple/thin for acceptance. It does have clear research application though!

[lmullen]

Thanks for getting your review in, @amoeba.