bib2df

[ottlngr]

Summary

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

Provides functionality to parse BibTeX files to data.frame which can be used for analyses and visualizations using common tools like dplyr, tidyr and ggplot2. Changes in the data.frame can be written back to a valid BibTeX file.

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

Package: bib2df
Type: Package
Title: Parse a BibTeX File to a data.frame
Version: 0.2
Date: 2017-05-21
Authors@R: c(person("Philipp", "Ottolinger", email = "philipp@ottolinger.de", role = c("aut", "cre")),
             person("Thomas", "Leeper", email = "thosjleeper@gmail.com", role = "ctb"),
             person("Maëlle", "Salmon", email = "maelle.salmon@yahoo.se", role = "ctb"))
Description: Parse a BibTeX file to a data.frame to make it accessible for further analysis and visualization.
URL: https://github.com/ottlngr/bib2df
BugReports: http://github.com/ottlngr/bib2df/issues
License: GPL-3
LazyData: TRUE
Imports:
    dplyr,
    plyr,
    stringr,
    humaniformat
Suggests:
    testthat,
    knitr,
    rmarkdown,
    ggplot2,
    tidyr
RoxygenNote: 6.0.1
VignetteBuilder: knitr

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

https://github.com/ottlngr/bib2df

• 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 bib2df makes entries of a BibTeX file accessible in the most common data structure, the data.frame.

• Who is the target audience?

Anyone who wants to gain insights in the characteristics and coherences of bibliographic references.

• Are there other R packages that accomplish the same thing? If so, what is different about yours?

There are a few packages that can deal with BibTeX in general, like RefManageR#119 and others mentioned there. These packages are very close to the actual purpose of BibTeX, providing special classes and can be used as reference managing software. bib2df is not for managing references, but for extracting the data to a common data structure. To my knowledge, only bib2df offers parsing to data.frame.

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? It already is on CRAN.
• Do you wish to automatically submit to the Journal of Open Source Software? If so:
  • The package contains a paper.md with a high-level description in the package root or in inst/.
  • The package is deposited in a long-term repository with the DOI:
  • (Do not submit your package separately to JOSS)

Detail

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

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

• 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:

[sckott]

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

Thanks for your submission @ottlngr !

Currently seeking reviewers. It's a good fit and not overlapping.

• goodpractice::gp() output is below. Some things for submitter and reviewers to consider.

It is good practice to

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

    R/bib2df_gather.R:20:NA
    R/bib2df_tidy.R:23:NA
    R/bib2df_tidy.R:30:NA
    R/df2bib.R:20:NA
    R/df2bib.R:21:NA
    ... and 3 more lines

  ✖ omit "Date" in DESCRIPTION. It is not required and it gets invalid quite
    often. A build date will be added to the package when you perform `R CMD build` on it.
  ✖ avoid long code lines, it is bad for readability. Also, many people prefer
    editor windows that are about 80 characters wide. Try make your lines shorter than 80
    characters

    inst/legacy/bib2df_explore.R:2:1
    inst/legacy/bib2df_explore.R:3:1
    inst/legacy/bib2df_scrape_l.R:34:1
    inst/legacy/bib2df_scrape_l.R:39:1
    R/bib2df_gather.R:23:1
    ... and 8 more lines

  ✖ avoid sapply(), it is not type safe. It might return a vector, or a list,
    depending on the input data. Consider using vapply() instead.

    inst/legacy/bib2df_gather2_l.R:2:12
    inst/legacy/bib2df_scrape_l.R:6:9
    inst/legacy/bib2df_scrape_l.R:37:40

  ✖ not import packages as a whole, as this can cause name clashes between the
    imported packages. Instead, import only the specific functions you need.
  ✖ avoid 'T' and 'F', as they are just variables which are set to the logicals
    'TRUE' and 'FALSE' by default, but are not reserved words and hence can be overwritten
    by the user.  Hence, one should always use 'TRUE' and 'FALSE' for the logicals.

    R/bib2df_gather.R:NA:NA
    R/bib2df_tidy.R:NA:NA
    R/bib2df_tidy.R:NA:NA

---

Reviewers: @vasantm @adamhsparks
Due date: 2017-07-03

[ottlngr]

Updated the package regarding to the gp() output. This is what remains:

It is good practice to

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

    R/bib2df_gather.R:20:NA
    R/bib2df_tidy.R:25:NA
    R/bib2df_tidy.R:26:NA
    R/bib2df_tidy.R:27:NA
    R/bib2df_tidy.R:28:NA
    ... and 18 more lines

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

[sckott]

thanks @ottlngr , one reviewer found, one more to go

[adamhsparks]

I've completed my review of bib2df, here are my comments and suggestions.

Package Review

Please check off boxes as applicable, and elaborate in comments below. Your review is not limited to these topics, as described in the reviewer guide

• 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 URL, Maintainer and BugReports fields in DESCRIPTION

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:

Total time to review was about 3.5 hours.

---

Review Comments

bib2df offers functionality for working with LaTeX .bib files in R as a data.frame object. This functionality is well appreciated and will serve many people well. I'm actually using it at the moment in a paper that I'm writing on reproducibility in plant pathology, https://github.com/phytopathology/Reproducible.Plant.Pathology. The package installs quickly with no issues from CRAN or from source building the package in RStudio. The vignette and README offer good examples of how it may be used, but the package itself doesn't attempt to do more than convert a .bib file to a data.frame() object. I appreciate that @ottlngr has created something that is simple and does one job and does it well.

General Comments

• Passes checks with no NOTES or WARNINGS on macOS Sierra, R 3.4.0

• Line widths are more than 80 chars in several of the .R files, using "CMD+^+A"
  will reformat the code in RStudio and wrap long lines. However, some may need to be manually shortened.

• Please check spelling using devtools::spell_check

• Please check spelling in vignette as well. RStudio offers built-in spell-check for Rmd files, .

• Commas should always have a space after, check using lintr::lint_package()

• Variables and function names should all be lowercase, e.g., df2bib.R line 19

• The details portion of bib2df() documentation includes,

Uses the internal bib2df_read(), bib2df_gather() and bib2df_tidy(). No magic, just a wrapper.

I'm not sure that this is necessary to include for the end users, but since you have documented these internal functions you can link to the help file for them. I would suggest not including this information here.

• Following on to the previous point, I'd suggest not exposing these functions outside the package namespace and not documenting them. If I understand correctly, bib2df_read(), bib2df_gather() and bib2df_tidy() are all internal functions that the end-user is unlikely to interact directly with. As the package is written now, I don't see how or why a user would, so I suggest not documenting in the help files and not exporting them.

Functions

• Using bib2df without specifying separate_names = results in a warning message. This should not happen, especially as bib2df(path) is the example and triggers this behaviour. I'd default to FALSE with the option to set to TRUE, but this really is your choice how you think it should be handled by default.

• Likewise, bib2df_tidy() exhibits the same behaviour and should not return values with a WARNING message.

• Using bib2df_tidy() with separate_names set to TRUE or FALSE results in an error message, e.g.,

  bib <- bib2df_tidy(bib, separate_names = FALSE)
  Show Traceback
  
  Rerun with Debug
  Error in mutate_impl(.data, dots) :
  Evaluation error: non-character argument.

  However, as noted, I'm not sure that this function should be exported and exposed to the user?

Documentation

• The bib2df-package help file could use some more formatting. You could use \code{\link{dplyr}} and the like for the other packages used. data.frame is not wrapped in a \code{} tag here either.

• The title field in .Rd files should not end in a period, the following files do and should be corrected,

  • bib2df.R

  • bib2df_gather.R

  • bib2df_tidy.R

  • bib2df_read.R

  • df2bib.R

• I'd change the documentation to say that this package returns a tibble, not a data.frame.

Vignette

• The vignette is not indexed so when searching for it, vignette(bib2df), the result is,

  Warning message:
  vignette ‘bib2df’ not found

• Please make sure that the %\VignetteIndexEntry{} is updated, e.g., %\VignetteIndexEntry{bib2df}

• Why is it advised to download a bib file? Why not read from a URL? Some more detail in the vignette about this would be welcome. Minor point, but is a shorter URL for the example bib file possible?

• A link to the humaniformat package would be nice.

NEWS.md

• Formatting of functions and R objects is inconsistent. Some use the code tags,
  others don't.

Packages Used

• plyr is no longer actively developed, and since dplyr is already imported and has bind_rows I'd suggest using this function. This also reduces dependencies by one package.

Tests

• Tests run successfully on macOS Sierra, R 3.4.0

• Tests cover 87% bib2df_tidy.R and df2bib.R have the least coverage according to covr.io, if tests could be written to cover these more completely it would be nice.

[sckott]

thanks for your review @adamhsparks !

[ottlngr]

Thanks for your extensive and detailed feedback, @adamhsparks. I will bundle your remarks in issues soon and process them as soon as possible.