Questions to Authorea
How to solve merging conflicts?
At some stage I run into merging conflicts. This was because I added a figure within an existing text bloc using the Authorea interface . Authorea then needs to splits the text bloc into two and adds a new html file to the repository that contains the second part of the original text bloc. In the background, Authorea of course integrates the new html file also intolayout.md
to make sure that the new text bloc is included into the document. I wasn't aware of that and changed layout.rm
from R at the same time, which obviously led to a merging conflict. In case of a merging conflict Authorea pushes to a separate branch (by default this branch is labeled as authorea, but you can change it in the deploy key settings). To fix the problem I created a new pull request from my GitHub repository and merged the authorea branch back into the master branch. This worked well and everything seemed to be fine again. However, I then started to change the figure from R as described above. The new figure turned up in the Data
folder of the Authorea document as expected but it did not change in the document itself. I suspected that this was an issue related to the cache of the browser, but simply reloading the html-page did not help. Furthermore, I soon ran into the next merging conflict that I did not really understood. I was not able to really understand the issue and to definitively solve it using pull request. Thus I decided to completely delete the document on Authorea and connected theGitHub repository to a new and empty Authorea document as explained above. I just opened the layout.md
file from Authorea (from the Data
folder ) and pasted the content from the old layout.md
file. After having done so the document reappeared as it used to be and everything worked fine again (including changing the figure from R). I think the short question is: How to properly solve a merging conflict?
Why Authorea stores a copy of a figure?
When adding a figure using the Authorea interface, Authorea seems to save the figure two times (one is labeled as the original). What is the use of it? This question is emerging when I aim to change a figure from R. Which figure do I need to change? I suspect that either figure could be used depending on how the document is viewed / exported (html vs. pdf vs. docx)? Is there a figure format that should be preferred? I personally would prefer to use .pdf or .png?
When do I need to manually pull or push from Github?
It is rather easy to push and pull from the Authorea interface. You just need to add /git_functions
at the end of the url and you get access to the two Git functions. When changing things from R it seems sometimes necessary to manually pull from or push to GitHub. However, I do not yet really understand when this is the case. Maybe I was also a bit misguided by the merging conflict described above and it is usually not necessary?
Discussion
Her we document our first experience with using Authorea in connection with R and GitHub. We aimed to better understand the behavior of Authorea and asked whether it could make sense to include Authorea into the workflow of conducting a data analyses project that should be finally published in a scientific manuscript. In short, we are very positive that integrating Authorea into our current workflow with R and GitHub could help to considerably improve the writing experience . We are also confident that it is in line with the emerging topic of reproducible research. So this document can be considered as a proof of concept.
In principle connecting the R/GitHub workflow with Authorea works quite well out of the box, but obviously the handling and tidy up of the different files is quite clumsy. We like to end up this document with starting a discussion about thing that might be developed (for instance as an R-package) that would help better incorporate Authorea into our R/GitHub workflow.
R-Function to automatically include a figure
Let's assume that I produced a plot in R that I would like to include into the Authorea document. It would be nice to have an R-Functions that would do this for me. Some
Add Authorea to the Rmarkdown workflow
This is more a goal in the long run. I suspect it might be possible to implement a new output format for R markdown. So I could write a normal Rmakrdown file and in the header of the document I would specify something like output: authorea_document
. When rendering the document figures and tables would be automatically added into the right place as described above. Normal text (including R junks) might be rendered to markdown and included as markdown into the document. I think the most difficult issue in this respect is how to feed the changes made in the Authorea document back into the Rmarkdown files. I suspect this might be possible using the following workflow:
- When rendering the Rmarkdown to markdown execute the R-junks as usual but additionally add the R-juncts as markdown comment into the markdown file. Thus the R-code is still there but will not be shown in the Authorea document.
- Let the co-authors make changes in the text using the Authorea interface.
- Make a function that takes the markdown file (that may contain edits from the coauthors made using the Authorea interface) and re-builds the Rmarkdown file (it basically needs to remove the numbers that were originally included by running the R-juncts and uncomment the R-junks.
- Maybe the function of 3. could be automatically run whenever one is using the push button in RStudio to get the changes from the remote git repository (GitHub).