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: 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: 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 nonredundant order of contiguity up to a specific order.
Parameters: 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: Returns: implicit – spatial weights object
Return type: Notes
Proper higher order neighbors are returned such that i and j are korder neighbors iff the shortest path from ij 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: 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: 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: 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: 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: Returns: nnd – maximum nearest neighbor distance between the n observations
Return type: 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: 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 quantifies how close the neighbors of observation are to being a clique:
where is the set of neighbors to , and is the set of nonzero elements of the weights between pairs in . [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 korder neighbors if the shortest path for i,j is k False: i,j are korder neighbors if there is a path from i,j of length k
 diagonal (boolean) – True: keep korder (i,j) joins when i==j False: remove korder (i,j) joins when i==j
Returns: wk – WSP, type matches type of w argument
Return type: 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: Returns: w – instance of spatial weights class W
Return type: 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.