bayespecon.graph.flow_design_matrix_with_orig¶

bayespecon.graph.flow_design_matrix_with_orig(Xd, Xo, col_names=None, dist=None, log_distance=True)[source]¶

Build a flow design matrix with separate destination and origin data.

This is a convenience wrapper around flow_design_matrix() that handles the common pattern of building a design matrix from destination attributes Xd and then splicing in separate origin attributes Xo.

When k_d == k_o (same number of destination and origin columns), this delegates to flow_design_matrix() and splices in the origin block. When k_d != k_o, it delegates to flow_design_matrix_asymmetric().

Parameters:¶

Xd : np.ndarray, shape (n, k_d)¶

Destination-side regional attribute matrix (no intercept).

Xo : np.ndarray, shape (n, k_o)¶

Origin-side regional attribute matrix (no intercept). k_o may differ from k_d.

col_names : list[str], optional¶

Names for the destination columns. Defaults to ["x0", "x1", ...]. When k_d != k_o, origin columns default to ["y0", "y1", ...].

dist : np.ndarray, shape (n, n), optional¶

Distance / cost matrix appended as the last predictor.

log_distance : bool, default True¶

If True and dist is provided, the appended column is log(1 + dist).ravel() and is named "log_distance".

Returns:¶

Dataclass with X_orig and combined updated to reflect Xo.

Return type:¶

FlowDesignMatrix

Raises:¶

ValueError – If Xd and Xo have incompatible row counts.

Examples

>>> import numpy as np
>>> n, k = 4, 2
>>> Xd = np.ones((n, k))
>>> Xo = 2 * np.ones((n, k))
>>> dm = flow_design_matrix_with_orig(Xd, Xo)
>>> dm.X_orig.shape
(16, 2)
>>> np.allclose(dm.X_orig[:, 0], 2.0)
True