Skip to content

Spatial

ConvexHull

Module Scipy.​Spatial.​ConvexHull wraps Python class scipy.spatial.ConvexHull.

type t

create

constructor and attributes create
val create :
  ?incremental:bool ->
  ?qhull_options:string ->
  points:[>`Ndarray] Np.Obj.t ->
  unit ->
  t

ConvexHull(points, incremental=False, qhull_options=None)

Convex hulls in N dimensions.

.. versionadded:: 0.12.0

Parameters

  • points : ndarray of floats, shape (npoints, ndim) Coordinates of points to construct a convex hull from

  • incremental : bool, optional Allow adding new points incrementally. This takes up some additional resources.

  • qhull_options : str, optional Additional options to pass to Qhull. See Qhull manual for details. (Default: 'Qx' for ndim > 4 and '' otherwise) Option 'Qt' is always enabled.

Attributes

  • points : ndarray of double, shape (npoints, ndim) Coordinates of input points.

  • vertices : ndarray of ints, shape (nvertices,) Indices of points forming the vertices of the convex hull. For 2-D convex hulls, the vertices are in counterclockwise order. For other dimensions, they are in input order.

  • simplices : ndarray of ints, shape (nfacet, ndim) Indices of points forming the simplical facets of the convex hull.

  • neighbors : ndarray of ints, shape (nfacet, ndim) Indices of neighbor facets for each facet. The kth neighbor is opposite to the kth vertex. -1 denotes no neighbor.

  • equations : ndarray of double, shape (nfacet, ndim+1) [normal, offset] forming the hyperplane equation of the facet (see Qhull documentation <http://www.qhull.org/>__ for more).

  • coplanar : ndarray of int, shape (ncoplanar, 3) Indices of coplanar points and the corresponding indices of the nearest facets and nearest vertex indices. Coplanar points are input points which were not included in the triangulation due to numerical precision issues.

    If option 'Qc' is not specified, this list is not computed.

  • good : ndarray of bool or None A one-dimensional Boolean array indicating which facets are good. Used with options that compute good facets, e.g. QGn and QG-n. Good facets are defined as those that are visible (n) or invisible (-n) from point n, where n is the nth point in 'points'. The 'good' attribute may be used as an index into 'simplices' to return the good (visible)

  • facets: simplices[good]. A facet is visible from the outside of the hull only, and neither coplanarity nor degeneracy count as cases of visibility.

    If a 'QGn' or 'QG-n' option is not specified, None is returned.

    .. versionadded:: 1.3.0

  • area : float Area of the convex hull.

    .. versionadded:: 0.17.0

  • volume : float Volume of the convex hull.

    .. versionadded:: 0.17.0

Raises

QhullError Raised when Qhull encounters an error condition, such as geometrical degeneracy when options to resolve are not enabled. ValueError Raised if an incompatible array is given as input.

Notes

The convex hull is computed using the Qhull library <http://www.qhull.org/>__.

Examples

Convex hull of a random set of points:

>>> from scipy.spatial import ConvexHull, convex_hull_plot_2d
>>> points = np.random.rand(30, 2)   # 30 random points in 2-D
>>> hull = ConvexHull(points)

Plot it:

>>> import matplotlib.pyplot as plt
>>> plt.plot(points[:,0], points[:,1], 'o')
>>> for simplex in hull.simplices:
...     plt.plot(points[simplex, 0], points[simplex, 1], 'k-')

We could also have directly used the vertices of the hull, which for 2-D are guaranteed to be in counterclockwise order:

>>> plt.plot(points[hull.vertices,0], points[hull.vertices,1], 'r--', lw=2)
>>> plt.plot(points[hull.vertices[0],0], points[hull.vertices[0],1], 'ro')
>>> plt.show()

Facets visible from a point:

Create a square and add a point above the square.

>>> generators = np.array([[0.2, 0.2],
...                        [0.2, 0.4],
...                        [0.4, 0.4],
...                        [0.4, 0.2],
...                        [0.3, 0.6]])

Call ConvexHull with the QG option. QG4 means compute the portions of the hull not including point 4, indicating the facets that are visible from point 4.

>>> hull = ConvexHull(points=generators,
...                   qhull_options='QG4')

The 'good' array indicates which facets are visible from point 4.

>>> print(hull.simplices)
    [[1 0]
     [1 2]
     [3 0]
     [3 2]]
>>> print(hull.good)
    [False  True False False]

Now plot it, highlighting the visible facets.

>>> fig = plt.figure()
>>> ax = fig.add_subplot(1,1,1)
>>> for visible_facet in hull.simplices[hull.good]:
...     ax.plot(hull.points[visible_facet, 0],
...             hull.points[visible_facet, 1],
...             color='violet',
...             lw=6)
>>> convex_hull_plot_2d(hull, ax=ax)
    <Figure size 640x480 with 1 Axes> # may vary
>>> plt.show()

References

.. [Qhull] http://www.qhull.org/

add_points

method add_points
val add_points :
  ?restart:bool ->
  points:[>`Ndarray] Np.Obj.t ->
  [> tag] Obj.t ->
  Py.Object.t

add_points(points, restart=False)

Process a set of additional new points.

Parameters

  • points : ndarray New points to add. The dimensionality should match that of the initial points.

  • restart : bool, optional Whether to restart processing from scratch, rather than adding points incrementally.

Raises

QhullError Raised when Qhull encounters an error condition, such as geometrical degeneracy when options to resolve are not enabled.

See Also

close

Notes

You need to specify incremental=True when constructing the object to be able to add points incrementally. Incremental addition of points is also not possible after close has been called.

close

method close
val close :
  [> tag] Obj.t ->
  Py.Object.t

close()

Finish incremental processing.

Call this to free resources taken up by Qhull, when using the incremental mode. After calling this, adding more points is no longer possible.

points

attribute points
val points : t -> Py.Object.t
val points_opt : t -> (Py.Object.t) option

This attribute is documented in create above. The first version raises Not_found if the attribute is None. The _opt version returns an option.

vertices

attribute vertices
val vertices : t -> Py.Object.t
val vertices_opt : t -> (Py.Object.t) option

This attribute is documented in create above. The first version raises Not_found if the attribute is None. The _opt version returns an option.

simplices

attribute simplices
val simplices : t -> Py.Object.t
val simplices_opt : t -> (Py.Object.t) option

This attribute is documented in create above. The first version raises Not_found if the attribute is None. The _opt version returns an option.

neighbors

attribute neighbors
val neighbors : t -> Py.Object.t
val neighbors_opt : t -> (Py.Object.t) option

This attribute is documented in create above. The first version raises Not_found if the attribute is None. The _opt version returns an option.

equations

attribute equations
val equations : t -> Py.Object.t
val equations_opt : t -> (Py.Object.t) option

This attribute is documented in create above. The first version raises Not_found if the attribute is None. The _opt version returns an option.

coplanar

attribute coplanar
val coplanar : t -> Py.Object.t
val coplanar_opt : t -> (Py.Object.t) option

This attribute is documented in create above. The first version raises Not_found if the attribute is None. The _opt version returns an option.

good

attribute good
val good : t -> Py.Object.t
val good_opt : t -> (Py.Object.t) option

This attribute is documented in create above. The first version raises Not_found if the attribute is None. The _opt version returns an option.

area

attribute area
val area : t -> float
val area_opt : t -> (float) option

This attribute is documented in create above. The first version raises Not_found if the attribute is None. The _opt version returns an option.

volume

attribute volume
val volume : t -> float
val volume_opt : t -> (float) option

This attribute is documented in create above. The first version raises Not_found if the attribute is None. The _opt version returns an option.

to_string

method to_string
val to_string: t -> string

Print the object to a human-readable representation.

show

method show
val show: t -> string

Print the object to a human-readable representation.

pp

method pp
val pp: Format.formatter -> t -> unit

Pretty-print the object to a formatter.

Delaunay

Module Scipy.​Spatial.​Delaunay wraps Python class scipy.spatial.Delaunay.

type t

create

constructor and attributes create
val create :
  ?furthest_site:bool ->
  ?incremental:bool ->
  ?qhull_options:string ->
  points:[>`Ndarray] Np.Obj.t ->
  unit ->
  t

Delaunay(points, furthest_site=False, incremental=False, qhull_options=None)

Delaunay tessellation in N dimensions.

.. versionadded:: 0.9

Parameters

  • points : ndarray of floats, shape (npoints, ndim) Coordinates of points to triangulate

  • furthest_site : bool, optional Whether to compute a furthest-site Delaunay triangulation.

  • Default: False

    .. versionadded:: 0.12.0

  • incremental : bool, optional Allow adding new points incrementally. This takes up some additional resources.

  • qhull_options : str, optional Additional options to pass to Qhull. See Qhull manual for details. Option 'Qt' is always enabled.

  • Default:'Qbb Qc Qz Qx Q12' for ndim > 4 and 'Qbb Qc Qz Q12' otherwise. Incremental mode omits 'Qz'.

    .. versionadded:: 0.12.0

Attributes

  • points : ndarray of double, shape (npoints, ndim) Coordinates of input points.

  • simplices : ndarray of ints, shape (nsimplex, ndim+1) Indices of the points forming the simplices in the triangulation. For 2-D, the points are oriented counterclockwise.

  • neighbors : ndarray of ints, shape (nsimplex, ndim+1) Indices of neighbor simplices for each simplex. The kth neighbor is opposite to the kth vertex. For simplices at the boundary, -1 denotes no neighbor.

  • equations : ndarray of double, shape (nsimplex, ndim+2) [normal, offset] forming the hyperplane equation of the facet on the paraboloid (see Qhull documentation <http://www.qhull.org/> for more). paraboloid_scale, paraboloid_shift : float Scale and shift for the extra paraboloid dimension (see Qhull documentation <http://www.qhull.org/> for more).

  • transform : ndarray of double, shape (nsimplex, ndim+1, ndim) Affine transform from x to the barycentric coordinates c. This is defined by::

    T c = x - r
    

    At vertex j, c_j = 1 and the other coordinates zero.

    For simplex i, transform[i,:ndim,:ndim] contains inverse of the matrix T, and transform[i,ndim,:] contains the vector r.

    If the simplex is degenerate or nearly degenerate, its barycentric transform contains NaNs.

  • vertex_to_simplex : ndarray of int, shape (npoints,) Lookup array, from a vertex, to some simplex which it is a part of. If qhull option 'Qc' was not specified, the list will contain -1 for points that are not vertices of the tessellation.

  • convex_hull : ndarray of int, shape (nfaces, ndim) Vertices of facets forming the convex hull of the point set. The array contains the indices of the points belonging to the (N-1)-dimensional facets that form the convex hull of the triangulation.

    .. note::

    Computing convex hulls via the Delaunay triangulation is inefficient and subject to increased numerical instability. Use ConvexHull instead.

  • coplanar : ndarray of int, shape (ncoplanar, 3) Indices of coplanar points and the corresponding indices of the nearest facet and the nearest vertex. Coplanar points are input points which were not included in the triangulation due to numerical precision issues.

    If option 'Qc' is not specified, this list is not computed.

    .. versionadded:: 0.12.0 vertices Same as simplices, but deprecated.

  • vertex_neighbor_vertices : tuple of two ndarrays of int; (indptr, indices) Neighboring vertices of vertices. The indices of neighboring vertices of vertex k are indices[indptr[k]:indptr[k+1]]. furthest_site True if this was a furthest site triangulation and False if not.

    .. versionadded:: 1.4.0

Raises

QhullError Raised when Qhull encounters an error condition, such as geometrical degeneracy when options to resolve are not enabled. ValueError Raised if an incompatible array is given as input.

Notes

The tessellation is computed using the Qhull library Qhull library <http://www.qhull.org/>__.

.. note::

Unless you pass in the Qhull option 'QJ', Qhull does not guarantee that each input point appears as a vertex in the Delaunay triangulation. Omitted points are listed in the coplanar attribute.

Examples

Triangulation of a set of points:

>>> points = np.array([[0, 0], [0, 1.1], [1, 0], [1, 1]])
>>> from scipy.spatial import Delaunay
>>> tri = Delaunay(points)

We can plot it:

>>> import matplotlib.pyplot as plt
>>> plt.triplot(points[:,0], points[:,1], tri.simplices)
>>> plt.plot(points[:,0], points[:,1], 'o')
>>> plt.show()

Point indices and coordinates for the two triangles forming the triangulation:

>>> tri.simplices
array([[2, 3, 0],                 # may vary
       [3, 1, 0]], dtype=int32)

Note that depending on how rounding errors go, the simplices may be in a different order than above.

>>> points[tri.simplices]
array([[[ 1. ,  0. ],            # may vary
        [ 1. ,  1. ],
        [ 0. ,  0. ]],
       [[ 1. ,  1. ],
        [ 0. ,  1.1],
        [ 0. ,  0. ]]])

Triangle 0 is the only neighbor of triangle 1, and it's opposite to vertex 1 of triangle 1:

>>> tri.neighbors[1]
array([-1,  0, -1], dtype=int32)
>>> points[tri.simplices[1,1]]
array([ 0. ,  1.1])

We can find out which triangle points are in:

>>> p = np.array([(0.1, 0.2), (1.5, 0.5), (0.5, 1.05)])
>>> tri.find_simplex(p)
array([ 1, -1, 1], dtype=int32)

The returned integers in the array are the indices of the simplex the corresponding point is in. If -1 is returned, the point is in no simplex. Be aware that the shortcut in the following example only works corretcly for valid points as invalid points result in -1 which is itself a valid index for the last simplex in the list.

>>> p_valids = np.array([(0.1, 0.2), (0.5, 1.05)])
>>> tri.simplices[tri.find_simplex(p_valids)]
array([[3, 1, 0],                 # may vary
       [3, 1, 0]], dtype=int32)

We can also compute barycentric coordinates in triangle 1 for these points:

>>> b = tri.transform[1,:2].dot(np.transpose(p - tri.transform[1,2]))
>>> np.c_[np.transpose(b), 1 - b.sum(axis=0)]
array([[ 0.1       ,  0.09090909,  0.80909091],
       [ 1.5       , -0.90909091,  0.40909091],
       [ 0.5       ,  0.5       ,  0.        ]])

The coordinates for the first point are all positive, meaning it is indeed inside the triangle. The third point is on a vertex, hence its null third coordinate.

add_points

method add_points
val add_points :
  ?restart:bool ->
  points:[>`Ndarray] Np.Obj.t ->
  [> tag] Obj.t ->
  Py.Object.t

add_points(points, restart=False)

Process a set of additional new points.

Parameters

  • points : ndarray New points to add. The dimensionality should match that of the initial points.

  • restart : bool, optional Whether to restart processing from scratch, rather than adding points incrementally.

Raises

QhullError Raised when Qhull encounters an error condition, such as geometrical degeneracy when options to resolve are not enabled.

See Also

close

Notes

You need to specify incremental=True when constructing the object to be able to add points incrementally. Incremental addition of points is also not possible after close has been called.

close

method close
val close :
  [> tag] Obj.t ->
  Py.Object.t

close()

Finish incremental processing.

Call this to free resources taken up by Qhull, when using the incremental mode. After calling this, adding more points is no longer possible.

find_simplex

method find_simplex
val find_simplex :
  ?bruteforce:bool ->
  ?tol:float ->
  xi:Py.Object.t ->
  [> tag] Obj.t ->
  Py.Object.t

find_simplex(self, xi, bruteforce=False, tol=None)

Find the simplices containing the given points.

Parameters

  • tri : DelaunayInfo Delaunay triangulation

  • xi : ndarray of double, shape (..., ndim) Points to locate

  • bruteforce : bool, optional Whether to only perform a brute-force search

  • tol : float, optional Tolerance allowed in the inside-triangle check. Default is 100*eps.

Returns

  • i : ndarray of int, same shape as xi Indices of simplices containing each point. Points outside the triangulation get the value -1.

Notes

This uses an algorithm adapted from Qhull's qh_findbestfacet, which makes use of the connection between a convex hull and a Delaunay triangulation. After finding the simplex closest to the point in N+1 dimensions, the algorithm falls back to directed search in N dimensions.

lift_points

method lift_points
val lift_points :
  x:Py.Object.t ->
  [> tag] Obj.t ->
  Py.Object.t

lift_points(self, x)

Lift points to the Qhull paraboloid.

plane_distance

method plane_distance
val plane_distance :
  xi:Py.Object.t ->
  [> tag] Obj.t ->
  Py.Object.t

plane_distance(self, xi)

Compute hyperplane distances to the point xi from all simplices.

points

attribute points
val points : t -> Py.Object.t
val points_opt : t -> (Py.Object.t) option

This attribute is documented in create above. The first version raises Not_found if the attribute is None. The _opt version returns an option.

simplices

attribute simplices
val simplices : t -> Py.Object.t
val simplices_opt : t -> (Py.Object.t) option

This attribute is documented in create above. The first version raises Not_found if the attribute is None. The _opt version returns an option.

neighbors

attribute neighbors
val neighbors : t -> Py.Object.t
val neighbors_opt : t -> (Py.Object.t) option

This attribute is documented in create above. The first version raises Not_found if the attribute is None. The _opt version returns an option.

equations

attribute equations
val equations : t -> Py.Object.t
val equations_opt : t -> (Py.Object.t) option

This attribute is documented in create above. The first version raises Not_found if the attribute is None. The _opt version returns an option.

transform

attribute transform
val transform : t -> Py.Object.t
val transform_opt : t -> (Py.Object.t) option

This attribute is documented in create above. The first version raises Not_found if the attribute is None. The _opt version returns an option.

vertex_to_simplex

attribute vertex_to_simplex
val vertex_to_simplex : t -> Py.Object.t
val vertex_to_simplex_opt : t -> (Py.Object.t) option

This attribute is documented in create above. The first version raises Not_found if the attribute is None. The _opt version returns an option.

convex_hull

attribute convex_hull
val convex_hull : t -> Py.Object.t
val convex_hull_opt : t -> (Py.Object.t) option

This attribute is documented in create above. The first version raises Not_found if the attribute is None. The _opt version returns an option.

coplanar

attribute coplanar
val coplanar : t -> Py.Object.t
val coplanar_opt : t -> (Py.Object.t) option

This attribute is documented in create above. The first version raises Not_found if the attribute is None. The _opt version returns an option.

vertices

attribute vertices
val vertices : t -> Py.Object.t
val vertices_opt : t -> (Py.Object.t) option

This attribute is documented in create above. The first version raises Not_found if the attribute is None. The _opt version returns an option.

vertex_neighbor_vertices

attribute vertex_neighbor_vertices
val vertex_neighbor_vertices : t -> Py.Object.t
val vertex_neighbor_vertices_opt : t -> (Py.Object.t) option

This attribute is documented in create above. The first version raises Not_found if the attribute is None. The _opt version returns an option.

furthest_site

attribute furthest_site
val furthest_site : t -> Py.Object.t
val furthest_site_opt : t -> (Py.Object.t) option

This attribute is documented in create above. The first version raises Not_found if the attribute is None. The _opt version returns an option.

to_string

method to_string
val to_string: t -> string

Print the object to a human-readable representation.

show

method show
val show: t -> string

Print the object to a human-readable representation.

pp

method pp
val pp: Format.formatter -> t -> unit

Pretty-print the object to a formatter.

HalfspaceIntersection

Module Scipy.​Spatial.​HalfspaceIntersection wraps Python class scipy.spatial.HalfspaceIntersection.

type t

create

constructor and attributes create
val create :
  ?incremental:bool ->
  ?qhull_options:string ->
  halfspaces:[>`Ndarray] Np.Obj.t ->
  interior_point:[>`Ndarray] Np.Obj.t ->
  unit ->
  t

HalfspaceIntersection(halfspaces, interior_point, incremental=False, qhull_options=None)

Halfspace intersections in N dimensions.

.. versionadded:: 0.19.0

Parameters

  • halfspaces : ndarray of floats, shape (nineq, ndim+1) Stacked Inequalities of the form Ax + b <= 0 in format [A; b]

  • interior_point : ndarray of floats, shape (ndim,) Point clearly inside the region defined by halfspaces. Also called a feasible point, it can be obtained by linear programming.

  • incremental : bool, optional Allow adding new halfspaces incrementally. This takes up some additional resources.

  • qhull_options : str, optional Additional options to pass to Qhull. See Qhull manual for details. (Default: 'Qx' for ndim > 4 and '' otherwise) Option 'H' is always enabled.

Attributes

  • halfspaces : ndarray of double, shape (nineq, ndim+1) Input halfspaces.

  • interior_point :ndarray of floats, shape (ndim,) Input interior point.

  • intersections : ndarray of double, shape (ninter, ndim) Intersections of all halfspaces.

  • dual_points : ndarray of double, shape (nineq, ndim) Dual points of the input halfspaces.

  • dual_facets : list of lists of ints Indices of points forming the (non necessarily simplicial) facets of the dual convex hull.

  • dual_vertices : ndarray of ints, shape (nvertices,) Indices of halfspaces forming the vertices of the dual convex hull. For 2-D convex hulls, the vertices are in counterclockwise order. For other dimensions, they are in input order.

  • dual_equations : ndarray of double, shape (nfacet, ndim+1) [normal, offset] forming the hyperplane equation of the dual facet (see Qhull documentation <http://www.qhull.org/>__ for more).

  • dual_area : float Area of the dual convex hull

  • dual_volume : float Volume of the dual convex hull

Raises

QhullError Raised when Qhull encounters an error condition, such as geometrical degeneracy when options to resolve are not enabled. ValueError Raised if an incompatible array is given as input.

Notes

The intersections are computed using the Qhull library <http://www.qhull.org/>__. This reproduces the 'qhalf' functionality of Qhull.

Examples

Halfspace intersection of planes forming some polygon

>>> from scipy.spatial import HalfspaceIntersection
>>> halfspaces = np.array([[-1, 0., 0.],
...                        [0., -1., 0.],
...                        [2., 1., -4.],
...                        [-0.5, 1., -2.]])
>>> feasible_point = np.array([0.5, 0.5])
>>> hs = HalfspaceIntersection(halfspaces, feasible_point)

Plot halfspaces as filled regions and intersection points:

>>> import matplotlib.pyplot as plt
>>> fig = plt.figure()
>>> ax = fig.add_subplot(1, 1, 1, aspect='equal')
>>> xlim, ylim = (-1, 3), (-1, 3)
>>> ax.set_xlim(xlim)
>>> ax.set_ylim(ylim)
>>> x = np.linspace(-1, 3, 100)
>>> symbols = ['-', '+', 'x', '*']
>>> signs = [0, 0, -1, -1]
>>> fmt = {'color': None, 'edgecolor': 'b', 'alpha': 0.5}
>>> for h, sym, sign in zip(halfspaces, symbols, signs):
...     hlist = h.tolist()
...     fmt['hatch'] = sym
...     if h[1]== 0:
...         ax.axvline(-h[2]/h[0], label='{}x+{}y+{}=0'.format( *hlist))
...         xi = np.linspace(xlim[sign], -h[2]/h[0], 100)
...         ax.fill_between(xi, ylim[0], ylim[1], **fmt)
...     else:
...         ax.plot(x, (-h[2]-h[0]*x)/h[1], label='{}x+{}y+{}=0'.format( *hlist))
...         ax.fill_between(x, (-h[2]-h[0]*x)/h[1], ylim[sign], **fmt)
>>> x, y = zip( *hs.intersections)
>>> ax.plot(x, y, 'o', markersize=8)

By default, qhull does not provide with a way to compute an interior point. This can easily be computed using linear programming. Considering halfspaces of the form :math:Ax + b \leq 0, solving the linear program:

max \: y
s.t. Ax + y ||A_i|| \leq -b
  • With :math:A_i being the rows of A, i.e. the normals to each plane.

Will yield a point x that is furthest inside the convex polyhedron. To be precise, it is the center of the largest hypersphere of radius y inscribed in the polyhedron. This point is called the Chebyshev center of the polyhedron (see [1]_ 4.3.1, pp148-149). The equations outputted by Qhull are always normalized.

>>> from scipy.optimize import linprog
>>> from matplotlib.patches import Circle
>>> norm_vector = np.reshape(np.linalg.norm(halfspaces[:, :-1], axis=1),
...     (halfspaces.shape[0], 1))
>>> c = np.zeros((halfspaces.shape[1],))
>>> c[-1] = -1
>>> A = np.hstack((halfspaces[:, :-1], norm_vector))
>>> b = - halfspaces[:, -1:]
>>> res = linprog(c, A_ub=A, b_ub=b, bounds=(None, None))
>>> x = res.x[:-1]
>>> y = res.x[-1]
>>> circle = Circle(x, radius=y, alpha=0.3)
>>> ax.add_patch(circle)
>>> plt.legend(bbox_to_anchor=(1.6, 1.0))
>>> plt.show()

References

.. [Qhull] http://www.qhull.org/ .. [1] S. Boyd, L. Vandenberghe, Convex Optimization, available at http://stanford.edu/~boyd/cvxbook/

add_halfspaces

method add_halfspaces
val add_halfspaces :
  ?restart:bool ->
  halfspaces:[>`Ndarray] Np.Obj.t ->
  [> tag] Obj.t ->
  Py.Object.t

add_halfspaces(halfspaces, restart=False)

Process a set of additional new halfspaces.

Parameters

  • halfspaces : ndarray New halfspaces to add. The dimensionality should match that of the initial halfspaces.

  • restart : bool, optional Whether to restart processing from scratch, rather than adding halfspaces incrementally.

Raises

QhullError Raised when Qhull encounters an error condition, such as geometrical degeneracy when options to resolve are not enabled.

See Also

close

Notes

You need to specify incremental=True when constructing the object to be able to add halfspaces incrementally. Incremental addition of halfspaces is also not possible after close has been called.

close

method close
val close :
  [> tag] Obj.t ->
  Py.Object.t

close()

Finish incremental processing.

Call this to free resources taken up by Qhull, when using the incremental mode. After calling this, adding more points is no longer possible.

halfspaces

attribute halfspaces
val halfspaces : t -> Py.Object.t
val halfspaces_opt : t -> (Py.Object.t) option

This attribute is documented in create above. The first version raises Not_found if the attribute is None. The _opt version returns an option.

interior_point

attribute interior_point
val interior_point : t -> [`ArrayLike|`Ndarray|`Object] Np.Obj.t
val interior_point_opt : t -> ([`ArrayLike|`Ndarray|`Object] Np.Obj.t) option

This attribute is documented in create above. The first version raises Not_found if the attribute is None. The _opt version returns an option.

intersections

attribute intersections
val intersections : t -> Py.Object.t
val intersections_opt : t -> (Py.Object.t) option

This attribute is documented in create above. The first version raises Not_found if the attribute is None. The _opt version returns an option.

dual_points

attribute dual_points
val dual_points : t -> Py.Object.t
val dual_points_opt : t -> (Py.Object.t) option

This attribute is documented in create above. The first version raises Not_found if the attribute is None. The _opt version returns an option.

dual_facets

attribute dual_facets
val dual_facets : t -> Py.Object.t
val dual_facets_opt : t -> (Py.Object.t) option

This attribute is documented in create above. The first version raises Not_found if the attribute is None. The _opt version returns an option.

dual_vertices

attribute dual_vertices
val dual_vertices : t -> Py.Object.t
val dual_vertices_opt : t -> (Py.Object.t) option

This attribute is documented in create above. The first version raises Not_found if the attribute is None. The _opt version returns an option.

dual_equations

attribute dual_equations
val dual_equations : t -> Py.Object.t
val dual_equations_opt : t -> (Py.Object.t) option

This attribute is documented in create above. The first version raises Not_found if the attribute is None. The _opt version returns an option.

dual_area

attribute dual_area
val dual_area : t -> float
val dual_area_opt : t -> (float) option

This attribute is documented in create above. The first version raises Not_found if the attribute is None. The _opt version returns an option.

dual_volume

attribute dual_volume
val dual_volume : t -> float
val dual_volume_opt : t -> (float) option

This attribute is documented in create above. The first version raises Not_found if the attribute is None. The _opt version returns an option.

to_string

method to_string
val to_string: t -> string

Print the object to a human-readable representation.

show

method show
val show: t -> string

Print the object to a human-readable representation.

pp

method pp
val pp: Format.formatter -> t -> unit

Pretty-print the object to a formatter.

KDTree

Module Scipy.​Spatial.​KDTree wraps Python class scipy.spatial.KDTree.

type t

create

constructor and attributes create
val create :
  ?leafsize:int ->
  data:Py.Object.t ->
  unit ->
  t

kd-tree for quick nearest-neighbor lookup

This class provides an index into a set of k-D points which can be used to rapidly look up the nearest neighbors of any point.

Parameters

  • data : (N,K) array_like The data points to be indexed. This array is not copied, and so modifying this data will result in bogus results.

  • leafsize : int, optional The number of points at which the algorithm switches over to brute-force. Has to be positive.

Raises

RuntimeError The maximum recursion limit can be exceeded for large data sets. If this happens, either increase the value for the leafsize parameter or increase the recursion limit by::

    >>> import sys
    >>> sys.setrecursionlimit(10000)

See Also

  • cKDTree : Implementation of KDTree in Cython

Notes

The algorithm used is described in Maneewongvatana and Mount 1999. The general idea is that the kd-tree is a binary tree, each of whose nodes represents an axis-aligned hyperrectangle. Each node specifies an axis and splits the set of points based on whether their coordinate along that axis is greater than or less than a particular value.

During construction, the axis and splitting point are chosen by the 'sliding midpoint' rule, which ensures that the cells do not all become long and thin.

The tree can be queried for the r closest neighbors of any given point (optionally returning only those within some maximum distance of the point). It can also be queried, with a substantial gain in efficiency, for the r approximate closest neighbors.

For large dimensions (20 is already large) do not expect this to run significantly faster than brute force. High-dimensional nearest-neighbor queries are a substantial open problem in computer science.

The tree also supports all-neighbors queries, both with arrays of points and with other kd-trees. These do use a reasonably efficient algorithm, but the kd-tree is not necessarily the best data structure for this sort of calculation.

count_neighbors

method count_neighbors
val count_neighbors :
  ?p:[`F of float | `T1_p_infinity of Py.Object.t] ->
  other:Py.Object.t ->
  r:[`F of float | `Ndarray of [>`Ndarray] Np.Obj.t] ->
  [> tag] Obj.t ->
  Py.Object.t

Count how many nearby pairs can be formed.

Count the number of pairs (x1,x2) can be formed, with x1 drawn from self and x2 drawn from other, and where distance(x1, x2, p) <= r. This is the 'two-point correlation' described in Gray and Moore 2000, 'N-body problems in statistical learning', and the code here is based on their algorithm.

Parameters

  • other : KDTree instance The other tree to draw points from.

  • r : float or one-dimensional array of floats The radius to produce a count for. Multiple radii are searched with a single tree traversal.

  • p : float, 1<=p<=infinity, optional Which Minkowski p-norm to use

Returns

  • result : int or 1-D array of ints The number of pairs. Note that this is internally stored in a numpy int, and so may overflow if very large (2e9).

query

method query
val query :
  ?k:int ->
  ?eps:Py.Object.t ->
  ?p:[`F of float | `T1_p_infinity of Py.Object.t] ->
  ?distance_upper_bound:Py.Object.t ->
  x:[`Ndarray of [>`Ndarray] Np.Obj.t | `Last_dimension_self_m of Py.Object.t] ->
  [> tag] Obj.t ->
  (Py.Object.t * Py.Object.t)

Query the kd-tree for nearest neighbors

Parameters

  • x : array_like, last dimension self.m An array of points to query.

  • k : int, optional The number of nearest neighbors to return.

  • eps : nonnegative float, optional Return approximate nearest neighbors; the kth returned value is guaranteed to be no further than (1+eps) times the distance to the real kth nearest neighbor.

  • p : float, 1<=p<=infinity, optional Which Minkowski p-norm to use. 1 is the sum-of-absolute-values 'Manhattan' distance 2 is the usual Euclidean distance infinity is the maximum-coordinate-difference distance

  • distance_upper_bound : nonnegative float, optional Return only neighbors within this distance. This is used to prune tree searches, so if you are doing a series of nearest-neighbor queries, it may help to supply the distance to the nearest neighbor of the most recent point.

Returns

  • d : float or array of floats The distances to the nearest neighbors. If x has shape tuple+(self.m,), then d has shape tuple if k is one, or tuple+(k,) if k is larger than one. Missing neighbors (e.g. when k > n or distance_upper_bound is given) are indicated with infinite distances. If k is None, then d is an object array of shape tuple, containing lists of distances. In either case the hits are sorted by distance (nearest first).

  • i : integer or array of integers The locations of the neighbors in self.data. i is the same shape as d.

Examples

>>> from scipy import spatial
>>> x, y = np.mgrid[0:5, 2:8]
>>> tree = spatial.KDTree(list(zip(x.ravel(), y.ravel())))
>>> tree.data
array([[0, 2],
       [0, 3],
       [0, 4],
       [0, 5],
       [0, 6],
       [0, 7],
       [1, 2],
       [1, 3],
       [1, 4],
       [1, 5],
       [1, 6],
       [1, 7],
       [2, 2],
       [2, 3],
       [2, 4],
       [2, 5],
       [2, 6],
       [2, 7],
       [3, 2],
       [3, 3],
       [3, 4],
       [3, 5],
       [3, 6],
       [3, 7],
       [4, 2],
       [4, 3],
       [4, 4],
       [4, 5],
       [4, 6],
       [4, 7]])
>>> pts = np.array([[0, 0], [2.1, 2.9]])
>>> tree.query(pts)
(array([ 2.        ,  0.14142136]), array([ 0, 13]))
>>> tree.query(pts[0])
(2.0, 0)

query_ball_point

method query_ball_point
val query_ball_point :
  ?p:float ->
  ?eps:Py.Object.t ->
  x:[`Ndarray of [>`Ndarray] Np.Obj.t | `Shape_tuple_self_m_ of Py.Object.t] ->
  r:float ->
  [> tag] Obj.t ->
  Py.Object.t

Find all points within distance r of point(s) x.

Parameters

  • x : array_like, shape tuple + (self.m,) The point or points to search for neighbors of.

  • r : positive float The radius of points to return.

  • p : float, optional Which Minkowski p-norm to use. Should be in the range [1, inf].

  • eps : nonnegative float, optional Approximate search. Branches of the tree are not explored if their nearest points are further than r / (1 + eps), and branches are added in bulk if their furthest points are nearer than r * (1 + eps).

Returns

  • results : list or array of lists If x is a single point, returns a list of the indices of the neighbors of x. If x is an array of points, returns an object array of shape tuple containing lists of neighbors.

Notes

If you have many points whose neighbors you want to find, you may save substantial amounts of time by putting them in a KDTree and using query_ball_tree.

Examples

>>> from scipy import spatial
>>> x, y = np.mgrid[0:5, 0:5]
>>> points = np.c_[x.ravel(), y.ravel()]
>>> tree = spatial.KDTree(points)
>>> tree.query_ball_point([2, 0], 1)
[5, 10, 11, 15]

Query multiple points and plot the results:

>>> import matplotlib.pyplot as plt
>>> points = np.asarray(points)
>>> plt.plot(points[:,0], points[:,1], '.')
>>> for results in tree.query_ball_point(([2, 0], [3, 3]), 1):
...     nearby_points = points[results]
...     plt.plot(nearby_points[:,0], nearby_points[:,1], 'o')
>>> plt.margins(0.1, 0.1)
>>> plt.show()

query_ball_tree

method query_ball_tree
val query_ball_tree :
  ?p:float ->
  ?eps:float ->
  other:Py.Object.t ->
  r:float ->
  [> tag] Obj.t ->
  Py.Object.t

Find all pairs of points whose distance is at most r

Parameters

  • other : KDTree instance The tree containing points to search against.

  • r : float The maximum distance, has to be positive.

  • p : float, optional Which Minkowski norm to use. p has to meet the condition 1 <= p <= infinity.

  • eps : float, optional Approximate search. Branches of the tree are not explored if their nearest points are further than r/(1+eps), and branches are added in bulk if their furthest points are nearer than r * (1+eps). eps has to be non-negative.

Returns

  • results : list of lists For each element self.data[i] of this tree, results[i] is a list of the indices of its neighbors in other.data.

query_pairs

method query_pairs
val query_pairs :
  ?p:float ->
  ?eps:float ->
  r:float ->
  [> tag] Obj.t ->
  Py.Object.t

Find all pairs of points within a distance.

Parameters

  • r : positive float The maximum distance.

  • p : float, optional Which Minkowski norm to use. p has to meet the condition 1 <= p <= infinity.

  • eps : float, optional Approximate search. Branches of the tree are not explored if their nearest points are further than r/(1+eps), and branches are added in bulk if their furthest points are nearer than r * (1+eps). eps has to be non-negative.

Returns

  • results : set Set of pairs (i,j), with i < j, for which the corresponding positions are close.

sparse_distance_matrix

method sparse_distance_matrix
val sparse_distance_matrix :
  ?p:float ->
  other:Py.Object.t ->
  max_distance:float ->
  [> tag] Obj.t ->
  Py.Object.t

Compute a sparse distance matrix

Computes a distance matrix between two KDTrees, leaving as zero any distance greater than max_distance.

Parameters

  • other : KDTree

  • max_distance : positive float

  • p : float, optional

Returns

  • result : dok_matrix Sparse matrix representing the results in 'dictionary of keys' format.

to_string

method to_string
val to_string: t -> string

Print the object to a human-readable representation.

show

method show
val show: t -> string

Print the object to a human-readable representation.

pp

method pp
val pp: Format.formatter -> t -> unit

Pretty-print the object to a formatter.

Rectangle

Module Scipy.​Spatial.​Rectangle wraps Python class scipy.spatial.Rectangle.

type t

create

constructor and attributes create
val create :
  maxes:Py.Object.t ->
  mins:Py.Object.t ->
  unit ->
  t

Hyperrectangle class.

Represents a Cartesian product of intervals.

max_distance_point

method max_distance_point
val max_distance_point :
  ?p:float ->
  x:[>`Ndarray] Np.Obj.t ->
  [> tag] Obj.t ->
  Py.Object.t

Return the maximum distance between input and points in the hyperrectangle.

Parameters

  • x : array_like Input array.

  • p : float, optional Input.

max_distance_rectangle

method max_distance_rectangle
val max_distance_rectangle :
  ?p:float ->
  other:Py.Object.t ->
  [> tag] Obj.t ->
  Py.Object.t

Compute the maximum distance between points in the two hyperrectangles.

Parameters

  • other : hyperrectangle Input.

  • p : float, optional Input.

min_distance_point

method min_distance_point
val min_distance_point :
  ?p:float ->
  x:[>`Ndarray] Np.Obj.t ->
  [> tag] Obj.t ->
  Py.Object.t

Return the minimum distance between input and points in the hyperrectangle.

Parameters

  • x : array_like Input.

  • p : float, optional Input.

min_distance_rectangle

method min_distance_rectangle
val min_distance_rectangle :
  ?p:float ->
  other:Py.Object.t ->
  [> tag] Obj.t ->
  Py.Object.t

Compute the minimum distance between points in the two hyperrectangles.

Parameters

  • other : hyperrectangle Input.

  • p : float Input.

split

method split
val split :
  d:int ->
  split:float ->
  [> tag] Obj.t ->
  Py.Object.t

Produce two hyperrectangles by splitting.

In general, if you need to compute maximum and minimum distances to the children, it can be done more efficiently by updating the maximum and minimum distances to the parent.

Parameters

  • d : int Axis to split hyperrectangle along.

  • split : float Position along axis d to split at.

volume

method volume
val volume :
  [> tag] Obj.t ->
  Py.Object.t

Total volume.

to_string

method to_string
val to_string: t -> string

Print the object to a human-readable representation.

show

method show
val show: t -> string

Print the object to a human-readable representation.

pp

method pp
val pp: Format.formatter -> t -> unit

Pretty-print the object to a formatter.

SphericalVoronoi

Module Scipy.​Spatial.​SphericalVoronoi wraps Python class scipy.spatial.SphericalVoronoi.

type t

create

constructor and attributes create
val create :
  ?radius:float ->
  ?center:[>`Ndarray] Np.Obj.t ->
  ?threshold:float ->
  points:[>`Ndarray] Np.Obj.t ->
  unit ->
  t

Voronoi diagrams on the surface of a sphere.

.. versionadded:: 0.18.0

Parameters

  • points : ndarray of floats, shape (npoints, ndim) Coordinates of points from which to construct a spherical Voronoi diagram.

  • radius : float, optional Radius of the sphere (Default: 1)

  • center : ndarray of floats, shape (ndim,) Center of sphere (Default: origin)

  • threshold : float Threshold for detecting duplicate points and mismatches between points and sphere parameters. (Default: 1e-06)

Attributes

  • points : double array of shape (npoints, ndim) the points in ndim dimensions to generate the Voronoi diagram from

  • radius : double radius of the sphere

  • center : double array of shape (ndim,) center of the sphere

  • vertices : double array of shape (nvertices, ndim) Voronoi vertices corresponding to points

  • regions : list of list of integers of shape (npoints, _ ) the n-th entry is a list consisting of the indices of the vertices belonging to the n-th point in points

Methods

calculate_areas Calculates the areas of the Voronoi regions. For 2D point sets, the regions are circular arcs. The sum of the areas is 2 * pi * radius. For 3D point sets, the regions are spherical polygons. The sum of the areas is 4 * pi * radius**2.

Raises

ValueError If there are duplicates in points. If the provided radius is not consistent with points.

Notes

The spherical Voronoi diagram algorithm proceeds as follows. The Convex Hull of the input points (generators) is calculated, and is equivalent to their Delaunay triangulation on the surface of the sphere [Caroli]_. The Convex Hull neighbour information is then used to order the Voronoi region vertices around each generator. The latter approach is substantially less sensitive to floating point issues than angle-based methods of Voronoi region vertex sorting.

Empirical assessment of spherical Voronoi algorithm performance suggests quadratic time complexity (loglinear is optimal, but algorithms are more challenging to implement).

References

.. [Caroli] Caroli et al. Robust and Efficient Delaunay triangulations of points on or close to a sphere. Research Report RR-7004, 2009.

.. [VanOosterom] Van Oosterom and Strackee. The solid angle of a plane triangle. IEEE Transactions on Biomedical Engineering, 2, 1983, pp 125--126.

See Also

  • Voronoi : Conventional Voronoi diagrams in N dimensions.

Examples

Do some imports and take some points on a cube:

>>> import matplotlib.pyplot as plt
>>> from scipy.spatial import SphericalVoronoi, geometric_slerp
>>> from mpl_toolkits.mplot3d import proj3d
>>> # set input data
>>> points = np.array([[0, 0, 1], [0, 0, -1], [1, 0, 0],
...                    [0, 1, 0], [0, -1, 0], [-1, 0, 0], ])

Calculate the spherical Voronoi diagram:

>>> radius = 1
>>> center = np.array([0, 0, 0])
>>> sv = SphericalVoronoi(points, radius, center)

Generate plot:

>>> # sort vertices (optional, helpful for plotting)
>>> sv.sort_vertices_of_regions()
>>> t_vals = np.linspace(0, 1, 2000)
>>> fig = plt.figure()
>>> ax = fig.add_subplot(111, projection='3d')
>>> # plot the unit sphere for reference (optional)
>>> u = np.linspace(0, 2 * np.pi, 100)
>>> v = np.linspace(0, np.pi, 100)
>>> x = np.outer(np.cos(u), np.sin(v))
>>> y = np.outer(np.sin(u), np.sin(v))
>>> z = np.outer(np.ones(np.size(u)), np.cos(v))
>>> ax.plot_surface(x, y, z, color='y', alpha=0.1)
>>> # plot generator points
>>> ax.scatter(points[:, 0], points[:, 1], points[:, 2], c='b')
>>> # plot Voronoi vertices
>>> ax.scatter(sv.vertices[:, 0], sv.vertices[:, 1], sv.vertices[:, 2],
...                    c='g')
>>> # indicate Voronoi regions (as Euclidean polygons)
>>> for region in sv.regions:
...    n = len(region)
...    for i in range(n):
...        start = sv.vertices[region][i]
...        end = sv.vertices[region][(i + 1) % n]
...        result = geometric_slerp(start, end, t_vals)
...        ax.plot(result[..., 0],
...                result[..., 1],
...                result[..., 2],
...                c='k')
>>> ax.azim = 10
>>> ax.elev = 40
>>> _ = ax.set_xticks([])
>>> _ = ax.set_yticks([])
>>> _ = ax.set_zticks([])
>>> fig.set_size_inches(4, 4)
>>> plt.show()

calculate_areas

method calculate_areas
val calculate_areas :
  [> tag] Obj.t ->
  Py.Object.t

Calculates the areas of the Voronoi regions.

For 2D point sets, the regions are circular arcs. The sum of the areas is 2 * pi * radius.

For 3D point sets, the regions are spherical polygons. The sum of the areas is 4 * pi * radius**2.

.. versionadded:: 1.5.0

Returns

  • areas : double array of shape (npoints,) The areas of the Voronoi regions.

sort_vertices_of_regions

method sort_vertices_of_regions
val sort_vertices_of_regions :
  [> tag] Obj.t ->
  Py.Object.t

Sort indices of the vertices to be (counter-)clockwise ordered.

Raises

TypeError If the points are not three-dimensional.

Notes

For each region in regions, it sorts the indices of the Voronoi vertices such that the resulting points are in a clockwise or counterclockwise order around the generator point.

This is done as follows: Recall that the n-th region in regions surrounds the n-th generator in points and that the k-th Voronoi vertex in vertices is the circumcenter of the k-th triangle in self._simplices. For each region n, we choose the first triangle (=Voronoi vertex) in self._simplices and a vertex of that triangle not equal to the center n. These determine a unique neighbor of that triangle, which is then chosen as the second triangle. The second triangle will have a unique vertex not equal to the current vertex or the center. This determines a unique neighbor of the second triangle, which is then chosen as the third triangle and so forth. We proceed through all the triangles (=Voronoi vertices) belonging to the generator in points and obtain a sorted version of the vertices of its surrounding region.

points

attribute points
val points : t -> Py.Object.t
val points_opt : t -> (Py.Object.t) option

This attribute is documented in create above. The first version raises Not_found if the attribute is None. The _opt version returns an option.

radius

attribute radius
val radius : t -> float
val radius_opt : t -> (float) option

This attribute is documented in create above. The first version raises Not_found if the attribute is None. The _opt version returns an option.

center

attribute center
val center : t -> Py.Object.t
val center_opt : t -> (Py.Object.t) option

This attribute is documented in create above. The first version raises Not_found if the attribute is None. The _opt version returns an option.

vertices

attribute vertices
val vertices : t -> Py.Object.t
val vertices_opt : t -> (Py.Object.t) option

This attribute is documented in create above. The first version raises Not_found if the attribute is None. The _opt version returns an option.

regions

attribute regions
val regions : t -> Py.Object.t
val regions_opt : t -> (Py.Object.t) option

This attribute is documented in create above. The first version raises Not_found if the attribute is None. The _opt version returns an option.

to_string

method to_string
val to_string: t -> string

Print the object to a human-readable representation.

show

method show
val show: t -> string

Print the object to a human-readable representation.

pp

method pp
val pp: Format.formatter -> t -> unit

Pretty-print the object to a formatter.

Voronoi

Module Scipy.​Spatial.​Voronoi wraps Python class scipy.spatial.Voronoi.

type t

create

constructor and attributes create
val create :
  ?furthest_site:bool ->
  ?incremental:bool ->
  ?qhull_options:string ->
  points:[>`Ndarray] Np.Obj.t ->
  unit ->
  t

Voronoi(points, furthest_site=False, incremental=False, qhull_options=None)

Voronoi diagrams in N dimensions.

.. versionadded:: 0.12.0

Parameters

  • points : ndarray of floats, shape (npoints, ndim) Coordinates of points to construct a convex hull from

  • furthest_site : bool, optional Whether to compute a furthest-site Voronoi diagram. Default: False

  • incremental : bool, optional Allow adding new points incrementally. This takes up some additional resources.

  • qhull_options : str, optional Additional options to pass to Qhull. See Qhull manual for details. (Default: 'Qbb Qc Qz Qx' for ndim > 4 and 'Qbb Qc Qz' otherwise. Incremental mode omits 'Qz'.)

Attributes

  • points : ndarray of double, shape (npoints, ndim) Coordinates of input points.

  • vertices : ndarray of double, shape (nvertices, ndim) Coordinates of the Voronoi vertices.

  • ridge_points : ndarray of ints, shape (nridges, 2) Indices of the points between which each Voronoi ridge lies.

  • ridge_vertices : list of list of ints, shape (nridges, * ) Indices of the Voronoi vertices forming each Voronoi ridge.

  • regions : list of list of ints, shape (nregions, * ) Indices of the Voronoi vertices forming each Voronoi region. -1 indicates vertex outside the Voronoi diagram.

  • point_region : list of ints, shape (npoints) Index of the Voronoi region for each input point. If qhull option 'Qc' was not specified, the list will contain -1 for points that are not associated with a Voronoi region. furthest_site True if this was a furthest site triangulation and False if not.

    .. versionadded:: 1.4.0

Raises

QhullError Raised when Qhull encounters an error condition, such as geometrical degeneracy when options to resolve are not enabled. ValueError Raised if an incompatible array is given as input.

Notes

The Voronoi diagram is computed using the Qhull library <http://www.qhull.org/>__.

Examples

Voronoi diagram for a set of point:

>>> points = np.array([[0, 0], [0, 1], [0, 2], [1, 0], [1, 1], [1, 2],
...                    [2, 0], [2, 1], [2, 2]])
>>> from scipy.spatial import Voronoi, voronoi_plot_2d
>>> vor = Voronoi(points)

Plot it:

>>> import matplotlib.pyplot as plt
>>> fig = voronoi_plot_2d(vor)
>>> plt.show()

The Voronoi vertices:

>>> vor.vertices
array([[0.5, 0.5],
       [0.5, 1.5],
       [1.5, 0.5],
       [1.5, 1.5]])

There is a single finite Voronoi region, and four finite Voronoi ridges:

>>> vor.regions
[[], [-1, 0], [-1, 1], [1, -1, 0], [3, -1, 2], [-1, 3], [-1, 2], [0, 1, 3, 2], [2, -1, 0], [3, -1, 1]]
>>> vor.ridge_vertices
[[-1, 0], [-1, 0], [-1, 1], [-1, 1], [0, 1], [-1, 3], [-1, 2], [2, 3], [-1, 3], [-1, 2], [1, 3], [0, 2]]

The ridges are perpendicular between lines drawn between the following input points:

>>> vor.ridge_points
array([[0, 3],
       [0, 1],
       [2, 5],
       [2, 1],
       [1, 4],
       [7, 8],
       [7, 6],
       [7, 4],
       [8, 5],
       [6, 3],
       [4, 5],
       [4, 3]], dtype=int32)

add_points

method add_points
val add_points :
  ?restart:bool ->
  points:[>`Ndarray] Np.Obj.t ->
  [> tag] Obj.t ->
  Py.Object.t

add_points(points, restart=False)

Process a set of additional new points.

Parameters

  • points : ndarray New points to add. The dimensionality should match that of the initial points.

  • restart : bool, optional Whether to restart processing from scratch, rather than adding points incrementally.

Raises

QhullError Raised when Qhull encounters an error condition, such as geometrical degeneracy when options to resolve are not enabled.

See Also

close

Notes

You need to specify incremental=True when constructing the object to be able to add points incrementally. Incremental addition of points is also not possible after close has been called.

close

method close
val close :
  [> tag] Obj.t ->
  Py.Object.t

close()

Finish incremental processing.

Call this to free resources taken up by Qhull, when using the incremental mode. After calling this, adding more points is no longer possible.

points

attribute points
val points : t -> Py.Object.t
val points_opt : t -> (Py.Object.t) option

This attribute is documented in create above. The first version raises Not_found if the attribute is None. The _opt version returns an option.

vertices

attribute vertices
val vertices : t -> Py.Object.t
val vertices_opt : t -> (Py.Object.t) option

This attribute is documented in create above. The first version raises Not_found if the attribute is None. The _opt version returns an option.

ridge_points

attribute ridge_points
val ridge_points : t -> Py.Object.t
val ridge_points_opt : t -> (Py.Object.t) option

This attribute is documented in create above. The first version raises Not_found if the attribute is None. The _opt version returns an option.

ridge_vertices

attribute ridge_vertices
val ridge_vertices : t -> Py.Object.t
val ridge_vertices_opt : t -> (Py.Object.t) option

This attribute is documented in create above. The first version raises Not_found if the attribute is None. The _opt version returns an option.

regions

attribute regions
val regions : t -> Py.Object.t
val regions_opt : t -> (Py.Object.t) option

This attribute is documented in create above. The first version raises Not_found if the attribute is None. The _opt version returns an option.

point_region

attribute point_region
val point_region : t -> Py.Object.t
val point_region_opt : t -> (Py.Object.t) option

This attribute is documented in create above. The first version raises Not_found if the attribute is None. The _opt version returns an option.

furthest_site

attribute furthest_site
val furthest_site : t -> Py.Object.t
val furthest_site_opt : t -> (Py.Object.t) option

This attribute is documented in create above. The first version raises Not_found if the attribute is None. The _opt version returns an option.

to_string

method to_string
val to_string: t -> string

Print the object to a human-readable representation.

show

method show
val show: t -> string

Print the object to a human-readable representation.

pp

method pp
val pp: Format.formatter -> t -> unit

Pretty-print the object to a formatter.

CKDTree

Module Scipy.​Spatial.​CKDTree wraps Python class scipy.spatial.cKDTree.

type t

create

constructor and attributes create
val create :
  ?leafsize:Py.Object.t ->
  ?compact_nodes:bool ->
  ?copy_data:bool ->
  ?balanced_tree:bool ->
  ?boxsize:[`S of string | `Ndarray of [>`Ndarray] Np.Obj.t | `I of int | `Bool of bool | `F of float] ->
  data:[>`Ndarray] Np.Obj.t ->
  unit ->
  t

cKDTree(data, leafsize=16, compact_nodes=True, copy_data=False, balanced_tree=True, boxsize=None)

kd-tree for quick nearest-neighbor lookup

This class provides an index into a set of k-dimensional points which can be used to rapidly look up the nearest neighbors of any point.

The algorithm used is described in Maneewongvatana and Mount 1999. The general idea is that the kd-tree is a binary trie, each of whose nodes represents an axis-aligned hyperrectangle. Each node specifies an axis and splits the set of points based on whether their coordinate along that axis is greater than or less than a particular value.

During construction, the axis and splitting point are chosen by the 'sliding midpoint' rule, which ensures that the cells do not all become long and thin.

The tree can be queried for the r closest neighbors of any given point (optionally returning only those within some maximum distance of the point). It can also be queried, with a substantial gain in efficiency, for the r approximate closest neighbors.

For large dimensions (20 is already large) do not expect this to run significantly faster than brute force. High-dimensional nearest-neighbor queries are a substantial open problem in computer science.

Parameters

  • data : array_like, shape (n,m) The n data points of dimension m to be indexed. This array is not copied unless this is necessary to produce a contiguous array of doubles, and so modifying this data will result in bogus results. The data are also copied if the kd-tree is built with copy_data=True.

  • leafsize : positive int, optional The number of points at which the algorithm switches over to brute-force. Default: 16.

  • compact_nodes : bool, optional If True, the kd-tree is built to shrink the hyperrectangles to the actual data range. This usually gives a more compact tree that is robust against degenerated input data and gives faster queries at the expense of longer build time. Default: True.

  • copy_data : bool, optional If True the data is always copied to protect the kd-tree against data corruption. Default: False.

  • balanced_tree : bool, optional If True, the median is used to split the hyperrectangles instead of the midpoint. This usually gives a more compact tree and faster queries at the expense of longer build time. Default: True.

  • boxsize : array_like or scalar, optional Apply a m-d toroidal topology to the KDTree.. The topology is generated

  • by :math:x_i + n_i L_i where :math:n_i are integers and :math:L_i is the boxsize along i-th dimension. The input data shall be wrapped

  • into :math:[0, L_i). A ValueError is raised if any of the data is outside of this bound.

Attributes

  • data : ndarray, shape (n,m) The n data points of dimension m to be indexed. This array is not copied unless this is necessary to produce a contiguous array of doubles. The data are also copied if the kd-tree is built with copy_data=True.

  • leafsize : positive int The number of points at which the algorithm switches over to brute-force.

  • m : int The dimension of a single data-point.

  • n : int The number of data points.

  • maxes : ndarray, shape (m,) The maximum value in each dimension of the n data points.

  • mins : ndarray, shape (m,) The minimum value in each dimension of the n data points.

  • tree : object, class cKDTreeNode This attribute exposes a Python view of the root node in the cKDTree object. A full Python view of the kd-tree is created dynamically on the first access. This attribute allows you to create your own query functions in Python.

  • size : int The number of nodes in the tree.

See Also

  • KDTree : Implementation of cKDTree in pure Python

count_neighbors

method count_neighbors
val count_neighbors :
  ?p:float ->
  ?weights:[`Ndarray of [>`Ndarray] Np.Obj.t | `Tuple of Py.Object.t] ->
  ?cumulative:bool ->
  other:Py.Object.t ->
  r:[`F of float | `Ndarray of [>`Ndarray] Np.Obj.t] ->
  [> tag] Obj.t ->
  Py.Object.t

count_neighbors(self, other, r, p=2., weights=None, cumulative=True)

Count how many nearby pairs can be formed. (pair-counting)

Count the number of pairs (x1,x2) can be formed, with x1 drawn from self and x2 drawn from other, and where distance(x1, x2, p) <= r.

Data points on self and other are optionally weighted by the weights argument. (See below)

The algorithm we implement here is based on [1]_. See notes for further discussion.

Parameters

  • other : cKDTree instance The other tree to draw points from, can be the same tree as self.

  • r : float or one-dimensional array of floats The radius to produce a count for. Multiple radii are searched with a single tree traversal. If the count is non-cumulative(cumulative=False), r defines the edges of the bins, and must be non-decreasing.

  • p : float, optional 1<=p<=infinity. Which Minkowski p-norm to use. Default 2.0. A finite large p may cause a ValueError if overflow can occur.

  • weights : tuple, array_like, or None, optional If None, the pair-counting is unweighted. If given as a tuple, weights[0] is the weights of points in self, and weights[1] is the weights of points in other; either can be None to indicate the points are unweighted. If given as an array_like, weights is the weights of points in self and other. For this to make sense, self and other must be the same tree. If self and other are two different trees, a ValueError is raised.

  • Default: None

  • cumulative : bool, optional Whether the returned counts are cumulative. When cumulative is set to False the algorithm is optimized to work with a large number of bins (>10) specified by r. When cumulative is set to True, the algorithm is optimized to work with a small number of r. Default: True

Returns

  • result : scalar or 1-D array The number of pairs. For unweighted counts, the result is integer. For weighted counts, the result is float. If cumulative is False, result[i] contains the counts with (-inf if i == 0 else r[i-1]) < R <= r[i]

Notes

Pair-counting is the basic operation used to calculate the two point correlation functions from a data set composed of position of objects.

Two point correlation function measures the clustering of objects and is widely used in cosmology to quantify the large scale structure in our Universe, but it may be useful for data analysis in other fields where self-similar assembly of objects also occur.

The Landy-Szalay estimator for the two point correlation function of D measures the clustering signal in D. [2]_

For example, given the position of two sets of objects,

  • objects D (data) contains the clustering signal, and

  • objects R (random) that contains no signal,

\xi(r) = \frac{<D, D> - 2 f <D, R> + f^2<R, R>}{f^2<R, R>},

where the brackets represents counting pairs between two data sets in a finite bin around r (distance), corresponding to setting cumulative=False, and f = float(len(D)) / float(len(R)) is the ratio between number of objects from data and random.

The algorithm implemented here is loosely based on the dual-tree algorithm described in [1]. We switch between two different pair-cumulation scheme depending on the setting of cumulative. The computing time of the method we use when for cumulative == False does not scale with the total number of bins. The algorithm for cumulative == True scales linearly with the number of bins, though it is slightly faster when only 1 or 2 bins are used. [5].

As an extension to the naive pair-counting, weighted pair-counting counts the product of weights instead of number of pairs. Weighted pair-counting is used to estimate marked correlation functions ([3], section 2.2), or to properly calculate the average of data per distance bin (e.g. [4], section 2.1 on redshift).

.. [1] Gray and Moore, 'N-body problems in statistical learning', Mining the sky, 2000,

  • https://arxiv.org/abs/astro-ph/0012333

.. [2] Landy and Szalay, 'Bias and variance of angular correlation functions', The Astrophysical Journal, 1993,

  • http://adsabs.harvard.edu/abs/1993ApJ...412...64L

.. [3] Sheth, Connolly and Skibba, 'Marked correlations in galaxy formation models', Arxiv e-print, 2005,

  • https://arxiv.org/abs/astro-ph/0511773

.. [4] Hawkins, et al., 'The 2dF Galaxy Redshift Survey: correlation functions, peculiar velocities and the matter density of the Universe', Monthly Notices of the Royal Astronomical Society, 2002,

  • http://adsabs.harvard.edu/abs/2003MNRAS.346...78H

.. [5] https://github.com/scipy/scipy/pull/5647#issuecomment-168474926

query_ball_point

method query_ball_point
val query_ball_point :
  ?p:float ->
  ?eps:Py.Object.t ->
  x:[`Ndarray of [>`Ndarray] Np.Obj.t | `Shape_tuple_self_m_ of Py.Object.t] ->
  r:[`F of float | `Ndarray of [>`Ndarray] Np.Obj.t] ->
  [> tag] Obj.t ->
  Py.Object.t

query_ball_point(self, x, r, p=2., eps=0)

Find all points within distance r of point(s) x.

Parameters

  • x : array_like, shape tuple + (self.m,) The point or points to search for neighbors of.

  • r : array_like, float The radius of points to return, shall broadcast to the length of x.

  • p : float, optional Which Minkowski p-norm to use. Should be in the range [1, inf]. A finite large p may cause a ValueError if overflow can occur.

  • eps : nonnegative float, optional Approximate search. Branches of the tree are not explored if their nearest points are further than r / (1 + eps), and branches are added in bulk if their furthest points are nearer than r * (1 + eps).

  • n_jobs : int, optional Number of jobs to schedule for parallel processing. If -1 is given all processors are used. Default: 1.

  • return_sorted : bool, optional Sorts returned indicies if True and does not sort them if False. If None, does not sort single point queries, but does sort multi-point queries which was the behavior before this option was added.

    .. versionadded:: 1.2.0

  • return_length: bool, optional Return the number of points inside the radius instead of a list of the indices. .. versionadded:: 1.3.0

Returns

  • results : list or array of lists If x is a single point, returns a list of the indices of the neighbors of x. If x is an array of points, returns an object array of shape tuple containing lists of neighbors.

Notes

If you have many points whose neighbors you want to find, you may save substantial amounts of time by putting them in a cKDTree and using query_ball_tree.

Examples

>>> from scipy import spatial
>>> x, y = np.mgrid[0:4, 0:4]
>>> points = np.c_[x.ravel(), y.ravel()]
>>> tree = spatial.cKDTree(points)
>>> tree.query_ball_point([2, 0], 1)
[4, 8, 9, 12]

query_ball_tree

method query_ball_tree
val query_ball_tree :
  ?p:float ->
  ?eps:float ->
  other:Py.Object.t ->
  r:float ->
  [> tag] Obj.t ->
  Py.Object.t

query_ball_tree(self, other, r, p=2., eps=0)

Find all pairs of points whose distance is at most r

Parameters

  • other : cKDTree instance The tree containing points to search against.

  • r : float The maximum distance, has to be positive.

  • p : float, optional Which Minkowski norm to use. p has to meet the condition 1 <= p <= infinity. A finite large p may cause a ValueError if overflow can occur.

  • eps : float, optional Approximate search. Branches of the tree are not explored if their nearest points are further than r/(1+eps), and branches are added in bulk if their furthest points are nearer than r * (1+eps). eps has to be non-negative.

Returns

  • results : list of lists For each element self.data[i] of this tree, results[i] is a list of the indices of its neighbors in other.data.

query_pairs

method query_pairs
val query_pairs :
  ?p:float ->
  ?eps:float ->
  r:float ->
  [> tag] Obj.t ->
  Py.Object.t

query_pairs(self, r, p=2., eps=0)

Find all pairs of points whose distance is at most r.

Parameters

  • r : positive float The maximum distance.

  • p : float, optional Which Minkowski norm to use. p has to meet the condition 1 <= p <= infinity. A finite large p may cause a ValueError if overflow can occur.

  • eps : float, optional Approximate search. Branches of the tree are not explored if their nearest points are further than r/(1+eps), and branches are added in bulk if their furthest points are nearer than r * (1+eps). eps has to be non-negative.

  • output_type : string, optional Choose the output container, 'set' or 'ndarray'. Default: 'set'

Returns

  • results : set or ndarray Set of pairs (i,j), with i < j, for which the corresponding positions are close. If output_type is 'ndarray', an ndarry is returned instead of a set.

sparse_distance_matrix

method sparse_distance_matrix
val sparse_distance_matrix :
  ?p:[`F of float | `T1_p_infinity of Py.Object.t] ->
  other:Py.Object.t ->
  max_distance:float ->
  [> tag] Obj.t ->
  Py.Object.t

sparse_distance_matrix(self, other, max_distance, p=2.)

Compute a sparse distance matrix

Computes a distance matrix between two cKDTrees, leaving as zero any distance greater than max_distance.

Parameters

  • other : cKDTree

  • max_distance : positive float

  • p : float, 1<=p<=infinity Which Minkowski p-norm to use. A finite large p may cause a ValueError if overflow can occur.

  • output_type : string, optional Which container to use for output data. Options: 'dok_matrix', 'coo_matrix', 'dict', or 'ndarray'. Default: 'dok_matrix'.

Returns

  • result : dok_matrix, coo_matrix, dict or ndarray Sparse matrix representing the results in 'dictionary of keys' format. If a dict is returned the keys are (i,j) tuples of indices. If output_type is 'ndarray' a record array with fields 'i', 'j', and 'v' is returned,

data

attribute data
val data : t -> [`ArrayLike|`Ndarray|`Object] Np.Obj.t
val data_opt : t -> ([`ArrayLike|`Ndarray|`Object] Np.Obj.t) option

This attribute is documented in create above. The first version raises Not_found if the attribute is None. The _opt version returns an option.

leafsize

attribute leafsize
val leafsize : t -> Py.Object.t
val leafsize_opt : t -> (Py.Object.t) option

This attribute is documented in create above. The first version raises Not_found if the attribute is None. The _opt version returns an option.

m

attribute m
val m : t -> int
val m_opt : t -> (int) option

This attribute is documented in create above. The first version raises Not_found if the attribute is None. The _opt version returns an option.

n

attribute n
val n : t -> int
val n_opt : t -> (int) option

This attribute is documented in create above. The first version raises Not_found if the attribute is None. The _opt version returns an option.

maxes

attribute maxes
val maxes : t -> [`ArrayLike|`Ndarray|`Object] Np.Obj.t
val maxes_opt : t -> ([`ArrayLike|`Ndarray|`Object] Np.Obj.t) option

This attribute is documented in create above. The first version raises Not_found if the attribute is None. The _opt version returns an option.

mins

attribute mins
val mins : t -> [`ArrayLike|`Ndarray|`Object] Np.Obj.t
val mins_opt : t -> ([`ArrayLike|`Ndarray|`Object] Np.Obj.t) option

This attribute is documented in create above. The first version raises Not_found if the attribute is None. The _opt version returns an option.

tree

attribute tree
val tree : t -> Py.Object.t
val tree_opt : t -> (Py.Object.t) option

This attribute is documented in create above. The first version raises Not_found if the attribute is None. The _opt version returns an option.

size

attribute size
val size : t -> int
val size_opt : t -> (int) option

This attribute is documented in create above. The first version raises Not_found if the attribute is None. The _opt version returns an option.

to_string

method to_string
val to_string: t -> string

Print the object to a human-readable representation.

show

method show
val show: t -> string

Print the object to a human-readable representation.

pp

method pp
val pp: Format.formatter -> t -> unit

Pretty-print the object to a formatter.

Ckdtree

Module Scipy.​Spatial.​Ckdtree wraps Python module scipy.spatial.ckdtree.

CKDTreeNode

Module Scipy.​Spatial.​Ckdtree.​CKDTreeNode wraps Python class scipy.spatial.ckdtree.cKDTreeNode.

type t

level

attribute level
val level : t -> int
val level_opt : t -> (int) option

This attribute is documented in create above. The first version raises Not_found if the attribute is None. The _opt version returns an option.

split_dim

attribute split_dim
val split_dim : t -> int
val split_dim_opt : t -> (int) option

This attribute is documented in create above. The first version raises Not_found if the attribute is None. The _opt version returns an option.

split

attribute split
val split : t -> float
val split_opt : t -> (float) option

This attribute is documented in create above. The first version raises Not_found if the attribute is None. The _opt version returns an option.

children

attribute children
val children : t -> int
val children_opt : t -> (int) option

This attribute is documented in create above. The first version raises Not_found if the attribute is None. The _opt version returns an option.

data_points

attribute data_points
val data_points : t -> Py.Object.t
val data_points_opt : t -> (Py.Object.t) option

This attribute is documented in create above. The first version raises Not_found if the attribute is None. The _opt version returns an option.

indices

attribute indices
val indices : t -> Py.Object.t
val indices_opt : t -> (Py.Object.t) option

This attribute is documented in create above. The first version raises Not_found if the attribute is None. The _opt version returns an option.

lesser

attribute lesser
val lesser : t -> Py.Object.t
val lesser_opt : t -> (Py.Object.t) option

This attribute is documented in create above. The first version raises Not_found if the attribute is None. The _opt version returns an option.

greater

attribute greater
val greater : t -> Py.Object.t
val greater_opt : t -> (Py.Object.t) option

This attribute is documented in create above. The first version raises Not_found if the attribute is None. The _opt version returns an option.

to_string

method to_string
val to_string: t -> string

Print the object to a human-readable representation.

show

method show
val show: t -> string

Print the object to a human-readable representation.

pp

method pp
val pp: Format.formatter -> t -> unit

Pretty-print the object to a formatter.

Coo_entries

Module Scipy.​Spatial.​Ckdtree.​Coo_entries wraps Python class scipy.spatial.ckdtree.coo_entries.

type t

to_string

method to_string
val to_string: t -> string

Print the object to a human-readable representation.

show

method show
val show: t -> string

Print the object to a human-readable representation.

pp

method pp
val pp: Format.formatter -> t -> unit

Pretty-print the object to a formatter.

Ordered_pairs

Module Scipy.​Spatial.​Ckdtree.​Ordered_pairs wraps Python class scipy.spatial.ckdtree.ordered_pairs.

type t

to_string

method to_string
val to_string: t -> string

Print the object to a human-readable representation.

show

method show
val show: t -> string

Print the object to a human-readable representation.

pp

method pp
val pp: Format.formatter -> t -> unit

Pretty-print the object to a formatter.

cpu_count

function cpu_count
val cpu_count :
  unit ->
  Py.Object.t

Returns the number of CPUs in the system

Distance

Module Scipy.​Spatial.​Distance wraps Python module scipy.spatial.distance.

MetricInfo

Module Scipy.​Spatial.​Distance.​MetricInfo wraps Python class scipy.spatial.distance.MetricInfo.

type t

create

constructor and attributes create
val create :
  ?types:Py.Object.t ->
  ?validator:Py.Object.t ->
  aka:Py.Object.t ->
  unit ->
  t

MetricInfo(aka, types, validator)

getitem

method getitem
val __getitem__ :
  key:Py.Object.t ->
  [> tag] Obj.t ->
  Py.Object.t

Return self[key].

iter

method iter
val __iter__ :
  [> tag] Obj.t ->
  Py.Object.t

Implement iter(self).

count

method count
val count :
  value:Py.Object.t ->
  [> tag] Obj.t ->
  Py.Object.t

Return number of occurrences of value.

index

method index
val index :
  ?start:Py.Object.t ->
  ?stop:Py.Object.t ->
  value:Py.Object.t ->
  [> tag] Obj.t ->
  Py.Object.t

Return first index of value.

Raises ValueError if the value is not present.

to_string

method to_string
val to_string: t -> string

Print the object to a human-readable representation.

show

method show
val show: t -> string

Print the object to a human-readable representation.

pp

method pp
val pp: Format.formatter -> t -> unit

Pretty-print the object to a formatter.

Partial

Module Scipy.​Spatial.​Distance.​Partial wraps Python class scipy.spatial.distance.partial.

type t

create

constructor and attributes create
val create :
  ?keywords:(string * Py.Object.t) list ->
  func:Py.Object.t ->
  Py.Object.t list ->
  t

partial(func, args, *keywords) - new function with partial application of the given arguments and keywords.

to_string

method to_string
val to_string: t -> string

Print the object to a human-readable representation.

show

method show
val show: t -> string

Print the object to a human-readable representation.

pp

method pp
val pp: Format.formatter -> t -> unit

Pretty-print the object to a formatter.

braycurtis

function braycurtis
val braycurtis :
  ?w:[>`Ndarray] Np.Obj.t ->
  u:[>`Ndarray] Np.Obj.t ->
  v:[>`Ndarray] Np.Obj.t ->
  unit ->
  float

Compute the Bray-Curtis distance between two 1-D arrays.

Bray-Curtis distance is defined as

\sum{ |u_i-v_i| } / \sum{ |u_i+v_i| }

The Bray-Curtis distance is in the range [0, 1] if all coordinates are positive, and is undefined if the inputs are of length zero.

Parameters

  • u : (N,) array_like Input array.

  • v : (N,) array_like Input array.

  • w : (N,) array_like, optional The weights for each value in u and v. Default is None, which gives each value a weight of 1.0

Returns

  • braycurtis : double The Bray-Curtis distance between 1-D arrays u and v.

Examples

>>> from scipy.spatial import distance
>>> distance.braycurtis([1, 0, 0], [0, 1, 0])
1.0
>>> distance.braycurtis([1, 1, 0], [0, 1, 0])
0.33333333333333331

canberra

function canberra
val canberra :
  ?w:[>`Ndarray] Np.Obj.t ->
  u:[>`Ndarray] Np.Obj.t ->
  v:[>`Ndarray] Np.Obj.t ->
  unit ->
  float

Compute the Canberra distance between two 1-D arrays.

The Canberra distance is defined as

d(u,v) = \sum_i \frac{ |u_i-v_i| } { |u_i|+|v_i| }.

Parameters

  • u : (N,) array_like Input array.

  • v : (N,) array_like Input array.

  • w : (N,) array_like, optional The weights for each value in u and v. Default is None, which gives each value a weight of 1.0

Returns

  • canberra : double The Canberra distance between vectors u and v.

Notes

When u[i] and v[i] are 0 for given i, then the fraction 0/0 = 0 is used in the calculation.

Examples

>>> from scipy.spatial import distance
>>> distance.canberra([1, 0, 0], [0, 1, 0])
2.0
>>> distance.canberra([1, 1, 0], [0, 1, 0])
1.0

cdist

function cdist
val cdist :
  ?metric:[`S of string | `Callable of Py.Object.t] ->
  ?kwargs:(string * Py.Object.t) list ->
  xa:[>`Ndarray] Np.Obj.t ->
  xb:[>`Ndarray] Np.Obj.t ->
  Py.Object.t list ->
  [`ArrayLike|`Ndarray|`Object] Np.Obj.t

Compute distance between each pair of the two collections of inputs.

See Notes for common calling conventions.

Parameters

  • XA : ndarray

  • An :math:m_A by :math:n array of :math:m_A original observations in an :math:n-dimensional space. Inputs are converted to float type.

  • XB : ndarray

  • An :math:m_B by :math:n array of :math:m_B original observations in an :math:n-dimensional space. Inputs are converted to float type.

  • metric : str or callable, optional The distance metric to use. If a string, the distance function can be 'braycurtis', 'canberra', 'chebyshev', 'cityblock', 'correlation', 'cosine', 'dice', 'euclidean', 'hamming', 'jaccard', 'jensenshannon', 'kulsinski', 'mahalanobis', 'matching', 'minkowski', 'rogerstanimoto', 'russellrao', 'seuclidean', 'sokalmichener', 'sokalsneath', 'sqeuclidean', 'wminkowski', 'yule'.

  • *args : tuple. Deprecated. Additional arguments should be passed as keyword arguments

  • **kwargs : dict, optional Extra arguments to metric: refer to each metric documentation for a list of all possible arguments.

    Some possible arguments:

  • p : scalar The p-norm to apply for Minkowski, weighted and unweighted.

  • Default: 2.

  • w : ndarray The weight vector for metrics that support weights (e.g., Minkowski).

  • V : ndarray The variance vector for standardized Euclidean.

  • Default: var(vstack([XA, XB]), axis=0, ddof=1)

  • VI : ndarray The inverse of the covariance matrix for Mahalanobis.

  • Default: inv(cov(vstack([XA, XB].T))).T

  • out : ndarray The output array If not None, the distance matrix Y is stored in this array.

  • Note: metric independent, it will become a regular keyword arg in a future scipy version

Returns

  • Y : ndarray

  • A :math:m_A by :math:m_B distance matrix is returned. For each :math:i and :math:j, the metric dist(u=XA[i], v=XB[j]) is computed and stored in the :math:ij th entry.

Raises

ValueError An exception is thrown if XA and XB do not have the same number of columns.

Notes

The following are common calling conventions:

  1. Y = cdist(XA, XB, 'euclidean')

Computes the distance between :math:m points using Euclidean distance (2-norm) as the distance metric between the points. The points are arranged as :math:m :math:n-dimensional row vectors in the matrix X.

  1. Y = cdist(XA, XB, 'minkowski', p=2.)

Computes the distances using the Minkowski distance :math:||u-v||_p (:math:p-norm) where :math:p \geq 1.

  1. Y = cdist(XA, XB, 'cityblock')

Computes the city block or Manhattan distance between the points.

  1. Y = cdist(XA, XB, 'seuclidean', V=None)

Computes the standardized Euclidean distance. The standardized Euclidean distance between two n-vectors u and v is

.. math::

  \sqrt{\sum {(u_i-v_i)^2 / V[x_i]}}.

V is the variance vector; V[i] is the variance computed over all the i'th components of the points. If not passed, it is automatically computed.

  1. Y = cdist(XA, XB, 'sqeuclidean')

Computes the squared Euclidean distance :math:||u-v||_2^2 between the vectors.

  1. Y = cdist(XA, XB, 'cosine')

Computes the cosine distance between vectors u and v,

.. math::

  1 - \frac{u \cdot v}
           {{ ||u|| }_2 { ||v|| }_2}
  • where :math:||*||_2 is the 2-norm of its argument *, and :math:u \cdot v is the dot product of :math:u and :math:v.

  • Y = cdist(XA, XB, 'correlation')

Computes the correlation distance between vectors u and v. This is

.. math::

  1 - \frac{(u - \bar{u}) \cdot (v - \bar{v})}
           {{ ||(u - \bar{u})|| }_2 { ||(v - \bar{v})|| }_2}
  • where :math:\bar{v} is the mean of the elements of vector v,

  • and :math:x \cdot y is the dot product of :math:x and :math:y.

  • Y = cdist(XA, XB, 'hamming')

Computes the normalized Hamming distance, or the proportion of those vector elements between two n-vectors u and v which disagree. To save memory, the matrix X can be of type boolean.

  1. Y = cdist(XA, XB, 'jaccard')

Computes the Jaccard distance between the points. Given two vectors, u and v, the Jaccard distance is the proportion of those elements u[i] and v[i] that disagree where at least one of them is non-zero.

  1. Y = cdist(XA, XB, 'chebyshev')

Computes the Chebyshev distance between the points. The Chebyshev distance between two n-vectors u and v is the maximum norm-1 distance between their respective elements. More precisely, the distance is given by

.. math::

  d(u,v) = \max_i { |u_i-v_i| }.
  1. Y = cdist(XA, XB, 'canberra')

Computes the Canberra distance between the points. The Canberra distance between two points u and v is

.. math::

 d(u,v) = \sum_i \frac{ |u_i-v_i| }
                      { |u_i|+|v_i| }.
  1. Y = cdist(XA, XB, 'braycurtis')

Computes the Bray-Curtis distance between the points. The Bray-Curtis distance between two points u and v is

.. math::

    d(u,v) = \frac{\sum_i (|u_i-v_i|)}
                  {\sum_i (|u_i+v_i|)}
  1. Y = cdist(XA, XB, 'mahalanobis', VI=None)

Computes the Mahalanobis distance between the points. The Mahalanobis distance between two points u and v is :math:\sqrt{(u-v)(1/V)(u-v)^T} where :math:(1/V) (the VI variable) is the inverse covariance. If VI is not None, VI will be used as the inverse covariance matrix.

  1. Y = cdist(XA, XB, 'yule')

Computes the Yule distance between the boolean vectors. (see yule function documentation)

  1. Y = cdist(XA, XB, 'matching')

Synonym for 'hamming'.

  1. Y = cdist(XA, XB, 'dice')

Computes the Dice distance between the boolean vectors. (see dice function documentation)

  1. Y = cdist(XA, XB, 'kulsinski')

Computes the Kulsinski distance between the boolean vectors. (see kulsinski function documentation)

  1. Y = cdist(XA, XB, 'rogerstanimoto')

Computes the Rogers-Tanimoto distance between the boolean vectors. (see rogerstanimoto function documentation)

  1. Y = cdist(XA, XB, 'russellrao')

Computes the Russell-Rao distance between the boolean vectors. (see russellrao function documentation)

  1. Y = cdist(XA, XB, 'sokalmichener')

Computes the Sokal-Michener distance between the boolean vectors. (see sokalmichener function documentation)

  1. Y = cdist(XA, XB, 'sokalsneath')

Computes the Sokal-Sneath distance between the vectors. (see sokalsneath function documentation)

  1. Y = cdist(XA, XB, 'wminkowski', p=2., w=w)

Computes the weighted Minkowski distance between the vectors. (see wminkowski function documentation)

  1. Y = cdist(XA, XB, f)

Computes the distance between all pairs of vectors in X using the user supplied 2-arity function f. For example, Euclidean distance between the vectors could be computed as follows::

 dm = cdist(XA, XB, lambda u, v: np.sqrt(((u-v)**2).sum()))

Note that you should avoid passing a reference to one of the distance functions defined in this library. For example,::

 dm = cdist(XA, XB, sokalsneath)

would calculate the pair-wise distances between the vectors in X using the Python function sokalsneath. This would result in sokalsneath being called :math:{n \choose 2} times, which is inefficient. Instead, the optimized C version is more efficient, and we call it using the following syntax::

 dm = cdist(XA, XB, 'sokalsneath')

Examples

Find the Euclidean distances between four 2-D coordinates:

>>> from scipy.spatial import distance
>>> coords = [(35.0456, -85.2672),
...           (35.1174, -89.9711),
...           (35.9728, -83.9422),
...           (36.1667, -86.7833)]
>>> distance.cdist(coords, coords, 'euclidean')
array([[ 0.    ,  4.7044,  1.6172,  1.8856],
       [ 4.7044,  0.    ,  6.0893,  3.3561],
       [ 1.6172,  6.0893,  0.    ,  2.8477],
       [ 1.8856,  3.3561,  2.8477,  0.    ]])

Find the Manhattan distance from a 3-D point to the corners of the unit cube:

>>> a = np.array([[0, 0, 0],
...               [0, 0, 1],
...               [0, 1, 0],
...               [0, 1, 1],
...               [1, 0, 0],
...               [1, 0, 1],
...               [1, 1, 0],
...               [1, 1, 1]])
>>> b = np.array([[ 0.1,  0.2,  0.4]])
>>> distance.cdist(a, b, 'cityblock')
array([[ 0.7],
       [ 0.9],
       [ 1.3],
       [ 1.5],
       [ 1.5],
       [ 1.7],
       [ 2.1],
       [ 2.3]])

chebyshev

function chebyshev
val chebyshev :
  ?w:[>`Ndarray] Np.Obj.t ->
  u:[>`Ndarray] Np.Obj.t ->
  v:[>`Ndarray] Np.Obj.t ->
  unit ->
  float

Compute the Chebyshev distance.

Computes the Chebyshev distance between two 1-D arrays u and v, which is defined as

\max_i { |u_i-v_i| }.

Parameters

  • u : (N,) array_like Input vector.

  • v : (N,) array_like Input vector.

  • w : (N,) array_like, optional Unused, as 'max' is a weightless operation. Here for API consistency.

Returns

  • chebyshev : double The Chebyshev distance between vectors u and v.

Examples

>>> from scipy.spatial import distance
>>> distance.chebyshev([1, 0, 0], [0, 1, 0])
1
>>> distance.chebyshev([1, 1, 0], [0, 1, 0])
1

cityblock

function cityblock
val cityblock :
  ?w:[>`Ndarray] Np.Obj.t ->
  u:[>`Ndarray] Np.Obj.t ->
  v:[>`Ndarray] Np.Obj.t ->
  unit ->
  float

Compute the City Block (Manhattan) distance.

Computes the Manhattan distance between two 1-D arrays u and v, which is defined as

\sum_i {\left| u_i - v_i \right| }.

Parameters

  • u : (N,) array_like Input array.

  • v : (N,) array_like Input array.

  • w : (N,) array_like, optional The weights for each value in u and v. Default is None, which gives each value a weight of 1.0

Returns

  • cityblock : double The City Block (Manhattan) distance between vectors u and v.

Examples

>>> from scipy.spatial import distance
>>> distance.cityblock([1, 0, 0], [0, 1, 0])
2
>>> distance.cityblock([1, 0, 0], [0, 2, 0])
3
>>> distance.cityblock([1, 0, 0], [1, 1, 0])
1

correlation

function correlation
val correlation :
  ?w:[>`Ndarray] Np.Obj.t ->
  ?centered:Py.Object.t ->
  u:[>`Ndarray] Np.Obj.t ->
  v:[>`Ndarray] Np.Obj.t ->
  unit ->
  float

Compute the correlation distance between two 1-D arrays.

The correlation distance between u and v, is defined as

1 - \frac{(u - \bar{u}) \cdot (v - \bar{v})} {{ ||(u - \bar{u})|| }_2 { ||(v - \bar{v})|| }_2}
  • where :math:\bar{u} is the mean of the elements of u

  • and :math:x \cdot y is the dot product of :math:x and :math:y.

Parameters

  • u : (N,) array_like Input array.

  • v : (N,) array_like Input array.

  • w : (N,) array_like, optional The weights for each value in u and v. Default is None, which gives each value a weight of 1.0

Returns

  • correlation : double The correlation distance between 1-D array u and v.

cosine

function cosine
val cosine :
  ?w:[>`Ndarray] Np.Obj.t ->
  u:[>`Ndarray] Np.Obj.t ->
  v:[>`Ndarray] Np.Obj.t ->
  unit ->
  float

Compute the Cosine distance between 1-D arrays.

The Cosine distance between u and v, is defined as

1 - \frac{u \cdot v} { ||u||_2 ||v||_2}.
  • where :math:u \cdot v is the dot product of :math:u and :math:v.

Parameters

  • u : (N,) array_like Input array.

  • v : (N,) array_like Input array.

  • w : (N,) array_like, optional The weights for each value in u and v. Default is None, which gives each value a weight of 1.0

Returns

  • cosine : double The Cosine distance between vectors u and v.

Examples

>>> from scipy.spatial import distance
>>> distance.cosine([1, 0, 0], [0, 1, 0])
1.0
>>> distance.cosine([100, 0, 0], [0, 1, 0])
1.0
>>> distance.cosine([1, 1, 0], [0, 1, 0])
0.29289321881345254

dice

function dice
val dice :
  ?w:[>`Ndarray] Np.Obj.t ->
  u:[>`Ndarray] Np.Obj.t ->
  v:[>`Ndarray] Np.Obj.t ->
  unit ->
  float

Compute the Dice dissimilarity between two boolean 1-D arrays.

The Dice dissimilarity between u and v, is

\frac{c_{TF} + c_{FT}} {2c_{TT} + c_{FT} + c_{TF}}
  • where :math:c_{ij} is the number of occurrences of :math:\mathtt{u[k]} = i and :math:\mathtt{v[k]} = j for :math:k < n.

Parameters

  • u : (N,) ndarray, bool Input 1-D array.

  • v : (N,) ndarray, bool Input 1-D array.

  • w : (N,) array_like, optional The weights for each value in u and v. Default is None, which gives each value a weight of 1.0

Returns

  • dice : double The Dice dissimilarity between 1-D arrays u and v.

Examples

>>> from scipy.spatial import distance
>>> distance.dice([1, 0, 0], [0, 1, 0])
1.0
>>> distance.dice([1, 0, 0], [1, 1, 0])
0.3333333333333333
>>> distance.dice([1, 0, 0], [2, 0, 0])
-0.3333333333333333

directed_hausdorff

function directed_hausdorff
val directed_hausdorff :
  ?seed:[`I of int | `None] ->
  u:[>`Ndarray] Np.Obj.t ->
  v:Py.Object.t ->
  unit ->
  (float * int * int)

Compute the directed Hausdorff distance between two N-D arrays.

Distances between pairs are calculated using a Euclidean metric.

Parameters

  • u : (M,N) ndarray Input array.

  • v : (O,N) ndarray Input array.

  • seed : int or None Local numpy.random.RandomState seed. Default is 0, a random shuffling of u and v that guarantees reproducibility.

Returns

  • d : double The directed Hausdorff distance between arrays u and v,

  • index_1 : int index of point contributing to Hausdorff pair in u

  • index_2 : int index of point contributing to Hausdorff pair in v

Raises

ValueError An exception is thrown if u and v do not have the same number of columns.

Notes

Uses the early break technique and the random sampling approach described by [1]_. Although worst-case performance is O(m * o) (as with the brute force algorithm), this is unlikely in practice as the input data would have to require the algorithm to explore every single point interaction, and after the algorithm shuffles the input points at that. The best case performance is O(m), which is satisfied by selecting an inner loop distance that is less than cmax and leads to an early break as often as possible. The authors have formally shown that the average runtime is closer to O(m).

.. versionadded:: 0.19.0

References

.. [1] A. A. Taha and A. Hanbury, 'An efficient algorithm for calculating the exact Hausdorff distance.' IEEE Transactions On Pattern Analysis And Machine Intelligence, vol. 37 pp. 2153-63, 2015.

See Also

  • scipy.spatial.procrustes : Another similarity test for two data sets

Examples

Find the directed Hausdorff distance between two 2-D arrays of coordinates:

>>> from scipy.spatial.distance import directed_hausdorff
>>> u = np.array([(1.0, 0.0),
...               (0.0, 1.0),
...               (-1.0, 0.0),
...               (0.0, -1.0)])
>>> v = np.array([(2.0, 0.0),
...               (0.0, 2.0),
...               (-2.0, 0.0),
...               (0.0, -4.0)])
>>> directed_hausdorff(u, v)[0]
2.23606797749979
>>> directed_hausdorff(v, u)[0]
3.0

Find the general (symmetric) Hausdorff distance between two 2-D arrays of coordinates:

>>> max(directed_hausdorff(u, v)[0], directed_hausdorff(v, u)[0])
3.0

Find the indices of the points that generate the Hausdorff distance (the Hausdorff pair):

>>> directed_hausdorff(v, u)[1:]
(3, 3)

euclidean

function euclidean
val euclidean :
  ?w:[>`Ndarray] Np.Obj.t ->
  u:[>`Ndarray] Np.Obj.t ->
  v:[>`Ndarray] Np.Obj.t ->
  unit ->
  float

Computes the Euclidean distance between two 1-D arrays.

The Euclidean distance between 1-D arrays u and v, is defined as

{ ||u-v|| }_2

\left(\sum{(w_i |(u_i - v_i)|^2)}\right)^{1/2}

Parameters

  • u : (N,) array_like Input array.

  • v : (N,) array_like Input array.

  • w : (N,) array_like, optional The weights for each value in u and v. Default is None, which gives each value a weight of 1.0

Returns

  • euclidean : double The Euclidean distance between vectors u and v.

Examples

>>> from scipy.spatial import distance
>>> distance.euclidean([1, 0, 0], [0, 1, 0])
1.4142135623730951
>>> distance.euclidean([1, 1, 0], [0, 1, 0])
1.0

hamming

function hamming
val hamming :
  ?w:[>`Ndarray] Np.Obj.t ->
  u:[>`Ndarray] Np.Obj.t ->
  v:[>`Ndarray] Np.Obj.t ->
  unit ->
  float

Compute the Hamming distance between two 1-D arrays.

The Hamming distance between 1-D arrays u and v, is simply the proportion of disagreeing components in u and v. If u and v are boolean vectors, the Hamming distance is

\frac{c_{01} + c_{10}}{n}
  • where :math:c_{ij} is the number of occurrences of :math:\mathtt{u[k]} = i and :math:\mathtt{v[k]} = j for :math:k < n.

Parameters

  • u : (N,) array_like Input array.

  • v : (N,) array_like Input array.

  • w : (N,) array_like, optional The weights for each value in u and v. Default is None, which gives each value a weight of 1.0

Returns

  • hamming : double The Hamming distance between vectors u and v.

Examples

>>> from scipy.spatial import distance
>>> distance.hamming([1, 0, 0], [0, 1, 0])
0.66666666666666663
>>> distance.hamming([1, 0, 0], [1, 1, 0])
0.33333333333333331
>>> distance.hamming([1, 0, 0], [2, 0, 0])
0.33333333333333331
>>> distance.hamming([1, 0, 0], [3, 0, 0])
0.33333333333333331

is_valid_dm

function is_valid_dm
val is_valid_dm :
  ?tol:float ->
  ?throw:bool ->
  ?name:string ->
  ?warning:bool ->
  d:[>`Ndarray] Np.Obj.t ->
  unit ->
  bool

Return True if input array is a valid distance matrix.

Distance matrices must be 2-dimensional numpy arrays. They must have a zero-diagonal, and they must be symmetric.

Parameters

  • D : ndarray The candidate object to test for validity.

  • tol : float, optional The distance matrix should be symmetric. tol is the maximum difference between entries ij and ji for the distance metric to be considered symmetric.

  • throw : bool, optional An exception is thrown if the distance matrix passed is not valid.

  • name : str, optional The name of the variable to checked. This is useful if throw is set to True so the offending variable can be identified in the exception message when an exception is thrown.

  • warning : bool, optional Instead of throwing an exception, a warning message is raised.

Returns

  • valid : bool True if the variable D passed is a valid distance matrix.

Notes

Small numerical differences in D and D.T and non-zeroness of the diagonal are ignored if they are within the tolerance specified by tol.

is_valid_y

function is_valid_y
val is_valid_y :
  ?warning:bool ->
  ?throw:bool ->
  ?name:bool ->
  y:[>`Ndarray] Np.Obj.t ->
  unit ->
  Py.Object.t

Return True if the input array is a valid condensed distance matrix.

Condensed distance matrices must be 1-dimensional numpy arrays. Their length must be a binomial coefficient :math:{n \choose 2} for some positive integer n.

Parameters

  • y : ndarray The condensed distance matrix.

  • warning : bool, optional Invokes a warning if the variable passed is not a valid condensed distance matrix. The warning message explains why the distance matrix is not valid. name is used when referencing the offending variable.

  • throw : bool, optional Throws an exception if the variable passed is not a valid condensed distance matrix.

  • name : bool, optional Used when referencing the offending variable in the warning or exception message.

jaccard

function jaccard
val jaccard :
  ?w:[>`Ndarray] Np.Obj.t ->
  u:[`Ndarray of [>`Ndarray] Np.Obj.t | `Bool of bool] ->
  v:[`Ndarray of [>`Ndarray] Np.Obj.t | `Bool of bool] ->
  unit ->
  float

Compute the Jaccard-Needham dissimilarity between two boolean 1-D arrays.

The Jaccard-Needham dissimilarity between 1-D boolean arrays u and v, is defined as

\frac{c_{TF} + c_{FT}} {c_{TT} + c_{FT} + c_{TF}}
  • where :math:c_{ij} is the number of occurrences of :math:\mathtt{u[k]} = i and :math:\mathtt{v[k]} = j for :math:k < n.

Parameters

  • u : (N,) array_like, bool Input array.

  • v : (N,) array_like, bool Input array.

  • w : (N,) array_like, optional The weights for each value in u and v. Default is None, which gives each value a weight of 1.0

Returns

  • jaccard : double The Jaccard distance between vectors u and v.

Notes

When both u and v lead to a 0/0 division i.e. there is no overlap between the items in the vectors the returned distance is 0. See the Wikipedia page on the Jaccard index [1], and this paper [2].

.. versionchanged:: 1.2.0 Previously, when u and v lead to a 0/0 division, the function would return NaN. This was changed to return 0 instead.

References

.. [1] https://en.wikipedia.org/wiki/Jaccard_index .. [2] S. Kosub, 'A note on the triangle inequality for the Jaccard distance', 2016, Available online: https://arxiv.org/pdf/1612.02696.pdf

Examples

>>> from scipy.spatial import distance
>>> distance.jaccard([1, 0, 0], [0, 1, 0])
1.0
>>> distance.jaccard([1, 0, 0], [1, 1, 0])
0.5
>>> distance.jaccard([1, 0, 0], [1, 2, 0])
0.5
>>> distance.jaccard([1, 0, 0], [1, 1, 1])
0.66666666666666663

jensenshannon

function jensenshannon
val jensenshannon :
  ?base:float ->
  p:[>`Ndarray] Np.Obj.t ->
  q:[>`Ndarray] Np.Obj.t ->
  unit ->
  float

Compute the Jensen-Shannon distance (metric) between two 1-D probability arrays. This is the square root of the Jensen-Shannon divergence.

The Jensen-Shannon distance between two probability vectors p and q is defined as,

\sqrt{\frac{D(p \parallel m) + D(q \parallel m)}{2}}
  • where :math:m is the pointwise mean of :math:p and :math:q

  • and :math:D is the Kullback-Leibler divergence.

This routine will normalize p and q if they don't sum to 1.0.

Parameters

  • p : (N,) array_like left probability vector

  • q : (N,) array_like right probability vector

  • base : double, optional the base of the logarithm used to compute the output if not given, then the routine uses the default base of scipy.stats.entropy.

Returns

  • js : double The Jensen-Shannon distance between p and q

.. versionadded:: 1.2.0

Examples

>>> from scipy.spatial import distance
>>> distance.jensenshannon([1.0, 0.0, 0.0], [0.0, 1.0, 0.0], 2.0)
1.0
>>> distance.jensenshannon([1.0, 0.0], [0.5, 0.5])
0.46450140402245893
>>> distance.jensenshannon([1.0, 0.0, 0.0], [1.0, 0.0, 0.0])
0.0

kulsinski

function kulsinski
val kulsinski :
  ?w:[>`Ndarray] Np.Obj.t ->
  u:[`Ndarray of [>`Ndarray] Np.Obj.t | `Bool of bool] ->
  v:[`Ndarray of [>`Ndarray] Np.Obj.t | `Bool of bool] ->
  unit ->
  float

Compute the Kulsinski dissimilarity between two boolean 1-D arrays.

The Kulsinski dissimilarity between two boolean 1-D arrays u and v, is defined as

\frac{c_{TF} + c_{FT} - c_{TT} + n} {c_{FT} + c_{TF} + n}
  • where :math:c_{ij} is the number of occurrences of :math:\mathtt{u[k]} = i and :math:\mathtt{v[k]} = j for :math:k < n.

Parameters

  • u : (N,) array_like, bool Input array.

  • v : (N,) array_like, bool Input array.

  • w : (N,) array_like, optional The weights for each value in u and v. Default is None, which gives each value a weight of 1.0

Returns

  • kulsinski : double The Kulsinski distance between vectors u and v.

Examples

>>> from scipy.spatial import distance
>>> distance.kulsinski([1, 0, 0], [0, 1, 0])
1.0
>>> distance.kulsinski([1, 0, 0], [1, 1, 0])
0.75
>>> distance.kulsinski([1, 0, 0], [2, 1, 0])
0.33333333333333331
>>> distance.kulsinski([1, 0, 0], [3, 1, 0])
-0.5

mahalanobis

function mahalanobis
val mahalanobis :
  u:[>`Ndarray] Np.Obj.t ->
  v:[>`Ndarray] Np.Obj.t ->
  vi:[>`Ndarray] Np.Obj.t ->
  unit ->
  float

Compute the Mahalanobis distance between two 1-D arrays.

The Mahalanobis distance between 1-D arrays u and v, is defined as

\sqrt{ (u-v) V^{-1} (u-v)^T }

where V is the covariance matrix. Note that the argument VI is the inverse of V.

Parameters

  • u : (N,) array_like Input array.

  • v : (N,) array_like Input array.

  • VI : ndarray The inverse of the covariance matrix.

Returns

  • mahalanobis : double The Mahalanobis distance between vectors u and v.

Examples

>>> from scipy.spatial import distance
>>> iv = [[1, 0.5, 0.5], [0.5, 1, 0.5], [0.5, 0.5, 1]]
>>> distance.mahalanobis([1, 0, 0], [0, 1, 0], iv)
1.0
>>> distance.mahalanobis([0, 2, 0], [0, 1, 0], iv)
1.0
>>> distance.mahalanobis([2, 0, 0], [0, 1, 0], iv)
1.7320508075688772

matching

function matching
val matching :
  ?kwds:(string * Py.Object.t) list ->
  Py.Object.t list ->
  Py.Object.t

matching is deprecated! spatial.distance.matching is deprecated in scipy 1.0.0; use spatial.distance.hamming instead.

Compute the Hamming distance between two boolean 1-D arrays.

This is a deprecated synonym for :func:hamming.

minkowski

function minkowski
val minkowski :
  ?p:int ->
  ?w:[>`Ndarray] Np.Obj.t ->
  u:[>`Ndarray] Np.Obj.t ->
  v:[>`Ndarray] Np.Obj.t ->
  unit ->
  float

Compute the Minkowski distance between two 1-D arrays.

The Minkowski distance between 1-D arrays u and v, is defined as

{ ||u-v|| }_p = (\sum{ |u_i - v_i|^p})^{1/p}.

\left(\sum{w_i(|(u_i - v_i)|^p)}\right)^{1/p}.

Parameters

  • u : (N,) array_like Input array.

  • v : (N,) array_like Input array.

  • p : int The order of the norm of the difference :math:{ ||u-v|| }_p.

  • w : (N,) array_like, optional The weights for each value in u and v. Default is None, which gives each value a weight of 1.0

Returns

  • minkowski : double The Minkowski distance between vectors u and v.

Examples

>>> from scipy.spatial import distance
>>> distance.minkowski([1, 0, 0], [0, 1, 0], 1)
2.0
>>> distance.minkowski([1, 0, 0], [0, 1, 0], 2)
1.4142135623730951
>>> distance.minkowski([1, 0, 0], [0, 1, 0], 3)
1.2599210498948732
>>> distance.minkowski([1, 1, 0], [0, 1, 0], 1)
1.0
>>> distance.minkowski([1, 1, 0], [0, 1, 0], 2)
1.0
>>> distance.minkowski([1, 1, 0], [0, 1, 0], 3)
1.0

namedtuple

function namedtuple
val namedtuple :
  ?rename:Py.Object.t ->
  ?defaults:Py.Object.t ->
  ?module_:Py.Object.t ->
  typename:Py.Object.t ->
  field_names:Py.Object.t ->
  unit ->
  Py.Object.t

Returns a new subclass of tuple with named fields.

>>> Point = namedtuple('Point', ['x', 'y'])
>>> Point.__doc__                   # docstring for the new class
'Point(x, y)'
>>> p = Point(11, y=22)             # instantiate with positional args or keywords
>>> p[0] + p[1]                     # indexable like a plain tuple
33
>>> x, y = p                        # unpack like a regular tuple
>>> x, y
(11, 22)
>>> p.x + p.y                       # fields also accessible by name
33
>>> d = p._asdict()                 # convert to a dictionary
>>> d['x']
11
>>> Point( **d)                      # convert from a dictionary
Point(x=11, y=22)
>>> p._replace(x=100)               # _replace() is like str.replace() but targets named fields
Point(x=100, y=22)

norm

function norm
val norm :
  ?ord:[`PyObject of Py.Object.t | `Fro] ->
  ?axis:[`I of int | `T2_tuple_of_ints of Py.Object.t] ->
  ?keepdims:bool ->
  ?check_finite:bool ->
  a:Py.Object.t ->
  unit ->
  Py.Object.t

Matrix or vector norm.

This function is able to return one of seven different matrix norms, or one of an infinite number of vector norms (described below), depending on the value of the ord parameter.

Parameters

  • a : (M,) or (M, N) array_like Input array. If axis is None, a must be 1D or 2D.

  • ord : {non-zero int, inf, -inf, 'fro'}, optional Order of the norm (see table under Notes). inf means NumPy's inf object

  • axis : {int, 2-tuple of ints, None}, optional If axis is an integer, it specifies the axis of a along which to compute the vector norms. If axis is a 2-tuple, it specifies the axes that hold 2-D matrices, and the matrix norms of these matrices are computed. If axis is None then either a vector norm (when a is 1-D) or a matrix norm (when a is 2-D) is returned.

  • keepdims : bool, optional If this is set to True, the axes which are normed over are left in the result as dimensions with size one. With this option the result will broadcast correctly against the original a.

  • check_finite : bool, optional Whether to check that the input matrix contains only finite numbers. Disabling may give a performance gain, but may result in problems (crashes, non-termination) if the inputs do contain infinities or NaNs.

Returns

  • n : float or ndarray Norm of the matrix or vector(s).

Notes

For values of ord <= 0, the result is, strictly speaking, not a mathematical 'norm', but it may still be useful for various numerical purposes.

The following norms can be calculated:

===== ============================ ========================== ord norm for matrices norm for vectors ===== ============================ ========================== None Frobenius norm 2-norm 'fro' Frobenius norm -- inf max(sum(abs(x), axis=1)) max(abs(x)) -inf min(sum(abs(x), axis=1)) min(abs(x)) 0 -- sum(x != 0) 1 max(sum(abs(x), axis=0)) as below -1 min(sum(abs(x), axis=0)) as below 2 2-norm (largest sing. value) as below -2 smallest singular value as below other -- sum(abs(x)ord)(1./ord) ===== ============================ ==========================

The Frobenius norm is given by [1]_:

:math:`||A||_F = [\sum_{i,j} abs(a_{i,j})^2]^{1/2}`

The axis and keepdims arguments are passed directly to numpy.linalg.norm and are only usable if they are supported by the version of numpy in use.

References

.. [1] G. H. Golub and C. F. Van Loan, Matrix Computations, Baltimore, MD, Johns Hopkins University Press, 1985, pg. 15

Examples

>>> from scipy.linalg import norm
>>> a = np.arange(9) - 4.0
>>> a
array([-4., -3., -2., -1.,  0.,  1.,  2.,  3.,  4.])
>>> b = a.reshape((3, 3))
>>> b
array([[-4., -3., -2.],
       [-1.,  0.,  1.],
       [ 2.,  3.,  4.]])
>>> norm(a)
7.745966692414834
>>> norm(b)
7.745966692414834
>>> norm(b, 'fro')
7.745966692414834
>>> norm(a, np.inf)
4
>>> norm(b, np.inf)
9
>>> norm(a, -np.inf)
0
>>> norm(b, -np.inf)
2
>>> norm(a, 1)
20
>>> norm(b, 1)
7
>>> norm(a, -1)
-4.6566128774142013e-010
>>> norm(b, -1)
6
>>> norm(a, 2)
7.745966692414834
>>> norm(b, 2)
7.3484692283495345
>>> norm(a, -2)
0
>>> norm(b, -2)
1.8570331885190563e-016
>>> norm(a, 3)
5.8480354764257312
>>> norm(a, -3)
0

num_obs_dm

function num_obs_dm
val num_obs_dm :
  [>`Ndarray] Np.Obj.t ->
  int

Return the number of original observations that correspond to a square, redundant distance matrix.

Parameters

  • d : ndarray The target distance matrix.

Returns

  • num_obs_dm : int The number of observations in the redundant distance matrix.

num_obs_y

function num_obs_y
val num_obs_y :
  [>`Ndarray] Np.Obj.t ->
  int

Return the number of original observations that correspond to a condensed distance matrix.

Parameters

  • Y : ndarray Condensed distance matrix.

Returns

  • n : int The number of observations in the condensed distance matrix Y.

pdist

function pdist
val pdist :
  ?metric:[`S of string | `Callable of Py.Object.t] ->
  ?kwargs:(string * Py.Object.t) list ->
  x:[>`Ndarray] Np.Obj.t ->
  Py.Object.t list ->
  [`ArrayLike|`Ndarray|`Object] Np.Obj.t

Pairwise distances between observations in n-dimensional space.

See Notes for common calling conventions.

Parameters

  • X : ndarray An m by n array of m original observations in an n-dimensional space.

  • metric : str or function, optional The distance metric to use. The distance function can be 'braycurtis', 'canberra', 'chebyshev', 'cityblock', 'correlation', 'cosine', 'dice', 'euclidean', 'hamming', 'jaccard', 'jensenshannon', 'kulsinski', 'mahalanobis', 'matching', 'minkowski', 'rogerstanimoto', 'russellrao', 'seuclidean', 'sokalmichener', 'sokalsneath', 'sqeuclidean', 'yule'.

  • *args : tuple. Deprecated. Additional arguments should be passed as keyword arguments

  • **kwargs : dict, optional Extra arguments to metric: refer to each metric documentation for a list of all possible arguments.

    Some possible arguments:

  • p : scalar The p-norm to apply for Minkowski, weighted and unweighted.

  • Default: 2.

  • w : ndarray The weight vector for metrics that support weights (e.g., Minkowski).

  • V : ndarray The variance vector for standardized Euclidean.

  • Default: var(X, axis=0, ddof=1)

  • VI : ndarray The inverse of the covariance matrix for Mahalanobis.

  • Default: inv(cov(X.T)).T

  • out : ndarray. The output array If not None, condensed distance matrix Y is stored in this array.

  • Note: metric independent, it will become a regular keyword arg in a future scipy version

Returns

  • Y : ndarray Returns a condensed distance matrix Y. For

  • each :math:i and :math:j (where :math:i<j<m),where m is the number of original observations. The metric dist(u=X[i], v=X[j]) is computed and stored in entry ij.

See Also

  • squareform : converts between condensed distance matrices and square distance matrices.

Notes

See squareform for information on how to calculate the index of this entry or to convert the condensed distance matrix to a redundant square matrix.

The following are common calling conventions.

  1. Y = pdist(X, 'euclidean')

Computes the distance between m points using Euclidean distance (2-norm) as the distance metric between the points. The points are arranged as m n-dimensional row vectors in the matrix X.

  1. Y = pdist(X, 'minkowski', p=2.)

Computes the distances using the Minkowski distance :math:||u-v||_p (p-norm) where :math:p \geq 1.

  1. Y = pdist(X, 'cityblock')

Computes the city block or Manhattan distance between the points.

  1. Y = pdist(X, 'seuclidean', V=None)

Computes the standardized Euclidean distance. The standardized Euclidean distance between two n-vectors u and v is

.. math::

  \sqrt{\sum {(u_i-v_i)^2 / V[x_i]}}

V is the variance vector; V[i] is the variance computed over all the i'th components of the points. If not passed, it is automatically computed.

  1. Y = pdist(X, 'sqeuclidean')

Computes the squared Euclidean distance :math:||u-v||_2^2 between the vectors.

  1. Y = pdist(X, 'cosine')

Computes the cosine distance between vectors u and v,

.. math::

  1 - \frac{u \cdot v}
           {{ ||u|| }_2 { ||v|| }_2}
  • where :math:||*||_2 is the 2-norm of its argument *, and :math:u \cdot v is the dot product of u and v.

  • Y = pdist(X, 'correlation')

Computes the correlation distance between vectors u and v. This is

.. math::

  1 - \frac{(u - \bar{u}) \cdot (v - \bar{v})}
           {{ ||(u - \bar{u})|| }_2 { ||(v - \bar{v})|| }_2}
  • where :math:\bar{v} is the mean of the elements of vector v,

  • and :math:x \cdot y is the dot product of :math:x and :math:y.

  • Y = pdist(X, 'hamming')

Computes the normalized Hamming distance, or the proportion of those vector elements between two n-vectors u and v which disagree. To save memory, the matrix X can be of type boolean.

  1. Y = pdist(X, 'jaccard')

Computes the Jaccard distance between the points. Given two vectors, u and v, the Jaccard distance is the proportion of those elements u[i] and v[i] that disagree.

  1. Y = pdist(X, 'chebyshev')

Computes the Chebyshev distance between the points. The Chebyshev distance between two n-vectors u and v is the maximum norm-1 distance between their respective elements. More precisely, the distance is given by

.. math::

  d(u,v) = \max_i { |u_i-v_i| }
  1. Y = pdist(X, 'canberra')

Computes the Canberra distance between the points. The Canberra distance between two points u and v is

.. math::

 d(u,v) = \sum_i \frac{ |u_i-v_i| }
                      { |u_i|+|v_i| }
  1. Y = pdist(X, 'braycurtis')

Computes the Bray-Curtis distance between the points. The Bray-Curtis distance between two points u and v is

.. math::

    d(u,v) = \frac{\sum_i { |u_i-v_i| }}
                   {\sum_i { |u_i+v_i| }}
  1. Y = pdist(X, 'mahalanobis', VI=None)

Computes the Mahalanobis distance between the points. The Mahalanobis distance between two points u and v is :math:\sqrt{(u-v)(1/V)(u-v)^T} where :math:(1/V) (the VI variable) is the inverse covariance. If VI is not None, VI will be used as the inverse covariance matrix.

  1. Y = pdist(X, 'yule')

Computes the Yule distance between each pair of boolean vectors. (see yule function documentation)

  1. Y = pdist(X, 'matching')

Synonym for 'hamming'.

  1. Y = pdist(X, 'dice')

Computes the Dice distance between each pair of boolean vectors. (see dice function documentation)

  1. Y = pdist(X, 'kulsinski')

Computes the Kulsinski distance between each pair of boolean vectors. (see kulsinski function documentation)

  1. Y = pdist(X, 'rogerstanimoto')

Computes the Rogers-Tanimoto distance between each pair of boolean vectors. (see rogerstanimoto function documentation)

  1. Y = pdist(X, 'russellrao')

Computes the Russell-Rao distance between each pair of boolean vectors. (see russellrao function documentation)

  1. Y = pdist(X, 'sokalmichener')

Computes the Sokal-Michener distance between each pair of boolean vectors. (see sokalmichener function documentation)

  1. Y = pdist(X, 'sokalsneath')

Computes the Sokal-Sneath distance between each pair of boolean vectors. (see sokalsneath function documentation)

  1. Y = pdist(X, 'wminkowski', p=2, w=w)

Computes the weighted Minkowski distance between each pair of vectors. (see wminkowski function documentation)

  1. Y = pdist(X, f)

Computes the distance between all pairs of vectors in X using the user supplied 2-arity function f. For example, Euclidean distance between the vectors could be computed as follows::

 dm = pdist(X, lambda u, v: np.sqrt(((u-v)**2).sum()))

Note that you should avoid passing a reference to one of the distance functions defined in this library. For example,::

 dm = pdist(X, sokalsneath)

would calculate the pair-wise distances between the vectors in X using the Python function sokalsneath. This would result in sokalsneath being called :math:{n \choose 2} times, which is inefficient. Instead, the optimized C version is more efficient, and we call it using the following syntax.::

 dm = pdist(X, 'sokalsneath')

rel_entr

function rel_entr
val rel_entr :
  ?out:[>`Ndarray] Np.Obj.t ->
  ?where:Py.Object.t ->
  x:Py.Object.t ->
  unit ->
  Py.Object.t

rel_entr(x1, x2, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj])

rel_entr(x, y, out=None)

Elementwise function for computing relative entropy.

\mathrm{rel\_entr}(x, y) = \begin{cases} x \log(x / y) & x > 0, y > 0 \\ 0 & x = 0, y \ge 0 \\ \infty & \text{otherwise} \end{cases}

Parameters

x, y : array_like Input arrays

  • out : ndarray, optional Optional output array for the function results

Returns

scalar or ndarray Relative entropy of the inputs

See Also

entr, kl_div

Notes

.. versionadded:: 0.15.0

This function is jointly convex in x and y.

The origin of this function is in convex programming; see [1]_. Given two discrete probability distributions :math:p_1, \ldots, p_n and :math:q_1, \ldots, q_n, to get the relative entropy of statistics compute the sum

\sum_{i = 1}^n \mathrm{rel\_entr}(p_i, q_i).

See [2]_ for details.

References

.. [1] Grant, Boyd, and Ye, 'CVX: Matlab Software for Disciplined Convex Programming', http://cvxr.com/cvx/ .. [2] Kullback-Leibler divergence,

  • https://en.wikipedia.org/wiki/Kullback%E2%80%93Leibler_divergence

rogerstanimoto

function rogerstanimoto
val rogerstanimoto :
  ?w:[>`Ndarray] Np.Obj.t ->
  u:[`Ndarray of [>`Ndarray] Np.Obj.t | `Bool of bool] ->
  v:[`Ndarray of [>`Ndarray] Np.Obj.t | `Bool of bool] ->
  unit ->
  float

Compute the Rogers-Tanimoto dissimilarity between two boolean 1-D arrays.

The Rogers-Tanimoto dissimilarity between two boolean 1-D arrays u and v, is defined as

\frac{R} {c_{TT} + c_{FF} + R}
  • where :math:c_{ij} is the number of occurrences of :math:\mathtt{u[k]} = i and :math:\mathtt{v[k]} = j for :math:k < n and :math:R = 2(c_{TF} + c_{FT}).

Parameters

  • u : (N,) array_like, bool Input array.

  • v : (N,) array_like, bool Input array.

  • w : (N,) array_like, optional The weights for each value in u and v. Default is None, which gives each value a weight of 1.0

Returns

  • rogerstanimoto : double The Rogers-Tanimoto dissimilarity between vectors u and v.

Examples

>>> from scipy.spatial import distance
>>> distance.rogerstanimoto([1, 0, 0], [0, 1, 0])
0.8
>>> distance.rogerstanimoto([1, 0, 0], [1, 1, 0])
0.5
>>> distance.rogerstanimoto([1, 0, 0], [2, 0, 0])
-1.0

russellrao

function russellrao
val russellrao :
  ?w:[>`Ndarray] Np.Obj.t ->
  u:[`Ndarray of [>`Ndarray] Np.Obj.t | `Bool of bool] ->
  v:[`Ndarray of [>`Ndarray] Np.Obj.t | `Bool of bool] ->
  unit ->
  float

Compute the Russell-Rao dissimilarity between two boolean 1-D arrays.

The Russell-Rao dissimilarity between two boolean 1-D arrays, u and v, is defined as

\frac{n - c_{TT}} {n}
  • where :math:c_{ij} is the number of occurrences of :math:\mathtt{u[k]} = i and :math:\mathtt{v[k]} = j for :math:k < n.

Parameters

  • u : (N,) array_like, bool Input array.

  • v : (N,) array_like, bool Input array.

  • w : (N,) array_like, optional The weights for each value in u and v. Default is None, which gives each value a weight of 1.0

Returns

  • russellrao : double The Russell-Rao dissimilarity between vectors u and v.

Examples

>>> from scipy.spatial import distance
>>> distance.russellrao([1, 0, 0], [0, 1, 0])
1.0
>>> distance.russellrao([1, 0, 0], [1, 1, 0])
0.6666666666666666
>>> distance.russellrao([1, 0, 0], [2, 0, 0])
0.3333333333333333

seuclidean

function seuclidean
val seuclidean :
  u:[>`Ndarray] Np.Obj.t ->
  v:[>`Ndarray] Np.Obj.t ->
  v':[>`Ndarray] Np.Obj.t ->
  unit ->
  float

Return the standardized Euclidean distance between two 1-D arrays.

The standardized Euclidean distance between u and v.

Parameters

  • u : (N,) array_like Input array.

  • v : (N,) array_like Input array.

  • V : (N,) array_like V is an 1-D array of component variances. It is usually computed among a larger collection vectors.

Returns

  • seuclidean : double The standardized Euclidean distance between vectors u and v.

Examples

>>> from scipy.spatial import distance
>>> distance.seuclidean([1, 0, 0], [0, 1, 0], [0.1, 0.1, 0.1])
4.4721359549995796
>>> distance.seuclidean([1, 0, 0], [0, 1, 0], [1, 0.1, 0.1])
3.3166247903553998
>>> distance.seuclidean([1, 0, 0], [0, 1, 0], [10, 0.1, 0.1])
3.1780497164141406

sokalmichener

function sokalmichener
val sokalmichener :
  ?w:[>`Ndarray] Np.Obj.t ->
  u:[`Ndarray of [>`Ndarray] Np.Obj.t | `Bool of bool] ->
  v:[`Ndarray of [>`Ndarray] Np.Obj.t | `Bool of bool] ->
  unit ->
  float

Compute the Sokal-Michener dissimilarity between two boolean 1-D arrays.

The Sokal-Michener dissimilarity between boolean 1-D arrays u and v, is defined as

\frac{R} {S + R}
  • where :math:c_{ij} is the number of occurrences of :math:\mathtt{u[k]} = i and :math:\mathtt{v[k]} = j for :math:k < n, :math:R = 2 * (c_{TF} + c_{FT}) and :math:S = c_{FF} + c_{TT}.

Parameters

  • u : (N,) array_like, bool Input array.

  • v : (N,) array_like, bool Input array.

  • w : (N,) array_like, optional The weights for each value in u and v. Default is None, which gives each value a weight of 1.0

Returns

  • sokalmichener : double The Sokal-Michener dissimilarity between vectors u and v.

Examples

>>> from scipy.spatial import distance
>>> distance.sokalmichener([1, 0, 0], [0, 1, 0])
0.8
>>> distance.sokalmichener([1, 0, 0], [1, 1, 0])
0.5
>>> distance.sokalmichener([1, 0, 0], [2, 0, 0])
-1.0

sokalsneath

function sokalsneath
val sokalsneath :
  ?w:[>`Ndarray] Np.Obj.t ->
  u:[`Ndarray of [>`Ndarray] Np.Obj.t | `Bool of bool] ->
  v:[`Ndarray of [>`Ndarray] Np.Obj.t | `Bool of bool] ->
  unit ->
  float

Compute the Sokal-Sneath dissimilarity between two boolean 1-D arrays.

The Sokal-Sneath dissimilarity between u and v,

\frac{R} {c_{TT} + R}
  • where :math:c_{ij} is the number of occurrences of :math:\mathtt{u[k]} = i and :math:\mathtt{v[k]} = j for :math:k < n and :math:R = 2(c_{TF} + c_{FT}).

Parameters

  • u : (N,) array_like, bool Input array.

  • v : (N,) array_like, bool Input array.

  • w : (N,) array_like, optional The weights for each value in u and v. Default is None, which gives each value a weight of 1.0

Returns

  • sokalsneath : double The Sokal-Sneath dissimilarity between vectors u and v.

Examples

>>> from scipy.spatial import distance
>>> distance.sokalsneath([1, 0, 0], [0, 1, 0])
1.0
>>> distance.sokalsneath([1, 0, 0], [1, 1, 0])
0.66666666666666663
>>> distance.sokalsneath([1, 0, 0], [2, 1, 0])
0.0
>>> distance.sokalsneath([1, 0, 0], [3, 1, 0])
-2.0

sqeuclidean

function sqeuclidean
val sqeuclidean :
  ?w:[>`Ndarray] Np.Obj.t ->
  u:[>`Ndarray] Np.Obj.t ->
  v:[>`Ndarray] Np.Obj.t ->
  unit ->
  float

Compute the squared Euclidean distance between two 1-D arrays.

The squared Euclidean distance between u and v is defined as

{ ||u-v|| }_2^2

\left(\sum{(w_i |(u_i - v_i)|^2)}\right)

Parameters

  • u : (N,) array_like Input array.

  • v : (N,) array_like Input array.

  • w : (N,) array_like, optional The weights for each value in u and v. Default is None, which gives each value a weight of 1.0

Returns

  • sqeuclidean : double The squared Euclidean distance between vectors u and v.

Examples

>>> from scipy.spatial import distance
>>> distance.sqeuclidean([1, 0, 0], [0, 1, 0])
2.0
>>> distance.sqeuclidean([1, 1, 0], [0, 1, 0])
1.0

squareform

function squareform
val squareform :
  ?force:string ->
  ?checks:bool ->
  x:[>`Ndarray] Np.Obj.t ->
  unit ->
  [`ArrayLike|`Ndarray|`Object] Np.Obj.t

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 n-by-n symmetric distance matrix X, v = squareform(X) returns a n * (n-1) / 2 (i.e. binomial coefficient n choose 2) sized vector v

  • where :math:v[{n \choose 2} - {n-i \choose 2} + (j-i-1)] is the distance between distinct points i and j. If X is non-square or asymmetric, an error is raised.

  • X = squareform(v)

Given a n * (n-1) / 2 sized vector v for some integer n >= 1 encoding distances as described, X = squareform(v) returns a n-by-n 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.

wminkowski

function wminkowski
val wminkowski :
  u:[>`Ndarray] Np.Obj.t ->
  v:[>`Ndarray] Np.Obj.t ->
  p:int ->
  w:[>`Ndarray] Np.Obj.t ->
  unit ->
  float

Compute the weighted Minkowski distance between two 1-D arrays.

The weighted Minkowski distance between u and v, defined as

\left(\sum{(|w_i (u_i - v_i)|^p)}\right)^{1/p}.

Parameters

  • u : (N,) array_like Input array.

  • v : (N,) array_like Input array.

  • p : int The order of the norm of the difference :math:{ ||u-v|| }_p.

  • w : (N,) array_like The weight vector.

Returns

  • wminkowski : double The weighted Minkowski distance between vectors u and v.

Notes

wminkowski is DEPRECATED. It implements a definition where weights are powered. It is recommended to use the weighted version of minkowski instead. This function will be removed in a future version of scipy.

Examples

>>> from scipy.spatial import distance
>>> distance.wminkowski([1, 0, 0], [0, 1, 0], 1, np.ones(3))
2.0
>>> distance.wminkowski([1, 0, 0], [0, 1, 0], 2, np.ones(3))
1.4142135623730951
>>> distance.wminkowski([1, 0, 0], [0, 1, 0], 3, np.ones(3))
1.2599210498948732
>>> distance.wminkowski([1, 1, 0], [0, 1, 0], 1, np.ones(3))
1.0
>>> distance.wminkowski([1, 1, 0], [0, 1, 0], 2, np.ones(3))
1.0
>>> distance.wminkowski([1, 1, 0], [0, 1, 0], 3, np.ones(3))
1.0

yule

function yule
val yule :
  ?w:[>`Ndarray] Np.Obj.t ->
  u:[`Ndarray of [>`Ndarray] Np.Obj.t | `Bool of bool] ->
  v:[`Ndarray of [>`Ndarray] Np.Obj.t | `Bool of bool] ->
  unit ->
  float

Compute the Yule dissimilarity between two boolean 1-D arrays.

The Yule dissimilarity is defined as

\frac{R}{c_{TT} * c_{FF} + \frac{R}{2}}
  • where :math:c_{ij} is the number of occurrences of :math:\mathtt{u[k]} = i and :math:\mathtt{v[k]} = j for :math:k < n and :math:R = 2.0 * c_{TF} * c_{FT}.

Parameters

  • u : (N,) array_like, bool Input array.

  • v : (N,) array_like, bool Input array.

  • w : (N,) array_like, optional The weights for each value in u and v. Default is None, which gives each value a weight of 1.0

Returns

  • yule : double The Yule dissimilarity between vectors u and v.

Examples

>>> from scipy.spatial import distance
>>> distance.yule([1, 0, 0], [0, 1, 0])
2.0
>>> distance.yule([1, 1, 0], [0, 1, 0])
0.0

Kdtree

Module Scipy.​Spatial.​Kdtree wraps Python module scipy.spatial.kdtree.

distance_matrix

function distance_matrix
val distance_matrix :
  ?p:[`F of float | `T1_p_infinity of Py.Object.t] ->
  ?threshold:Py.Object.t ->
  x:Py.Object.t ->
  y:Py.Object.t ->
  unit ->
  [`ArrayLike|`Ndarray|`Object] Np.Obj.t

Compute the distance matrix.

Returns the matrix of all pair-wise distances.

Parameters

  • x : (M, K) array_like Matrix of M vectors in K dimensions.

  • y : (N, K) array_like Matrix of N vectors in K dimensions.

  • p : float, 1 <= p <= infinity Which Minkowski p-norm to use.

  • threshold : positive int If M * N * K > threshold, algorithm uses a Python loop instead of large temporary arrays.

Returns

  • result : (M, N) ndarray Matrix containing the distance from every vector in x to every vector in y.

Examples

>>> from scipy.spatial import distance_matrix
>>> distance_matrix([[0,0],[0,1]], [[1,0],[1,1]])
array([[ 1.        ,  1.41421356],
       [ 1.41421356,  1.        ]])

heappop

function heappop
val heappop :
  Py.Object.t ->
  Py.Object.t

Pop the smallest item off the heap, maintaining the heap invariant.

heappush

function heappush
val heappush :
  heap:Py.Object.t ->
  item:Py.Object.t ->
  unit ->
  Py.Object.t

Push item onto heap, maintaining the heap invariant.

minkowski_distance

function minkowski_distance
val minkowski_distance :
  ?p:[`F of float | `T1_p_infinity of Py.Object.t] ->
  x:Py.Object.t ->
  y:Py.Object.t ->
  unit ->
  Py.Object.t

Compute the L**p distance between two arrays.

Parameters

  • x : (M, K) array_like Input array.

  • y : (N, K) array_like Input array.

  • p : float, 1 <= p <= infinity Which Minkowski p-norm to use.

Examples

>>> from scipy.spatial import minkowski_distance
>>> minkowski_distance([[0,0],[0,0]], [[1,1],[0,1]])
array([ 1.41421356,  1.        ])

minkowski_distance_p

function minkowski_distance_p
val minkowski_distance_p :
  ?p:[`F of float | `T1_p_infinity of Py.Object.t] ->
  x:Py.Object.t ->
  y:Py.Object.t ->
  unit ->
  Py.Object.t

Compute the pth power of the L**p distance between two arrays.

For efficiency, this function computes the Lp distance but does not extract the pth root. If p is 1 or infinity, this is equal to the actual Lp distance.

Parameters

  • x : (M, K) array_like Input array.

  • y : (N, K) array_like Input array.

  • p : float, 1 <= p <= infinity Which Minkowski p-norm to use.

Examples

>>> from scipy.spatial import minkowski_distance_p
>>> minkowski_distance_p([[0,0],[0,0]], [[1,1],[0,1]])
array([2, 1])

Qhull

Module Scipy.​Spatial.​Qhull wraps Python module scipy.spatial.qhull.

QhullError

Module Scipy.​Spatial.​Qhull.​QhullError wraps Python class scipy.spatial.qhull.QhullError.

type t

with_traceback

method with_traceback
val with_traceback :
  tb:Py.Object.t ->
  [> tag] Obj.t ->
  Py.Object.t

Exception.with_traceback(tb) -- set self.traceback to tb and return self.

to_string

method to_string
val to_string: t -> string

Print the object to a human-readable representation.

show

method show
val show: t -> string

Print the object to a human-readable representation.

pp

method pp
val pp: Format.formatter -> t -> unit

Pretty-print the object to a formatter.

asbytes

function asbytes
val asbytes :
  Py.Object.t ->
  Py.Object.t

tsearch

function tsearch
val tsearch :
  tri:Py.Object.t ->
  xi:Py.Object.t ->
  unit ->
  Py.Object.t

tsearch(tri, xi)

Find simplices containing the given points. This function does the same thing as Delaunay.find_simplex.

.. versionadded:: 0.9

See Also

Delaunay.find_simplex

Examples

>>> import numpy as np
>>> import matplotlib.pyplot as plt
>>> from scipy.spatial import Delaunay, delaunay_plot_2d, tsearch

The Delaunay triangulation of a set of random points:

>>> pts = np.random.rand(20, 2)
>>> tri = Delaunay(pts)
>>> _ = delaunay_plot_2d(tri)

Find the simplices containing a given set of points:

>>> loc = np.random.uniform(0.2, 0.8, (5, 2))
>>> s = tsearch(tri, loc)
>>> plt.triplot(pts[:, 0], pts[:, 1], tri.simplices[s], 'b-', mask=s==-1)
>>> plt.scatter(loc[:, 0], loc[:, 1], c='r', marker='x')
>>> plt.show()

Transform

Module Scipy.​Spatial.​Transform wraps Python module scipy.spatial.transform.

Rotation

Module Scipy.​Spatial.​Transform.​Rotation wraps Python class scipy.spatial.transform.Rotation.

type t

create

constructor and attributes create
val create :
  ?normalize:Py.Object.t ->
  ?copy:Py.Object.t ->
  quat:Py.Object.t ->
  unit ->
  t

Rotation in 3 dimensions.

This class provides an interface to initialize from and represent rotations with:

  • Quaternions
  • Rotation Matrices
  • Rotation Vectors
  • Euler Angles

The following operations on rotations are supported:

  • Application on vectors
  • Rotation Composition
  • Rotation Inversion
  • Rotation Indexing

Indexing within a rotation is supported since multiple rotation transforms can be stored within a single Rotation instance.

To create Rotation objects use from_... methods (see examples below). Rotation(...) is not supposed to be instantiated directly.

Methods

len from_quat from_matrix from_rotvec from_euler as_quat as_matrix as_rotvec as_euler apply mul inv magnitude mean reduce create_group getitem identity random align_vectors

See Also

Slerp

Notes

.. versionadded: 1.2.0

Examples

>>> from scipy.spatial.transform import Rotation as R

A Rotation instance can be initialized in any of the above formats and converted to any of the others. The underlying object is independent of the representation used for initialization.

Consider a counter-clockwise rotation of 90 degrees about the z-axis. This corresponds to the following quaternion (in scalar-last format):

>>> r = R.from_quat([0, 0, np.sin(np.pi/4), np.cos(np.pi/4)])

The rotation can be expressed in any of the other formats:

>>> r.as_matrix()
array([[ 2.22044605e-16, -1.00000000e+00,  0.00000000e+00],
[ 1.00000000e+00,  2.22044605e-16,  0.00000000e+00],
[ 0.00000000e+00,  0.00000000e+00,  1.00000000e+00]])
>>> r.as_rotvec()
array([0.        , 0.        , 1.57079633])
>>> r.as_euler('zyx', degrees=True)
array([90.,  0.,  0.])

The same rotation can be initialized using a rotation matrix:

>>> r = R.from_matrix([[0, -1, 0],
...                    [1, 0, 0],
...                    [0, 0, 1]])

Representation in other formats:

>>> r.as_quat()
array([0.        , 0.        , 0.70710678, 0.70710678])
>>> r.as_rotvec()
array([0.        , 0.        , 1.57079633])
>>> r.as_euler('zyx', degrees=True)
array([90.,  0.,  0.])

The rotation vector corresponding to this rotation is given by:

>>> r = R.from_rotvec(np.pi/2 * np.array([0, 0, 1]))

Representation in other formats:

>>> r.as_quat()
array([0.        , 0.        , 0.70710678, 0.70710678])
>>> r.as_matrix()
array([[ 2.22044605e-16, -1.00000000e+00,  0.00000000e+00],
       [ 1.00000000e+00,  2.22044605e-16,  0.00000000e+00],
       [ 0.00000000e+00,  0.00000000e+00,  1.00000000e+00]])
>>> r.as_euler('zyx', degrees=True)
array([90.,  0.,  0.])

The from_euler method is quite flexible in the range of input formats it supports. Here we initialize a single rotation about a single axis:

>>> r = R.from_euler('z', 90, degrees=True)

Again, the object is representation independent and can be converted to any other format:

>>> r.as_quat()
array([0.        , 0.        , 0.70710678, 0.70710678])
>>> r.as_matrix()
array([[ 2.22044605e-16, -1.00000000e+00,  0.00000000e+00],
       [ 1.00000000e+00,  2.22044605e-16,  0.00000000e+00],
       [ 0.00000000e+00,  0.00000000e+00,  1.00000000e+00]])
>>> r.as_rotvec()
array([0.        , 0.        , 1.57079633])

It is also possible to initialize multiple rotations in a single instance using any of the from_... functions. Here we initialize a stack of 3 rotations using the from_euler method:

>>> r = R.from_euler('zyx', [
... [90, 0, 0],
... [0, 45, 0],
... [45, 60, 30]], degrees=True)

The other representations also now return a stack of 3 rotations. For example:

>>> r.as_quat()
array([[0.        , 0.        , 0.70710678, 0.70710678],
       [0.        , 0.38268343, 0.        , 0.92387953],
       [0.39190384, 0.36042341, 0.43967974, 0.72331741]])

Applying the above rotations onto a vector:

>>> v = [1, 2, 3]
>>> r.apply(v)
array([[-2.        ,  1.        ,  3.        ],
       [ 2.82842712,  2.        ,  1.41421356],
       [ 2.24452282,  0.78093109,  2.89002836]])

A Rotation instance can be indexed and sliced as if it were a single 1D array or list:

>>> r.as_quat()
array([[0.        , 0.        , 0.70710678, 0.70710678],
       [0.        , 0.38268343, 0.        , 0.92387953],
       [0.39190384, 0.36042341, 0.43967974, 0.72331741]])
>>> p = r[0]
>>> p.as_matrix()
array([[ 2.22044605e-16, -1.00000000e+00,  0.00000000e+00],
       [ 1.00000000e+00,  2.22044605e-16,  0.00000000e+00],
       [ 0.00000000e+00,  0.00000000e+00,  1.00000000e+00]])
>>> q = r[1:3]
>>> q.as_quat()
array([[0.        , 0.38268343, 0.        , 0.92387953],
       [0.39190384, 0.36042341, 0.43967974, 0.72331741]])

Multiple rotations can be composed using the * operator:

>>> r1 = R.from_euler('z', 90, degrees=True)
>>> r2 = R.from_rotvec([np.pi/4, 0, 0])
>>> v = [1, 2, 3]
>>> r2.apply(r1.apply(v))
array([-2.        , -1.41421356,  2.82842712])
>>> r3 = r2 * r1 # Note the order
>>> r3.apply(v)
array([-2.        , -1.41421356,  2.82842712])

Finally, it is also possible to invert rotations:

>>> r1 = R.from_euler('z', [90, 45], degrees=True)
>>> r2 = r1.inv()
>>> r2.as_euler('zyx', degrees=True)
array([[-90.,   0.,   0.],
       [-45.,   0.,   0.]])

These examples serve as an overview into the Rotation class and highlight major functionalities. For more thorough examples of the range of input and output formats supported, consult the individual method's examples.

getitem

method getitem
val __getitem__ :
  indexer:[`Slice of Np.Wrap_utils.Slice.t | `PyObject of Py.Object.t] ->
  [> tag] Obj.t ->
  Py.Object.t

Extract rotation(s) at given index(es) from object.

Create a new Rotation instance containing a subset of rotations stored in this object.

Parameters

  • indexer : index, slice, or index array Specifies which rotation(s) to extract. A single indexer must be specified, i.e. as if indexing a 1 dimensional array or list.

Returns

  • rotation : Rotation instance Contains - a single rotation, if indexer is a single index - a stack of rotation(s), if indexer is a slice, or and index array.

Examples

>>> from scipy.spatial.transform import Rotation as R
>>> r = R.from_quat([
... [1, 1, 0, 0],
... [0, 1, 0, 1],
... [1, 1, -1, 0]])
>>> r.as_quat()
array([[ 0.70710678,  0.70710678,  0.        ,  0.        ],
       [ 0.        ,  0.70710678,  0.        ,  0.70710678],
       [ 0.57735027,  0.57735027, -0.57735027,  0.        ]])

Indexing using a single index:

>>> p = r[0]
>>> p.as_quat()
array([0.70710678, 0.70710678, 0.        , 0.        ])

Array slicing:

>>> q = r[1:3]
>>> q.as_quat()
array([[ 0.        ,  0.70710678,  0.        ,  0.70710678],
       [ 0.57735027,  0.57735027, -0.57735027,  0.        ]])

align_vectors

method align_vectors
val align_vectors :
  ?weights:[>`Ndarray] Np.Obj.t ->
  ?return_sensitivity:bool ->
  a:[>`Ndarray] Np.Obj.t ->
  b:[>`Ndarray] Np.Obj.t ->
  [> tag] Obj.t ->
  (Py.Object.t * float * [`ArrayLike|`Ndarray|`Object] Np.Obj.t)

Estimate a rotation to optimally align two sets of vectors.

Find a rotation between frames A and B which best aligns a set of vectors a and b observed in these frames. The following loss function is minimized to solve for the rotation matrix :math:C:

L(C) = \frac{1}{2} \sum_{i = 1}^{n} w_i \lVert \mathbf{a}_i - C \mathbf{b}_i \rVert^2 ,
  • where :math:w_i's are the weights corresponding to each vector.

The rotation is estimated with Kabsch algorithm [1]_.

Parameters

  • a : array_like, shape (N, 3) Vector components observed in initial frame A. Each row of a denotes a vector.

  • b : array_like, shape (N, 3) Vector components observed in another frame B. Each row of b denotes a vector.

  • weights : array_like shape (N,), optional Weights describing the relative importance of the vector observations. If None (default), then all values in weights are assumed to be 1.

  • return_sensitivity : bool, optional Whether to return the sensitivity matrix. See Notes for details. Default is False.

Returns

  • estimated_rotation : Rotation instance Best estimate of the rotation that transforms b to a.

  • rmsd : float Root mean square distance (weighted) between the given set of vectors after alignment. It is equal to sqrt(2 * minimum_loss), where minimum_loss is the loss function evaluated for the found optimal rotation.

  • sensitivity_matrix : ndarray, shape (3, 3) Sensitivity matrix of the estimated rotation estimate as explained in Notes. Returned only when return_sensitivity is True.

Notes

This method can also compute the sensitivity of the estimated rotation to small perturbations of the vector measurements. Specifically we consider the rotation estimate error as a small rotation vector of frame A. The sensitivity matrix is proportional to the covariance of this rotation vector assuming that the vectors in a was measured with errors significantly less than their lengths. To get the true covariance matrix, the returned sensitivity matrix must be multiplied by harmonic mean [3]_ of variance in each observation. Note that weights are supposed to be inversely proportional to the observation variances to get consistent results. For example, if all vectors are measured with the same accuracy of 0.01 (weights must be all equal), then you should multiple the sensitivity matrix by 0.01**2 to get the covariance.

Refer to [2]_ for more rigorous discussion of the covariance estimation.

References

.. [1] https://en.wikipedia.org/wiki/Kabsch_algorithm .. [2] F. Landis Markley, 'Attitude determination using vector observations: a fast optimal matrix algorithm', Journal of Astronautical Sciences, Vol. 41, No.2, 1993, pp. 261-280. .. [3] https://en.wikipedia.org/wiki/Harmonic_mean

apply

method apply
val apply :
  ?inverse:bool ->
  vectors:[>`Ndarray] Np.Obj.t ->
  [> tag] Obj.t ->
  [`ArrayLike|`Ndarray|`Object] Np.Obj.t

Apply this rotation to a set of vectors.

If the original frame rotates to the final frame by this rotation, then its application to a vector can be seen in two ways:

- As a projection of vector components expressed in the final frame
  to the original frame.
- As the physical rotation of a vector being glued to the original
  frame as it rotates. In this case the vector components are
  expressed in the original frame before and after the rotation.

In terms of rotation matricies, this application is the same as self.as_matrix().dot(vectors).

Parameters

  • vectors : array_like, shape (3,) or (N, 3) Each vectors[i] represents a vector in 3D space. A single vector can either be specified with shape (3, ) or (1, 3). The number of rotations and number of vectors given must follow standard numpy broadcasting rules: either one of them equals unity or they both equal each other.

  • inverse : boolean, optional If True then the inverse of the rotation(s) is applied to the input vectors. Default is False.

Returns

  • rotated_vectors : ndarray, shape (3,) or (N, 3) Result of applying rotation on input vectors. Shape depends on the following cases:
    - If object contains a single rotation (as opposed to a stack
      with a single rotation) and a single vector is specified with
      shape ``(3,)``, then `rotated_vectors` has shape ``(3,)``.
    - In all other cases, `rotated_vectors` has shape ``(N, 3)``,
      where ``N`` is either the number of rotations or vectors.
    

Examples

>>> from scipy.spatial.transform import Rotation as R

Single rotation applied on a single vector:

>>> vector = np.array([1, 0, 0])
>>> r = R.from_rotvec([0, 0, np.pi/2])
>>> r.as_matrix()
array([[ 2.22044605e-16, -1.00000000e+00,  0.00000000e+00],
       [ 1.00000000e+00,  2.22044605e-16,  0.00000000e+00],
       [ 0.00000000e+00,  0.00000000e+00,  1.00000000e+00]])
>>> r.apply(vector)
array([2.22044605e-16, 1.00000000e+00, 0.00000000e+00])
>>> r.apply(vector).shape
(3,)

Single rotation applied on multiple vectors:

>>> vectors = np.array([
... [1, 0, 0],
... [1, 2, 3]])
>>> r = R.from_rotvec([0, 0, np.pi/4])
>>> r.as_matrix()
array([[ 0.70710678, -0.70710678,  0.        ],
       [ 0.70710678,  0.70710678,  0.        ],
       [ 0.        ,  0.        ,  1.        ]])
>>> r.apply(vectors)
array([[ 0.70710678,  0.70710678,  0.        ],
       [-0.70710678,  2.12132034,  3.        ]])
>>> r.apply(vectors).shape
(2, 3)

Multiple rotations on a single vector:

>>> r = R.from_rotvec([[0, 0, np.pi/4], [np.pi/2, 0, 0]])
>>> vector = np.array([1,2,3])
>>> r.as_matrix()
array([[[ 7.07106781e-01, -7.07106781e-01,  0.00000000e+00],
        [ 7.07106781e-01,  7.07106781e-01,  0.00000000e+00],
        [ 0.00000000e+00,  0.00000000e+00,  1.00000000e+00]],
       [[ 1.00000000e+00,  0.00000000e+00,  0.00000000e+00],
        [ 0.00000000e+00,  2.22044605e-16, -1.00000000e+00],
        [ 0.00000000e+00,  1.00000000e+00,  2.22044605e-16]]])
>>> r.apply(vector)
array([[-0.70710678,  2.12132034,  3.        ],
       [ 1.        , -3.        ,  2.        ]])
>>> r.apply(vector).shape
(2, 3)

Multiple rotations on multiple vectors. Each rotation is applied on the corresponding vector:

>>> r = R.from_euler('zxy', [
... [0, 0, 90],
... [45, 30, 60]], degrees=True)
>>> vectors = [
... [1, 2, 3],
... [1, 0, -1]]
>>> r.apply(vectors)
array([[ 3.        ,  2.        , -1.        ],
       [-0.09026039,  1.11237244, -0.86860844]])
>>> r.apply(vectors).shape
(2, 3)

It is also possible to apply the inverse rotation:

>>> r = R.from_euler('zxy', [
... [0, 0, 90],
... [45, 30, 60]], degrees=True)
>>> vectors = [
... [1, 2, 3],
... [1, 0, -1]]
>>> r.apply(vectors, inverse=True)
array([[-3.        ,  2.        ,  1.        ],
       [ 1.09533535, -0.8365163 ,  0.3169873 ]])

as_euler

method as_euler
val as_euler :
  ?degrees:bool ->
  seq:[`S of string | `Length_3 of Py.Object.t] ->
  [> tag] Obj.t ->
  [`ArrayLike|`Ndarray|`Object] Np.Obj.t

Represent as Euler angles.

Any orientation can be expressed as a composition of 3 elementary rotations. Once the axis sequence has been chosen, Euler angles define the angle of rotation around each respective axis [1]_.

The algorithm from [2]_ has been used to calculate Euler angles for the rotation about a given sequence of axes.

Euler angles suffer from the problem of gimbal lock [3]_, where the representation loses a degree of freedom and it is not possible to determine the first and third angles uniquely. In this case, a warning is raised, and the third angle is set to zero. Note however that the returned angles still represent the correct rotation.

Parameters

  • seq : string, length 3 3 characters belonging to the set {'X', 'Y', 'Z'} for intrinsic rotations, or {'x', 'y', 'z'} for extrinsic rotations [1]_. Adjacent axes cannot be the same. Extrinsic and intrinsic rotations cannot be mixed in one function call.

  • degrees : boolean, optional Returned angles are in degrees if this flag is True, else they are in radians. Default is False.

Returns

  • angles : ndarray, shape (3,) or (N, 3) Shape depends on shape of inputs used to initialize object. The returned angles are in the range:

    • First angle belongs to [-180, 180] degrees (both inclusive)
    • Third angle belongs to [-180, 180] degrees (both inclusive)
    • Second angle belongs to:

      • [-90, 90] degrees if all axes are different (like xyz)
      • [0, 180] degrees if first and third axes are the same (like zxz)

References

.. [1] https://en.wikipedia.org/wiki/Euler_angles#Definition_by_intrinsic_rotations .. [2] Malcolm D. Shuster, F. Landis Markley, 'General formula for extraction the Euler angles', Journal of guidance, control, and dynamics, vol. 29.1, pp. 215-221. 2006 .. [3] https://en.wikipedia.org/wiki/Gimbal_lock#In_applied_mathematics

Examples

>>> from scipy.spatial.transform import Rotation as R

Represent a single rotation:

>>> r = R.from_rotvec([0, 0, np.pi/2])
>>> r.as_euler('zxy', degrees=True)
array([90.,  0.,  0.])
>>> r.as_euler('zxy', degrees=True).shape
(3,)

Represent a stack of single rotation:

>>> r = R.from_rotvec([[0, 0, np.pi/2]])
>>> r.as_euler('zxy', degrees=True)
array([[90.,  0.,  0.]])
>>> r.as_euler('zxy', degrees=True).shape
(1, 3)

Represent multiple rotations in a single object:

>>> r = R.from_rotvec([
... [0, 0, np.pi/2],
... [0, -np.pi/3, 0],
... [np.pi/4, 0, 0]])
>>> r.as_euler('zxy', degrees=True)
array([[ 90.,   0.,   0.],
       [  0.,   0., -60.],
       [  0.,  45.,   0.]])
>>> r.as_euler('zxy', degrees=True).shape
(3, 3)

as_matrix

method as_matrix
val as_matrix :
  [> tag] Obj.t ->
  [`ArrayLike|`Ndarray|`Object] Np.Obj.t

Represent as rotation matrix.

3D rotations can be represented using rotation matrices, which are 3 x 3 real orthogonal matrices with determinant equal to +1 [1]_.

Returns

  • matrix : ndarray, shape (3, 3) or (N, 3, 3) Shape depends on shape of inputs used for initialization.

References

.. [1] https://en.wikipedia.org/wiki/Rotation_matrix#In_three_dimensions

Examples

>>> from scipy.spatial.transform import Rotation as R

Represent a single rotation:

>>> r = R.from_rotvec([0, 0, np.pi/2])
>>> r.as_matrix()
array([[ 2.22044605e-16, -1.00000000e+00,  0.00000000e+00],
       [ 1.00000000e+00,  2.22044605e-16,  0.00000000e+00],
       [ 0.00000000e+00,  0.00000000e+00,  1.00000000e+00]])
>>> r.as_matrix().shape
(3, 3)

Represent a stack with a single rotation:

>>> r = R.from_quat([[1, 1, 0, 0]])
>>> r.as_matrix()
array([[[ 0.,  1.,  0.],
        [ 1.,  0.,  0.],
        [ 0.,  0., -1.]]])
>>> r.as_matrix().shape
(1, 3, 3)

Represent multiple rotations:

>>> r = R.from_rotvec([[np.pi/2, 0, 0], [0, 0, np.pi/2]])
>>> r.as_matrix()
array([[[ 1.00000000e+00,  0.00000000e+00,  0.00000000e+00],
        [ 0.00000000e+00,  2.22044605e-16, -1.00000000e+00],
        [ 0.00000000e+00,  1.00000000e+00,  2.22044605e-16]],
       [[ 2.22044605e-16, -1.00000000e+00,  0.00000000e+00],
        [ 1.00000000e+00,  2.22044605e-16,  0.00000000e+00],
        [ 0.00000000e+00,  0.00000000e+00,  1.00000000e+00]]])
>>> r.as_matrix().shape
(2, 3, 3)

Notes

This function was called as_dcm before.

.. versionadded:: 1.4.0

as_quat

method as_quat
val as_quat :
  [> tag] Obj.t ->
  Py.Object.t

Represent as quaternions.

Rotations in 3 dimensions can be represented using unit norm quaternions [1]_. The mapping from quaternions to rotations is two-to-one, i.e. quaternions q and -q, where -q simply reverses the sign of each component, represent the same spatial rotation.

Returns

  • quat : numpy.ndarray, shape (4,) or (N, 4) Shape depends on shape of inputs used for initialization.

References

.. [1] https://en.wikipedia.org/wiki/Quaternions_and_spatial_rotation

Examples

>>> from scipy.spatial.transform import Rotation as R

Represent a single rotation:

>>> r = R.from_matrix([[0, -1, 0],
...                    [1, 0, 0],
...                    [0, 0, 1]])
>>> r.as_quat()
array([0.        , 0.        , 0.70710678, 0.70710678])
>>> r.as_quat().shape
(4,)

Represent a stack with a single rotation:

>>> r = R.from_quat([[0, 0, 0, 1]])
>>> r.as_quat().shape
(1, 4)

Represent multiple rotations in a single object:

>>> r = R.from_rotvec([[np.pi, 0, 0], [0, 0, np.pi/2]])
>>> r.as_quat().shape
(2, 4)

as_rotvec

method as_rotvec
val as_rotvec :
  [> tag] Obj.t ->
  [`ArrayLike|`Ndarray|`Object] Np.Obj.t

Represent as rotation vectors.

A rotation vector is a 3 dimensional vector which is co-directional to the axis of rotation and whose norm gives the angle of rotation (in radians) [1]_.

Returns

  • rotvec : ndarray, shape (3,) or (N, 3) Shape depends on shape of inputs used for initialization.

References

.. [1] https://en.wikipedia.org/wiki/Axis%E2%80%93angle_representation#Rotation_vector

Examples

>>> from scipy.spatial.transform import Rotation as R

Represent a single rotation:

>>> r = R.from_euler('z', 90, degrees=True)
>>> r.as_rotvec()
array([0.        , 0.        , 1.57079633])
>>> r.as_rotvec().shape
(3,)

Represent a stack with a single rotation:

>>> r = R.from_quat([[0, 0, 1, 1]])
>>> r.as_rotvec()
array([[0.        , 0.        , 1.57079633]])
>>> r.as_rotvec().shape
(1, 3)

Represent multiple rotations in a single object:

>>> r = R.from_quat([[0, 0, 1, 1], [1, 1, 0, 1]])
>>> r.as_rotvec()
array([[0.        , 0.        , 1.57079633],
       [1.35102172, 1.35102172, 0.        ]])
>>> r.as_rotvec().shape
(2, 3)

create_group

method create_group
val create_group :
  ?axis:int ->
  group:string ->
  [> tag] Obj.t ->
  Py.Object.t

Create a 3D rotation group.

Parameters

  • group : string The name of the group. Must be one of 'I', 'O', 'T', 'Dn', 'Cn', where n is a positive integer. The groups are:

    * I: Icosahedral group
    * O: Octahedral group
    * T: Tetrahedral group
    * D: Dicyclic group
    * C: Cyclic group
    
  • axis : integer The cyclic rotation axis. Must be one of ['X', 'Y', 'Z'] (or lowercase). Default is 'Z'. Ignored for groups 'I', 'O', and 'T'.

Returns

  • rotation : Rotation instance Object containing the elements of the rotation group.

Notes

This method generates rotation groups only. The full 3-dimensional point groups [PointGroups]_ also contain reflections.

References

.. [PointGroups] Point groups <https://en.wikipedia.org/wiki/Point_groups_in_three_dimensions>_ on Wikipedia.

from_dcm

method from_dcm
val from_dcm :
  ?kwds:(string * Py.Object.t) list ->
  Py.Object.t list ->
  [> tag] Obj.t ->
  Py.Object.t

from_dcm is deprecated! from_dcm is renamed to from_matrix in scipy 1.4.0 and will be removed in scipy 1.6.0

from_euler

method from_euler
val from_euler :
  ?degrees:bool ->
  seq:string ->
  angles:[`F of float | `Ndarray of [>`Ndarray] Np.Obj.t] ->
  [> tag] Obj.t ->
  Py.Object.t

Initialize from Euler angles.

Rotations in 3-D can be represented by a sequence of 3 rotations around a sequence of axes. In theory, any three axes spanning the 3-D Euclidean space are enough. In practice, the axes of rotation are chosen to be the basis vectors.

The three rotations can either be in a global frame of reference (extrinsic) or in a body centred frame of reference (intrinsic), which is attached to, and moves with, the object under rotation [1]_.

Parameters

  • seq : string Specifies sequence of axes for rotations. Up to 3 characters belonging to the set {'X', 'Y', 'Z'} for intrinsic rotations, or {'x', 'y', 'z'} for extrinsic rotations. Extrinsic and intrinsic rotations cannot be mixed in one function call.

  • angles : float or array_like, shape (N,) or (N, [1 or 2 or 3]) Euler angles specified in radians (degrees is False) or degrees (degrees is True). For a single character seq, angles can be:

    • a single value
    • array_like with shape (N,), where each angle[i] corresponds to a single rotation
    • array_like with shape (N, 1), where each angle[i, 0] corresponds to a single rotation

    For 2- and 3-character wide seq, angles can be:

    • array_like with shape (W,) where W is the width of seq, which corresponds to a single rotation with W axes
    • array_like with shape (N, W) where each angle[i] corresponds to a sequence of Euler angles describing a single rotation
  • degrees : bool, optional If True, then the given angles are assumed to be in degrees. Default is False.

Returns

  • rotation : Rotation instance Object containing the rotation represented by the sequence of rotations around given axes with given angles.

References

.. [1] https://en.wikipedia.org/wiki/Euler_angles#Definition_by_intrinsic_rotations

Examples

>>> from scipy.spatial.transform import Rotation as R

Initialize a single rotation along a single axis:

>>> r = R.from_euler('x', 90, degrees=True)
>>> r.as_quat().shape
(4,)

Initialize a single rotation with a given axis sequence:

>>> r = R.from_euler('zyx', [90, 45, 30], degrees=True)
>>> r.as_quat().shape
(4,)

Initialize a stack with a single rotation around a single axis:

>>> r = R.from_euler('x', [90], degrees=True)
>>> r.as_quat().shape
(1, 4)

Initialize a stack with a single rotation with an axis sequence:

>>> r = R.from_euler('zyx', [[90, 45, 30]], degrees=True)
>>> r.as_quat().shape
(1, 4)

Initialize multiple elementary rotations in one object:

>>> r = R.from_euler('x', [90, 45, 30], degrees=True)
>>> r.as_quat().shape
(3, 4)

Initialize multiple rotations in one object:

>>> r = R.from_euler('zyx', [[90, 45, 30], [35, 45, 90]], degrees=True)
>>> r.as_quat().shape
(2, 4)

from_matrix

method from_matrix
val from_matrix :
  matrix:[>`Ndarray] Np.Obj.t ->
  [> tag] Obj.t ->
  Py.Object.t

Initialize from rotation matrix.

Rotations in 3 dimensions can be represented with 3 x 3 proper orthogonal matrices [1]. If the input is not proper orthogonal, an approximation is created using the method described in [2].

Parameters

  • matrix : array_like, shape (N, 3, 3) or (3, 3) A single matrix or a stack of matrices, where matrix[i] is the i-th matrix.

Returns

  • rotation : Rotation instance Object containing the rotations represented by the rotation matrices.

References

.. [1] https://en.wikipedia.org/wiki/Rotation_matrix#In_three_dimensions .. [2] F. Landis Markley, 'Unit Quaternion from Rotation Matrix', Journal of guidance, control, and dynamics vol. 31.2, pp. 440-442, 2008.

Examples

>>> from scipy.spatial.transform import Rotation as R

Initialize a single rotation:

>>> r = R.from_matrix([
... [0, -1, 0],
... [1, 0, 0],
... [0, 0, 1]])
>>> r.as_matrix().shape
(3, 3)

Initialize multiple rotations in a single object:

>>> r = R.from_matrix([
... [
...     [0, -1, 0],
...     [1, 0, 0],
...     [0, 0, 1],
... ],
... [
...     [1, 0, 0],
...     [0, 0, -1],
...     [0, 1, 0],
... ]])
>>> r.as_matrix().shape
(2, 3, 3)

If input matrices are not special orthogonal (orthogonal with determinant equal to +1), then a special orthogonal estimate is stored:

>>> a = np.array([
... [0, -0.5, 0],
... [0.5, 0, 0],
... [0, 0, 0.5]])
>>> np.linalg.det(a)
0.12500000000000003
>>> r = R.from_matrix(a)
>>> matrix = r.as_matrix()
>>> matrix
array([[-0.38461538, -0.92307692,  0.        ],
       [ 0.92307692, -0.38461538,  0.        ],
       [ 0.        ,  0.        ,  1.        ]])
>>> np.linalg.det(matrix)
1.0000000000000002

It is also possible to have a stack containing a single rotation:

>>> r = R.from_matrix([[
... [0, -1, 0],
... [1, 0, 0],
... [0, 0, 1]]])
>>> r.as_matrix()
array([[[ 0., -1.,  0.],
        [ 1.,  0.,  0.],
        [ 0.,  0.,  1.]]])
>>> r.as_matrix().shape
(1, 3, 3)

Notes

This function was called from_dcm before.

.. versionadded:: 1.4.0

from_quat

method from_quat
val from_quat :
  ?normalized:Py.Object.t ->
  quat:[>`Ndarray] Np.Obj.t ->
  [> tag] Obj.t ->
  Py.Object.t

Initialize from quaternions.

3D rotations can be represented using unit-norm quaternions [1]_.

Parameters

  • quat : array_like, shape (N, 4) or (4,) Each row is a (possibly non-unit norm) quaternion in scalar-last (x, y, z, w) format. Each quaternion will be normalized to unit norm. normalized Deprecated argument. Has no effect, input quat is always normalized.

    .. deprecated:: 1.4.0

Returns

  • rotation : Rotation instance Object containing the rotations represented by input quaternions.

References

.. [1] https://en.wikipedia.org/wiki/Quaternions_and_spatial_rotation

Examples

>>> from scipy.spatial.transform import Rotation as R

Initialize a single rotation:

>>> r = R.from_quat([1, 0, 0, 0])
>>> r.as_quat()
array([1., 0., 0., 0.])
>>> r.as_quat().shape
(4,)

Initialize multiple rotations in a single object:

>>> r = R.from_quat([
... [1, 0, 0, 0],
... [0, 0, 0, 1]
... ])
>>> r.as_quat()
array([[1., 0., 0., 0.],
       [0., 0., 0., 1.]])
>>> r.as_quat().shape
(2, 4)

It is also possible to have a stack of a single rotation:

>>> r = R.from_quat([[0, 0, 0, 1]])
>>> r.as_quat()
array([[0., 0., 0., 1.]])
>>> r.as_quat().shape
(1, 4)

Quaternions are normalized before initialization.

>>> r = R.from_quat([0, 0, 1, 1])
>>> r.as_quat()
array([0.        , 0.        , 0.70710678, 0.70710678])

from_rotvec

method from_rotvec
val from_rotvec :
  rotvec:[>`Ndarray] Np.Obj.t ->
  [> tag] Obj.t ->
  Py.Object.t

Initialize from rotation vectors.

A rotation vector is a 3 dimensional vector which is co-directional to the axis of rotation and whose norm gives the angle of rotation (in radians) [1]_.

Parameters

  • rotvec : array_like, shape (N, 3) or (3,) A single vector or a stack of vectors, where rot_vec[i] gives the ith rotation vector.

Returns

  • rotation : Rotation instance Object containing the rotations represented by input rotation vectors.

References

.. [1] https://en.wikipedia.org/wiki/Axis%E2%80%93angle_representation#Rotation_vector

Examples

>>> from scipy.spatial.transform import Rotation as R

Initialize a single rotation:

>>> r = R.from_rotvec(np.pi/2 * np.array([0, 0, 1]))
>>> r.as_rotvec()
array([0.        , 0.        , 1.57079633])
>>> r.as_rotvec().shape
(3,)

Initialize multiple rotations in one object:

>>> r = R.from_rotvec([
... [0, 0, np.pi/2],
... [np.pi/2, 0, 0]])
>>> r.as_rotvec()
array([[0.        , 0.        , 1.57079633],
       [1.57079633, 0.        , 0.        ]])
>>> r.as_rotvec().shape
(2, 3)

It is also possible to have a stack of a single rotaton:

>>> r = R.from_rotvec([[0, 0, np.pi/2]])
>>> r.as_rotvec().shape
(1, 3)

identity

method identity
val identity :
  ?num:int ->
  [> tag] Obj.t ->
  Py.Object.t

Get identity rotation(s).

Composition with the identity rotation has no effect.

Parameters

  • num : int or None, optional Number of identity rotations to generate. If None (default), then a single rotation is generated.

Returns

  • identity : Rotation object The identity rotation.

inv

method inv
val inv :
  [> tag] Obj.t ->
  Py.Object.t

Invert this rotation.

Composition of a rotation with its inverse results in an identity transformation.

Returns

  • inverse : Rotation instance Object containing inverse of the rotations in the current instance.

Examples

>>> from scipy.spatial.transform import Rotation as R

Inverting a single rotation:

>>> p = R.from_euler('z', 45, degrees=True)
>>> q = p.inv()
>>> q.as_euler('zyx', degrees=True)
array([-45.,   0.,   0.])

Inverting multiple rotations:

>>> p = R.from_rotvec([[0, 0, np.pi/3], [-np.pi/4, 0, 0]])
>>> q = p.inv()
>>> q.as_rotvec()
array([[-0.        , -0.        , -1.04719755],
       [ 0.78539816, -0.        , -0.        ]])

magnitude

method magnitude
val magnitude :
  [> tag] Obj.t ->
  Py.Object.t

Get the magnitude(s) of the rotation(s).

Returns

  • magnitude : ndarray or float Angle(s) in radians, float if object contains a single rotation and ndarray if object contains multiple rotations.

Examples

>>> from scipy.spatial.transform import Rotation as R
>>> r = R.from_quat(np.eye(4))
>>> r.magnitude()
array([3.14159265, 3.14159265, 3.14159265, 0.        ])

Magnitude of a single rotation:

>>> r[0].magnitude()
3.141592653589793

match_vectors

method match_vectors
val match_vectors :
  ?kwds:(string * Py.Object.t) list ->
  Py.Object.t list ->
  [> tag] Obj.t ->
  Py.Object.t

match_vectors is deprecated! match_vectors is deprecated in favor of align_vectors in scipy 1.4.0 and will be removed in scipy 1.6.0

Deprecated in favor of align_vectors.

mean

method mean
val mean :
  ?weights:[>`Ndarray] Np.Obj.t ->
  [> tag] Obj.t ->
  Py.Object.t

Get the mean of the rotations.

Parameters

  • weights : array_like shape (N,), optional Weights describing the relative importance of the rotations. If None (default), then all values in weights are assumed to be equal.

Returns

  • mean : Rotation instance Object containing the mean of the rotations in the current instance.

Notes

The mean used is the chordal L2 mean (also called the projected or induced arithmetic mean). If p is a set of rotations with mean m, then m is the rotation which minimizes (weights[:, None, None] * (p.as_matrix() - m.as_matrix())**2).sum().

Examples

>>> from scipy.spatial.transform import Rotation as R
>>> r = R.from_euler('zyx', [[0, 0, 0],
...                          [1, 0, 0],
...                          [0, 1, 0],
...                          [0, 0, 1]], degrees=True)
>>> r.mean().as_euler('zyx', degrees=True)
array([0.24945696, 0.25054542, 0.24945696])

random

method random
val random :
  ?num:int ->
  ?random_state:[`I of int | `RandomState of Py.Object.t] ->
  [> tag] Obj.t ->
  Py.Object.t

Generate uniformly distributed rotations.

Parameters

  • num : int or None, optional Number of random rotations to generate. If None (default), then a single rotation is generated.

  • random_state : int, RandomState instance or None, optional Accepts an integer as a seed for the random generator or a RandomState object. If None (default), uses global numpy.random random state.

Returns

  • random_rotation : Rotation instance Contains a single rotation if num is None. Otherwise contains a stack of num rotations.

Examples

>>> from scipy.spatial.transform import Rotation as R

Sample a single rotation:

>>> R.random(random_state=1234).as_euler('zxy', degrees=True)
array([-110.5976185 ,   55.32758512,   76.3289269 ])

Sample a stack of rotations:

>>> R.random(5, random_state=1234).as_euler('zxy', degrees=True)
array([[-110.5976185 ,   55.32758512,   76.3289269 ],
       [ -91.59132005,  -14.3629884 ,  -93.91933182],
       [  25.23835501,   45.02035145, -121.67867086],
       [ -51.51414184,  -15.29022692, -172.46870023],
       [ -81.63376847,  -27.39521579,    2.60408416]])

reduce

method reduce
val reduce :
  ?left:Py.Object.t ->
  ?right:Py.Object.t ->
  ?return_indices:bool ->
  [> tag] Obj.t ->
  Py.Object.t

Reduce this rotation with the provided rotation groups.

Reduction of a rotation p is a transformation of the form q = l * p * r, where l and r are chosen from left and right respectively, such that rotation q has the smallest magnitude.

If left and right are rotation groups representing symmetries of two objects rotated by p, then q is the rotation of the smallest magnitude to align these objects considering their symmetries.

Parameters

  • left : Rotation instance, optional Object containing the left rotation(s). Default value (None) corresponds to the identity rotation.

  • right : Rotation instance, optional Object containing the right rotation(s). Default value (None) corresponds to the identity rotation.

  • return_indices : bool, optional Whether to return the indices of the rotations from left and right used for reduction.

Returns

  • reduced : Rotation instance Object containing reduced rotations. left_best, right_best: integer ndarray Indices of elements from left and right used for reduction.

to_string

method to_string
val to_string: t -> string

Print the object to a human-readable representation.

show

method show
val show: t -> string

Print the object to a human-readable representation.

pp

method pp
val pp: Format.formatter -> t -> unit

Pretty-print the object to a formatter.

RotationSpline

Module Scipy.​Spatial.​Transform.​RotationSpline wraps Python class scipy.spatial.transform.RotationSpline.

type t

create

constructor and attributes create
val create :
  times:[>`Ndarray] Np.Obj.t ->
  rotations:Py.Object.t ->
  unit ->
  t

Interpolate rotations with continuous angular rate and acceleration.

The rotation vectors between each consecutive orientation are cubic functions of time and it is guaranteed that angular rate and acceleration are continuous. Such interpolation are analogous to cubic spline interpolation.

Refer to [1]_ for math and implementation details.

Parameters

  • times : array_like, shape (N,) Times of the known rotations. At least 2 times must be specified.

  • rotations : Rotation instance Rotations to perform the interpolation between. Must contain N rotations.

Methods

call

References

.. [1] Smooth Attitude Interpolation <https://github.com/scipy/scipy/files/2932755/attitude_interpolation.pdf>_

Examples

>>> from scipy.spatial.transform import Rotation, RotationSpline

Define the sequence of times and rotations from the Euler angles:

>>> times = [0, 10, 20, 40]
>>> angles = [[-10, 20, 30], [0, 15, 40], [-30, 45, 30], [20, 45, 90]]
>>> rotations = Rotation.from_euler('XYZ', angles, degrees=True)

Create the interpolator object:

>>> spline = RotationSpline(times, rotations)

Interpolate the Euler angles, angular rate and acceleration:

>>> angular_rate = np.rad2deg(spline(times, 1))
>>> angular_acceleration = np.rad2deg(spline(times, 2))
>>> times_plot = np.linspace(times[0], times[-1], 100)
>>> angles_plot = spline(times_plot).as_euler('XYZ', degrees=True)
>>> angular_rate_plot = np.rad2deg(spline(times_plot, 1))
>>> angular_acceleration_plot = np.rad2deg(spline(times_plot, 2))

On this plot you see that Euler angles are continuous and smooth:

>>> import matplotlib.pyplot as plt
>>> plt.plot(times_plot, angles_plot)
>>> plt.plot(times, angles, 'x')
>>> plt.title('Euler angles')
>>> plt.show()

The angular rate is also smooth:

>>> plt.plot(times_plot, angular_rate_plot)
>>> plt.plot(times, angular_rate, 'x')
>>> plt.title('Angular rate')
>>> plt.show()

The angular acceleration is continuous, but not smooth. Also note that the angular acceleration is not a piecewise-linear function, because it is different from the second derivative of the rotation vector (which is a piecewise-linear function as in the cubic spline).

>>> plt.plot(times_plot, angular_acceleration_plot)
>>> plt.plot(times, angular_acceleration, 'x')
>>> plt.title('Angular acceleration')
>>> plt.show()

to_string

method to_string
val to_string: t -> string

Print the object to a human-readable representation.

show

method show
val show: t -> string

Print the object to a human-readable representation.

pp

method pp
val pp: Format.formatter -> t -> unit

Pretty-print the object to a formatter.

Slerp

Module Scipy.​Spatial.​Transform.​Slerp wraps Python class scipy.spatial.transform.Slerp.

type t

create

constructor and attributes create
val create :
  times:[>`Ndarray] Np.Obj.t ->
  rotations:Py.Object.t ->
  unit ->
  t

Spherical Linear Interpolation of Rotations.

The interpolation between consecutive rotations is performed as a rotation around a fixed axis with a constant angular velocity [1]_. This ensures that the interpolated rotations follow the shortest path between initial and final orientations.

Parameters

  • times : array_like, shape (N,) Times of the known rotations. At least 2 times must be specified.

  • rotations : Rotation instance Rotations to perform the interpolation between. Must contain N rotations.

Methods

call

See Also

Rotation

Notes

.. versionadded:: 1.2.0

References

.. [1] https://en.wikipedia.org/wiki/Slerp#Quaternion_Slerp

Examples

>>> from scipy.spatial.transform import Rotation as R
>>> from scipy.spatial.transform import Slerp

Setup the fixed keyframe rotations and times:

>>> key_rots = R.random(5, random_state=2342345)
>>> key_times = [0, 1, 2, 3, 4]

Create the interpolator object:

>>> slerp = Slerp(key_times, key_rots)

Interpolate the rotations at the given times:

>>> times = [0, 0.5, 0.25, 1, 1.5, 2, 2.75, 3, 3.25, 3.60, 4]
>>> interp_rots = slerp(times)

The keyframe rotations expressed as Euler angles:

>>> key_rots.as_euler('xyz', degrees=True)
array([[ 14.31443779, -27.50095894,  -3.7275787 ],
       [ -1.79924227, -24.69421529, 164.57701743],
       [146.15020772,  43.22849451, -31.34891088],
       [ 46.39959442,  11.62126073, -45.99719267],
       [-88.94647804, -49.64400082, -65.80546984]])

The interpolated rotations expressed as Euler angles. These agree with the keyframe rotations at both endpoints of the range of keyframe times.

>>> interp_rots.as_euler('xyz', degrees=True)
array([[  14.31443779,  -27.50095894,   -3.7275787 ],
       [   4.74588574,  -32.44683966,   81.25139984],
       [  10.71094749,  -31.56690154,   38.06896408],
       [  -1.79924227,  -24.69421529,  164.57701743],
       [  11.72796022,   51.64207311, -171.7374683 ],
       [ 146.15020772,   43.22849451,  -31.34891088],
       [  68.10921869,   20.67625074,  -48.74886034],
       [  46.39959442,   11.62126073,  -45.99719267],
       [  12.35552615,    4.21525086,  -64.89288124],
       [ -30.08117143,  -19.90769513,  -78.98121326],
       [ -88.94647804,  -49.64400082,  -65.80546984]])

to_string

method to_string
val to_string: t -> string

Print the object to a human-readable representation.

show

method show
val show: t -> string

Print the object to a human-readable representation.

pp

method pp
val pp: Format.formatter -> t -> unit

Pretty-print the object to a formatter.

Rotation'

Module Scipy.​Spatial.​Transform.​Rotation' wraps Python module scipy.spatial.transform.rotation.

check_random_state

function check_random_state
val check_random_state :
  Py.Object.t ->
  Py.Object.t

Turn seed into a np.random.RandomState instance

If seed is None (or np.random), return the RandomState singleton used by np.random. If seed is an int, return a new RandomState instance seeded with seed. If seed is already a RandomState instance, return it. If seed is a new-style np.random.Generator, return it. Otherwise, raise ValueError.

create_group

function create_group
val create_group :
  ?axis:Py.Object.t ->
  cls:Py.Object.t ->
  group:Py.Object.t ->
  unit ->
  Py.Object.t

convex_hull_plot_2d

function convex_hull_plot_2d
val convex_hull_plot_2d :
  ?ax:Py.Object.t ->
  hull:Py.Object.t ->
  unit ->
  Py.Object.t

Plot the given convex hull diagram in 2-D

Parameters

  • hull : scipy.spatial.ConvexHull instance Convex hull to plot

  • ax : matplotlib.axes.Axes instance, optional Axes to plot on

Returns

  • fig : matplotlib.figure.Figure instance Figure for the plot

See Also

ConvexHull

Notes

Requires Matplotlib.

Examples

>>> import matplotlib.pyplot as plt
>>> from scipy.spatial import ConvexHull, convex_hull_plot_2d

The convex hull of a random set of points:

>>> points = np.random.rand(30, 2)
>>> hull = ConvexHull(points)

Plot it:

>>> _ = convex_hull_plot_2d(hull)
>>> plt.show()

delaunay_plot_2d

function delaunay_plot_2d
val delaunay_plot_2d :
  ?ax:Py.Object.t ->
  tri:Py.Object.t ->
  unit ->
  Py.Object.t

Plot the given Delaunay triangulation in 2-D

Parameters

  • tri : scipy.spatial.Delaunay instance Triangulation to plot

  • ax : matplotlib.axes.Axes instance, optional Axes to plot on

Returns

  • fig : matplotlib.figure.Figure instance Figure for the plot

See Also

Delaunay matplotlib.pyplot.triplot

Notes

Requires Matplotlib.

Examples

>>> import matplotlib.pyplot as plt
>>> from scipy.spatial import Delaunay, delaunay_plot_2d

The Delaunay triangulation of a set of random points:

>>> points = np.random.rand(30, 2)
>>> tri = Delaunay(points)

Plot it:

>>> _ = delaunay_plot_2d(tri)
>>> plt.show()

distance_matrix

function distance_matrix
val distance_matrix :
  ?p:[`F of float | `T1_p_infinity of Py.Object.t] ->
  ?threshold:Py.Object.t ->
  x:Py.Object.t ->
  y:Py.Object.t ->
  unit ->
  [`ArrayLike|`Ndarray|`Object] Np.Obj.t

Compute the distance matrix.

Returns the matrix of all pair-wise distances.

Parameters

  • x : (M, K) array_like Matrix of M vectors in K dimensions.

  • y : (N, K) array_like Matrix of N vectors in K dimensions.

  • p : float, 1 <= p <= infinity Which Minkowski p-norm to use.

  • threshold : positive int If M * N * K > threshold, algorithm uses a Python loop instead of large temporary arrays.

Returns

  • result : (M, N) ndarray Matrix containing the distance from every vector in x to every vector in y.

Examples

>>> from scipy.spatial import distance_matrix
>>> distance_matrix([[0,0],[0,1]], [[1,0],[1,1]])
array([[ 1.        ,  1.41421356],
       [ 1.41421356,  1.        ]])

geometric_slerp

function geometric_slerp
val geometric_slerp :
  ?tol:float ->
  start:[>`Ndarray] Np.Obj.t ->
  end_:[>`Ndarray] Np.Obj.t ->
  t:[`F of float | `Ndarray of [>`Ndarray] Np.Obj.t] ->
  unit ->
  Py.Object.t

Geometric spherical linear interpolation.

The interpolation occurs along a unit-radius great circle arc in arbitrary dimensional space.

Parameters

  • start : (n_dimensions, ) array-like Single n-dimensional input coordinate in a 1-D array-like object. n must be greater than 1.

  • end : (n_dimensions, ) array-like Single n-dimensional input coordinate in a 1-D array-like object. n must be greater than 1.

  • t: float or (n_points,) array-like A float or array-like of doubles representing interpolation parameters, with values required in the inclusive interval between 0 and 1. A common approach is to generate the array with np.linspace(0, 1, n_pts) for linearly spaced points. Ascending, descending, and scrambled orders are permitted.

  • tol: float The absolute tolerance for determining if the start and end coordinates are antipodes.

Returns

  • result : (t.size, D) An array of doubles containing the interpolated spherical path and including start and end when 0 and 1 t are used. The interpolated values should correspond to the same sort order provided in the t array. The result may be 1-dimensional if t is a float.

Raises

ValueError If start and end are antipodes, not on the unit n-sphere, or for a variety of degenerate conditions.

Notes

The implementation is based on the mathematical formula provided in [1], and the first known presentation of this algorithm, derived from study of 4-D geometry, is credited to Glenn Davis in a footnote of the original quaternion Slerp publication by Ken Shoemake [2].

.. versionadded:: 1.5.0

References

.. [1] https://en.wikipedia.org/wiki/Slerp#Geometric_Slerp .. [2] Ken Shoemake (1985) Animating rotation with quaternion curves. ACM SIGGRAPH Computer Graphics, 19(3): 245-254.

See Also

  • scipy.spatial.transform.Slerp : 3-D Slerp that works with quaternions

Examples

Interpolate four linearly-spaced values on the circumference of a circle spanning 90 degrees:

>>> from scipy.spatial import geometric_slerp
>>> import matplotlib.pyplot as plt
>>> fig = plt.figure()
>>> ax = fig.add_subplot(111)
>>> start = np.array([1, 0])
>>> end = np.array([0, 1])
>>> t_vals = np.linspace(0, 1, 4)
>>> result = geometric_slerp(start,
...                          end,
...                          t_vals)

The interpolated results should be at 30 degree intervals recognizable on the unit circle:

>>> ax.scatter(result[...,0], result[...,1], c='k')
>>> circle = plt.Circle((0, 0), 1, color='grey')
>>> ax.add_artist(circle)
>>> ax.set_aspect('equal')
>>> plt.show()

Attempting to interpolate between antipodes on a circle is ambiguous because there are two possible paths, and on a sphere there are infinite possible paths on the geodesic surface. Nonetheless, one of the ambiguous paths is returned along with a warning:

>>> opposite_pole = np.array([-1, 0])
>>> with np.testing.suppress_warnings() as sup:
...     sup.filter(UserWarning)
...     geometric_slerp(start,
...                     opposite_pole,
...                     t_vals)
array([[ 1.00000000e+00,  0.00000000e+00],
       [ 5.00000000e-01,  8.66025404e-01],
       [-5.00000000e-01,  8.66025404e-01],
       [-1.00000000e+00,  1.22464680e-16]])

Extend the original example to a sphere and plot interpolation points in 3D:

>>> from mpl_toolkits.mplot3d import proj3d
>>> fig = plt.figure()
>>> ax = fig.add_subplot(111, projection='3d')

Plot the unit sphere for reference (optional):

>>> u = np.linspace(0, 2 * np.pi, 100)
>>> v = np.linspace(0, np.pi, 100)
>>> x = np.outer(np.cos(u), np.sin(v))
>>> y = np.outer(np.sin(u), np.sin(v))
>>> z = np.outer(np.ones(np.size(u)), np.cos(v))
>>> ax.plot_surface(x, y, z, color='y', alpha=0.1)

Interpolating over a larger number of points may provide the appearance of a smooth curve on the surface of the sphere, which is also useful for discretized integration calculations on a sphere surface:

>>> start = np.array([1, 0, 0])
>>> end = np.array([0, 0, 1])
>>> t_vals = np.linspace(0, 1, 200)
>>> result = geometric_slerp(start,
...                          end,
...                          t_vals)
>>> ax.plot(result[...,0],
...         result[...,1],
...         result[...,2],
...         c='k')
>>> plt.show()

minkowski_distance

function minkowski_distance
val minkowski_distance :
  ?p:[`F of float | `T1_p_infinity of Py.Object.t] ->
  x:Py.Object.t ->
  y:Py.Object.t ->
  unit ->
  Py.Object.t

Compute the L**p distance between two arrays.

Parameters

  • x : (M, K) array_like Input array.

  • y : (N, K) array_like Input array.

  • p : float, 1 <= p <= infinity Which Minkowski p-norm to use.

Examples

>>> from scipy.spatial import minkowski_distance
>>> minkowski_distance([[0,0],[0,0]], [[1,1],[0,1]])
array([ 1.41421356,  1.        ])

minkowski_distance_p

function minkowski_distance_p
val minkowski_distance_p :
  ?p:[`F of float | `T1_p_infinity of Py.Object.t] ->
  x:Py.Object.t ->
  y:Py.Object.t ->
  unit ->
  Py.Object.t

Compute the pth power of the L**p distance between two arrays.

For efficiency, this function computes the Lp distance but does not extract the pth root. If p is 1 or infinity, this is equal to the actual Lp distance.

Parameters

  • x : (M, K) array_like Input array.

  • y : (N, K) array_like Input array.

  • p : float, 1 <= p <= infinity Which Minkowski p-norm to use.

Examples

>>> from scipy.spatial import minkowski_distance_p
>>> minkowski_distance_p([[0,0],[0,0]], [[1,1],[0,1]])
array([2, 1])

procrustes

function procrustes
val procrustes :
  data1:[>`Ndarray] Np.Obj.t ->
  data2:[>`Ndarray] Np.Obj.t ->
  unit ->
  ([`ArrayLike|`Ndarray|`Object] Np.Obj.t * [`ArrayLike|`Ndarray|`Object] Np.Obj.t * float)

Procrustes analysis, a similarity test for two data sets.

Each input matrix is a set of points or vectors (the rows of the matrix). The dimension of the space is the number of columns of each matrix. Given two identically sized matrices, procrustes standardizes both such that:

  • :math:tr(AA^{T}) = 1.

  • Both sets of points are centered around the origin.

Procrustes ([1], [2]) then applies the optimal transform to the second matrix (including scaling/dilation, rotations, and reflections) to minimize :math:M^{2}=\sum(data1-data2)^{2}, or the sum of the squares of the pointwise differences between the two input datasets.

This function was not designed to handle datasets with different numbers of datapoints (rows). If two data sets have different dimensionality (different number of columns), simply add columns of zeros to the smaller of the two.

Parameters

  • data1 : array_like Matrix, n rows represent points in k (columns) space data1 is the reference data, after it is standardised, the data from data2 will be transformed to fit the pattern in data1 (must have >1 unique points).

  • data2 : array_like n rows of data in k space to be fit to data1. Must be the same shape (numrows, numcols) as data1 (must have >1 unique points).

Returns

  • mtx1 : array_like A standardized version of data1.

  • mtx2 : array_like The orientation of data2 that best fits data1. Centered, but not

  • necessarily :math:tr(AA^{T}) = 1.

  • disparity : float :math:M^{2} as defined above.

Raises

ValueError If the input arrays are not two-dimensional. If the shape of the input arrays is different. If the input arrays have zero columns or zero rows.

See Also

scipy.linalg.orthogonal_procrustes

  • scipy.spatial.distance.directed_hausdorff : Another similarity test for two data sets

Notes

  • The disparity should not depend on the order of the input matrices, but the output matrices will, as only the first output matrix is guaranteed to be scaled such that :math:tr(AA^{T}) = 1.

  • Duplicate data points are generally ok, duplicating a data point will increase its effect on the procrustes fit.

  • The disparity scales as the number of points per input matrix.

References

.. [1] Krzanowski, W. J. (2000). 'Principles of Multivariate analysis'. .. [2] Gower, J. C. (1975). 'Generalized procrustes analysis'.

Examples

>>> from scipy.spatial import procrustes

The matrix b is a rotated, shifted, scaled and mirrored version of a here:

>>> a = np.array([[1, 3], [1, 2], [1, 1], [2, 1]], 'd')
>>> b = np.array([[4, -2], [4, -4], [4, -6], [2, -6]], 'd')
>>> mtx1, mtx2, disparity = procrustes(a, b)
>>> round(disparity)
0.0

tsearch

function tsearch
val tsearch :
  tri:Py.Object.t ->
  xi:Py.Object.t ->
  unit ->
  Py.Object.t

tsearch(tri, xi)

Find simplices containing the given points. This function does the same thing as Delaunay.find_simplex.

.. versionadded:: 0.9

See Also

Delaunay.find_simplex

Examples

>>> import numpy as np
>>> import matplotlib.pyplot as plt
>>> from scipy.spatial import Delaunay, delaunay_plot_2d, tsearch

The Delaunay triangulation of a set of random points:

>>> pts = np.random.rand(20, 2)
>>> tri = Delaunay(pts)
>>> _ = delaunay_plot_2d(tri)

Find the simplices containing a given set of points:

>>> loc = np.random.uniform(0.2, 0.8, (5, 2))
>>> s = tsearch(tri, loc)
>>> plt.triplot(pts[:, 0], pts[:, 1], tri.simplices[s], 'b-', mask=s==-1)
>>> plt.scatter(loc[:, 0], loc[:, 1], c='r', marker='x')
>>> plt.show()

voronoi_plot_2d

function voronoi_plot_2d
val voronoi_plot_2d :
  ?ax:Py.Object.t ->
  ?kw:(string * Py.Object.t) list ->
  vor:Py.Object.t ->
  unit ->
  Py.Object.t

Plot the given Voronoi diagram in 2-D

Parameters

  • vor : scipy.spatial.Voronoi instance Diagram to plot

  • ax : matplotlib.axes.Axes instance, optional Axes to plot on

  • show_points: bool, optional Add the Voronoi points to the plot.

  • show_vertices : bool, optional Add the Voronoi vertices to the plot.

  • line_colors : string, optional Specifies the line color for polygon boundaries

  • line_width : float, optional Specifies the line width for polygon boundaries

  • line_alpha: float, optional Specifies the line alpha for polygon boundaries

  • point_size: float, optional Specifies the size of points

Returns

  • fig : matplotlib.figure.Figure instance Figure for the plot

See Also

Voronoi

Notes

Requires Matplotlib.

Examples

Set of point:

>>> import matplotlib.pyplot as plt
>>> points = np.random.rand(10,2) #random

Voronoi diagram of the points:

>>> from scipy.spatial import Voronoi, voronoi_plot_2d
>>> vor = Voronoi(points)

using voronoi_plot_2d for visualisation:

>>> fig = voronoi_plot_2d(vor)

using voronoi_plot_2d for visualisation with enhancements:

>>> fig = voronoi_plot_2d(vor, show_vertices=False, line_colors='orange',
...                 line_width=2, line_alpha=0.6, point_size=2)
>>> plt.show()