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.

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.

Create a spatial weights object.

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 the id_order_set property will return False. This can be set after creation by setting the id_order property.
silence_warnings : bool¶: By default libpysal will print a warning if the dataset contains any disconnected components or islands. To silence this warning set this parameter to True.
ids : list¶: Values to use for keys of the neighbors and weights dict objects.

Methods

`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 PySAL `W` object.
`from_shapefile`(args, *kwargs)
`from_sparse`(sparse)	Convert a `scipy.sparse` array to a PySAL `W` object.
`full`()	Generate a full `numpy.ndarray`.
`get_transform`()	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 from `w.id_order` to `new_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.
`to_networkx`()	Convert a weights object to a `networkx` graph.
`to_sparse`([fmt])	Generate a `scipy.sparse` array object from a pysal W.

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 set `id_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 in `id_order`.
`nonzero`	Number of nonzero weights.
`pct_nonzero`	Percentage of nonzero weights.
`s0`	`s0` is defined as
`s1`	`s1` is defined as
`s2`	`s2` is defined as
`s2array`	Individual elements comprising `s2`.
`sd`	Standard deviation of number of neighbors.
`sparse`	Sparse matrix object.
`transform`	Getter for transform property.
`trcW2`	Trace of \(WW\).
`trcWtW`	Trace of \(W^{'}W\).
`trcWtW_WW`	Trace of \(W^{'}W + WW\).

property asymmetries[source]¶: List of id pairs with asymmetric weights sorted in ascending index location order.

asymmetry(intrinsic=True)[source]¶

Asymmetry check.

Parameters:¶

intrinsic : bool¶

Default is True. Intrinsic symmetry is defined as:

\[w_{i,j} == w_{j,i}\]

If intrinsic is False symmetry is defined as:

\[i \in N_j \ \& \ j \in N_i\]

where \(N_j\) is the set of neighbors for \(j\).

Returns:¶

asymmetries – 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.

Return type:¶

list

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[source]¶: Number of neighbors for each observation.

property component_labels[source]¶: Store the graph component in which each observation falls.

property diagW2[source]¶: Diagonal of \(WW\).

See also

trcW2

property diagWtW[source]¶: Diagonal of \(W^{'}W\).

See also

trcWtW

property diagWtW_WW[source]¶: 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:¶

WSP : WSP¶: PySAL sparse weights object.
silence_warnings : bool¶: By default libpysal will print a warning if the dataset contains disconnected components or islands. Set to True to silence it.

Returns:¶

w – PySAL weights object

Return type:¶

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.

classmethod from_file(path='', format=None)[source]¶

Read a weights file into a W object.

Parameters:¶

path : string¶: location to save the file
format : string¶: string denoting the format to write the weights to.

Return type:¶

W object

classmethod from_networkx(graph, weight_col='weight')[source]¶

Convert a networkx graph to a PySAL W object.

Parameters:¶

graph : networkx.Graph¶: The graph to convert to a W.
weight_col : string¶: If the graph is labeled, this should be the name of the field to use as the weight for the W.

Returns:¶

w – A W object containing the same graph as the networkx graph.

Return type:¶

libpysal.weights.W

classmethod from_shapefile(*args, **kwargs)[source]¶

classmethod from_sparse(sparse)[source]¶

Convert a scipy.sparse array to a PySAL W object.

Parameters:¶

sparse : scipy.sparse array¶

Returns:¶

w – A W object containing the same graph as the scipy.sparse graph.

Return type:¶

libpysal.weights.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.

Returns:¶: (fullw, keys) – The first element being the full numpy.ndarray and second element keys being the ids associated with each row in the array.
Return type:¶: tuple

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:¶: transformation – Valid transformation value. See the transform parameters in set_transform() for a detailed description.
Return type:¶: str, None

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]

See also

set_transform

property histogram[source]¶: Cardinality histogram as a dictionary where key is the id and value is the number of neighbors for that unit.

property id2i[source]¶: Dictionary where the key is an ID and the value is that ID’s index in W.id_order.

property id_order[source]¶: Returns the ids for the observations in the order in which they would be encountered if iterating over the weights.

property id_order_set[source]¶

Returns True if user has set id_order, False if not.

Examples

>>> from libpysal.weights import lat2W
>>> w=lat2W()
>>> w.id_order_set
True

property islands[source]¶: List of ids without any neighbors.

property max_neighbors[source]¶: Largest number of neighbors.

property mean_neighbors[source]¶: Average number of neighbors.

property min_neighbors[source]¶: Minimum number of neighbors.

property n[source]¶: Number of units.

property n_components[source]¶: Store whether the adjacency matrix is fully connected.

property neighbor_offsets[source]¶

Given the current id_order, neighbor_offsets[id] is the offsets of the id’s neighbors in id_order.

Returns:¶: neighbor_list – Offsets of the id’s neighbors in id_order.
Return type:¶: 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[source]¶: Number of nonzero weights.

property pct_nonzero[source]¶: 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 a geopandas.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 is None, so the index of the geopandas.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.

Returns:¶

f (matplotlib.figure.Figure) – Figure on which the plot is made.
ax (matplotlib.axes.Axes) – Axis on which the plot is made.

Notes

If you’d like to overlay the actual shapes from the geopandas.GeoDataFrame, call gdf.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 from w.id_order to new_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 of w.id_order, second element of new_ids replaces second element of w.id_order and so on.

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[source]¶: s0 is defined as

\[s0=\sum_i \sum_j w_{i,j}\]

property s1[source]¶: s1 is defined as

\[s1=1/2 \sum_i \sum_j \Big(w_{i,j} + w_{j,i}\Big)^2\]

property s2[source]¶: s2 is defined as

\[s2=\sum_j \Big(\sum_i w_{i,j} + \sum_i w_{j,i}\Big)^2\]

property s2array[source]¶: Individual elements comprising s2.

See also

s2

property sd[source]¶: Standard deviation of number of neighbors.

set_shapefile(shapefile, idVariable=None, full=False)[source]¶

Adding metadata for writing headers of .gal and .gwt files.

Parameters:¶

shapefile : str¶: The shapefile name used to construct weights.
idVariable : str¶: The name of the attribute in the shapefile to associate with ids in the weights.
full : bool¶: Write out the entire path for a shapefile (True) or only the base of the shapefile without extension (False). Default is True.

set_transform(value='B')[source]¶

Transformations of weights.

Parameters:¶

value : 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)

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[source]¶: Sparse matrix object. For any matrix manipulations required for w, w.sparse should be used. This is based on scipy.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 have k neighbors for each observation.

to_WSP()[source]¶

Generate a WSP object.

Returns:¶: implicit – Thin W class
Return type:¶: libpysal.weights.WSP

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