squareForm

首发版本：3.00.6.1

语法

squareForm(X, [checkInput=true])

详情

在压缩距离向量和方阵形式的距离矩阵之间进行双向转换。

  • 输入一维数值向量时，函数将其转换为对称距离矩阵，主对角线填充为 0。

  • 输入数值矩阵时，函数提取严格上三角区域，转换为一维压缩距离向量。

注：
DolphinDB 的 squareForm 与 SciPy 的 scipy.spatial.distance.squareform 均用于压缩距离向量和方阵形式的距离矩阵之间的双向转换，均提供关闭对称性、对角线检查的参数；SciPy 提供 force 参数强制转换方向。二者边界处理存在差异，详见 DolphinDB 与 SciPy 表现不同的边界情况。

参数

X 数值向量或矩阵，表示待转换的压缩距离向量或距离矩阵。

  • 若为向量，其长度必须为 n * (n - 1) / 2，其中 n >= 2。

  • 若为矩阵，则必须为方阵。

  • X 的所有元素必须为有效数值，不能包含 NULL、NaN 或 Inf。

checkInput 可选参数，布尔标量或数值标量（0 或 1），仅在 X 为矩阵时生效，表示是否检查矩阵的对称性和主对角线。默认值为 true。

  • true 或 1：检查矩阵是否对称，并检查主对角线是否全部为 0，任一项检查不通过则报错。

  • false 或 0：不检查矩阵对称性和主对角线。

返回值

  • 当 X 为长度 n * (n - 1) / 2 的数值向量时，返回 n × n 的数值矩阵。输出矩阵为对称矩阵，主对角线全部为 0；输入向量中的每个元素会同时写入对应的上三角和下三角位置。

  • 当 X 为 n × n 数值矩阵时，返回长度为 n * (n - 1) / 2 的数值向量。输出元素来自 X 的严格上三角区域，顺序为 (0,1), (0,2), ..., (0,n-1), (1,2), ..., (n-2,n-1)。

  • 当 X 为空向量时，返回 1 × 1 的零矩阵；当 X 为 1 × 1 矩阵时，返回空向量。

  • 返回值的数据类型及类型扩展参数与 X 一致。

DolphinDB 与 SciPy 表现不同的边界情况

输入 SciPy squareform DolphinDB squareForm
BOOL 或 STRING 向量 允许转换，并保留输入类型 报错：X must be a numeric vector or matrix.
向量包含 NaN、Inf 或 None/NULL 允许转换，特殊值会被复制到输出矩阵 无论 checkInput 取值如何都报错：X must not contain NULL, NaN, or Inf.
矩阵包含 NULL、NaN 或 Inf checks=false 时允许提取；checks=true 时可能因对称性或对角线检查失败而报错 无论 checkInput 是否开启都不允许转换，直接报错：X must not contain NULL, NaN, or Inf.
checks/checkInput 为 0/1 以外的数值 按 Python 布尔值解释，例如 2 等价于开启检查 仅接受 BOOL 或数值 0/1，其他数值直接报错

例子

例 1. 将压缩距离向量转换为对称距离矩阵。

v = 1 2 3
result = squareForm(v)
/* Output:
#0 #1 #2
-- -- --
0  1  2 
1  0  3 
2  3  0 
*/

例 2. 将对称距离矩阵转换为压缩距离向量。

m = matrix(0 1 2, 1 0 3, 2 3 0)
result = squareForm(m)
// Output: [1,2,3]

例 3. 默认开启矩阵对称性和主对角线检查，输入不对称矩阵时会报错。

m = matrix(0 1 2, 4 0 3, 7 6 0)
result = squareForm(m)
// X must be symmetric.

例 4. 指定 checkInput 为 false，关闭矩阵对称性和主对角线检查，函数只提取严格上三角区域。

m = matrix(0 1 2, 4 0 3, 7 6 0)
result = squareForm(m, false)
// Output: [4,7,6]