bcea#

pymovements.measure.samples.bcea(column: str = 'position', *, n_components: int = 2, confidence: float = 68.27) → Expr[source]#

Bivariate contour ellipse area (BCEA).

The Bivariate Contour Ellipse Area (BCEA) [Crossland and Rubin, 2002] quantifies the area covered by samples. It represents the area of an ellipse that encompasses a specified proportion of all samples. BCEA accounts for both the spread of samples and their correlation between the horizontal and vertical axes:

\[\sigma_x = \sqrt{\frac{1}{n-1} \sum_{i=1}^{n} (x_i - \bar{x})^2},\quad \sigma_y = \sqrt{\frac{1}{n-1} \sum_{i=1}^{n} (y_i - \bar{y})^2}\]
\[\rho = \frac{\sum_{i=1}^{n} (x_i - \bar{x})(y_i - \bar{y})} {\sqrt{\sum_{i=1}^{n} (x_i - \bar{x})^2} \sqrt{\sum_{i=1}^{n} (y_i - \bar{y})^2}}\]
\[k = -2 \ln(1 - P/100),\quad \text{BCEA} = k \pi \sigma_x \sigma_y \sqrt{1 - \rho^2}\]

where \(x_i\) and \(y_i\) are the x and y sample components, \(\bar{x}\) and \(\bar{y}\) are their respective means, \(\sigma_x\) and \(\sigma_y\) are the standard deviations, \(\rho\) is the Pearson correlation coefficient between the horizontal and vertical components, \(P\) is the desired confidence level (as a percentage), and \(k\) is the scaling factor derived from the chi-square distribution with 2 degrees of freedom [Niehorster et al., 2020].

Parameters:

  • column (str) – The column name of the position tuples. (default: ‘position’)

  • n_components (int) – Number of positional components. Usually these are the two components yaw and pitch. (default: 2)

  • confidence (float) – The confidence level as a percentage (0-100). This is the proportion of samples that should fall within the ellipse contour. Most commonly used values are 68.27 (±1σ), 95.45 (±2σ), and 99.73 (±3σ). (default: 68.27)

Returns:

The bivariate contour ellipse area.

Return type:

pl.Expr

Raises:

  • ValueError – If number of components is not 2.

  • ValueError – If confidence is not between 0 and 100.

Notes

This implementation uses sample variance (dividing by \(n-1\)) for computing the variances and correlation coefficient.

The relationship between confidence level \(P\) and scaling factor \(k\) comes from the chi-square distribution. For a bivariate normal distribution, the contours of constant Mahalanobis distance form ellipses. The value of squared Mahalanobis distance corresponding to confidence \(P\) is \(k = -2 \ln(1-P/100)\), which is the \(P/100\) quantile of the chi-square distribution with 2 degrees of freedom (i.e., \(k = \chi^2_2(P/100)\)). Common confidence levels and their corresponding \(k\) values are:

  • 68.27%: \(k \approx 2.30\)

  • 95.45%: \(k \approx 6.18\)

  • 99.73%: \(k \approx 9.21\)

The confidence level of 68.27% is the default as it corresponds to the same probability mass as a ±1σ interval in 1D. To choose the confidence \(P\) based on the familiar 1D “±σ” coverage, first compute \(P = \Pr(|Z| \le \sigma) = \chi^2_1(\sigma^2)\) (since \(Z^2 \sim \chi^2_1\)), then use the same probability mass to get \(k = \chi^2_2(P)\).

>>> from scipy.stats import chi2
>>> sigma = 1.0
>>> confidence = chi2.cdf(sigma*sigma, df=1)
>>> k = chi2.ppf(confidence, df=2)
>>> print(confidence, k)
0.6826894921370859 2.295748928898636

For sequences with fewer than 2 samples, or when the variance of either component is zero, this measure returns None since statistics (variance, correlation) cannot be meaningfully computed.

rms_s2s() is closely proportional to the average velocity of the signal during fixations, making it a good indicator of slowest detectable eye movements. Unlike std_rms(), which measures spatial spread, rms_s2s() captures the velocity aspect of signal variability. This makes rms_s2s() particularly useful for assessing what threshold might differentiate eye movements from measurement noise [Niehorster et al., 2020].

On this page
Show Source