Collaborating on R projects

Samarbejde om R projekter

Author

Søren O’Neill & Steen Harsted

Published

September 11, 2024

When collaborting with co-authors, you are likely to encounter one of these three scenarios:

1 If your co-authors want to stick to Word (or similar):

  • Render your Quarto documents into a Word (or OpenDocument) file, then send it to your co-authors
  • Co-authors can use Track changes in their word-processor and then return it to you
  • You can then manually revise, accept or reject changes by editing your Quarto file

2 If your co-authors are not afraid to try some simple new software:

  • Share your Quarto document with the co-authors
  • Co-authors can use any Markdown editor to edit the Quarto document directly
  • You then simply continue working on the Quarto file
  • You use a Diff’ing program to revise, accept and reject changes made by your co-authors (see the following section 2. Your co-authors are R users for details about Diff’ing)

Your co-authors will need to install a MarkDown editor (or use an online version).

There are many markdown editors available, some are online solutions, some are apps that need to be installed, some are free and some cost money – for a list of some options see this webpage.

We make the following recommendations:

Note, there are also several online version (e.g. Dillinger). They are a good place for your co-authors to try out MarkDown before commiting … but you should consider whether your manuscript is suitable for uploading to a website.

If you and your co-authors all use R :

  • Share your Quarto files with your co-authors
  • Co-authors edit the Quarto files directly
  • Diff the two (or more) version of the Quarto file and merge them selectively

If you and your co-authors want to collaborate on the entire project, i.e. be able to run and edit the same code, render output etc, you will have to share the entire project folder.

It is possible to do so using networked folders like OneDrive or Google Drive. This is may present a few challenges however, as individual settings are stored in the same folder – e.g. the folder .Rproj.user. You will need to exempt these files from sync’ing with the server.

The following files hould not be synchronized with the network drive:

  • .RProj.user
  • .RData
  • .RHistory
  • .git (doesn’t exist, unless you used git)
  • .gitignore (doesn’t exist, unless you use git)

A warning about storing Quarto files in a shared network folder: If you choose to store your files in a shared folder instead of sending files back and forth, you should take care to secure different versions. E.g. if your co-author over-writes you latest version with his/her revisions, you latest version is no longer available for Diff’ing – don’t overwrite, add new versions.1

If you’re very concerned (or bothered) by the manual versioning nightmare, consider GIT … see section _3. We are all tech savvy nerds*.

Diff’ing is a process where two (or more) text files are compared and presented in a way that highlights the differences between them.

It makes it easy to see what has been changed between two versions of the same text document, and to accept, reject, and/or revise the changes.

Figure 1: Two text documents with several differences, presented side-by-side with differences highlighted. Arrows in the central margin allows for changes to be accepted from one version to the other.

There are several software solutions for Diff’ing to text files, e.g.:

  • Meld (recommended)
  • Beyond compare
  • Araxis merge
  • P4Merge
  • DeltaWalker
  • ..and others

There are also several online version .. e.g. mergely

Please, consider whether using an online version for ‘production’ manuscripts is smart.

RStudio also has built-in Diff’ing for GIT versions, but it is not as user friendly as some of the recommende option listed above.

Please, meet GIT

2.1 GIT

GIT is a Versioning system – it can be used to store all the files in you R project (locally and in an online repository) and maintain a comprehensive history of changes and versions over time.

We won’t lie: GIT is a bit difficult to learn.

  • Instead of storing multiple versions of the same file, GIT stores just the current version of the file, and a complete (hidden) version-history
  • Unlike other versioning systems, GIT does not store the changes between versions, but rather snapshots of each version.
  • One of GITs killer features is branching – the ability to fork a project into new projects and later merge them together again.
  • All changes are documented
  • All2 changes are reversible
  • GIT is indispensable for very large projects – we are talking of software development with tens-of-thousands of co-authors collaborating on many millions of lines of code … overkill for most research manuscripts
  • GIT is a separate program, supported by RStudio.

You can read more about GIT here

SDU runs an online GIT repository at gitlab.sdu.dk. Alternatively, check out Github and Bitbucket.

Når du skal samarbejde med medforfattere, vil du sandsynligvis støde på et af disse tre scenarier:

3 Hvis dine medforfattere kun vil bruge Word (eller lignende):

  • Render dine Quarto-dokumenter til en Word-fil (eller OpenDocument) og send den til dine medforfattere
  • Medforfatterene kan bruge Track Changes i deres tekstbehandler og returnere det til dig
  • Du kan derefter manuelt revidere, acceptere eller afvise ændringer ved at redigere din Quarto-fil

4 Hvis dine medforfattere er ikke bange for at prøve noget simpelt nyt software:

  • Del dit Quarto-dokument med medforfatterne
  • Medforfatterene kan bruge enhver Markdown-editor til at redigere Quarto-dokumentet direkte
  • Du fortsætter så bare med at arbejde på Quarto-filen
  • Du kan bruge et Diff’ing-program til at revidere, acceptere og afvise ændringer foretaget af dine medforfattere (se følgende afsnit 2. Dine medforfattere er R-brugere for detaljer om Diff’ing)

Dine medforfattere skal installere en MarkDown-editor (eller bruge en onlineversion).

Der er mange forskellige markdown-editorer tilgængelige, nogle er onlineløsninger, nogle er apps der skal installeres, nogle er gratis og nogle koster penge – for en liste over nogle muligheder se denne webside.

Vi kommer med følgende anbefalinger:

Bemærk, der er også flere onlineversioner (f.eks. Dillinger). De er et godt sted for dine medforfattere at prøve MarkDown, før de forpligter sig … men du bør overveje, om dit manuskript er egnet til at uploade til en hjemmeside.

Hvis du og dine medforfattere alle bruger R :

  • Del dine Quarto-filer med dine medforfattere
  • Medforfatterne redigerer Quarto-filerne direkte
  • Diff de to (eller flere) versioner af Quarto-filen og sammenflet dem selektivt

Hvis du og dine medforfattere ønsker at samarbejde om hele projektet, det vil sige at kunne køre og redigere den samme kode, rendere output osv., bliver I nødt til at dele hele projektmappen.

Det er muligt at gøre det ved at bruge netværksmapper som OneDrive eller Google Drive. Dette kan dog give nogle få udfordringer, da individuelle indstillinger er gemt i samme mappe - f.eks. mappen .Rproj.bruger. Du bliver nødt til at ekskludere disse filer fra at synkronisere med serveren.

Følgende filer bør ikke synkroniseres med netværksdrevet:

  • .RProj.user
  • .RData
  • .RHistory
  • .git (eksisterer sandsynligvis ikke)
  • .gitignore (eksisterer sandsynligvis ikke)

En advarsel om lagring af Quarto-filer i en delt netværksmappe: Hvis du vælger at gemme dine filer i en delt mappe i stedet for at sende filer frem og tilbage, bør du sørge for at sikre forskellige versioner. F.eks. hvis din medforfatter overskriver din seneste version med hans/hendes revisioner, er din gamle version ikke længere tilgængelig for Diff’ing – overskriv ikke, tilføj nye versioner.3

Hvis du er meget bekymret (eller generet) af det manuelle versions-mareridt, så overvej GIT … se afsnit _3. Vi er alle teknologikyndige nørder*.

Diff’ing er en proces, hvor to (eller flere) tekstfiler sammenlignes og præsenteres på en måde, der fremhæver forskellene mellem dem.

Det gør det nemt at se, hvad der er blevet ændret mellem to versioner af det samme tekstdokument, og at acceptere, afvise og/eller revidere ændringerne.

Figure 2: To tekstdokumenter med flere forskelle, præsenteret side om side med forskellene fremhævet. Pile i den centrale margin gør det muligt at acceptere ændringer fra den ene version til den anden.

Der er adskillige softwareløsninger til Diff’ing til tekstfiler, f.eks.:

  • Meld (anbefales)
  • Beyond compare
  • Araxis-fusion
  • P4Merge
  • DeltaWalker
  • ..og andre

Der findes også flere online versioner .. f.eks. mergely

Overvej venligst, om det er smart at bruge en onlineversion til ‘produktions’ manuskripter.

RStudio har også indbygget Diff’ing til GIT versioner, men det er ikke så brugervenligt som nogle af de anbefalede muligheder, der er anført ovenfor.

Må jeg præsentere: GIT

4.1 GIT

GIT er et versionssystem – det kan bruges til at gemme alle filerne i dit R-projekt (lokalt og i et online lager) og vedligeholde en omfattende historik over ændringer og versioner over tid.

Vi vil ikke lyve: GIT er lidt svært at lære.

  • I stedet for at gemme flere versioner af den samme fil, gemmer GIT kun den aktuelle version af filen, og en komplet, men skjult versionshistorik
  • I modsætning til andre versionssystemer gemmer GIT ikke ændringerne mellem versioner, men snarere snapshots af hver version.
  • En af GITs største styrker er branching – evnen til at forgrene et projekt i nye projekter og senere flette dem sammen igen.
  • Alle ændringer er dokumenteret
  • Alle4 ændringer er reversible
  • GIT er uundværlig for meget store projekter – vi taler om softwareudvikling med ti-tusinder af medforfattere, der samarbejder om mange millioner linjer kode … overkill for de fleste forskningsmanuskripter
  • GIT er et separat program, understøttet af RStudio.

Du kan læse mere om GIT her

SDU driver et online GIT-lager på gitlab.sdu.dk. Alternativt kan du tjekke Github og Bitbucket.

Footnotes

  1. Some shared folders (e.g. SharePoint) has an underlying versioning system, which keeps older versions.↩︎

  2. It is possible to make irreversible changes, but you have to use both hands and really, really mean it!↩︎

  3. Nogle delte mapper (f.eks. SharePoint) har et underliggende versioneringssystem, som beholder ældre versioner.↩︎

  4. Det er muligt at lave irreversible ændringer, men du skal bruge begge hænder og virkelig, virkelig mene det!↩︎