Wishlist for rOpenSci tools

I’ve just added A Google Docs-Rmarkdown GUI to the rOpenSci ‘wishlist’.

^{(GUI = graphical user interface).}

Thought I may as well reproduce it below:

Summary:

• Use Google Docs for ease of drafting, aiming to output Rmarkdown to increase the use of reproducible documents
  • Add some special codes to be interpreted as code chunks, perhaps make YAML generation more intuitive etc.
• More an idea for Google App Script (Javascript derivative) than an R package
  • Noam suggested this links to RGoogleDrive package dev. (wishlist item 1)
• Fledgling to-do list is at the end

Why Google Docs?

• Free desktop publishing program
• Multi-user collaboration features (even chat)
• Native interface to the popular Drive storage system
• Search functions built in
  • e.g. type a phrase, select it, Ctrl + K to make a link: suggests top 2 search hits, tab + enter to open the webpage
• Fast drafting of documents with a ton of keyboard shortcuts formatting, most elements of which have markdown equivalents
  • e.g. Ctrl + Alt + 1 for top-level header
  • Ctrl + Alt + i for research side-pane including Google Scholar, associated PDF links, citation entry etc.
• Access/’extensibility’ through the Apps Script API

Google Docs is designed to be intuitive, so I find drafting a document with it is much easier than writing out Rmarkdown, which feels like writing code by hand where software is already out there to do so.

It’d also be nice to use a graphical editor just to see the document in preparation more clearly during its writing.

Motivation

At a recent Open Data Manchester talk, Carole Goble suggested boosting productivity is the best way to advocate for the open science/RR project (arguably more so than reproducibility per se).

As I noted at the time though, ‘open science’ isn’t in and of itself intrinsically productivity-boosting as Carole seemed to imply. If it is, the benefit emerges both in the long-term and on the scale of scientific community (rather than individuals), i.e. removal of the barrier to entry in carrying out a published analysis for verification/interrogation, often referred to as “accelerating the scientific process”.

If anything, doing ‘open science’ is currently counter to productivity:

• not well-established practices, package/software infrastructure, or examples

• new ways of going about the research process require active dev involvement ∴ productivity gains long-term/community-wide

  

  Carole showed a version of the Gartner hype cycle during her talk, comparing how software/tools development leads to improvements in researcher productivity only after the trough of its development

Advantages and impracticality of Rmarkdown

Rmarkdown will aid productivity since it:

• supports templating (no reduplication of efforts, consistent formatting, TeX control)
• provides the ability to tweak code settings and re-iterate on your own/other people’s work (again no reduplication of efforts)
  • with HTMLwidgets and such, potentially even within a display of the document itself
• separates content from styling: text formatting is an afterthought, enabling single-minded focus on content
  • cognitive psychological argument for improved productivity in the act of writing itself
  • …irony being markdown formatting visually litters content with formatting code (asterisks, brackets etc.) and can become a consideration unlike in GUI writing tools
• diffs on a non-binary file such as .Rmd enable rational change tracking cf. the likes of a Word doc

All these things computational researchers seem to appreciate. However, the barrier to entry — i.e. the need to code for basic functions and put effort into reading/writing markdown formatting — mean the productivity gains won’t become apparent for scientists at large without further development work, as I see it at least.

• not really accessible without constant awareness of technical details when writing [R]markdown
• not really ‘scalable’ in that any reasonably sized document requires an inordinate amount of manual fiddling with formatting code: traditional GUI document editor would be favoured as the only reasonable approach
  • removing these barriers would make reproducible research documents viable on a whole new level, possible with further development, e.g. to prevent the time taken for knitr to compile large documents becoming unwieldy through modularity

With an existing script gdocs2md* it’s easy to generate documents with the basic elements of markdown from a Google Doc.

^{* a particularly well-functioning fork of which I’ve now tracked down and started modifying on GitHub as gdocs2Rmd}

• Google Docs would provide the collaborative and GUI pieces of the puzzle needed for a Rmarkdown setup to compete with the likes of (more aesthetically pleasing/user-friendly but closed source) Office suite, Scrivener etc.
• Noted post hoc that it mimics the Jupyter Project’s storage of notebooks (also code documents) on Google Drive.
  • There is at least one existing script to convert IPyNBs to Rmd (by Ramnath)
  • Potential for greater crossover (a button to send your Google Doc to Rmd/JupyterNB?)
• Clarification of aims and feedback on desired use cases would be good.
• The core of the Apps Script code converting a Google doc to a markdown string is here

To do

Some of the following are implemented and/or described in existing forks of gdocs2md – Switch from script editor to UI menu – Remove hard-coded folder ID (look at what other forks did to use currently active doc within UI button) – (Option to) view output markdown in browser rather than saving/emailing – Publish to the Chrome web store. NB guidelines state:

The add-on must be fully functional—can't be a “work in progress”

• see also the guide to developing a plugin on supreetpal’s fork
  • Way to add linked images (Google Docs by default converts to base64 for ![]({URL})/ style images pasted in, and storing image files locally isn’t er, ‘scalable’. Hosting will be online anyway
  • Extensible way to add classes to objects, e.g. on elements
  • Some way to convert tag interior to HTML… [This style]() link formatting won’t work within – Javascript post-processing?
  • Extensible way to pass HTML on (markdown can mix the 2)
  • Extensible way to add in DOIs – ideally from dx.doi.org links
• perhaps use in-text like {{cite:#DOI#}} as implemented in this Google Apps script already (or brilliantly {{cite:http://dx.doi.org/#DOI#}}
  • check all links, any dx.doi.org link could be passed as that, either generate citations or pass on to knitcitations

Please add more items to the to-do list if you have ideas.