parameters: (X, force="no", checks=True)
docstring: Convert a vector-form distance vector to a square-form distance
      matrix, and vice-versa.
  
      Parameters
      ----------
      X : ndarray
          Either a condensed or redundant distance matrix.
      force : str, optional
          As with MATLAB(TM), if force is equal to ``'tovector'`` or
          ``'tomatrix'``, the input will be treated as a distance matrix or
          distance vector respectively.
      checks : bool, optional
          If set to False, no checks will be made for matrix
          symmetry nor zero diagonals. This is useful if it is known that
          ``X - X.T1`` is small and ``diag(X)`` is close to zero.
          These values are ignored any way so they do not disrupt the
          squareform transformation.
  
      Returns
      -------
      Y : ndarray
          If a condensed distance matrix is passed, a redundant one is
          returned, or if a redundant one is passed, a condensed distance
          matrix is returned.
  
      Notes
      -----
      1. v = squareform(X)
  
         Given a square d-by-d symmetric distance matrix X,
         ``v = squareform(X)`` returns a ``d * (d-1) / 2`` (or
         :math:`{n \\choose 2}`) sized vector v.
  
        :math:`v[{n \\choose 2}-{n-i \\choose 2} + (j-i-1)]` is the distance
        between points i and j. If X is non-square or asymmetric, an error
        is returned.
  
      2. X = squareform(v)
  
        Given a ``d*(d-1)/2`` sized v for some integer ``d >= 2`` encoding
        distances as described, ``X = squareform(v)`` returns a d by d distance
        matrix X.  The ``X[i, j]`` and ``X[j, i]`` values are set to
        :math:`v[{n \\choose 2}-{n-i \\choose 2} + (j-i-1)]` and all
        diagonal elements are zero.
  
      In Scipy 0.19.0, ``squareform`` stopped casting all input types to
      float64, and started returning arrays of the same dtype as the input.
docstring_summary: Convert a vector-form distance vector to a square-form distance
      matrix, and vice-versa.
docstring_tokens: Convert a vector - form distance vector to a square - form distance matrix and vice - versa .
function: def squareform(X, force="no", checks=True):
      """
      Convert a vector-form distance vector to a square-form distance
      matrix, and vice-versa.
  
      Parameters
      ----------
      X : ndarray
          Either a condensed or redundant distance matrix.
      force : str, optional
          As with MATLAB(TM), if force is equal to ``'tovector'`` or
          ``'tomatrix'``, the input will be treated as a distance matrix or
          distance vector respectively.
      checks : bool, optional
          If set to False, no checks will be made for matrix
          symmetry nor zero diagonals. This is useful if it is known that
          ``X - X.T1`` is small and ``diag(X)`` is close to zero.
          These values are ignored any way so they do not disrupt the
          squareform transformation.
  
      Returns
      -------
      Y : ndarray
          If a condensed distance matrix is passed, a redundant one is
          returned, or if a redundant one is passed, a condensed distance
          matrix is returned.
  
      Notes
      -----
      1. v = squareform(X)
  
         Given a square d-by-d symmetric distance matrix X,
         ``v = squareform(X)`` returns a ``d * (d-1) / 2`` (or
         :math:`{n \\choose 2}`) sized vector v.
  
        :math:`v[{n \\choose 2}-{n-i \\choose 2} + (j-i-1)]` is the distance
        between points i and j. If X is non-square or asymmetric, an error
        is returned.
  
      2. X = squareform(v)
  
        Given a ``d*(d-1)/2`` sized v for some integer ``d >= 2`` encoding
        distances as described, ``X = squareform(v)`` returns a d by d distance
        matrix X.  The ``X[i, j]`` and ``X[j, i]`` values are set to
        :math:`v[{n \\choose 2}-{n-i \\choose 2} + (j-i-1)]` and all
        diagonal elements are zero.
  
      In Scipy 0.19.0, ``squareform`` stopped casting all input types to
      float64, and started returning arrays of the same dtype as the input.
  
      """
  
      X = np.ascontiguousarray(X)
  
      s = X.shape
  
      if force.lower() == 'tomatrix':
          if len(s) != 1:
              raise ValueError("Forcing 'tomatrix' but input X is not a "
                               "distance vector.")
      elif force.lower() == 'tovector':
          if len(s) != 2:
              raise ValueError("Forcing 'tovector' but input X is not a "
                               "distance matrix.")
  
      # X = squareform(v)
      if len(s) == 1:
          if s[0] == 0:
              return np.zeros((1, 1), dtype=X.dtype)
  
          # Grab the closest value to the square root of the number
          # of elements times 2 to see if the number of elements
          # is indeed a binomial coefficient.
          d = int(np.ceil(np.sqrt(s[0] * 2)))
  
          # Check that v is of valid dimensions.
          if d * (d - 1) != s[0] * 2:
              raise ValueError('Incompatible vector size. It must be a binomial '
                               'coefficient n choose 2 for some integer n >= 2.')
  
          # Allocate memory for the distance matrix.
          M = np.zeros((d, d), dtype=X.dtype)
  
          # Since the C code does not support striding using strides.
          # The dimensions are used instead.
          X = _copy_array_if_base_present(X)
  
          # Fill in the values of the distance matrix.
          _distance_wrap.to_squareform_from_vector_wrap(M, X)
  
          # Return the distance matrix.
          return M
      elif len(s) == 2:
          if s[0] != s[1]:
              raise ValueError('The matrix argument must be square.')
          if checks:
              is_valid_dm(X, throw=True, name='X')
  
          # One-side of the dimensions is set here.
          d = s[0]
  
          if d <= 1:
              return np.array([], dtype=X.dtype)
  
          # Create a vector.
          v = np.zeros((d * (d - 1)) // 2, dtype=X.dtype)
  
          # Since the C code does not support striding using strides.
          # The dimensions are used instead.
          X = _copy_array_if_base_present(X)
  
          # Convert the vector to squareform.
          _distance_wrap.to_vector_from_squareform_wrap(X, v)
          return v
      else:
          raise ValueError(('The first argument must be one or two dimensional '
                            'array. A %d-dimensional array is not '
                            'permitted') % len(s))
function_tokens: def squareform ( X , force = "no" , checks = True ) : X = np . ascontiguousarray ( X ) s = X . shape if force . lower ( ) == 'tomatrix' : if len ( s ) != 1 : raise ValueError ( "Forcing 'tomatrix' but input X is not a " "distance vector." ) elif force . lower ( ) == 'tovector' : if len ( s ) != 2 : raise ValueError ( "Forcing 'tovector' but input X is not a " "distance matrix." ) # X = squareform(v) if len ( s ) == 1 : if s [ 0 ] == 0 : return np . zeros ( ( 1 , 1 ) , dtype = X . dtype ) # Grab the closest value to the square root of the number # of elements times 2 to see if the number of elements # is indeed a binomial coefficient. d = int ( np . ceil ( np . sqrt ( s [ 0 ] * 2 ) ) ) # Check that v is of valid dimensions. if d * ( d - 1 ) != s [ 0 ] * 2 : raise ValueError ( 'Incompatible vector size. It must be a binomial ' 'coefficient n choose 2 for some integer n >= 2.' ) # Allocate memory for the distance matrix. M = np . zeros ( ( d , d ) , dtype = X . dtype ) # Since the C code does not support striding using strides. # The dimensions are used instead. X = _copy_array_if_base_present ( X ) # Fill in the values of the distance matrix. _distance_wrap . to_squareform_from_vector_wrap ( M , X ) # Return the distance matrix. return M elif len ( s ) == 2 : if s [ 0 ] != s [ 1 ] : raise ValueError ( 'The matrix argument must be square.' ) if checks : is_valid_dm ( X , throw = True , name = 'X' ) # One-side of the dimensions is set here. d = s [ 0 ] if d <= 1 : return np . array ( [ ] , dtype = X . dtype ) # Create a vector. v = np . zeros ( ( d * ( d - 1 ) ) // 2 , dtype = X . dtype ) # Since the C code does not support striding using strides. # The dimensions are used instead. X = _copy_array_if_base_present ( X ) # Convert the vector to squareform. _distance_wrap . to_vector_from_squareform_wrap ( X , v ) return v else : raise ValueError ( ( 'The first argument must be one or two dimensional ' 'array. A %d-dimensional array is not ' 'permitted' ) % len ( s ) )