pyPPG: a Python toolbox for comprehensive photoplethysmography signal analysis

Abstract Objective. Photoplethysmography is a non-invasive optical technique that measures changes in blood volume within tissues. It is commonly and being increasingly used for a variety of research and clinical applications to assess vascular dynamics and physiological parameters. Yet, contrary to heart rate variability measures, a field which has seen the development of stable standards and advanced toolboxes and software, no such standards and limited open tools exist for continuous photoplethysmogram (PPG) analysis. Consequently, the primary objective of this research was to identify, standardize, implement and validate key digital PPG biomarkers. Approach. This work describes the creation of a standard Python toolbox, denoted pyPPG, for long-term continuous PPG time-series analysis and demonstrates the detection and computation of a high number of fiducial points and digital biomarkers using a standard fingerbased transmission pulse oximeter. Main results. The improved PPG peak detector had an F1-score of 88.19% for the state-of-the-art benchmark when evaluated on 2054 adult polysomnography recordings totaling over 91 million reference beats. The algorithm outperformed the open-source original Matlab implementation by ∼5% when benchmarked on a subset of 100 randomly selected MESA recordings. More than 3000 fiducial points were manually annotated by two annotators in order to validate the fiducial points detector. The detector consistently demonstrated high performance, with a mean absolute error of less than 10 ms for all fiducial points. Significance. Based on these fiducial points, pyPPG engineered a set of 74 PPG biomarkers. Studying PPG time-series variability using pyPPG can enhance our understanding of the manifestations and etiology of diseases. This toolbox can also be used for biomarker engineering in training data-driven models. pyPPG is available on https://physiozoo.com/.


Introduction
Photoplethysmography is an optical sensing technique widely used for health and fitness monitoring in clinical and consumer devices [22], such as smartwatches and pulse oximeters.Photoplethysmography was developed in the 1930s [6], and its potential value for assessing cardiovascular health was recognised in the 1940s [34].It was not until the 1970s that photoplethysmography became widely used as the sensing technology in pulse oximeters [9].Photoplethysmography-based wearable devices entered the consumer market in the 2010s [24], and are now used by millions of people for unobtrusive health monitoring [55].
The photoplethysmogram (PPG) signal contains a wealth of information on the heart, blood vessels, breathing, and autonomic nervous system [6].Consequently, much research is focused on extracting physiological information from the PPG [52], including physiological parameters such as blood pressure and breathing rate [18,54], and disease indicators, such as vascular age and cardiovascular risk markers [22,25].The value of photoplethysmography is rapidly increasing: its value for heart rate and oxygen saturation monitoring is well established, its utility for detecting atrial fibrillation has recently been demonstrated [61], and its potential to detect other diseases such as sleep apneas and peripheral arterial disease is being researched [22,25].Despite the widespread and increasing use of photoplethysmography, there is a lack of open-source tools for detailed analysis of the PPG.This paper presents pyP P G, an open-source, validated Python toolbox for PPG signal analysis.

The photoplethysmogram (PPG) signal
The PPG signal is an optical measurement of the arterial pulse wave [23], i.e., the wave generated when blood is ejected from the heart, temporarily increasing arterial pressure and causing vessel expansion and contraction [5].Consequently, the PPG signal is influenced by a range of physiological systems, such as: the heart, including heart rate, heart rhythm, and the nature of ejection [22]; the blood vessels, including vessel stiffness, diameter, and blood pressure [22]; the microvasculature, including peripheral compliance and resistance [22]; the autonomic nervous system which influences heart rate variability [38]; and the respiratory system, which impacts the pulse wave through changes in intrathoracic pressure [19].Thus, there is potential to extract much physiological information from the PPG signal.
The PPG signal can be acquired using a range of sensors and devices.PPG sensors consist of a light source such as an LED, and a light sensor, such as a photodiode [68].The light source illuminates a region with vasculature, such as the fingertip, and the light sensor measures how much light is either transmitted through or reflected from the tissue.The amount of light received fluctuates with each heartbeat: usually, the amount of absorbed light increases during systole when blood volume is greatest, and then decreases during diastole when blood volume returns to its initial level [6].This produces a pulse wave bearing several features, which can be interpreted as physiological biomarkers (see Figure 2) [22].In pulse oximeters, the PPG is typically acquired in transmission mode using a fingerclip probe [57], while in consumer devices such as smartwatches, fitness trackers, and earbuds (i.e.hearables), it is typically acquired reflection mode [24].

Applications of photoplethysmography
At present, the most common applications of photoplethysmography are for heart rate monitoring in smartwatches [71], and for oxygen saturation monitoring in pulse oximeters [57].Smartwatches, fitness trackers and hearables are widely used, with an estimated 1.1 billion connected wearable devices worldwide in 2022 [66].Pulse oximetry is a standard-of-care technique used in a range of clinical settings from intensive care to home monitoring [40,58].Recently, the applications of photoplethysmography-based wearables have been expanded to include atrial fibrillation detection [61], blood pressure monitoring [79], and oxygen saturation monitoring [64].Several additional potential applications of wearable photoplethysmography devices are being researched [72], including sleep staging [44], mental health assessment [15,50], identifying obstructive sleep apnea [11,12], and detecting peripheral arterial disease [65].Each of these applications uses PPG signal analysis to derive physiological information from the PPG.
Photoplethysmography confers several advantages over other physiological monitoring technologies, which has resulted in its widespread adoption.Measurements can be obtained quickly without the need for a trained operator, and photoplethysmography sensors are non-invasive, unobtrusive, and low-cost.It is also a more compact and accessible monitoring modality than other measurements such as electrocardiogram (ECG) and blood pressure measurement.Furthermore, PPG measurements can be obtained without significantly disrupting daily activities, while ECG electrodes for instance may require careful placement and proper skin preparation to ensure accurate readings.However, a key disadvantage is that the PPG signal is highly susceptible to noise, such as in the cases of poor sensor contact or motion [46].

Standardising PPG signal analysis
A key step in the use of photoplethysmography for health and fitness monitoring is the development of PPG signal analysis algorithms.Such algorithms typically extract either inter-beat-intervals (e.g., for detection of atrial fibrillation) or features of PPG pulse wave shape (e.g., for estimation of blood pressure).However, unlike in other fields such as heart rate variability analysis, there are no standards for PPG signal analysis, and only limited open tools are available.Consequently, standardized and reproducible analysis of PPG signals is lacking.Although there are some open-source PPG toolboxes, they lack validation and are often incomplete (see Table 1).
Despite the extensive research and applications in the field of PPG analysis, there is an urgent need to standardize approaches, terminologies, variables and definitions.Furthermore, there is no comprehensive toolbox available that covers all standard PPG biomarkers.It is important to acknowledge that certain variables may have different terminologies in the scientific literature, but our objective was to unify them to facilitate a broader understanding of PPG biomarkers.To fill this gap, we have developed a standardized nomenclature and toolbox.The assigned names for variables aim to provide insights into their origin, while the definitions ensure accurate interpretation and improved comprehensibility.

Paper overview
The primary aim of this research was to create a standardized toolbox (pyP P G) to analyze long-term finger PPG recordings in real-time.This paper presents standardized definitions for the state-of-the-art PPG fiducial points and biomarkers implemented within the pyP P G toolbox.It provides an overview of the steps involved in raw data processing and biomarker engineering, as well as a validation of the fiducial point extraction process (see Figure 1).Additionally, the paper presents performance results and benchmarks them against other publicly available toolboxes.
2 Materials and methods

Databases
Two databases were used to validate the pyP P G toolbox.The Multi-Ethnic Study of Atherosclerosis (MESA) database [32,82] was used to validate our peak detector, and the PPG and Blood Pressure (PPG-BP) database [47] was used to validate the fiducial point detection algorithm.The MESA database consists of polysomnography (PSG) recordings from 2,056 adults aged 54-95 years, with subclinical cardiovascular disease, including 19,998 hours of PPG recordings [26,63].Males accounted for 45.5% of the subjects.The database was downloaded from the National Sleep Resource Center [82]

Overview of the pyPPG toolbox
The pyPPG toolbox is a standardized resource for real-time analysis of long-term finger PPG recordings.The toolbox consists of five main components, as summarized in Figure 1: 1. Loading a raw PPG signal: The toolbox can accept various file formats such as .mat,.csv,.txt,or .edf .These files should contain raw PPG data along with the corresponding sampling rate.2. Preprocessing: The raw signal is filtered to remove unwanted noise and artifacts.Subsequently, the signal is resampled to a uniform rate of 75 Hz.
3. Pulse wave segmentation: The toolbox employs a peak detector to identify the systolic peaks.
Based on the peak locations, the toolbox also detects the pulse onsets and offsets, which indicate the start and end of the PPG pulse waves.4. Fiducial points identification: For each pulse wave, the toolbox detects a set of fiducial points.5. Biomarker engineering: Based on the fiducial points, a set of 74 PPG digital biomarkers are engineered.
The pyP P G toolbox also provides an optional PPG signal quality index based on the Matlab implementation of the work by Li et al. [46].

Preprocessing
The PPG signal filtering is one of the most essential parts of preprocessing.The human heart rate ranges between 30 and 200 beats per minute [59].Therefore in PPG signal analysis, it is common to apply bandpass filtering such: 0.5−8 Hz [1], 0.5−10 Hz [37], 0.5−15 Hz [52], 0.5−20 Hz [7,47], or 0.5−25 Hz [27], to conserve the frequency content of the PPG pulse waves while filtering out lower frequency content (e.g.baseline wander due to respiration) and higher frequency content (e.g.muscle noise or power interference).
We selected a frequency range of 0.5−12 Hz.Whilst fiducial point detection can be simpler with lower low-pass cut-off frequencies such as 8 Hz, the drawback of using lower cut-off frequencies is that they significantly distort the pulse wave shape and reduce the accuracy with which the pulse onset and other fiducial points can be identified.Conversely, cut-off frequencies above 12 Hz can make it more complex to detect fiducial points due to the presence of extra waves in the PPG derivatives.Therefore, during the benchmarking process of other toolboxes for fiducial point detection (see Section 3.2), the 0.5−12 Hz frequency band was employed for filtering purposes.Although the 0.5−12 Hz band is recommended by default for PPG analysis, it is possible for the user to customize the passband filter in the pyPPG toolbox.
To meet the above-mentioned requirements, the following zero-phase filters were implemented: 1. Bandpass filtering between 0.5−12 Hz: A fourth-order Chebyshev Type II filter was used for the original signal.The 12 Hz low-pass cut-off was used to avoid time-shifting of fiducial points (particularly pulse onset, and dicrotic notch) and to eliminate unwanted high-frequency content from the PPG derivatives.The 0.5 Hz high-pass cut-off was used to minimize baseline wandering whilst retaining content at low heart rates.2. 20 ms moving average filtering (MAF): In the case of very noisy signals, some high-frequency content can remain in the band-pass filter signal.For this purpose, a 20 ms standard flat (boxcar or top-hat) MAF with a 22.5 Hz cut-off frequency was applied after the band-pass filtering.3. 10 ms MAF for the PPG derivatives: To eliminate the high-frequency content in the PPG derivatives, a 10 ms standard flat (boxcar or top-hat) MAF with 45 Hz cut-off frequency was applied.
It is common for the PPG signal to be sampled at over 100 Hz and up to 1 kHz, as, for example, in the PPG-BP dataset.However, an excessive sampling frequency may not be ideal for long-term data processing due to the computational load.The default behavior of the toolbox is to resample PPG signals at 75 Hz using the Python resample function using the Fourier method.

Pulse wave segmentation
The toolbox identifies individual pulse waves in a PPG signal by identifying systolic peaks (sp), and then identifying the pulse onset (on) and offset (of f ) on either side of each systolic peak which indicate the start and end of the pulse wave, respectively.

Systolic peak detection
The sp is the most important fiducial point of the PPG signal (see Figure 2).It is defined as the point with the highest amplitude between two consecutive pulse onsets (see Fig. 2).The pyPPG toolbox uses   If there is no diastolic peak, then it is the inflection point between the systolic peak and f-point 4 dp Diastolic peak .The first local maximum of the PPG pulse wave after the dicrotic notch and before the 0.8 pulse interval; if no maxima then the first local maximum of PPG' pulse wave after the e-point and before the 0.8 pulse interval. [69] 5 off Pulse offset: The local minimum preceding the next pulse wave's systolic upslope PPG' 5 u The highest amplitude between the pulse onset and systolic peak on PPG' [8] 6 v The lowest amplitude between the u-point and diastolic peak on PPG' [67] 7 w The first local maximum or inflection point after the dicrotic notch on PPG' [67] PPG" 8 a The highest amplitude between pulse onset and systolic peak on PPG" [69] 9 b The first local minimum after the a-point on PPG" [69] 10c The local maximum with the highest amplitude between the b-point and e-point, or if no local maximum is present then the inflection point on PPG" [69] 11d The local minimum with the lowest amplitude between the c-point and e-point, or if no local minimum is present then the inflection point on PPG" [69] 12e The local maximum with the highest amplitude after the b-point and before the diastolic peak on PPG" [69] 13f The first local minimum after the e-point on PPG" [69] PPG'" 14p1 The first local maximum after the b-point on PPG'" [20] 15p2 The last local minimum after the b-point and before the d-point on PPG'" an enhanced sp detection algorithm to enable real-time analysis of long-term PPG measurements.The algorithm is an enhanced version of the Aboy beat detector [2], which performed either best [42], or amongst the best [21] in recent benchmarking studies of PPG beat detectors.We focused on improving the beat detector's performance and reducing its computational complexity.
The original Aboy algorithm utilizes an advanced filtering technique to accurately detect systolic peaks [2].PPG recordings are segmented into 10-second windows and then filtered using three digital filters.The first filter helps to estimate the heart rate, while the second and third filters are used for peak detection.Two modifications were made to the Aboy algorithm [2].Firstly, to enhance the speed of the previous Matlab implementation [21], the finite impulse response (FIR) filter was replaced by a zerophase fifth-order Chebyshev Type II infinite impulse response (IIR) filter, which applied the same cut-off frequencies as the original Aboy peak detector.Secondly, the enhanced algorithm includes adaptive heart rate estimation to handle strong baseline wandering and rapid amplitude fluctuations [39].The resulting modified peak detector is denoted Aboy++.

Pulse onset detection
The on corresponds to the beginning of the pulse wave and the beginning of the systolic upslope (see Figure 2 and Table 3).This systolic upslope is caused by increasing arterial pressure during systole [3]. on is typically a minimum point, but not necessarily.pyP P G includes a novel on detection algorithm.Previously, on has been identified as the minimum value between two successive detected sp [36,74], or identified using the slope sum function approach [33,56].However, during long-term measurements there can be multiple local minima between successive sp, particularly in a noisy PPG signal.We define the on as the initiation of the systolic upslope, which is usually a minimum point, although not always.We used a simple yet accurate approach to detect the on as the first maximum preceding the p 1 -point on the PPG'". of f is equivalent to the on on the next pulse wave.

Dicrotic notch detection
The dicrotic notch (dn) plays an important role as a fiducial point in the analysis of PPG signals, holding immense potential for various applications such as heart disease detection [41] and arterial stiffness assessment [3].Its significance stems from its association with the duration of systole, which is known to be affected by heart disease.Additionally, the appearance of the diastolic wave following the dn allows for the evaluation of arterial stiffness, with the hypothesis that the presence of the dn is influenced by the arterial stiffness.However, it should be noted that the visibility of the dn diminishes progressively with age, making it typically no longer discernible in elderly subjects [25].
None of the existing definitions of dn are entirely satisfactory.Typically, the dn is easily recognizable when a distinct local minimum exists between the sp and the dp (see Figure 2).Yet, in many cases, the dp is not clearly visible, rendering it difficult to accurately identify the dn.Dawber et al. [31] categorized different classes of dn, which are illustrated in Figure 3. Another morphological approach for dn identification involves locating it at the time of zero-crossing of the PPG" between the d and e points [17].However, debate regarding the precise location for defining the dn is ongoing.For instance, situations may arise where the local minimum of the dn is visible, but the occurrence of the d and e points precedes the zero-crossing point, as depicted in Figure 2.

Fiducial points of PPG derivatives
Additional fiducial points were defined on the PPG derivatives (PPG', PPG" and PPG'") as depicted in Figure 2 [25,67].The fiducial point detection algorithms in pyP P G are based on standardized, morphological definitions (see Table 3).Consequently, these points do not necessarily correspond to points with consistent physiological interpretations.On the PPG' signal, the maximum point of the systolic slope Fig. 3 The dicrotic notch (dn) is considered visible when there is a local minimum between the sp and dp.However, the dp is not always clearly visible.The dn can be classified into four classes: Class 1, in which the dn is with an incisura, Class 2, in which there is a horizontal line at the dn, Class 3, in which there is a change in gradient on the downslope, or and Class 4, in which there is no clear evidence of the dn.The figure was adapted from Charlton et al. [25].
is denoted as the u-point, while the minimum point is referred to as the v -point.The u-point has been used to assess arterial stiffness [78].On the PPG" signal, six further fiducial points are defined.Among these, four points (a, b, c, and d) are typically observed during the systolic phase (see Figure 2).As the diastolic phase begins, the e-point becomes visible, followed by the appearance of the f -point [67].Points a to e have been used to assess vascular ageing [69], and the d -point has been identified as a predictor of cardiovascular mortality.On the PPG'" signal, p 1 represents the early systolic component of the PPG pulse wave, while p 2 corresponds to the late systolic component [69].p 1 and p 2 are used to calculate the augmentation index, which has been found to be elevated in atherosclerotic and diabetic subjects [14,62].

Biomarker engineering
The pyPPG toolbox includes a comprehensive collection of 74 standard PPG morphological biomarkers which are calculated from the timings and amplitudes of the fiducial points (see Tables 4, 5, 6, 7).The biomarkers were categorized into four groups: (1) PPG Signal -biomarkers that are based on the location of the fiducial points of the PPG signal; (2) Signal Ratios -biomarkers that are based on ratios of the fiducial points of the PPG signal; (3) PPG Derivatives -biomarkers that are based on the location of the fiducial points of the PPG derivatives; and (4) Derivatives Ratios -biomarkers that are based on ratios of the fiducial points of the PPG derivatives.
For a given window consisting of a set of beats, pyPPG provides the following nine general statistics for each biomarker (see Supplementary Table S2, S3, S4, S5): signal duration; average (AVG); median (MED); standard deviation (STD); lower and upper quartiles (Q1, Q3); inter-quartile range (IQR); Skewness (SKW, indicating a lack of symmetry in the distribution; Kurtosis (KUR, indicating the pointedness of a peak in the distribution curve); and the average difference between the mean and each data value (MAD).

Systolic peak detection
The performance and computational complexity of the enhanced sp detection algorithm, Aboy++, were evaluated.Performance was assessed in comparison to reference ECG-derived beats using the F 1 -score, which is a commonly used statistic for evaluating the performance of such algorithms.The F 1 -score is particularly suitable for this purpose because it effectively combines multiple fractional measures by utilizing a harmonic mean between the sensitivity and positive predictive value.F 1 -scores are reported as median (MED) and quartiles (Q1, Q3).The performance and computational complexity of Aboy++ were compared against the implementation of Aboy provided by Charlton et al. [21].Due to the high computational needs of Aboy, the two algorithms were compared on a subset of MESA consisting of 100 recordings (1,173 hours) of PPG.Aboy++ was then assessed on the entire MESA database, with the exception of two recordings which did not have an ECG reference signal.Thus 2,054 PPG recordings were Asp/∆T Stiffness index, ratio of the systolic peak amplitude vs. the time delay [53] 12 Asp/(T pi -Tsp) Ratio of the systolic peak amplitude vs. the difference between the pulse interval and systolic peak time [27] Table 6 Biomarkers derived from the PPG derivatives Table 7 Biomarkers derived from the derivatives ratios categorized into intervals, amplitudes, areas, and combinations of these included, consisting of more than 19,000 hours of continuous PPG signals and over 91 million reference beats.The median recording length was 10 hours, with a 2.5-hour interquartile range (IQR).The 10-hourlong recordings were divided into 10-minute segments.Segments were excluded if they did not contain a minimum of 300 ECG reference beats or if the extracted biomarkers could not be successfully evaluated.

Intervals
A key step in this assessment was to synchronise the timings of ECG-derived beats and PPG systolic peaks.This was achieved by forecasting the PPG sp by extracting electrocardiogram (ECG) peaks from the PSG recordings as a reference signal similar to the work of Kotzen et al. [43].The evaluation metric was based on the alignment of the ECG-R-wave and PPG sp.The methods for performance assessment are elaborated in more detail in our previous work [39,43].

Fiducial point detection
The fiducial point detection algorithm was validated by comparison against the manual annotations of the PPG-BP [47] database.The data were manually annotated by two annotators (MAG and PHC) following the definitions in Table 3.An annotation tool was adapted from the open source RRest toolbox for this purpose [19].If an annotator could not confidently identify a fiducial point then they did not annotate it.After both annotators independently annotated the prefiltered signal, the time difference between the two annotators annotations was calculated.If the time discrepancy was >10 ms, then the annotators discussed the case and either: (i) agreed on a location; or (ii) excluded the fiducial point (i.e. the annotators were not confident of its location).The final reference annotations were determined as the average of the annotations provided by the two annotators.In the PPG-BP database, each subject has three recordings.The first complete, high-quality pulse wave was selected for each subject.In total, more than 3,000 fiducial points from 219 patients were manually annotated by the two annotators.The PPG signals were filtered within the frequency band of 0.5-12 Hz during the manual annotation and benchmarking of the toolboxes (see Section 3.2).The Inter-rater reliability of annotations is presented in Table S1.
To assess the performance of the fiducial point detection algorithm, pyP P G was benchmarked against two publicly available PPG toolboxes capable of detecting fiducial points (P ulseAnalyse [23] and P P GF eat [1]).Both benchmarked toolboxes were implemented in Matlab.Performance was assessed using the mean absolute error (MAE) and the standard deviation of the absolute errors (STD) of the fiducial point detections in comparison to the reference .Bland-Altman plots [13] with the limits of agreement (1.96STD, indicating 95% of errors) are also included.

Systolic peak detection
The improved sp detector, Aboy++, outperformed the original Aboy implementation when benchmarked on a subset of 100 randomly selected MESA recordings.The F 1 -score of Aboy++ was ∼5% greater than that of Aboy.In addition, the computational time of Aboy++ was over 57 times faster than that of Aboy.Specifically, the median peak detection time for 1-hour-long segments was 114.24 seconds for Aboy, compared to 1.98 seconds for Aboy++.When evaluated on the 2,054 recordings of the MESA dataset, Aboy++ obtained an F 1 -score of 88.19% (81.73−92.71).
Fig. 4 Bland-Altman plot comparing the detected fiducial points and manual annotations at 99% percentile of the data, with the reference pulse onset serving as the starting point.The panels (a) to (d) depict the results of the PPG signal and its derivatives.LOA: limits of agreement, n: number of fiducial points, RMSE: root mean squared error, STD: standard deviation of the differences.

pyPPG and PhysioZoo PPG
The resulting systolic peak detection and fiducial points detection algorithms are package into an open source Python library denoted pyP P G.In addition, a user-friendly interface is also implemented in the PhysioZoo Software.In order to ensure that pyP P G could process a large dataset without technical issues, we run it over the full MESA database and reported standard statistics for all biomarkers (see Supplementary Table S2, S3, S4, S5).(The library and software will be placed online following publication.)

Discussion
This work is expected to contribute significantly to the scientific field of computerized cardiology, leading to a better understanding of the PPG signal.Firstly, it standardized the definition of PPG fiducial points and biomarkers.The second major contribution consists in the implementation and quantitative validation of a fiducial point detector.The third key contribution pertains to the implementation in pyP P G of 74 physiological PPG.The toolbox is made open-source, making it the only comprehensive and validated Python library that is publicly accessible.A user-friendly interface is also implemented in the PhysioZoo Software software.This interface enables data visualization, exploration and quantitative analysis of a PPG recording.By offering this novel solution, researchers and clinicians are empowered with a valuable resource for comprehensive and reproducible PPG analysis.Finally, the manual annotations of the 219 recordings, including more than 3,000 fiducial points are made open access to ensure reproducibility of the results and to enable further investigations and advancements in the field of PPG analysis.
This research has limitations.The performance of the peak detection algorithms were only performed on sleep data from atherosclerosis patients (see Supplementary Table S2, S3, S4, S5).Therefore the evaluation of Aboy++ on additional databases would be very beneficial.Another limitation of the work is the focus on the analysis of PPG measured using standard clinical oximeter.Adapting the toolbox to incorporate PPG sources like earlobe PPG or smartwatches will also be of interest, particularly given the widespread use of the later.The program has another limitation related to the controversial nature of morphological and physiological characteristics of fiducial points (see Supplementary Figure ??).Hence, creating a standardized toolbox presented a significant challenge.
In conclusion, this work provides a standards and advanced toolbox for the analysis of PPG.Studying the PPG time series variability using pyPPG can enhance our understanding of the manifestations and etiology of diseases.This toolbox can also be used for biomarker engineering in training data-driven models.

Code Availability
The source code used and the annotations of the fiducial points in this research are available at physiozoo.com.

Acknowledgments
MAG and JAB acknowledge the Estate of Zofia (Sophie) Fridman and funding from the Israel Innovation Authority.PHC acknowledges funding from the British Heart Foundation (grant FS/20/20/34626).
The Multi-Ethnic Study of Atherosclerosis (MESA) Sleep Ancillary study was funded by NIH-NHLBI Association of Sleep Disorders with Cardiovascular Health Across Ethnic Groups (RO1 HL098433).

Supplementary Material
Table S1 Inter-annotator differences for fiducial points The mean and standard deviation of the absolute errors (MAE and STD respectively) are reported for each fiducial in ms.
. The institutional review board from the Technion-IIT Rapport Faculty of Medicine was obtained under number 62-2019 in order to use the retrospective databases obtained from the open-access sleepdata.orgresource for this research.The PSG recordings in MESA were acquired at home, including fingertip PPG signals measured at 256 Hz from the fingertip using Nonin 8000 series pulse oximeters (Nonin Medical Inc., Plymouth, US), alongside simultaneous ECG signals.The PPG-BP dataset contains 657 short (2 s) PPG recordings collected from 219 adult subjects aged 20-89 years with different health statuses (including healthy, hypertensive and diabetic subjects).Males accounted for 48% of the subjects.The data include fingertip PPG signals measured at 1 kHz using a SEP9AF-2 PPG sensor (SMPLUS Company, Korea).Signals were acquired using a 12-bit ADC, and the hardware applied a 0.5-12Hz band-pass filter.

Fig. 2
Fig.2The fiducial points of the PPG signal include the systolic peak (sp), the pulse onset and offset (on, of f ), the dicrotic notch (dn), and the diastolic peak (dp).The fiducial points of PPG derivatives are represented by u, v, w, a, b, c, d, e, f , p 1 , p 2 .The biomarkers are calculated based on this set of fiducial points.

1 on
Pulse onset.The beginning of the systolic upslope, typically, but not necessarily, a minimum point 2 sp Systolic peak .The highest amplitude between two consecutive pulse onsets 3 dn Dicrotic notch.If a diastolic peak is present, then it is the local minimum preceding the diastolic peak.
Tu u-point time, the time between the pulse onset and u-point ms Tu v-point time, the time between the pulse onset and v-point [67] Tw w-point time, the time between the pulse onset and w-point [67] Ta a-point time, the time between the pulse onset and a-point [67] T b b-point time, the time between the pulse onset and b-point [67] Tc c-point time, the time between the pulse onset and c-point [67] T d d-point time, the time between the pulse onset and d-point [67] Te e-point time, the time between the pulse onset and e-point [67] T f f-point time, the time between the pulse onset and f-point [67] 10 T b−c b−c time, the time between the b-point and c-point [20] 11 T b−d b−d time, the time between the b-point and d-point [20] 12 Tp 1 p 1 -point time, the time between the pulse onset and p 1 -point [67] 13 Tp 2 p 2 -point time, the time between the pulse onset and p 2 -point [67] 14 T p 1 −dp p 1 −dia time, the time between the p 1 -point and diastolic peak [60] 15T p 2 −dp p 2 −dia time, the time between the p 2 -point and diastolic peak[60] Tu/TpiRatio of the u-point time vs. the pulse interval [27] Tv/T pi Ratio of the v-point time vs. the pulse interval [27] Tw/T pi Ratio of the w-point time vs. the pulse interval Ta/T pi Ratio of the a-point time vs. the pulse interval [27] T b /T pi Ratio of the b-point time vs. the pulse interval [27] Tc/T pi Ratio of the c-point time vs. the pulse interval T d /T pi Ratio of the d-point time vs. the pulse interval Te/T pi Ratio of the e-point time vs. the pulse interval T f /T pi Ratio of the f-point time vs. the pulse interval (Tu-Ta)/T pi Ratio of the difference between the u-point time and a-point time vs. the pulse interval [27] (Tv-T b )/T pi Ratio of the difference between the v-point time and b-point time vs. the pulse interval [27] Amplitudes Au/Asp Ratio of the u-point amplitude vs. the systolic peak amplitude [8] Av/Au Ratio of the v-point amplitude vs. the u-point amplitude Aw/Au Ratio of the w-point amplitude vs. the u-point amplitude A b /Aa Ratio of the b-point amplitude vs. the a-point amplitude [69] Ac/Aa Ratio of the c-point amplitude vs. the a-point amplitude [69] A d /Aa Ratio of the d-point amplitude vs. the a-point amplitude [69] Ae/Aa Ratio of the e-point amplitude vs. the a-point amplitude [69] A f /Aa Ratio of the f-point amplitude vs. the a-point amplitude Ap 2 /Ap 1 Ratio of the p 2 -point amplitude vs. the p 1 -point amplitude [60] (Ac-A b )/Aa Ratio of the difference between the b-point amplitude and c-point amplitude vs. the a-point amplitude [4] (A d -A b )/A Ratio of the difference between the b-point amplitude and d-point amplitude vs. the a-point amplitude [4] AGI Aging index, (A b -Ac-A d -Ae)/Aa [69] AGI mod Modified aging index, (A b -Ac-A d )/Aa [73] AGI inf Informal aging index, (A b -Ae)/Aa [10] AI Augmentation index, (PPG(Tp2)-PPG(Tp1))/Asp [69] RIp 1 Reflection index of p 1 , A dp /(PPG(Tp 1 )-PPG(T pi (0))) [60] RIp 2 Reflection index of p 2 , A dp /(PPG(p 2 )-PPG(T pi (0))) [60] Combined SC Spring constant, PPG"(Tsp)/((Asp-Au)/Asp) [81] IPAD Inflection point area plus normalised d-point amplitude, AUC dia /AUCsys+A d /Aa [4]

Fig. S1
Fig. S1 Prefiltering of the PPG, PPG', PPG", and PPG"' signals.In panel (a), the raw PPG signal is represented by the black curve, while the red curve represents the application of a fourth-order Chebyshev Type II filter (Cheby2).In panels (a) to (d), the green dashed curve represents the filtered version of the red curve obtained through moving average filtering (MAF).Panels (b) to (d) display the PPG', PPG", and PPG'" signals, respectively.The black curve depicts the derivatives of the red curve from the preceding panel.Likewise, the red curve corresponds to the derivative of the green curve shown in the previous panel.

Fig. S2
Fig. S2 Comparison of fiducial point annotations.The first manual reference annotation is represented by empty circles and squares, while the crosses and stars indicate the mark of the second annotator.The black lines illustrate the PPG signal and its derivatives.More than 3000 fiducial points were manually annotated in 219 different PPG waves by two annotators on the PPG-BP dataset to validate the implemented fiducial points detector

Table 2
Fingertip PPG databases used for the quantitative validation experiments

Table 3
Definition of PPG fiducial points

Table 4
Biomarkers derived from the PPG signal categorized into intervals, amplitudes, and areas

Table 5
Biomarkers derived from the signal ratios categorized into intervals, amplitudes, areas, and combinations thereof

Table 8
Benchmark of PPG toolboxes for fiducial points detection.The mean (and standard deviation) of the absolute errors are reported for each fiducial in ms.
The peak detection algorithm in the pyP P G toolbox was validated on 19,000 hours of continuous PPG data, encompassing more than 91 million reference beats.It performed with an 88.18% F 1 -score while processing a 1-hour segment in 1.98 seconds.When evaluated on 3,000 manually annotated fiducial points pyP P G had a low MAE and consistently outperformed two other open toolboxes.

Table S2
Summary statistics for biomarkers of PPG signal from the MESA database for 2,054 PPG recordings STD); lower and upper quartiles (Q1, Q3); inter-quartile range (IQR); Skewness (SKW, indicating a lack of symmetry in the distribution; Kurtosis (KUR, indicating the pointedness of a peak in the distribution curve); and the average difference between the mean and each data value (MAD).TableS3Summary statistics for biomarkers of signal ratios from the MESA database for 2,054 PPG recordings AVG); median (MED); standard deviation (STD); lower and upper quartiles (Q1, Q3); inter-quartile range (IQR); Skewness (SKW, indicating a lack of symmetry in the distribution; Kurtosis (KUR, indicating the pointedness of a peak in the distribution curve); and the average difference between the mean and each data value (MAD).Table S4 Summary statistics for biomarkers of PPG derivative from the MESA database for 2,054 PPG recordings Average (AVG); median (MED); standard deviation (STD); lower and upper quartiles (Q1, Q3); inter-quartile range (IQR); Skewness (SKW, indicating a lack of symmetry in the distribution; Kurtosis (KUR, indicating the pointedness of a peak in the distribution curve); and the average difference between the mean and each data value (MAD).