UNIFORM_DIRECTION

Overview

The UNIFORM_DIRECTION function generates random unit vectors that are uniformly distributed on the surface of a hypersphere in a specified number of dimensions. This is useful in statistics, machine learning, and simulation for sampling random directions in N-dimensional space. The underlying method is based on the scipy.stats.uniform_direction class, which draws samples from the uniform distribution on the unit sphere $S^{d-1}$ in $\mathbb{R}^d$ .

The probability density function for a uniform direction on the unit sphere is:

f(\mathbf{x}) = \frac{1}{A_{d-1}}, \quad \mathbf{x} \in S^{d-1}

where $A_{d-1}$ is the surface area of the $(d-1)$ -dimensional sphere.

For more details, see the scipy.stats.uniform_direction documentation .

This wrapper simplifies the function by omitting the random_state/seed parameter, as Excel does not support reproducible random number generation. The function always returns a 2D list of floats (unit vectors), or an error message if the input is invalid.

This example function is provided as-is without any representation of accuracy.

Usage

To use the function in Excel:


=UNIFORM_DIRECTION(dim, [size])

dim (int, required): Number of dimensions for the unit vectors. Must be >= 2.
size (int, optional, default=1): Number of samples to generate. Must be >= 1.

The function returns a 2D array (list) of floats, where each row is a unit vector of length dim. If the input is invalid, it returns an error message (string).

Examples

Example 1: Basic 2D Single Sample

Inputs:

dim
2

Excel formula:


=UNIFORM_DIRECTION(2)

Expected output:

x	y
0.707	-0.707

Example 2: Basic 3D Single Sample

Inputs:

dim
3

Excel formula:


=UNIFORM_DIRECTION(3)

Expected output:

x	y	z
0.577	0.577	0.577

Example 3: 2D Multiple Samples

Inputs:

dim	size
2	4

Excel formula:


=UNIFORM_DIRECTION(2, 4)

Expected output:

x	y
0.866	0.500
-0.866	0.500
0.000	-1.000
1.000	0.000

Example 4: 5D Multiple Samples

Inputs:

dim	size
5	2

Excel formula:


=UNIFORM_DIRECTION(5, 2)

Expected output:

x1	x2	x3	x4	x5
0.447	0.447	0.447	0.447	0.447
-0.447	0.447	-0.447	0.447	-0.447

Python Code


from scipy.stats import uniform_direction as scipy_uniform_direction
from typing import Optional, List, Union
 
def uniform_direction(dim: int, size: Optional[int] = 1) -> Union[List[List[float]], str]:
    """
    Draws random unit vectors uniformly distributed on the surface of a hypersphere in the specified dimension.
 
    Args:
        dim: Dimension of directions (int). Must be >= 2.
        size: Number of samples to draw (int). Default is 1.
 
    Returns:
        2D list of float values representing unit vectors, or an error message (str) if input is invalid.
 
    This example function is provided as-is without any representation of accuracy.
    """
    # Validate dim
    if not isinstance(dim, int) or dim < 2:
        return "Invalid input: dim must be an integer >= 2."
    # Validate size
    if size is None:
        size = 1
    if not isinstance(size, int) or size < 1:
        return "Invalid input: size must be an integer >= 1."
    try:
        # Draw random unit vectors
        result = scipy_uniform_direction.rvs(dim=dim, size=size)
    except Exception as e:
        return f"scipy.stats.uniform_direction error: {e}"
    # Always return a 2D list of floats
    import numpy as np
    arr = np.array(result)
    if arr.ndim == 1:
        # Single sample: shape (dim,)
        return [arr.astype(float).tolist()]
    elif arr.ndim == 2:
        # Multiple samples: shape (size, dim)
        return arr.astype(float).tolist()
    else:
        return "Unexpected output shape from scipy.stats.uniform_direction."

Example Workbook

Link to Workbook