weights.util — Utility functions on spatial weights

The weights.util module provides utility functions on spatial weights .. versionadded:: 1.0

pysal.weights.util.lat2W(nrows=5, ncols=5, rook=True, id_type='int')[source]

Create a W object for a regular lattice.

Parameters:
  • nrows (int) – number of rows
  • ncols (int) – number of columns
  • rook (boolean) – type of contiguity. Default is rook. For queen, rook =False
  • id_type (string) – string defining the type of IDs to use in the final W object; options are ‘int’ (0, 1, 2 ...; default), ‘float’ (0.0, 1.0, 2.0, ...) and ‘string’ (‘id0’, ‘id1’, ‘id2’, ...)
Returns:

w – instance of spatial weights class W

Return type:

W

Notes

Observations are row ordered: first k observations are in row 0, next k in row 1, and so on.

Examples

>>> from pysal import lat2W
>>> w9 = lat2W(3,3)
>>> "%.3f"%w9.pct_nonzero
'29.630'
>>> w9[0]
{1: 1.0, 3: 1.0}
>>> w9[3]
{0: 1.0, 4: 1.0, 6: 1.0}
>>>
pysal.weights.util.block_weights(regimes, ids=None, sparse=False)[source]

Construct spatial weights for regime neighbors.

Block contiguity structures are relevant when defining neighbor relations based on membership in a regime. For example, all counties belonging to the same state could be defined as neighbors, in an analysis of all counties in the US.

Parameters:
  • regimes (list, array) – ids of which regime an observation belongs to
  • ids (list, array) – Ordered sequence of IDs for the observations
  • sparse (boolean) – If True return WSP instance If False return W instance
Returns:

W

Return type:

spatial weights instance

Examples

>>> from pysal import block_weights
>>> import numpy as np
>>> regimes = np.ones(25)
>>> regimes[range(10,20)] = 2
>>> regimes[range(21,25)] = 3
>>> regimes
array([ 1.,  1.,  1.,  1.,  1.,  1.,  1.,  1.,  1.,  1.,  2.,  2.,  2.,
        2.,  2.,  2.,  2.,  2.,  2.,  2.,  1.,  3.,  3.,  3.,  3.])
>>> w = block_weights(regimes)
>>> w.weights[0]
[1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0]
>>> w.neighbors[0]
[1, 2, 3, 4, 5, 6, 7, 8, 9, 20]
>>> regimes = ['n','n','s','s','e','e','w','w','e']
>>> n = len(regimes)
>>> w = block_weights(regimes)
>>> w.neighbors
{0: [1], 1: [0], 2: [3], 3: [2], 4: [5, 8], 5: [4, 8], 6: [7], 7: [6], 8: [4, 5]}
pysal.weights.util.comb(items, n=None)[source]

Combinations of size n taken from items

Parameters:
  • items (list) – items to be drawn from
  • n (integer) – size of combinations to take from items
Returns:

implicit – combinations of size n taken from items

Return type:

generator

Examples

>>> x = range(4)
>>> for c in comb(x, 2):
...     print c
...
[0, 1]
[0, 2]
[0, 3]
[1, 2]
[1, 3]
[2, 3]
pysal.weights.util.order(w, kmax=3)[source]

Determine the non-redundant order of contiguity up to a specific order.

Parameters:
  • w (W) – spatial weights object
  • kmax (int) – maximum order of contiguity
Returns:

info – observation id is the key, value is a list of contiguity orders with a negative 1 in the ith position

Return type:

dictionary

Notes

Implements the algorithm in Anselin and Smirnov (1996) [Anselin1996b]

Examples

>>> from pysal import rook_from_shapefile as rfs
>>> w = rfs(pysal.examples.get_path('10740.shp'))
WARNING: there is one disconnected observation (no neighbors)
Island id:  [163]
>>> w3 = order(w, kmax = 3)
>>> w3[1][0:5]
[1, -1, 1, 2, 1]
pysal.weights.util.higher_order(w, k=2)[source]

Contiguity weights object of order k.

Parameters:
  • w (W) – spatial weights object
  • k (int) – order of contiguity
Returns:

implicit – spatial weights object

Return type:

W

Notes

Proper higher order neighbors are returned such that i and j are k-order neighbors iff the shortest path from i-j is of length k.

Examples

>>> from pysal import lat2W, higher_order
>>> w10 = lat2W(10, 10)
>>> w10_2 = higher_order(w10, 2)
>>> w10_2[0]
{2: 1.0, 11: 1.0, 20: 1.0}
>>> w5 = lat2W()
>>> w5[0]
{1: 1.0, 5: 1.0}
>>> w5[1]
{0: 1.0, 2: 1.0, 6: 1.0}
>>> w5_2 = higher_order(w5,2)
>>> w5_2[0]
{10: 1.0, 2: 1.0, 6: 1.0}
pysal.weights.util.shimbel(w)[source]

Find the Shimbel matrix for first order contiguity matrix.

Parameters:w (W) – spatial weights object
Returns:info – list of lists; one list for each observation which stores the shortest order between it and each of the the other observations.
Return type:list

Examples

>>> from pysal import lat2W, shimbel
>>> w5 = lat2W()
>>> w5_shimbel = shimbel(w5)
>>> w5_shimbel[0][24]
8
>>> w5_shimbel[0][0:4]
[-1, 1, 2, 3]
>>>
pysal.weights.util.remap_ids(w, old2new, id_order=[])[source]

Remaps the IDs in a spatial weights object.

Parameters:
  • w (W) – Spatial weights object
  • old2new (dictionary) – Dictionary where the keys are the IDs in w (i.e. “old IDs”) and the values are the IDs to replace them (i.e. “new IDs”)
  • id_order (list) – An ordered list of new IDs, which defines the order of observations when iterating over W. If not set then the id_order in w will be used.
Returns:

implicit – Spatial weights object with new IDs

Return type:

W

Examples

>>> from pysal import lat2W, remap_ids
>>> w = lat2W(3,2)
>>> w.id_order
[0, 1, 2, 3, 4, 5]
>>> w.neighbors[0]
[2, 1]
>>> old_to_new = {0:'a', 1:'b', 2:'c', 3:'d', 4:'e', 5:'f'}
>>> w_new = remap_ids(w, old_to_new)
>>> w_new.id_order
['a', 'b', 'c', 'd', 'e', 'f']
>>> w_new.neighbors['a']
['c', 'b']
pysal.weights.util.full2W(m, ids=None)[source]

Create a PySAL W object from a full array.

Parameters:
  • m (array) – nxn array with the full weights matrix
  • ids (list) – User ids assumed to be aligned with m
Returns:

w – PySAL weights object

Return type:

W

Examples

>>> import pysal as ps
>>> import numpy as np

Create an array of zeros

>>> a = np.zeros((4, 4))

For loop to fill it with random numbers

>>> for i in range(len(a)):
...     for j in range(len(a[i])):
...         if i!=j:
...             a[i, j] = np.random.random(1)

Create W object

>>> w = ps.weights.util.full2W(a)
>>> w.full()[0] == a
array([[ True,  True,  True,  True],
       [ True,  True,  True,  True],
       [ True,  True,  True,  True],
       [ True,  True,  True,  True]], dtype=bool)

Create list of user ids

>>> ids = ['myID0', 'myID1', 'myID2', 'myID3']
>>> w = ps.weights.util.full2W(a, ids=ids)
>>> w.full()[0] == a
array([[ True,  True,  True,  True],
       [ True,  True,  True,  True],
       [ True,  True,  True,  True],
       [ True,  True,  True,  True]], dtype=bool)
pysal.weights.util.full(w)[source]

Generate a full numpy array.

Parameters:w (W) – spatial weights object
Returns:(fullw, keys) – first element being the full numpy array and second element keys being the ids associated with each row in the array.
Return type:tuple

Examples

>>> from pysal import W, full
>>> neighbors = {'first':['second'],'second':['first','third'],'third':['second']}
>>> weights = {'first':[1],'second':[1,1],'third':[1]}
>>> w = W(neighbors, weights)
>>> wf, ids = full(w)
>>> wf
array([[ 0.,  1.,  0.],
       [ 1.,  0.,  1.],
       [ 0.,  1.,  0.]])
>>> ids
['first', 'second', 'third']
pysal.weights.util.WSP2W(wsp, silent_island_warning=False)[source]

Convert a pysal WSP object (thin weights matrix) to a pysal W object.

Parameters:
  • wsp (WSP) – PySAL sparse weights object
  • silent_island_warning (boolean) – Switch to turn off (default on) print statements for every observation with islands
Returns:

w – PySAL weights object

Return type:

W

Examples

>>> import pysal

Build a 10x10 scipy.sparse matrix for a rectangular 2x5 region of cells (rook contiguity), then construct a PySAL sparse weights object (wsp).

>>> sp = pysal.weights.lat2SW(2, 5)
>>> wsp = pysal.weights.WSP(sp)
>>> wsp.n
10
>>> print wsp.sparse[0].todense()
[[0 1 0 0 0 1 0 0 0 0]]

Convert this sparse weights object to a standard PySAL weights object.

>>> w = pysal.weights.WSP2W(wsp)
>>> w.n
10
>>> print w.full()[0][0]
[ 0.  1.  0.  0.  0.  1.  0.  0.  0.  0.]
pysal.weights.util.get_ids(shapefile, idVariable)[source]

Gets the IDs from the DBF file that moves with a given shape file.

Parameters:
  • shapefile (string) – name of a shape file including suffix
  • idVariable (string) – name of a column in the shapefile’s DBF to use for ids
Returns:

ids – a list of IDs

Return type:

list

Examples

>>> from pysal.weights.util import get_ids
>>> polyids = get_ids(pysal.examples.get_path("columbus.shp"), "POLYID")
>>> polyids[:5]
[1, 2, 3, 4, 5]
pysal.weights.util.get_points_array_from_shapefile(shapefile)[source]

Gets a data array of x and y coordinates from a given shapefile.

Parameters:shapefile (string) – name of a shape file including suffix
Returns:points – (n, 2) a data array of x and y coordinates
Return type:array

Notes

If the given shape file includes polygons, this function returns x and y coordinates of the polygons’ centroids

Examples

Point shapefile

>>> from pysal.weights.util import get_points_array_from_shapefile
>>> xy = get_points_array_from_shapefile(pysal.examples.get_path('juvenile.shp'))
>>> xy[:3]
array([[ 94.,  93.],
       [ 80.,  95.],
       [ 79.,  90.]])

Polygon shapefile

>>> xy = get_points_array_from_shapefile(pysal.examples.get_path('columbus.shp'))
>>> xy[:3]
array([[  8.82721847,  14.36907602],
       [  8.33265837,  14.03162401],
       [  9.01226541,  13.81971908]])
pysal.weights.util.min_threshold_distance(data, p=2)[source]

Get the maximum nearest neighbor distance.

Parameters:
  • data (array) – (n,k) or KDTree where KDtree.data is array (n,k) n observations on k attributes
  • p (float) – Minkowski p-norm distance metric parameter: 1<=p<=infinity 2: Euclidean distance 1: Manhattan distance
Returns:

nnd – maximum nearest neighbor distance between the n observations

Return type:

float

Examples

>>> from pysal.weights.util import min_threshold_distance
>>> import numpy as np
>>> x, y = np.indices((5, 5))
>>> x.shape = (25, 1)
>>> y.shape = (25, 1)
>>> data = np.hstack([x, y])
>>> min_threshold_distance(data)
1.0
pysal.weights.util.lat2SW(nrows=3, ncols=5, criterion='rook', row_st=False)[source]

Create a sparse W matrix for a regular lattice.

Parameters:
  • nrows (int) – number of rows
  • ncols (int) – number of columns
  • rook ({"rook", "queen", "bishop"}) – type of contiguity. Default is rook.
  • row_st (boolean) – If True, the created sparse W object is row-standardized so every row sums up to one. Defaults to False.
Returns:

w – instance of a scipy sparse matrix

Return type:

scipy.sparse.dia_matrix

Notes

Observations are row ordered: first k observations are in row 0, next k in row 1, and so on. This method directly creates the W matrix using the strucuture of the contiguity type.

Examples

>>> from pysal import weights
>>> w9 = weights.lat2SW(3,3)
>>> w9[0,1]
1
>>> w9[3,6]
1
>>> w9r = weights.lat2SW(3,3, row_st=True)
>>> w9r[3,6]
0.33333333333333331
pysal.weights.util.w_local_cluster(w)[source]

Local clustering coefficients for each unit as a node in a graph. [ws]

Parameters:w (W) – spatial weights object
Returns:c – (w.n,1) local clustering coefficients
Return type:array

Notes

The local clustering coefficient c_i quantifies how close the neighbors of observation i are to being a clique:

c_i = | \{w_{j,k}\} |/ (k_i(k_i - 1)): j,k \in N_i

where N_i is the set of neighbors to i, k_i =
|N_i| and \{w_{j,k}\} is the set of non-zero elements of the weights between pairs in N_i. [Watts1998]

Examples

>>> w = pysal.lat2W(3,3, rook=False)
>>> w_local_cluster(w)
array([[ 1.        ],
       [ 0.6       ],
       [ 1.        ],
       [ 0.6       ],
       [ 0.42857143],
       [ 0.6       ],
       [ 1.        ],
       [ 0.6       ],
       [ 1.        ]])
pysal.weights.util.higher_order_sp(w, k=2, shortest_path=True, diagonal=False)[source]

Contiguity weights for either a sparse W or pysal.weights.W for order k.

Parameters:
  • w (W) – sparse_matrix, spatial weights object or scipy.sparse.csr.csr_instance
  • k (int) – Order of contiguity
  • shortest_path (boolean) – True: i,j and k-order neighbors if the shortest path for i,j is k False: i,j are k-order neighbors if there is a path from i,j of length k
  • diagonal (boolean) – True: keep k-order (i,j) joins when i==j False: remove k-order (i,j) joins when i==j
Returns:

wk – WSP, type matches type of w argument

Return type:

W

Notes

Lower order contiguities are removed.

Examples

>>> import pysal
>>> w25 = pysal.lat2W(5,5)
>>> w25.n
25
>>> w25[0]
{1: 1.0, 5: 1.0}
>>> w25_2 = pysal.weights.util.higher_order_sp(w25, 2)
>>> w25_2[0]
{10: 1.0, 2: 1.0, 6: 1.0}
>>> w25_2 = pysal.weights.util.higher_order_sp(w25, 2, diagonal=True)
>>> w25_2[0]
{0: 1.0, 10: 1.0, 2: 1.0, 6: 1.0}
>>> w25_3 = pysal.weights.util.higher_order_sp(w25, 3)
>>> w25_3[0]
{15: 1.0, 3: 1.0, 11: 1.0, 7: 1.0}
>>> w25_3 = pysal.weights.util.higher_order_sp(w25, 3, shortest_path=False)
>>> w25_3[0]
{1: 1.0, 3: 1.0, 5: 1.0, 7: 1.0, 11: 1.0, 15: 1.0}
pysal.weights.util.hexLat2W(nrows=5, ncols=5)[source]

Create a W object for a hexagonal lattice.

Parameters:
  • nrows (int) – number of rows
  • ncols (int) – number of columns
Returns:

w – instance of spatial weights class W

Return type:

W

Notes

Observations are row ordered: first k observations are in row 0, next k in row 1, and so on.

Construction is based on shifting every other column of a regular lattice down 1/2 of a cell.

Examples

>>> import pysal as ps
>>> w = ps.lat2W()
>>> w.neighbors[1]
[0, 6, 2]
>>> w.neighbors[21]
[16, 20, 22]
>>> wh = ps.hexLat2W()
>>> wh.neighbors[1]
[0, 6, 2, 5, 7]
>>> wh.neighbors[21]
[16, 20, 22]
>>>
pysal.weights.util.regime_weights(regimes)[source]

Construct spatial weights for regime neighbors.

Block contiguity structures are relevant when defining neighbor relations based on membership in a regime. For example, all counties belonging to the same state could be defined as neighbors, in an analysis of all counties in the US.

Parameters:regimes (array, list) – ids of which regime an observation belongs to
Returns:W
Return type:spatial weights instance

Examples

>>> from pysal import regime_weights
>>> import numpy as np
>>> regimes = np.ones(25)
>>> regimes[range(10,20)] = 2
>>> regimes[range(21,25)] = 3
>>> regimes
array([ 1.,  1.,  1.,  1.,  1.,  1.,  1.,  1.,  1.,  1.,  2.,  2.,  2.,
        2.,  2.,  2.,  2.,  2.,  2.,  2.,  1.,  3.,  3.,  3.,  3.])
>>> w = regime_weights(regimes)
PendingDepricationWarning: regime_weights will be renamed to block_weights in PySAL 2.0
>>> w.weights[0]
[1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0]
>>> w.neighbors[0]
[1, 2, 3, 4, 5, 6, 7, 8, 9, 20]
>>> regimes = ['n','n','s','s','e','e','w','w','e']
>>> n = len(regimes)
>>> w = regime_weights(regimes)
PendingDepricationWarning: regime_weights will be renamed to block_weights in PySAL 2.0
>>> w.neighbors
{0: [1], 1: [0], 2: [3], 3: [2], 4: [5, 8], 5: [4, 8], 6: [7], 7: [6], 8: [4, 5]}

Notes

regime_weights will be deprecated in PySAL 2.0 and renamed to block_weights.