Skip to content

Missing-Event Gap Filling

biosigpy.hrv.fillgaps

Iterative reconstruction of missing events in ordered time series.

FillGapsResult

Bases: NamedTuple

Named, unpackable result of :func:fillgaps.

Attributes:

Name Type Description
tn ndarray

Corrected event timestamps in seconds. Every original timestamp is preserved exactly and reconstructed timestamps may be inserted.
dtn ndarray

Successive corrected intervals in seconds. An interval spanning an unresolved gap is represented by NaN.
Source code in src/biosigpy/hrv/fillgaps.py 
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
class FillGapsResult(NamedTuple):
    """Named, unpackable result of :func:`fillgaps`.

    Attributes
    ----------
    tn : numpy.ndarray
        Corrected event timestamps in seconds. Every original timestamp is
        preserved exactly and reconstructed timestamps may be inserted.
    dtn : numpy.ndarray
        Successive corrected intervals in seconds. An interval spanning an
        unresolved gap is represented by ``NaN``.
    """

    tn: np.ndarray
    dtn: np.ndarray

fillgaps 

fillgaps(tk: ArrayLike, gap_detection_factor: float = 1.5, correction_upper_factor: float = 1.15, correction_lower_factor: float = 0.75, minimum_interval: float = 0.5, max_gap_duration: float = 10.0, debug: bool = False) -> FillGapsResult

Reconstruct missing event timestamps inside locally detected gaps.

Parameters:

Name Type Description Default
tk array_like

Non-empty, finite, strictly increasing event timestamps in seconds. The series must already have undergone any desired false-positive removal.

 required
gap_detection_factor float

Positive factor applied to the local adaptive baseline for detection.

 1.5
correction_upper_factor float

Upper factor used to accept reconstructed intervals.

 1.15
correction_lower_factor float

Lower factor used to detect over-insertion.

 0.75
minimum_interval float

Non-negative absolute interval boundary in seconds.

 0.5
max_gap_duration float

Positive maximum gap duration attempted for reconstruction, in seconds.

 10.0
debug bool

When true, show the current gaps and every reconstruction attempt in an interactive figure. Accepted attempts are green, rejected attempts are red, and execution waits for a key press or mouse click after each attempt. The figure closes when processing finishes.

 False

Returns:

Type Description
FillGapsResult

Named result containing corrected timestamps tn and their aligned successive intervals dtn. The result can also be unpacked in that order.

Raises:

Type Description
TypeError

If a numeric input is non-numeric or complex.
ValueError

If timestamps, parameter values, or factor relationships violate the Biosiglib contract.
Notes

This function never calls :func:biosigpy.hrv.removefp implicitly. The recommended explicit preprocessing sequence is removefp(tk) followed by fillgaps(cleaned_tk). Normal calls have no plotting or other GUI side effects. Interactive inspection is enabled only by debug=True and requires Matplotlib with an interactive backend.

Examples:

>>> from biosigpy.hrv import fillgaps
>>> result = fillgaps([0, 1, 2, 4, 5, 6])
>>> result.tn
array([0., 1., 2., 3., 4., 5., 6.])
Source code in src/biosigpy/hrv/fillgaps.py 
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
def fillgaps(
    tk: ArrayLike,
    gap_detection_factor: float = 1.5,
    correction_upper_factor: float = 1.15,
    correction_lower_factor: float = 0.75,
    minimum_interval: float = 0.5,
    max_gap_duration: float = 10.0,
    debug: bool = False,
) -> FillGapsResult:
    """Reconstruct missing event timestamps inside locally detected gaps.

    Parameters
    ----------
    tk : array_like
        Non-empty, finite, strictly increasing event timestamps in seconds.
        The series must already have undergone any desired false-positive
        removal.
    gap_detection_factor : float, default=1.5
        Positive factor applied to the local adaptive baseline for detection.
    correction_upper_factor : float, default=1.15
        Upper factor used to accept reconstructed intervals.
    correction_lower_factor : float, default=0.75
        Lower factor used to detect over-insertion.
    minimum_interval : float, default=0.5
        Non-negative absolute interval boundary in seconds.
    max_gap_duration : float, default=10.0
        Positive maximum gap duration attempted for reconstruction, in
        seconds.
    debug : bool, default=False
        When true, show the current gaps and every reconstruction attempt in
        an interactive figure. Accepted attempts are green, rejected attempts
        are red, and execution waits for a key press or mouse click after each
        attempt. The figure closes when processing finishes.

    Returns
    -------
    FillGapsResult
        Named result containing corrected timestamps ``tn`` and their aligned
        successive intervals ``dtn``. The result can also be unpacked in that
        order.

    Raises
    ------
    TypeError
        If a numeric input is non-numeric or complex.
    ValueError
        If timestamps, parameter values, or factor relationships violate the
        Biosiglib contract.

    Notes
    -----
    This function never calls :func:`biosigpy.hrv.removefp` implicitly. The
    recommended explicit preprocessing sequence is ``removefp(tk)`` followed
    by ``fillgaps(cleaned_tk)``. Normal calls have no plotting or other GUI
    side effects. Interactive inspection is enabled only by ``debug=True``
    and requires Matplotlib with an interactive backend.

    Examples
    --------
    >>> from biosigpy.hrv import fillgaps
    >>> result = fillgaps([0, 1, 2, 4, 5, 6])
    >>> result.tn
    array([0., 1., 2., 3., 4., 5., 6.])
    """

    events = _validate_events(tk)
    gap_detection_factor = as_positive_real_scalar(
        gap_detection_factor, name="gap_detection_factor"
    )
    correction_upper_factor = as_positive_real_scalar(
        correction_upper_factor, name="correction_upper_factor"
    )
    correction_lower_factor = as_positive_real_scalar(
        correction_lower_factor, name="correction_lower_factor"
    )
    minimum_interval = _as_nonnegative_real_scalar(
        minimum_interval, name="minimum_interval"
    )
    max_gap_duration = as_positive_real_scalar(
        max_gap_duration, name="max_gap_duration"
    )
    debug = _as_boolean(debug, name="debug")
    if not (
        correction_lower_factor
        < correction_upper_factor
        <= gap_detection_factor
    ):
        raise ValueError(
            "factors must satisfy 0 < correction_lower_factor < "
            "correction_upper_factor <= gap_detection_factor"
        )

    if events.size < 3:
        return FillGapsResult(events.copy(), np.diff(events))

    debugger: FillGapsDebugger | None = None
    try:
        if debug:
            from biosigpy.hrv._fillgaps_debug import FillGapsDebugger

            debugger = FillGapsDebugger()
        return _fillgaps_validated(
            events,
            gap_detection_factor=gap_detection_factor,
            correction_upper_factor=correction_upper_factor,
            correction_lower_factor=correction_lower_factor,
            minimum_interval=minimum_interval,
            max_gap_duration=max_gap_duration,
            debugger=debugger,
        )
    finally:
        if debugger is not None:
            debugger.close()

View executable example