libpysal.weights.W¶
- class libpysal.weights.W(neighbors, weights=None, id_order=None, silence_warnings=False, ids=None)[source]¶
Spatial weights class. Class attributes are described by their docstrings. to view, use the
help
function.- Parameters:
- neighbors
dict
Key is region ID, value is a list of neighbor IDS. For example,
{'a':['b'],'b':['a','c'],'c':['b']}
.- weights
dict
Key is region ID, value is a list of edge weights. If not supplied all edge weights are assumed to have a weight of 1. For example,
{'a':[0.5],'b':[0.5,1.5],'c':[1.5]}
.- id_order
list
An ordered list of ids, defines the order of observations when iterating over
W
if not set, lexicographical ordering is used to iterate and theid_order_set
property will returnFalse
. This can be set after creation by setting theid_order
property.- silence_warningsbool
By default
libpysal
will print a warning if the dataset contains any disconnected components or islands. To silence this warning set this parameter toTrue
.- ids
list
Values to use for keys of the neighbors and weights
dict
objects.
- neighbors
Examples
>>> from libpysal.weights import W >>> neighbors = {0: [3, 1], 1: [0, 4, 2], 2: [1, 5], 3: [0, 6, 4], 4: [1, 3, 7, 5], 5: [2, 4, 8], 6: [3, 7], 7: [4, 6, 8], 8: [5, 7]} >>> weights = {0: [1, 1], 1: [1, 1, 1], 2: [1, 1], 3: [1, 1, 1], 4: [1, 1, 1, 1], 5: [1, 1, 1], 6: [1, 1], 7: [1, 1, 1], 8: [1, 1]} >>> w = W(neighbors, weights) >>> "%.3f"%w.pct_nonzero '29.630'
Read from external .gal file.
>>> import libpysal >>> w = libpysal.io.open(libpysal.examples.get_path("stl.gal")).read() >>> w.n 78 >>> "%.3f"%w.pct_nonzero '6.542'
Set weights implicitly.
>>> neighbors = {0: [3, 1], 1: [0, 4, 2], 2: [1, 5], 3: [0, 6, 4], 4: [1, 3, 7, 5], 5: [2, 4, 8], 6: [3, 7], 7: [4, 6, 8], 8: [5, 7]} >>> w = W(neighbors) >>> round(w.pct_nonzero,3) 29.63 >>> from libpysal.weights import lat2W >>> w = lat2W(100, 100) >>> w.trcW2 39600.0 >>> w.trcWtW 39600.0 >>> w.transform='r' >>> round(w.trcW2, 3) 2530.722 >>> round(w.trcWtW, 3) 2533.667
Cardinality Histogram:
>>> w.histogram [(2, 4), (3, 392), (4, 9604)]
Disconnected observations (islands):
>>> from libpysal.weights import W >>> w = W({1:[0],0:[1],2:[], 3:[]})
UserWarning: The weights matrix is not fully connected: There are 3 disconnected components. There are 2 islands with ids: 2, 3.
- Attributes:
asymmetries
List of id pairs with asymmetric weights sorted in ascending index location order.
cardinalities
Number of neighbors for each observation.
component_labels
Store the graph component in which each observation falls.
diagW2
Diagonal of \(WW\).
diagWtW
Diagonal of \(W^{'}W\).
diagWtW_WW
Diagonal of \(W^{'}W + WW\).
histogram
Cardinality histogram as a dictionary where key is the id and value is the number of neighbors for that unit.
id2i
Dictionary where the key is an ID and the value is that ID’s index in
W.id_order
.id_order
Returns the ids for the observations in the order in which they would be encountered if iterating over the weights.
id_order_set
Returns
True
if user has setid_order
,False
if not.islands
List of ids without any neighbors.
max_neighbors
Largest number of neighbors.
mean_neighbors
Average number of neighbors.
min_neighbors
Minimum number of neighbors.
n
Number of units.
n_components
Store whether the adjacency matrix is fully connected.
neighbor_offsets
Given the current
id_order
,neighbor_offsets[id]
is the offsets of the id’s neighbors inid_order
.nonzero
Number of nonzero weights.
pct_nonzero
Percentage of nonzero weights.
s0
s0
is defined ass1
s1
is defined ass2
s2
is defined ass2array
Individual elements comprising
s2
.sd
Standard deviation of number of neighbors.
sparse
Sparse matrix object.
trcW2
Trace of \(WW\).
trcWtW
Trace of \(W^{'}W\).
trcWtW_WW
Trace of \(W^{'}W + WW\).
transform
Getter for transform property.
Methods
__init__
(neighbors[, weights, id_order, ...])asymmetry
([intrinsic])Asymmetry check.
from_WSP
(WSP[, silence_warnings])Create a pysal W from a pysal WSP object (thin weights matrix).
from_adjlist
(adjlist[, focal_col, ...])Return an adjacency list representation of a weights object.
from_file
([path, format])Read a weights file into a W object.
from_networkx
(graph[, weight_col])Convert a
networkx
graph to a PySALW
object.from_shapefile
(*args, **kwargs)from_sparse
(sparse)Convert a
scipy.sparse
array to a PySALW
object.full
()Generate a full
numpy.ndarray
.Getter for transform property.
plot
(gdf[, indexed_on, ax, color, node_kws, ...])Plot spatial weights objects.
remap_ids
(new_ids)In place modification throughout
W
of id values fromw.id_order
tonew_ids
in all.set_shapefile
(shapefile[, idVariable, full])Adding metadata for writing headers of
.gal
and.gwt
files.set_transform
([value])Transformations of weights.
symmetrize
([inplace])Construct a symmetric KNN weight.
to_WSP
()Generate a
WSP
object.to_adjlist
([remove_symmetric, drop_islands, ...])Compute an adjacency list representation of a weights object.
to_file
([path, format])Write a weights to a file.
Convert a weights object to a
networkx
graph.to_sparse
([fmt])Generate a
scipy.sparse
array object from a pysal W.Attributes
List of id pairs with asymmetric weights sorted in ascending index location order.
Number of neighbors for each observation.
Store the graph component in which each observation falls.
Diagonal of \(WW\).
Diagonal of \(W^{'}W\).
Diagonal of \(W^{'}W + WW\).
Cardinality histogram as a dictionary where key is the id and value is the number of neighbors for that unit.
Dictionary where the key is an ID and the value is that ID's index in
W.id_order
.Returns the ids for the observations in the order in which they would be encountered if iterating over the weights.
Returns
True
if user has setid_order
,False
if not.List of ids without any neighbors.
Largest number of neighbors.
Average number of neighbors.
Minimum number of neighbors.
Number of units.
Store whether the adjacency matrix is fully connected.
Given the current
id_order
,neighbor_offsets[id]
is the offsets of the id's neighbors inid_order
.Number of nonzero weights.
Percentage of nonzero weights.
s0
is defined ass1
is defined ass2
is defined asIndividual elements comprising
s2
.Standard deviation of number of neighbors.
Sparse matrix object.
Getter for transform property.
Trace of \(WW\).
Trace of \(W^{'}W\).
Trace of \(W^{'}W + WW\).
- property asymmetries¶
List of id pairs with asymmetric weights sorted in ascending index location order.
- asymmetry(intrinsic=True)[source]¶
Asymmetry check.
- Parameters:
- intrinsicbool
Default is
True
. Intrinsic symmetry is defined as:\[w_{i,j} == w_{j,i}\]If
intrinsic
isFalse
symmetry is defined as:\[i \in N_j \ \& \ j \in N_i\]where \(N_j\) is the set of neighbors for \(j\).
- Returns:
- asymmetries
list
Empty if no asymmetries are found. If there are asymmetries, then a
list
of(i,j)
tuples is returned sorted in ascending index location order.
- asymmetries
Examples
>>> from libpysal.weights import lat2W >>> w=lat2W(3,3) >>> w.asymmetry() [] >>> w.transform='r' >>> w.asymmetry() [(0, 1), (0, 3), (1, 0), (1, 2), (1, 4), (2, 1), (2, 5), (3, 0), (3, 4), (3, 6), (4, 1), (4, 3), (4, 5), (4, 7), (5, 2), (5, 4), (5, 8), (6, 3), (6, 7), (7, 4), (7, 6), (7, 8), (8, 5), (8, 7)] >>> result = w.asymmetry(intrinsic=False) >>> result [] >>> neighbors={0:[1,2,3], 1:[1,2,3], 2:[0,1], 3:[0,1]} >>> weights={0:[1,1,1], 1:[1,1,1], 2:[1,1], 3:[1,1]} >>> w=W(neighbors,weights) >>> w.asymmetry() [(0, 1), (1, 0)]
- property cardinalities¶
Number of neighbors for each observation.
- property component_labels¶
Store the graph component in which each observation falls.
- property diagWtW_WW¶
Diagonal of \(W^{'}W + WW\).
- classmethod from_WSP(WSP, silence_warnings=True)[source]¶
Create a pysal W from a pysal WSP object (thin weights matrix).
- Parameters:
- Returns:
- w
W
PySAL weights object
- w
Examples
>>> from libpysal.weights import lat2W, WSP, W
Build a 10x10 scipy.sparse matrix for a rectangular 2x5 region of cells (rook contiguity), then construct a PySAL sparse weights object (wsp).
>>> sp = lat2SW(2, 5) >>> wsp = WSP(sp) >>> wsp.n 10 >>> wsp.sparse[0].todense() matrix([[0, 1, 0, 0, 0, 1, 0, 0, 0, 0]], dtype=int8)
Create a standard PySAL W from this sparse weights object.
>>> w = W.from_WSP(wsp) >>> w.n 10 >>> print(w.full()[0][0]) [0 1 0 0 0 1 0 0 0 0]
- classmethod from_adjlist(adjlist, focal_col='focal', neighbor_col='neighbor', weight_col=None)[source]¶
Return an adjacency list representation of a weights object.
- Parameters:
- adjlist
pandas.DataFrame
Adjacency list with a minimum of two columns.
- focal_col
str
Name of the column with the “source” node ids.
- neighbor_col
str
Name of the column with the “destination” node ids.
- weight_col
str
Name of the column with the weight information. If not provided and the dataframe has no column named “weight” then all weights are assumed to be 1.
- adjlist
- classmethod from_networkx(graph, weight_col='weight')[source]¶
Convert a
networkx
graph to a PySALW
object.- Parameters:
- graph
networkx.Graph
The graph to convert to a
W
.- weight_col
str
If the graph is labeled, this should be the name of the field to use as the weight for the
W
.
- graph
- Returns:
- w
libpysal.weights.W
A
W
object containing the same graph as thenetworkx
graph.
- w
- classmethod from_sparse(sparse)[source]¶
Convert a
scipy.sparse
array to a PySALW
object.- Parameters:
- sparse
scipy.sparse
array
- sparse
- Returns:
- w
libpysal.weights.W
A
W
object containing the same graph as thescipy.sparse
graph.
- w
Notes
When the sparse array has a zero in its data attribute, and the corresponding row and column values are equal, the value for the pysal weight will be 0 for the “loop”.
- full()[source]¶
Generate a full
numpy.ndarray
.- Parameters:
- self
libpysal.weights.W
spatial weights object
- self
- Returns:
- (fullw, keys)
tuple
The first element being the full
numpy.ndarray
and second element keys being the ids associated with each row in the array.
- (fullw, keys)
Examples
>>> from libpysal.weights 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']
- get_transform()[source]¶
Getter for transform property.
- Returns:
See also
Examples
>>> from libpysal.weights import lat2W >>> w=lat2W() >>> w.weights[0] [1.0, 1.0] >>> w.transform 'O' >>> w.transform='r' >>> w.weights[0] [0.5, 0.5] >>> w.transform='b' >>> w.weights[0] [1.0, 1.0]
- property histogram¶
Cardinality histogram as a dictionary where key is the id and value is the number of neighbors for that unit.
- property id2i¶
Dictionary where the key is an ID and the value is that ID’s index in
W.id_order
.
- property id_order¶
Returns the ids for the observations in the order in which they would be encountered if iterating over the weights.
- property id_order_set¶
Returns
True
if user has setid_order
,False
if not.Examples
>>> from libpysal.weights import lat2W >>> w=lat2W() >>> w.id_order_set True
- property islands¶
List of ids without any neighbors.
- property max_neighbors¶
Largest number of neighbors.
- property mean_neighbors¶
Average number of neighbors.
- property min_neighbors¶
Minimum number of neighbors.
- property n¶
Number of units.
- property n_components¶
Store whether the adjacency matrix is fully connected.
- property neighbor_offsets¶
Given the current
id_order
,neighbor_offsets[id]
is the offsets of the id’s neighbors inid_order
.- Returns:
- neighbor_list
list
Offsets of the id’s neighbors in
id_order
.
- neighbor_list
Examples
>>> from libpysal.weights import W >>> neighbors={'c': ['b'], 'b': ['c', 'a'], 'a': ['b']} >>> weights ={'c': [1.0], 'b': [1.0, 1.0], 'a': [1.0]} >>> w=W(neighbors,weights) >>> w.id_order = ['a','b','c'] >>> w.neighbor_offsets['b'] [2, 0] >>> w.id_order = ['b','a','c'] >>> w.neighbor_offsets['b'] [2, 1]
- property nonzero¶
Number of nonzero weights.
- property pct_nonzero¶
Percentage of nonzero weights.
- plot(gdf, indexed_on=None, ax=None, color='k', node_kws=None, edge_kws=None)[source]¶
Plot spatial weights objects. Requires
matplotlib
, and implicitly requires ageopandas.GeoDataFrame
as input.- Parameters:
- gdf
geopandas.GeoDataFrame
The original shapes whose topological relations are modelled in
W
.- indexed_on
str
Column of
geopandas.GeoDataFrame
that the weights object uses as an index. Default isNone
, so the index of thegeopandas.GeoDataFrame
is used.- ax
matplotlib.axes.Axes
Axis on which to plot the weights. Default is
None
, so plots on the current figure.- color
str
matplotlib
color string, will color both nodes and edges the same by default.- node_kws
dict
Keyword arguments dictionary to send to
pyplot.scatter
, which provides fine-grained control over the aesthetics of the nodes in the plot.- edge_kws
dict
Keyword arguments dictionary to send to
pyplot.plot
, which provides fine-grained control over the aesthetics of the edges in the plot.
- gdf
- Returns:
- f
matplotlib.figure.Figure
Figure on which the plot is made.
- ax
matplotlib.axes.Axes
Axis on which the plot is made.
- f
Notes
If you’d like to overlay the actual shapes from the
geopandas.GeoDataFrame
, callgdf.plot(ax=ax)
after this. To plot underneath, adjust the z-order of the plot as follows:gdf.plot(ax=ax,zorder=0)
.Examples
>>> from libpysal.weights import Queen >>> import libpysal as lp >>> import geopandas >>> gdf = geopandas.read_file(lp.examples.get_path("columbus.shp")) >>> weights = Queen.from_dataframe(gdf) >>> tmp = weights.plot(gdf, color='firebrickred', node_kws=dict(marker='*', color='k'))
- remap_ids(new_ids)[source]¶
In place modification throughout
W
of id values fromw.id_order
tonew_ids
in all.- Parameters:
- new_ids
list
,numpy.ndarray
Aligned list of new ids to be inserted. Note that first element of
new_ids
will replace first element ofw.id_order
, second element ofnew_ids
replaces second element ofw.id_order
and so on.
- new_ids
Examples
>>> from libpysal.weights import lat2W >>> w = lat2W(3, 3) >>> w.id_order [0, 1, 2, 3, 4, 5, 6, 7, 8] >>> w.neighbors[0] [3, 1] >>> new_ids = ['id%i'%id for id in w.id_order] >>> _ = w.remap_ids(new_ids) >>> w.id_order ['id0', 'id1', 'id2', 'id3', 'id4', 'id5', 'id6', 'id7', 'id8'] >>> w.neighbors['id0'] ['id3', 'id1']
- property s0¶
s0
is defined as\[s0=\sum_i \sum_j w_{i,j}\]
- property s1¶
s1
is defined as\[s1=1/2 \sum_i \sum_j \Big(w_{i,j} + w_{j,i}\Big)^2\]
- property s2¶
s2
is defined as\[s2=\sum_j \Big(\sum_i w_{i,j} + \sum_i w_{j,i}\Big)^2\]
- property sd¶
Standard deviation of number of neighbors.
- set_shapefile(shapefile, idVariable=None, full=False)[source]¶
Adding metadata for writing headers of
.gal
and.gwt
files.
- set_transform(value='B')[source]¶
Transformations of weights.
- Parameters:
- transform
str
This parameter is not case sensitive. The following are valid transformations.
B – Binary
R – Row-standardization (global sum \(=n\))
D – Double-standardization (global sum \(=1\))
V – Variance stabilizing
O – Restore original transformation (from instantiation)
- transform
Notes
Transformations are applied only to the value of the weights at instantiation. Chaining of transformations cannot be done on a
W
instance.Examples
>>> from libpysal.weights import lat2W >>> w=lat2W() >>> w.weights[0] [1.0, 1.0] >>> w.transform 'O' >>> w.transform='r' >>> w.weights[0] [0.5, 0.5] >>> w.transform='b' >>> w.weights[0] [1.0, 1.0]
- property sparse¶
Sparse matrix object. For any matrix manipulations required for w,
w.sparse
should be used. This is based onscipy.sparse
.
- symmetrize(inplace=False)[source]¶
Construct a symmetric KNN weight. This ensures that the neighbors of each focal observation consider the focal observation itself as a neighbor. This returns a generic
W
object, since the object is no longer guaranteed to havek
neighbors for each observation.
- to_WSP()[source]¶
Generate a
WSP
object.- Returns:
- implicit
libpysal.weights.WSP
Thin
W
class
- implicit
See also
Examples
>>> from libpysal.weights import W, WSP >>> neighbors={'first':['second'],'second':['first','third'],'third':['second']} >>> weights={'first':[1],'second':[1,1],'third':[1]} >>> w=W(neighbors,weights) >>> wsp=w.to_WSP() >>> isinstance(wsp, WSP) True >>> wsp.n 3 >>> wsp.s0 4
- to_adjlist(remove_symmetric=False, drop_islands=None, focal_col='focal', neighbor_col='neighbor', weight_col='weight', sort_joins=False)[source]¶
Compute an adjacency list representation of a weights object.
- Parameters:
- remove_symmetricbool
Whether or not to remove symmetric entries. If the
W
is symmetric, a standard directed adjacency list will contain both the forward and backward links by default because adjacency lists are a directed graph representation. If this isTrue
, aW
created from this adjacency list MAY NOT BE THE SAME as the originalW
. If you would like to consider (1,2) and (2,1) as distinct links, leave this asFalse
.- drop_islandsbool
Whether or not to preserve islands as entries in the adjacency list. By default, observations with no neighbors do not appear in the adjacency list. If islands are kept, they are coded as self-neighbors with zero weight.
- focal_col
str
Name of the column in which to store “source” node ids.
- neighbor_col
str
Name of the column in which to store “destination” node ids.
- weight_col
str
Name of the column in which to store weight information.
- sort_joinsbool
Whether or not to lexicographically sort the adjacency list by (focal_col, neighbor_col). Default is False.
- to_file(path='', format=None)[source]¶
Write a weights to a file. The format is guessed automatically from the path, but can be overridden with the format argument.
See libpysal.io.FileIO for more information.
- to_networkx()[source]¶
Convert a weights object to a
networkx
graph.- Returns:
A
networkx
graph
representation
of
the
W
object.
- to_sparse(fmt='coo')[source]¶
Generate a
scipy.sparse
array object from a pysal W.- Parameters:
- fmt{‘bsr’, ‘coo’, ‘csc’, ‘csr’}
scipy.sparse format
- Returns:
scipy.sparse
array
A scipy.sparse array with a format of fmt.
Notes
The keys of the w.neighbors are encoded to determine row,col in the sparse array.
- property transform¶
Getter for transform property.
- Returns:
See also
Examples
>>> from libpysal.weights import lat2W >>> w=lat2W() >>> w.weights[0] [1.0, 1.0] >>> w.transform 'O' >>> w.transform='r' >>> w.weights[0] [0.5, 0.5] >>> w.transform='b' >>> w.weights[0] [1.0, 1.0]
- property trcWtW_WW¶
Trace of \(W^{'}W + WW\).