data_loss_histogram#

pymovements.plotting.data_loss_histogram(gaze: Gaze, *, column: str = 'position', sampling_rate: float | None = None, unit: Literal['count', 'time'] = 'count', time_column: str = 'time', figsize: tuple[int, int] = (12, 6), title: str | None = None, bins: int | str | None = 'auto', color: str | None = None, edgecolor: str = 'black', alpha: float = 0.7, ax: Axes | None = None) → tuple[Figure, Axes][source]#

Plot histogram of consecutive data loss chunk lengths.

Identifies consecutive regions of data loss (invalid values or time gaps) and creates a histogram showing the distribution of chunk lengths.

This function internally uses matplotlib.pyplot.hist().

Parameters:

  • gaze (Gaze) – The gaze data to analyze.

  • column (str) – The column to check for invalid values (i.e. ‘pixel’ for pixel columns, ‘position’ for position data). (default ‘position’)

  • sampling_rate (float | None) – Sampling rate in Hz. Required if unit=’time’. (default: None)

  • unit (Literal['count', 'time']) – Unit for chunk length: ‘count’ for sample count or ‘time’ for milliseconds. (default: ‘count’)

  • time_column (str) – The column name containing timestamps. (default: ‘time’)

  • figsize (tuple[int, int]) – Figure size in inches (width, height). (default (12, 6))

  • title (str | None) – Title for the plot. Auto-generated if None. (default: None)

  • bins (int | str | None) – Number of bins or binning strategy for the histogram. See matplotlib.pyplot.hist() for available options. (default: ‘auto’)

  • color (str | None) – Fill color of the histogram bars, if None, use matplotlib default. See matplotlib.pyplot.hist() for available options. (default: None)

  • edgecolor (str) – Edge color of the histogram bars. See matplotlib.pyplot.hist() for available options. (default: ‘black’)

  • alpha (float) – Transparency of bars (0.0 transparent to 1.0 opaque). See matplotlib.pyplot.hist() for available options. (default: 0.7)

  • ax (plt.Axes | None) – Matplotlib axes to plot on. Creates new figure if None. (default: None)

Returns:

Figure and axes objects.

Return type:

tuple[plt.Figure, plt.Axes]

Raises:

  • ValueError – If sampling_rate is not provided when unit=’time’.

  • ValueError – If unit is not ‘count’ or ‘time’.