Introducing circStudio, a Python package for preprocessing, analyzing and modeling actigraphy data

Dit paper introduceert circStudio, een Python-pakket dat de preprocessing, analyse en wiskundige modellering van actigrafiedata verenigt in één flexibel raamwerk om reproduceerbare workflows voor circadiaan biologisch onderzoek te faciliteren.

De kern

circStudio: De Alles-in-Één Keuken voor Je Slaap- en Actiedata

Stel je voor dat je een superkrachtige horloge (een 'actimeter') draagt die de hele dag en nacht meet hoe actief je bent, hoeveel licht je ziet en hoe warm het om je heen is. Dit horloge slaat duizenden gegevens op, maar die gegevens zijn als een enorme berg rauwe ingrediënten: ze zijn nuttig, maar je kunt er nog geen maaltijd van maken zonder ze eerst te wassen, snijden en bereiden.

Vroeger was het voor onderzoekers een gedoe om deze data te verwerken. Het was alsof je voor het wassen van de groenten naar de ene winkel moest, voor het snijden naar de tweede, en voor het koken naar de derde. Elk programmaatje deed maar één ding, en ze werkten niet goed samen.

circStudio is de oplossing: het is een nieuwe, slimme 'keuken' (een computerprogramma in Python) die alles in één ruimte brengt. Hier is hoe het werkt, vertaald naar alledaags taal:

1. De 'Vertaler' (Invoer en Voorbereiding)

Elk horloge merk praat zijn eigen taal. Soms is het een raadsel of de data zelfs een beetje 'rommelig' (bijvoorbeeld als je horloge even los zat).

• De Analogie: circStudio heeft speciale vertalers (adapters) die de taal van elk horloge direct begrijpen.
• Het Wassen en Schillen: Het programma kan automatisch de 'rotte stukjes' van de data verwijderen (zoals tijden dat je horloge niet droeg) en de gaten opvullen met een slimme schatting, zodat je een schoon, doorlopend verhaal hebt van je dag.

2. De 'Rekenmachine' (Berekeningen)

Nu je schone data hebt, wil je weten: Was ik een goede slaper? Was mijn dagritme stabiel?

• De Analogie: In plaats van zelf te gaan tellen, geeft circStudio je een set slimme meetinstrumenten.
• Het berekent automatisch bekende cijfers, zoals:
  • SRI (Slaap-Regelmaat Index): Hoe consistent is je slaap? (Lijkt je slaap elke dag op elkaar, of is het een chaos?)
  • RA (Relatieve Amplitude): Hoe groot is het verschil tussen je drukste momenten en je rustigste momenten? (Is je dag een duidelijke berg met pieken en dalen, of een vlakke vlakte?)

3. De 'Kristallen Bol' (Wiskundige Modellen)

Dit is het meest spannende deel. circStudio kan niet alleen kijken naar wat er gebeurd is, maar ook simuleren wat er zou kunnen gebeuren als je lichtinname verandert.

• De Analogie: Stel je voor dat je een simulatie-spel speelt. Je voert je lichtgegevens in (wanneer je op de computer zat, wanneer je buiten was) en circStudio draait een wiskundig model dat precies nadoet wat er in je hersenen (in het 'slaapcentrum' of SCN) gebeurt.
• Het kan voorspellen: Op welk tijdstip zou je lichaamsvlak melatonine (het slaaphormoon) aanmaken als je morgen anders gaat slapen? Het gebruikt hiervoor complexe formules (zoals die van Forger of Hannay), maar voor jou is het gewoon een knop die je indrukt.

4. Een Echte Test: De Onderzeeër

Om te laten zien hoe goed het werkt, hebben de makers het getest op data van bemanningsleden in een onderzeeër.

• Het Scenario: In een onderzeeër is er geen dag- en nachtritme (geen zon). Mensen werken in ploegen en slapen op vreemde tijden.
• Het Resultaat: Met circStudio konden ze snel zien dat de bemanningsleden met een onregelmatige slaap (een lage SRI) ook een zwakker dagritme hadden (een lage RA). Het programma maakte het mogelijk om deze link snel te vinden, zonder maandenlang in spreadsheets te zitten.

Waarom is dit belangrijk voor jou?

Vroeger moesten onderzoekers veel verschillende softwarepakketten combineren, wat veel fouten en gedoe veroorzaakte. circStudio is als een alles-in-één keukenapparaat:

1. Je gooit je ruwe data erin.
2. Het wast, snijdt en bereidt het voor.
3. Het meet de smaak (de statistieken).
4. Het simuleert hoe het zou smaken met andere ingrediënten (de modellen).

Het maakt wetenschappelijk onderzoek over slaap en circadiane ritmes makkelijker, sneller en betrouwbaarder, zodat we beter kunnen begrijpen hoe licht en slaap ons lichaam beïnvloeden. Of je nu een wetenschapper bent of gewoon iemand die meer wil weten over zijn eigen slaappatronen: circStudio is de brug tussen ruwe data en begrijpelijke antwoorden.

Technische samenvatting

Probleemstelling

Actigrafie is een niet-invasieve en kosteneffectieve methode om gedragsrhythmen (zoals slaap-waakpatronen) te monitoren onder real-world omstandigheden. Hoewel er verschillende open-source softwarepakketten bestaan voor specifieke aspecten van actigrafie-analyse, is de functionaliteit vaak versnipperd.

• Fragmentatie: Taken zoals data-preprocessing, het berekenen van metrieken (zoals slaapregulariteit) en wiskundige modellering van circadiane ritmen zijn vaak verdeeld over verschillende softwarepakketten.
• Interoperabiliteitsproblemen: Dit versnipperde landschap beperkt de interoperabiliteit en verhoogt de programmeerlast voor onderzoekers.
• Beperkingen van bestaande tools: Bestaande Python-bibliotheken zoals pyActigraphy (voor data-analyse) en circadian (voor modellering) werken niet naadloos samen. circadian is bijvoorbeeld niet geoptimaliseerd voor ruwe lichtschema's en faalt vaak bij het berekenen van modeltoestanden onder realistische omstandigheden. Het overschakelen tussen deze pakketten vereist extra programmeerwerk.

Methodologie

Het paper introduceert circStudio, een Python-pakket dat actigrafiedata-verwerking en wiskundige modellering van circadiane ritmen unificeert binnen één raamwerk.

Architectuur en Ontwerp:

• Basis: Het pakket is gebouwd op de codebasis van pyActigraphy, maar introduceert een nieuwe architectuur om code-duplicatie te verminderen en flexibiliteit te vergroten.
• Modulaire Structuur: Het pakket is verdeeld in twee hoofdmodules:
  1. io: Verwerkt invoer/uitvoer en preprocessing (bestandsadapters, masking, data cleaning).
  2. analysis: Biedt functionaliteit voor data-analyse en modellering.
• Ontkoppeling: In tegenstelling tot pyActigraphy is de berekening van metrieken losgekoppeld van de Raw-klasse (die verantwoordelijk is voor het lezen en voorverwerken van bestanden). Dit stelt gebruikers in staat om aangepaste preprocessing-pijplijnen te implementeren en metrieken toe te passen op andere tijdreeksen (bijv. perifere lichaamstemperatuur).

Kernfunctionaliteiten:

1. Data-Import en Preprocessing:
   • Ondersteuning voor diverse actigrafiebestandsformaten via 'adaptor'-klassen (bijv. voor ActTrust-apparaten).
   • Tools voor het maskeren van ongeldige periodes (bijv. niet-dragen van het apparaat) en het imputeren van ontbrekende waarden (gebaseerd op het gemiddelde van dezelfde tijdstippen op andere dagen).
   • Mogelijkheid tot binarisering en smoothing van signalen.
2. Berekening van Actigrafie-metrieken:
   • Standalone functies voor veelgebruikte variabelen zoals Interdaily Stability (IS), Sleep Regularity Index (SRI), Relative Amplitude (RA), en M10 (gemiddelde activiteit tijdens de 10 meest actieve uren).
3. Wiskundige Modellering:
   • Implementatie van een uitgebreide reeks modellen voor circadiane ritmen, waaronder:
     • Forger, Jewett, HannaySP, HannayTP (gebaseerd op Van der Pol-oscillatoren).
     • Hilaire07 (met ingebouwde slaapdetectie-algoritmen zoals Roenneberg).
     • Breslow13 (simulatie van melatoninetrajecten in verschillende compartimenten).
     • Skeldon23 (een model dat feedback tussen continue en discrete componenten gebruikt voor slaapdruk).
   • Het pakket biedt methoden om initiële modelcondities te schatten door iteratief door de lichtdata te lopen, wat essentieel is voor het voorspellen van markers zoals DLMO (Dim Light Melatonin Onset).

Belangrijkste Bijdragen

• Unificatie: De eerste Python-pakket die preprocessing, metriekberekening en geavanceerde circadiane modellering in één geïntegreerde workflow aanbiedt.
• Flexibiliteit en Uitbreidbaarheid: Door de scheiding tussen data-invoer en analyse kunnen onderzoekers aangepaste preprocessing-pijplijnen maken zonder de analysefuncties aan te passen.
• Toegang tot Geavanceerde Modellen: Het brengt complexe modellen (oorspronkelijk ontwikkeld door het Arcascope-team) toegankelijk en robuust maakt voor gebruik met ruwe actigrafiedata.
• Reproduceerbaarheid: Het biedt een gestandaardiseerde basis voor reproduceerbare workflows in circadiane biologie en slaaponderzoek.

Resultaten en Validatie

Het paper demonstreert de functionaliteit van circStudio aan de hand van een praktijkvoorbeeld gebaseerd op een eerdere studie met militaire onderzeeërs:

• Gebruiksscenario: Onderzoekers analyseerden actigrafiedata om te onderzoeken of verminderde slaapregulariteit (SRI) geassocieerd was met een lagere relatieve amplitude (RA).
• Analyse: Met circStudio werden SRI, RA en L5 (gemiddelde activiteit tijdens de minst actieve uren) berekend voor individuele deelnemers.
• Vindingen: Er werd een matige positieve correlatie gevonden tussen SRI en RA ($\rho = 0.422$) en een negatieve correlatie tussen SRI en L5 ($\rho = -0.514$).
• Conclusie van het geval: Dit bevestigt de hypothese dat onregelmatige slaap-waakpatronen geassocieerd zijn met verminderde robustheid van circadiane ritmen, mogelijk veroorzaakt door verhoogde nachtelijke activiteit. Dit illustreert hoe circStudio snel biologisch zinvolle relaties kan onthullen.

Significantie

• Voor de Gemeenschap: circStudio verlaagt de drempel voor onderzoekers om geavanceerde wiskundige modellen toe te passen op draagbare sensordata. Het lost het probleem op van het moeten schakelen tussen verschillende softwaretools.
• Toekomstperspectief: Het pakket vormt een flexibele basis voor het ontwikkelen van gezondheidsgerichte toepassingen en het bouwen van aangepaste analysepijplijnen.
• Open Science: Als open-source pakket (beschikbaar via PyPI en GitHub) bevordert het transparantie en reproduceerbaarheid in het veld van chronobiologie en digitale gezondheid.
• Toekomstige Ontwikkeling: De auteurs noemen plannen voor het toevoegen van algoritmen voor automatische detectie van niet-draagperiodes en potentiële uitbreiding naar een algemener pakket voor biologische tijdreeksanalyse.