squareForm

First introduced in version: 3.00.5.1

Syntax

squareForm(X, [checkInput=true])

Details

Convert a vector-form distance vector to a square-form distance matrix, and vice-versa.

When the input is a one-dimensional numeric vector, the function converts it into a symmetric distance matrix with zeros on the main diagonal.
When the input is a numeric matrix, the function extracts the strict upper triangular region and converts it into a one-dimensional condensed distance vector.

Note:

Note: DolphinDB's squareForm and SciPy's scipy.spatial.distance.squareform both perform bidirectional conversion between condensed distance vectors and square-form distance matrices, and both provide parameters to disable symmetry and diagonal checks; SciPy offers a force parameter to enforce the conversion direction. There are differences in edge case handling between the two; see Edge Cases Where Behavior Differs from SciPy for details.

Parameters

X A numeric vector or matrix representing the condensed distance vector or distance matrix to be converted.

If it is a vector, its length must be n * (n - 1) / 2, where n >= 2.
If it is a matrix, it must be a square matrix.
All elements of X must be valid numeric values and cannot contain NULL, NaN, or Inf.

checkInput (Optional) A Boolean scalar or numeric scalar (0 or 1). It takes effect only when X is a matrix, indicating whether to check the matrix for symmetry and the main diagonal. The default value is true.

true or 1: Check whether the matrix is symmetric and whether the main diagonal is all zeros. An error is raised if either check fails.
false or 0: Do not check matrix symmetry or the main diagonal.

Returns

When X is a numeric vector of length n * (n - 1) / 2, returns an n × n numeric matrix. The output matrix is symmetric with zeros on the main diagonal; each element from the input vector is written to the corresponding upper triangular and lower triangular positions.
When X is an n × n numeric matrix, returns a numeric vector of length n * (n - 1) / 2. The output elements come from the strict upper triangular region of X, in the order (0,1), (0,2), ..., (0,n-1), (1,2), ..., (n-2,n-1).
When X is an empty vector, returns a 1 × 1 zero matrix; when X is a 1 × 1 matrix, returns an empty vector.
The data type and type promotion of the return value are the same as X.

Edge Cases Where Behavior Differs from SciPy


Input	SciPy `squareform`	DolphinDB `squareForm`
BOOL or STRING vector	Conversion allowed, preserving the input type.	Error: `X must be a numeric vector or matrix.`
Vector contains NaN, Inf, or None/NULL	Conversion allowed; special values are copied to the output matrix.	Error regardless of the value of `checkInput`: `X must not contain NULL, NaN, or Inf.`
Matrix contains NULL, NaN, or Inf	When `checks=false`, extraction is allowed; when `checks=true`, an error may occur due to failed symmetry or diagonal checks.	Conversion is not allowed regardless of whether `checkInput` is enabled, and it directly raises an error: `X must not contain NULL, NaN, or Inf.`
`checks/checkInput` is a numeric value other than 0 or 1	Interpreted as a Python Boolean; for example, 2 is equivalent to enabling the check.	Only BOOL or numeric 0/1 is accepted; other numeric values raise an error.

Examples

Example 1. Convert a condensed distance vector to a symmetric distance matrix.

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

Example 2. Convert a symmetric distance matrix to a condensed distance vector.

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

Example 3. With matrix symmetry and main diagonal checks enabled by default, an error is raised when the input matrix is asymmetric.

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

Example 4. Specify checkInput as false to disable matrix symmetry and main diagonal checks; the function only extracts the strict upper triangular region.

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