Vetenskaplig kod

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.
  
  • När du använder 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 för 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 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 kommentartecken, om den inte används av programmet.

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.
  

• 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 så kallad "literate programming". Det innebär att kod i programspråk varvas med text skriven i 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 möjliggör att kod och metodbeskrivningar effektivt kan blandas 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 "literate programming".
• Positron är ett annat öppet källkods-IDE för dataanalys som bygger på Visual Studio Code och är särskilt anpassat 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.
  

• Exempel på utmatning från din kod och den data du använt, som har skapats i din egen programmeringsmiljö, bör om möjligt bifogas så att en återanvändare kan jämföra den med egna resultat.
• Utmatningsexempel kan exempelvis vara figurfilerna du använt i en artikel eller annan utmatning som ligger till grund för resultat som 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 ä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.

Om kod som någon annan skapat saknar licens som tillåter vidare publicering krävs tillstånd från upphovsrättsinnehavaren innan publicering, eftersom även ordagrant hämtad kod 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 alternativt publiceras med begränsad åtkomst.

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 eller att det finns information om hur de kan laddas ner.
• 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änsts verktyg DORIS har du möjlighet att dela dina filer med granskare utan att de publiceras öppet innan artikeln har accepterats.