Vetenskaplig kod

Välj ett repositorium som kan sätta beständiga identifierare, exempelvis DOI:er, när du publicerar kod, 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.
  • När du använder Svensk nationell datatjänsts verktyg DORISÖppnas i en ny tabb får publicerade dataset en beständig identifierare (DOI) och kod kan publiceras och bevaras tillsammans med datasetet.
• 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Öppnas i en ny tabb.
  • Programpaket kan även publiceras i repositorier för paket, som CRAN Öppnas i en ny tabb eller PyPIÖppnas i en ny tabb.
• För att fler ska hitta din publicerade kod kan du registrera den i en ämneskatalog, exempelvis rOpenSciÖppnas i en ny tabb.
• Infrastrukturen Software Heritage möjliggör att du kan skapa en långtidssäker publicering av kod som finns på Github eller andra ställen. Du får en beständig identifierare, SWHIDÖppnas i en ny tabb, som kan användas för att referera till koden.
• 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 på beskrivningar av nya program 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 sådan 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.

• Ge filer och mappar beskrivande namn så att det är tydligt vilken del av programmet som gör vad.
• Förpacka filerna i en logisk mappstruktur. Håll isär underliggande data, kod och resultat och förse dem med separata versionsnummer. Undvik att nästla in kod och data i svårseparerade mappstrukturer om det inte krävs av en specifik standard som du måste följa.
• 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.

• Strukturera koden du skriver så att den är lätt att läsa och förstå.
• Dela upp koden i moduler eller paket med tydliga syften och avgränsningar.
• Indentera kodstycken på det sätt som är brukligt i det programspråk du använder eller den formella stilkonvention du vill följa.
• 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 kommentarstecken om koden inte längre används av programmet.

För att försäkra dig om att koden förblir användbar över tid är det viktigt att beskriva den miljö som den skapades 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 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 som en metadatafil som kan läsas av stödprogramvara, exempelvis Pipenv i Python eller renv i R.
• För att förenkla återskapandet 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, till exempel Docker, paketerar programmet tillsammans med tillhörande kodbibliotek så att det kan köras isolerat i en kontrollerad miljö och därmed fungera på olika datorer.
  

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, exempelvis om det finns hjälpkommandon tillgängliga.
  • 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. Om så är fallet, ska det tydliggöras 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 litterär programmering, eller ”literate programming”. Det innebär att kod i programspråk varvas med text skriven i naturligt (mänskligt) språk. Olika lösningar som låter dig arbeta på detta sätt hanterar ofta dokumentationen i uppmärkningsspråket (markup language) Markdown, vilket gör det möjligt att blanda kod och metodbeskrivningar i samma fil.

• Med Markdown är det möjligt att skapa reproducerbara rapporter med text och analysresultat som sedan kan konverteras till PDF, Worddokument eller HTML-format. Quarto är ett populärt system för att kombinera kod med Markdown, som kan användas för litterär programmering.
• Positron är en integrerad utvecklingsmiljö eller IDE (Integrated Development Environment) med öppen källkod som är avsedd för dataanalys. Den bygger på Visual Studio Code och är särskilt anpassad för R och Python. Det har tagits fram av företaget Posit som också utvecklat RStudio. Det är inte ett Markdown-baserat system, men har inbyggt stöd för Jupyter Notebook, Quarto och andra verktyg för reproducerbara och publicerbara analyser.
• Ett annat sätt att dokumentera arbetsflödet i programmet är genom att använda ett skript som automatiserar stegen i arbetet.
  

• Bifoga om möjligt exempel på resultat från din kod och de data du använt, som har skapats i din egen programmeringsmiljö. Då kan den som vill återanvända koden jämföra dina resultat med resultaten från sin egen programmeringsmiljö.
• Resultat kan exempelvis vara figurerna du använt i en artikel eller datatabeller som ligger till grund för resultaten du redovisar.

Ö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 koden är det viktigt att försäkra dig om 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 LICENCE.txt (eller LICENCE.md om du använder Markdown). Inkludera också information om licensen och upphovsrättsinnehavaren i källkodsfilens sidhuvud. Du kan även 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 koden inte har försetts med en licens som tillåter vidare publicering behöver du tillstånd från upphovsrättsinnehavaren innan du publicerar programmet.
• Kom ihåg att ange referenser till skaparna när du använder kod som någon annan skapat.

Om kod som någon annan skapat saknar licens som tillåter vidare publicering krävs tillstånd från upphovsrättsinnehavaren före publicering eftersom även kod som hämtats ordagrant från onlinekällor kan vara upphovsrättsskyddad. Korta, standardiserade kodavsnitt saknar oftast verkshöjd, men längre eller mer kreativa delar bör skrivas om, användas med tillstånd eller publiceras med begränsad åtkomst.

Se till att det går att köra programmet innan du publicerar koden. 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 koden på sin dator.

• Se till att alla filer som behövs för att köra programmet finns med i publikationen eller att det finns information om hur de kan laddas ner.
• Kontrollera att hänvisningar till filer pekar till filer i den mappstruktur du publicerar, inte till filsökvägar 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å en absolut sökväg i Windows:

"C:\Users\jdoe\research_project\analysis\article2024\mycode\data\data_file.csv"

Exempel på en relativ sökväg i Windows:

"..\data\data_file.csv" 

• En del tidskrifter vill att du tillgängliggör data och kod under granskningsprocessen av en artikel.
  • Om du väljer att publicera via Svensk nationell datatjänsts verktyg DORIS kan du dela dina data och kodfiler med granskare utan att de publiceras öppet innan artikeln har accepterats.