Granska vetenskaplig kod

För att skapa programvara används formella språk som kallas programspråk (eller programmeringsspråk). Textfiler skrivna i programspråk kallas källkodsfiler. Instruktionerna som ges i programspråken översätts sedan till en form som kan förstås av en dators hårdvara och därmed köras direkt på den. 
 
En del programspråk, som C eller Fortran, behöver översättas på detta sätt innan programmet kan köras. Dessa programspråk kallas kompilerade språk. Andra programspråk, som R och Python, kallas tolkade språk och översätts efter hand som programmet körs. Programkod som behöver tolkas av en programvarutolk på detta sätt kallas ofta för skript.  

Vetenskaplig programvara utgör digitala objekt som, liksom andra data, bör förses med beständiga identifierare och beskrivas väl med tillämpliga metadata vid publicering för att vara hittbara, tillgängliga, interoperabla och återanvändbara (FAIR). 

Programvara som förbereds för publicering kan utgöra dokumentation av arbetsflöde och analysmetoder, och ibland även vara del av forskningsresultaten. Det är vanligt att publicera kod tillsammans med annan data och dokumentation i samma datapublicering. Att tillgängliggöra vetenskaplig programvara öppet kan vara ett bra sätt att göra arbetsflöden transparenta och reproducerbara. 

Programvara kan deponeras i en fryst version i ett datarepositorium som SND. Ofta är dock ett repositorium specifikt för kod, som GitHub, att föredra för programvara, eftersom koden där kan underhållas och vidareutvecklas. Om programvara, data och dokumentation som hör samman publiceras på olika platser, bör skaparen tänka på att hänvisa och länka dem till varandra på ett beständigt sätt.  

Notera: Om programvara inlämnas som dokumentation av, eller för att möjliggöra reproduktion av, resultat som redan är framtagna bör granskare vara försiktiga med att be skaparen göra ändringar i namn på ingående variabler, funktioner i källkoden etc. eftersom det kan påverka resultaten. Hur programvaran bör granskas och beskrivas vid publicering skiljer sig åt mellan olika programspråk, så det första steget i granskningen är att identifiera vilket språk som använts. 

Vid publicering av forskningsdata fastställs exakta versioner för datafiler och dokumentationsfiler och den exakta versionen av all tillhörande kod bör också anges. Kodversionering hanteras ofta med hjälp av ett kodrepositorium som till exempel GitLab eller GitHub. 

• Kod och data som hör samman kan publiceras tillsammans i ett forskningsdatarepositorium. 
• Det är även möjligt att bifoga en kopia av källkoden till en datapublicering men samtidigt också göra en relationshänvisning till kodrepositoriet eller  mjukvarupubliceringen. Då säkerställs att den version av programvaran som tillhör datasetet alltid finns tillgänglig och bevarad, medan en återanvändare också kan följa vad som eventuellt har hänt med programvaruutvecklingen sedan datapubliceringen.  
• Flera möjligheter finns för långsiktig paketering och publicering av en version av den relevanta koden så att den får en egen beständig identifierare (PID). Vid användning av Software Heritage tilldelas ett SWHID, och med hjälp av Zenodo-integrationen med Github kan en release i ett GitHub-repositorium få en DOI. 

• Programvara kan omfattas av upphovsrätt, och därmed kan det vara relevant att sätta en licens på koden om överlämnaren så önskar. I vissa fall kan upphovsrätten till datorprogram övergå till arbetsgivaren, så ta reda på vad som gäller för publicering och licensiering vid skaparens organisation. 
• Att förse programvaran med en licens ökar graden av FAIRness för publikationen eftersom det tydliggör om programvaran får återanvändas och på vilket sätt. Licenser som uppfyller krav på öppen källkod är att föredra. Öppen källkod innebär att skaparen av programvaran möjliggör att koden kan läsas, modifieras och vidaredistribueras för olika typer av återanvändning. 

I många fall är det lämpligt att beskriva och/eller inkludera filer som visar den förväntade utmatningen från programmet. Sådana utmatningsexempel kan antingen redovisas i dokumentationen eller bifogas som separata filer. Dessa kan användas vid reproduktionstestning för att jämföra genererad utmatning och fungerar samtidigt som en kontroll för att granska att processen beter sig som avsett.  

Om samtliga utmatningsfiler är för omfattande eller otympliga att inkludera i reproduktionspaketet kan ett representativt, avgränsat utmatningsexempel bifogas i stället. 

En README-fil kan användas för att beskriva: 

• Kodens syfte och användning, förväntad utmatning. 
• De ingående filerna och vad de gör. Om det finns flera filer, beskriva hur de relaterar till varandra och i vilken ordning de ska köras. 
• Information om hur programmet installeras och körs. 
• Kontaktinformation till upphovspersonen (e-post, ORCID). 
• Licensinformation. 
• Versionshistorik. 
• Erkännanden till och citeringar av kodstycken, paket etc. skapade av andra som använts i programmet. 

Kodfiler bör ha ett sidhuvud i form av en kommentar som beskriver grundläggande information som: 

• Titel. 
• Vad koden gör. 
• Funktioner och argument som en användare behöver känna till. Innehåller programmet något hjälp-kommando som kan ge användaren mer information? 
• Eventuellt, hur filen relaterar till andra filer i publikationen. 

Kodfiler innehåller ofta versions- och kontaktinformation, som kan upprepa information som finns i en README-fil: 

• Version. 
• Kontaktinformation till upphovsperson (e-post, ORCID). 
• Datum. 
• Eventuell licens. 

Vid sidan om vanliga källkodsfiler finns också filer där källkod och mer detaljerade beskrivningar lagras tillsammans, enligt ett programmeringsparadigm som på engelska kallas för literate programming. De är i regel strukturerade för att köra kod i en viss sekvens och tydligt visa upp resultaten av varje bearbetningssteg direkt. Filer av detta slag kallas på engelska computational notebooks. Exempel på sådana filer är Jupyter Notebook (.ipynb), R Markdown (.Rmd) och Quarto (.qmd). 

• Det behöver finnas information om hur man kör koden. 
• Säkerställ att körningsmiljön finns beskriven på ett så detaljerat sätt att en återanvändare kan återskapa den utan svårigheter. Oftast behöver exakta versioner av alla komponenter - varje beroende till individuella paket eller kodbibliotek - beskrivas för att säkerställa detta. 
• Även när kod publiceras på andra platser bör den sammantagna dokumentationen innehålla tillräcklig information för att säkerställa möjligheterna till återanvändning.  
• Om källkod ska bli versionerad tillsammans med data eller dokumentation är det en god idé att fråga om programvaran redan finns versionshanterad någonstans, eller om den kanske till och med redan publicerats självständigt på annan plats. 

• Kontrollera att filnamn och variabelnamn faktiskt överensstämmer med eventuella uppgifter i README, artikelmanuskript eller liknande. Det är vanligt att man arbetar om kodfiler men glömmer att uppdatera hänvisningar som refererar till filen utifrån. 
• Sökvägar bör vara relativa. Det innebär att när programmet läser in datafiler så är det viktigt att sökvägar inte pekar till filer sparade på unika platser på överlämnarens egen dator. I stället bör sökvägar utgå från paketeringen och peka till filer som finns sparade i samma mapp som det publicerade skriptet, eller en utpekad mapp i samma hierarki, oavsett på vilken dator mappen används. Detta är ett vanligt problem som bör åtgärdas innan publicering. 
• Säkerställ att alla datafiler och stödfiler (bildfiler, mallfiler osv) som programmet behöver för att köras finns med i publiceringen och de har samma namn som står i skriptet. Om datafilernas namn har ändrats under kureringen behöver filnamnen också uppdateras i bifogade källkodsfiler. 

• Att kontrollera att en paketering är komplett underlättas genom att ge paketet en genomtänkt mappstruktur så att kod, in- och -utdata delas i skilda mappar. Se till att rätt mappstruktur bifogas koden, även om det innebär tomma mappar. 
• Undersök om utmatningsexempel har angetts i dokumentationen eller bifogats som filer. Om så inte är fallet kan inlämnaren uppmuntras att bifoga filer som visa hur utmatning från programmet förväntas se ut. Om programmet kräver stora datamängder eller beräkningsresurser kan du föreslå att ett avgränsat men representativt utmatningsexempel bifogas för att främja reproducerbarhet. 

• Följ eventuella instruktioner, t.ex. från README-filen. 
• Se efter om det finns en särskild arbetsordning som olika skript är tänkta att köras i och försök följa denna. Ordningen kan finnas i dokumentationsfiler eller i form av ett överordnat styrskript. 
• Om du lyckats med att köra programmet, jämför med utmatningsexempel om sådana har tillhandahållits. Filjämförelsesverktyg (antingen kommandotolkssverktyg som fc i Windows eller diff i macOS/Linux, eller GUI-baserade verktyg som Meld) kan användas för att utvärdera om programmet har återgivit utmatningsexempel exakt, eller för att lokalisera skillnader i textbaserad utmatning.  

I de fall då programvaran inte fungerar vid testkörning kan en viss detaljgranskning av källkodfiler behövas.   

• Om du får olika fel som relaterar till filer som inte kan hittas, granska koden för att se hur filerna hänvisas till. Det är vanligt att skripten förväntar sig att datafiler ligger på en viss plats i en bestämd mappstruktur för att kunna hittas, där mapparna har vissa förutbestämda namn. Om detta inte finns dokumenterat kan det gå att lista ut genom att titta på koden eller de felmeddelanden du får. Sökvägar borde vara relativa till platsen du kör skriptet ifrån, men i vissa fall har skaparen gjort en absolut sökväg som sannolikt bara fungerar på skaparens egen dator, något som förhindrar återanvändbarhet och bör åtgärdas. 
• Det är också vanligt att koden inte går att köra på grund av att koden är beroende av olika externa paket eller kodbibliotek som saknas i testmiljön eller är av en version som inte fungerar med koden. När ett nödvändigt kodbibliotek saknas i testmiljön är felmeddelanden vanligtvis ganska självförklarande. Kontrollera om du har missat någon viktig information eller om beroendet inte fanns med i dokumentationen eller miljöbeskrivningen.  
• När ett kodbibliotek som krävs finns med i testmiljön, men koden inte fungerar med den tillgängliga kodbiblioteksversionen, kan felmeddelanden vara svårare att tolka. Om något ser underligt eller tvetydigt ut, hör efter med inlämnaren om de exakta beroenden som använts.  

Om du fortfarande inte lyckats med att köra programmet, återkoppla till överlämnaren om de problem som uppstått. Skicka med eventuella felmeddelanden och be överlämnaren själv köra koden för att säkerställa att den fungerar som tänkt. Om överlämnaren inte kan reproducera felen, föreslå att hen testar koden på en annan dator eller ber en kollega köra koden.