Bivariate Distribution

Shipping

bivariate_distribution

Full joint X–Y analysis: correlation, covariance, KDE contours, ellipses, marginals, OLS + PCA axes

Signature

Inputs

xSignal|Vectorrequired— X-axis samples (Signal values, or a 1-D array).
ySignal|Vectorrequired— Y-axis samples, paired element-wise with x.

Outputs

statsDataFrame— One-row table: n, means, σ, variances, covariance, Pearson r, Spearman ρ, R², slope, intercept, eigenvalues, axis angle, eccentricity.
pearson_rScalar— Pearson linear correlation (dimensionless); NaN if degenerate.
spearman_rhoScalar— Spearman rank correlation (dimensionless); NaN when $n<3$.
covarianceScalar— Sample covariance $\operatorname{cov}(x,y)$, unit $u_x\cdot u_y$.
ellipseSignal— Nested concentration/confidence ellipse ring(s) as a plottable (x, y) polyline (NaN-separated).
kde_contoursSignal— KDE iso-density contour segments as an (x, y) polyline.
densityMatrix— 2-D histogram heatmap (rows = y bins, cols = x bins).
marginal_xSignal— X-axis marginal histogram (bin centers vs counts).
marginal_ySignal— Y-axis marginal histogram.
regression_lineSignal— OLS y-on-x line drawn across the x-range.
principal_axisSignal— Major-eigenvector (PCA) axis through the centroid, $\pm 2\sqrt{\lambda_{\text{major}}}$.

Parameters

Key	Type	Default	Notes
`estimator`	enum	classical	one of: classical, robust
`robust_fraction`	float	0.75	MCD subset coverage $h/n$ (0.5 = max breakdown). Active only when estimator = robust.
`ellipse_levels`	text	1,2,3	Comma-separated nested contour levels — σ multiples in σ mode, probabilities (0.5,0.95,0.99) in confidence mode.
`scale_mode`	enum	sigma	one of: sigma, confidence
`distribution`	enum	normal	one of: normal, student
`purpose`	enum	concentration	one of: concentration, mean_confidence, prediction
`ellipse_segments`	int	96	Number of vertices per ellipse ring.
`kde_bins`	int	64	Resolution of the KDE evaluation grid (per axis).
`kde_bandwidth`	enum	scott	one of: scott, silverman, manual
`kde_bw_scale`	float	1.0	Smoothing multiplier on the selected bandwidth rule.
`kde_levels`	int	6	Number of iso-density KDE contour levels.
`kde_pad`	float	0.12	Fraction of the data range to pad the KDE grid by on each side.
`heatmap_bins`	int	40	2-D histogram resolution for the density Matrix output.
`marginal_bins`	int	30	Bin count for the marginal_x / marginal_y histograms.
`max_points`	int	200000	Cap on points used for the estimate; larger clouds are decimated by a fixed deterministic stride.

Description

Bivariate Distribution takes two paired sample streams (x, y) and produces a complete statistical and geometric breakdown of their joint distribution in one node. Alongside the classic scalar summaries — Pearson $r$ (linear), Spearman $ρ$ (rank/monotone), and the sample covariance — it emits a one-row stats DataFrame with everything from the means and variances to $R^{2}$ , the OLS slope/intercept, and the covariance-ellipse eigen-decomposition (major/minor eigenvalues, axis angle, eccentricity).

The visual outputs are emitted as plottable Signals whose timestamps carry the polyline X and values the Y, with NaN breaks separating disjoint rings/segments — so wiring ellipse, kde_contours, regression_line, or principal_axis straight into a plot draws closed curves with zero plot-side special-casing. The density output is a 2-D histogram heatmap Matrix (rows = y, cols = x), and marginal_x / marginal_y are per-axis histograms.

Two estimators are offered: classical sample covariance, or robust MCD (Minimum Covariance Determinant), which fits only the densest robust_fraction of the cloud and ignores outliers and heavy tails. Confidence ellipses can be scaled by σ-multiples or by probability (Normal χ² or Student-F for small $n$ ), and can represent data spread, the confidence region of the mean, or a prediction region for a new point.

Uncertainty is not propagated ( $σ$ -class drops) because these summary statistics are non-linear functions of the inputs. The node is stateless.

Mathematics

r = \frac{cov ( x , y )}{σ _{x} σ _{y}}, \overset{y}{^} = a + b x, b = \frac{cov ( x , y )}{σ _{x}^{2}}

[σ_{x}^{2} σ_{x y} σ_{x y} σ_{y}^{2}] v = λ v \Rightarrow ellipse axes \propto λ, θ = \frac{1}{2} arctan \frac{2 σ _{x y}}{σ _{x}^{2} - σ _{y}^{2}}

(p - μ)^{⊤} Σ^{- 1} (p - μ) = c^{2} (Mahalanobis ellipse at radius c)

Examples

Correlation of a noisy line

Feed x = 1..5 and y ≈ 2x with small noise. pearson_r reads near $+ 1$ , the stats DataFrame reports slope $\approx 2$ , intercept $\approx 0$ , $R^{2} \approx 1$ , and regression_line draws the OLS fit. Wire ellipse and kde_contours into the same plot to see the cloud, its 1σ/2σ/3σ rings, and the KDE density overlaid.

Robust estimate with outliers

Set estimator = robust and robust_fraction = 0.5 so the covariance ellipse and correlation follow the dense core of the data, ignoring a scatter of outliers that would otherwise inflate the classical variance and rotate the principal axis.

Applications

Correlation / dependency analysis between two measured channels (linear via Pearson, monotone via Spearman).
Publication-ready scatter overlays: confidence ellipses, KDE density contours, marginal histograms, and regression + PCA axes from a single node.
Outlier-robust covariance estimation (MCD) for noisy experimental clouds.
Feeding the density heatmap Matrix into an image/heatmap sink for 2-D density visualization.

Neat

Every geometry output is a Signal whose timestamps ARE the X coordinates and values the Y, with NaN gaps breaking disjoint rings — so a plot renders nested ellipses and marching-squares KDE contours as closed curves with no special casing.

The confidence ellipse uses a proper Mahalanobis radius that adapts to the chosen distribution (Normal χ² or Student-F for small n) and purpose (data spread vs mean-confidence vs prediction), not a fixed 2σ approximation.

The robust MCD estimator finds the densest data subset and computes covariance from it alone, giving a high-breakdown-point fit that classical covariance cannot.

The principal axis is the major eigenvector of the covariance matrix drawn ±2√λ through the centroid — a live PCA direction indicator over the scatter.

Known issues

Uncertainty is dropped (not propagated) because the summary statistics are non-linear in the inputs.

Spearman ρ is NaN for fewer than 3 points and Pearson r / ellipse geometry are undefined for a degenerate (rank-deficient) cloud.

Clouds larger than max_points are decimated by a fixed stride before estimation; KDE contours further cap at 20,000 points.