Fun facts—The history of ezActi3

I have been thinking of streamlining the actigraphy analysis since early 2016 when he started working on a project that involved more than 6,000 actigraphy recordings.

Initially, two research assistants were working with me helping with the quality control of these recordings. To facilitate a “semi-automatic” process, a MATLAB^©-based simple App called DefineGap was born.

The App simply helps the research assistants and myself visualize the signal and document the “gap” if we ever identify any. Some user friendly tools have been implemented in order to zoom in specific areas and to show the data points using tooltips.

Almost at the same time, the research group started performing detrended fluctuation analysis (check this publication and this article for some results from this project). The two research assistants clearly preferred a small tool with a user interface instead of running through command lines. A DFATool App paired with a DFAFit App were thus developed to facilitate this process.

Similarly, to facilitate the process of performing some nonparametric circadian rest-activity rhythms analysis, I also wrote a small tool called MISIVTool. As it was named, the tool performs IS (stands for interdaily stability) and IV (stands for intradaily variability) analysis on a multiscale (the “M” in the name) basis. Also, to better estimate the actual period (especially for example in animal studies without 12:12 light-dark cycles), a variant of the MISIVTool was made to implement the $\chi$² periodogram—the PeriodTool.

All of these small tools continue to evolve and being updated separately.

To simplify the story, let’s focus on the timeline of the DefineGap, which soon evolved into its updated version—ConfirmGap. It came with a tabular-formated gap visualizer and also highlights the identified gap areas in the actigraphy. It was also featured with an “advanced option” that facilitate the display of the actual time of the signal (in addition to data points).

Code-wise, both DefineGap and ConfirmGap were developed based on the classical approach for developing user interfaces in MATLAB^©–the GUIDE^©. It quickly became complicated to maintain and manage the code as new functions were being added. In early 2018, the object-oriented (OO) structure of MATLAB^© became more and more mature, and I started migrating this App to a more manageable programming style based on OO. At the beginning of this attempt, a temporal workaround was being used that relied on the GUIDE^© to offer an interface while all functions (i.e., “call-backs of all buttons etc.) were coded through a class. This led to the new release called Gapp.

Until the end of 2019, Gapp has been continuedly updated including the addition of a pilot automatic process for sensing gaps and later a function to identify napping episodes with a user-customizable time window for daytime. This nap detection algorithm was pretty pilot and mainly based on activity counts.

With the continuing effort in streamlining different calculations (including cosinor analysis, detrended fluctuation analysis, etc.), the temporal turnaround by using the GUIDE^© to provide an interface became not efficient eventually. In the end of 2019, I finally launched the ezActi project and started refining all of these processes using the modern OO and the AppDesigner^© in MATLAB^©. This led to the born of the first release of ezActi.

The ezActi started to separate the control panel and the actigraphy display window. It also introduced several different running modes such as the gap detection, sleep and nap detection, as well as circadian analysis. It inherited the process by using a list file to perform batch analysis. It introduced a knob for facilitating the identification of time.

The DFATool and DFAFit were merged into the ezActi with a newly introduced mydfa class, which significantly improved the computational speed (more than 10x faster by a conservatively estimation).

The ezActi2 was first launched in November 2022. The idea of this new release was to feature a brand-new and easily-manageable import wizard and a newly updated actigraphy display window. New functions have been added since then, including structured visualizations and the additions of nonparametric analysis as well as empirical mode decomposition based circadian analysis. The new version also came with several newly introduced classes, including the cosinor class (which was initially implemented in ezActi based on the traditional procedural programming style), the ImportWizard, the new display window actigraphy2, and actogram. The empirical mode decomposition process was currently still based on the procedural style (which calls the built-in emd function).

After its first launch, there have been several rounds of updates to improve the performance of ezActi2. The most significant update is the addition of a new feature that evaluates the signal quality of actigraphy data based on several pre-defined rules. By no means the rules can be exclusive, so the quality control (Auto QC) is still in its beta version at this moment, as I have not come up with a better algorithm to perform the QC. This will hopefully be a focus of a future release.

The ezActi3 was first launched in Oct 2025. The idea of this new release was to enable the ability to work with raw 3-dimensional accelerometer signals, as this becomes more popular in modern watches that offer access to raw data. Instead of creating a separate tool or menu item to work with raw data, I decided to upgrade the Import Wizard to enable the import of raw files. This current release of ezActi3 only supports raw files in the format of comma separated file.

Another major update is the consolidation of sleep and nap detection, as essentially they follow the same algorithm. This consolidation reduces the confusion and offers a simpler way for me to manage the code on the back-end.