Råd för dig som ska publicera vetenskaplig kod öppet

Välj ett repositorium som kan sätta beständiga identifierare, exempelvis DOI:er, på koden när du publicerar, så gör du det möjligt att citera och länka till kodpublikationen på ett hållbart sätt. Publicera helst kod, data och dokumentation som hör ihop tillsammans i ett och samma repositorium. Om de publiceras på olika platser, se till att de hänvisar till varandra med beständiga länkar.

• Om du har en specifik version av kod och data, som hör samman med ett projekt eller vetenskaplig artikel, kan du publicera dina filer tillsammans i ett repositorium för forskningsdata. Hos Svensk nationell datatjänst får publikationer en beständig identifierare, och det du publicerar bevaras och arkiveras hos SLU.
• Program som du planerar att vidareutveckla och underhålla kan publiceras i ett kodrepositorium som till exempel Gitlab eller Github. I Github finns möjlighet att få en DOI för en specifik version av koden via en integration med Zenodo.
• Programpaket kan även publiceras i repositorier för paket, som CRAN, PyPI eller Bioconductor.
• För att fler ska hitta din publicerade kod, kan du registrera den i en ämneskatalog, exempelvis rOpenSci.
• Du kan också få mer synlighet för ditt publicerade program eller paket genom att beskriva det i en vetenskaplig artikel. Det finns tidskrifter som är specialiserade för beskrivningar av nya program (exempelvis Journal of Open Source Software), och ämnestidskrifter som ger möjlighet att publicera speciella artikeltyper för detta ändamål (till exempel ”software notes” eller ”software articles”). När du skriver en artikel har du möjlighet att beskriva ditt program mer ingående, och du kan också uppmana användare av programmet eller paketet att citera artikeln.

Läs mer

• Svensk nationell datatjänst (SND)
• Github, en plattform där utvecklare kan skapa, lagra, hantera och dela sin kod
• CRAN (the Comprehensive R Archive Network), ett datornätverk för att arkivera och distribuera program för programspråket R
• The Python Package Index (PyPI), ett repositorium för mjukvara skriven i Python
• Bioconductor,  ett projekt som utvecklar, stödjer och sprider fri programvara med öppen källkod inom bioinformatik 
• rOpenSci, ett icke-vinstdrivande initiativ som arbetar för öppen och reproducerbar forskning med hjälp av delade data och återanvändbar programvara

• Organisera filer i en logisk mappstruktur, som håller isär underliggande data, kod och resultat.
• Ge filer och mappar beskrivande namn, så att det är tydligt vilken fil som gör vad.
• Versionera kod och tillhörande data separat från varandra. Du kan särskilja versioner av filer genom filnamnen eller genom att ta hjälp av versionshanteringsprogram som Git.

• Dela upp koden i moduler eller paket med tydliga syften och avgränsningar.
• Indentera kodstycken med tabb eller mellanslag på det sätt som vedertaget i det programspråk du använder.
• Ge beskrivande namn till funktioner, klasser och variabler, så att andra lättare kan förstå vad de innehåller.
• Städa koden innan publicering. Ta till exempel bort kod du inaktiverat med kommentartecken, om den inte används av programmet.

Underlätta för andra att förstå hur programmet används, och vad koden gör, genom att dokumentera utförligt.

• Bifoga en så kallad README-fil, en textfil som ska vara direkt läsbar för en användare.
  
  • Beskriv i README-filen hur programmet kompileras, körs och används. Inkludera all information som är användbar för en användare att känna till, till exempel om det finns hjälpkommandon tillgängliga. Om relevant, beskriv hur programmet kompileras.
  • Om den publicerade koden innehåller flera källkodsfiler ska du ange vad varje fil gör och om filerna är avsedda att köras som skript och, om så är fallet, om de ska köras i en viss ordning.
  • Inkludera referenser till eventuella andra vetenskapliga publikationer som kod och analysmetoder bygger på.
• Använd dig av kommentarer i koden för att beskriva vad koden gör och varför.
• Inled varje källkodsfil med ett sidhuvud i form av en kommentar som innehåller:
  • titel
  • en beskrivning av vad filen gör, och hur den relaterar till andra filer i publikationen
  • version
  • datum
  • kodpublikationens identifierare (t.ex. DOI)
  • identifierare eller referenser till relaterade publikationer (ex. en artikel, rapport eller datapublikation)
  • kontaktinformation till skaparen (namn och e-post, samt om relevant ORCID och affiliering)
  • Information om eventuell licens 
• Ett sätt att dokumentera arbetsflöden är att använda sig av så kallad "literate programming". Det innebär att kod i programspråk varvas med text skriven i mänskligt språk. För detta kan du använda märkspråket Markdown. Med Markdown är det möjligt att skapa reproducerbara rapporter med text och analysresultat som sedan kan konverteras till PDF eller Worddokument. Quarto är ett populärt system för att kombinera kod med Markdown, som kan användas för "literate programming". 
• Ett annat sätt att dokumentera arbetsflödet i programmet är genom att använda ett skript som automatiserar stegen i arbetet.

Läs mer

• Information om författaridentfikationer, inklusive ORCID, från SLU-biblioteket: Författaridentifikatorer
• Så anger du affiliering till SLU vid publicering
• Quarto, ett vetenskapligt och tekniskt publiceringssystem med öppen källkod

För att koden ska kunna användas över tid, är det viktigt att beskriva den miljö som programmet skapats i. Beskriv vilken version av operativsystem, programspråk och eventuella kodbibliotek, moduler och paket som används av programmet. Detta kan göras på olika sätt:

• Bifoga den informationen i en README-fil.
• I R kan du använda dig av kommandot sessionInfo() för att hämta den aktuella informationen efter att du kört ditt program. Du kan spara resultatet som en textfil som du sedan publicerar tillsammans med koden.
• Ett annat sätt är att bifoga informationen i form av en metadatafil som kan läsas av stödmjukvara, exempelvis Pipenv i Python eller renv i R.
• För att förenkla återskapande av den miljö som behövs för att köra programmet kan du använda så kallad containerteknologi. Det innebär att ett verktyg, exempelvis Docker, paketerar programmet tillsammans med tillhörande kodbibliotek, så det kan köras isolerat i en kontrollerad miljö och därmed fungera på olika datorer.

Läs mer

• Docker, en plattform för att skapa containrar

Öppen källkod innebär att programvara är fri att använda, modifiera och dela vidare. Undvik om möjligt att göra koden du publicerar beroende av program som inte har öppen källkod. Innan du publicerar är det viktigt att säkerställa att du har rättigheterna till koden i sin helhet och därmed har rätt att sprida den.  

• Kod som du har skapat själv kan du förse med en licens för hur den får återanvändas. Licenser som uppfyller krav på öppen källkod är att föredra.
• Bifoga licensinformationen som en textfil med namnet LICENSE.txt (eller LICENSE.md om du använder Markdown). Inkludera också information om licensen samt upphovsrättshavare i källkodsfilens sidhuvud. Du kan alternativt klistra in hela licensinformationen i själva källkodsfilen.
• Alla personer som varit med och skapat koden behöver ge sitt medgivande till publicering.
• När du använder delar av kod som skapats av någon annan än du själv, behöver du följa den licens som angetts för vidareanvändning. Om kod som någon annan skapat inte har försetts med en licens som tillåter vidare publicering, behöver du tillstånd från den som har upphovsrätten innan du publicerar programmet.
• Kom ihåg att referera när du använder kod som någon annan skapat. 

Läs mer

• Webbsidan choosealicense.com kan användas för hjälp att välja kodlicens.
• På SLU-bibliotekets sidor om att skriva referenser kan du läsa mer om hur du citerar och refererar till kod.

Se till att programmet fungerar att köra innan du publicerar din kod. Det är bra att testa om programmet fungerar som förväntat på en annan dator än din egen. Om du har möjlighet, be en kollega att granska och testa att köra din kod på sin dator.

• Se till att alla filer som behövs för att köra programmet finns med i publikationen.
• Kontrollera att hänvisningar till filer pekar till filer i den mappstuktur du publicerar, och inte till platser exempelvis på din egen dator. Det brukar benämnas att man använder relativa sökvägar i stället för absoluta sökvägar.
  
  • Exempel på absolut sökväg i Windows: "C:\Users\jdoe\research_project\analysis\article2024\mycode\data\data_file.csv"
  • Exempel på relativ sökväg i Windows:  "..\data\data_file.csv"
• En del tidskrifter önskar att du tillgängliggör data och kod under granskningsprocessen av en artikel.  Om du väljer att publicera via Svensk nationell datatjänst har du möjlighet att dela dina filer med granskare utan att de publiceras öppet innan artikeln har accepterats.

Läs mer

• Om du blivit ombedd av en kollega eller tidskrift att granska någon annans kod, kan du hitta råd här: Implementing code review in the scientific workflow: Insights from ecology and evolutionary biology.