libpysal.weights.KNN¶
-
class libpysal.weights.KNN(data, k=
2, p=2, ids=None, radius=None, distance_metric='euclidean', **kwargs)[source]¶ Creates nearest neighbor weights matrix based on k nearest neighbors.
Examples
>>> import libpysal >>> import numpy as np >>> points = [(10, 10), (20, 10), (40, 10), (15, 20), (30, 20), (30, 30)] >>> kd = libpysal.cg.KDTree(np.array(points)) >>> wnn2 = libpysal.weights.KNN(kd, 2) >>> [1,3] == wnn2.neighbors[0] True >>> wnn2 = KNN(kd,2) >>> wnn2[0] {1: 1.0, 3: 1.0} >>> wnn2[1] {0: 1.0, 3: 1.0}now with 1 rather than 0 offset
>>> wnn2 = libpysal.weights.KNN(kd, 2, ids=range(1,7)) >>> wnn2[1] {2: 1.0, 4: 1.0} >>> wnn2[2] {1: 1.0, 4: 1.0} >>> 0 in wnn2.neighbors FalseNotes
Ties between neighbors of equal distance are arbitrarily broken.
Further, if many points occupy the same spatial location (i.e. observations are coincident), then you may need to increase k for those observations to acquire neighbors at different spatial locations. For example, if five points are coincident, then their four nearest neighbors will all occupy the same spatial location; only the fifth nearest neighbor will result in those coincident points becoming connected to the graph as a whole.
Solutions to this problem include jittering the points (by adding a small random value to each observation’s location) or by adding higher-k neighbors only to the coincident points, using the weights.w_sets.w_union() function.
See also
Create nearest-neighbor weights.
- Parameters:¶
- data : object¶
PySAL KDTree or ArcKDTree where
KDTree.datais an(n, k)array.- k : int, default 2¶
Number of nearest neighbors.
- p : float, default 2¶
Minkowski p-norm distance metric parameter. Ignored if the tree uses arc distance.
- ids : list, optional¶
Identifiers to attach to each observation.
- radius : float, optional¶
If supplied, arc distances will be calculated based on the radius.
- distance_metric : str, default "euclidean"¶
Distance metric used when building a KDTree from raw coordinates.
- **kwargs¶
Additional keyword arguments passed to
libpysal.weights.W.
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_array(array, *args, **kwargs)Creates nearest neighbor weights matrix based on k nearest neighbors.
from_dataframe(df[, geom_col, ids, use_index])Make KNN weights from a dataframe.
from_file([path, format])Read a weights file into a W object.
from_networkx(graph[, weight_col])Convert a
networkxgraph to a PySALWobject.from_shapefile(filepath[, k, p, ids, ...])Nearest neighbor weights from a shapefile.
from_sparse(sparse)Convert a
scipy.sparsearray to a PySALWobject.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
Wof id values fromw.id_ordertonew_idsin all.reweight([k, p, new_data, new_ids, inplace])Redo K-Nearest Neighbor weights construction using given parameters
set_shapefile(shapefile[, idVariable, full])Adding metadata for writing headers of
.galand.gwtfiles.set_transform([value])Transformations of weights.
symmetrize([inplace])Construct a symmetric KNN weight.
to_WSP()Generate a
WSPobject.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
networkxgraph.to_sparse([fmt])Generate a
scipy.sparsearray 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
Trueif user has setid_order,Falseif 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.
s0is defined ass1is defined ass2is 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[source]¶
List of id pairs with asymmetric weights sorted in ascending index location order.
-
asymmetry(intrinsic=
True)[source]¶ Asymmetry check.
- Parameters:¶
- Returns:¶
asymmetries – Empty if no asymmetries are found. If there are asymmetries, then a
listof(i,j)tuples is returned sorted in ascending index location order.- Return type:¶
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)]
-
classmethod from_WSP(WSP, silence_warnings=
True)[source]¶ Create a pysal W from a pysal WSP object (thin weights matrix).
Examples
>>> from libpysal.weights import lat2W, WSP, WBuild 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_array(array, *args, **kwargs)[source]¶
Creates nearest neighbor weights matrix based on k nearest neighbors.
Examples
>>> from libpysal.weights import KNN >>> points = [(10, 10), (20, 10), (40, 10), (15, 20), (30, 20), (30, 30)] >>> wnn2 = KNN.from_array(points, 2) >>> [1,3] == wnn2.neighbors[0] True >>> wnn2 = KNN.from_array(points,2) >>> wnn2[0] {1: 1.0, 3: 1.0} >>> wnn2[1] {0: 1.0, 3: 1.0}now with 1 rather than 0 offset
>>> wnn2 = KNN.from_array(points, 2, ids=range(1,7)) >>> wnn2[1] {2: 1.0, 4: 1.0} >>> wnn2[2] {1: 1.0, 4: 1.0} >>> 0 in wnn2.neighbors FalseNotes
Ties between neighbors of equal distance are arbitrarily broken.
See also
-
classmethod from_dataframe(df, geom_col=
None, ids=None, use_index=True, *args, **kwargs)[source]¶ Make KNN weights from a dataframe.
- Parameters:¶
- df : pandas.dataframe¶
a dataframe with a geometry column that can be used to construct a W object
- geom_col : string¶
the name of the column in df that contains the geometries. Defaults to active geometry column.
- ids : list-like, string¶
a list-like of ids to use to index the spatial weights object or the name of the column to use as IDs. If nothing is provided, the dataframe index is used if use_index=True or a positional index is used if use_index=False. Order of the resulting W is not respected from this list.
- use_index : bool¶
use index of df as ids to index the spatial weights object.
See also
-
classmethod from_networkx(graph, weight_col=
'weight')[source]¶ Convert a
networkxgraph to a PySALWobject.
-
classmethod from_shapefile(filepath, k=
2, p=2, ids=None, radius=None, distance_metric='euclidean', **kwargs)[source]¶ Nearest neighbor weights from a shapefile.
- Parameters:¶
- filepath : str¶
Shapefile containing attribute data.
- k : int¶
number of nearest neighbors
- p : float¶
Minkowski p-norm distance metric parameter: 1<=p<=infinity 2: Euclidean distance 1: Manhattan distance
- ids : list¶
identifiers to attach to each observation
- radius : float¶
If supplied arc_distances will be calculated based on the given radius. p will be ignored.
- distance_metric : str, default "euclidean"¶
Distance metric used when building the KDTree.
- Returns:¶
w – instance; Weights object with binary weights.
- Return type:¶
Examples
Polygon shapefile >>> import libpysal >>> from libpysal.weights import KNN >>> wc=KNN.from_shapefile(libpysal.examples.get_path(“columbus.shp”)) >>> “%.4f”%wc.pct_nonzero ‘4.0816’ >>> set([2,1]) == set(wc.neighbors[0]) True >>> wc3=KNN.from_shapefile(libpysal.examples.get_path(“columbus.shp”),k=3) >>> set(wc3.neighbors[0]) == set([2,1,3]) True >>> set(wc3.neighbors[2]) == set([4,3,0]) True
Point shapefile
>>> w=KNN.from_shapefile(libpysal.examples.get_path("juvenile.shp")) >>> w.pct_nonzero 1.1904761904761905 >>> w1=KNN.from_shapefile(libpysal.examples.get_path("juvenile.shp"),k=1) >>> "%.3f"%w1.pct_nonzero '0.595'Notes
Ties between neighbors of equal distance are arbitrarily broken.
See also
- classmethod from_sparse(sparse)[source]¶
Convert a
scipy.sparsearray to a PySALWobject.- Parameters:¶
- sparse : scipy.sparse array¶
- Returns:¶
w – A
Wobject containing the same graph as thescipy.sparsegraph.- Return type:¶
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.ndarrayand second element keys being the ids associated with each row in the array.- Return type:¶
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
transformparameters inset_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
- 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
Trueif user has setid_order,Falseif not.Examples
>>> from libpysal.weights import lat2W >>> w=lat2W() >>> w.id_order_set True
- property neighbor_offsets[source]¶
Given the current
id_order,neighbor_offsets[id]is the offsets of the id’s neighbors inid_order.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]
-
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.GeoDataFrameas input.- Parameters:¶
- gdf : geopandas.GeoDataFrame¶
The original shapes whose topological relations are modelled in
W.- indexed_on : str¶
Column of
geopandas.GeoDataFramethat the weights object uses as an index. Default isNone, so the index of thegeopandas.GeoDataFrameis used.- ax : matplotlib.axes.Axes¶
Axis on which to plot the weights. Default is
None, so plots on the current figure.- color : str¶
matplotlibcolor 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, 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
Wof id values fromw.id_ordertonew_idsin all.- Parameters:¶
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']
-
reweight(k=
None, p=None, new_data=None, new_ids=None, inplace=True)[source]¶ Redo K-Nearest Neighbor weights construction using given parameters
- Parameters:¶
- new_data : np.ndarray¶
an array containing additional data to use in the KNN weight
- new_ids : list¶
a list aligned with new_data that provides the ids for each new observation
- inplace : bool¶
a flag denoting whether to modify the KNN object in place or to return a new KNN object
- k : int¶
number of nearest neighbors
- p : float¶
Minkowski p-norm distance metric parameter: 1<=p<=infinity 2: Euclidean distance 1: Manhattan distance Ignored if the KDTree is an ArcKDTree
- Returns:¶
A copy of the object using the new parameterization, or None if the
object is reweighted in place.
-
set_shapefile(shapefile, idVariable=
None, full=False)[source]¶ Adding metadata for writing headers of
.galand.gwtfiles.- Parameters:¶
-
set_transform(value=
'B')[source]¶ Transformations of weights.
- Parameters:¶
Notes
Transformations are applied only to the value of the weights at instantiation. Chaining of transformations cannot be done on a
Winstance.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.sparseshould 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
Wobject, since the object is no longer guaranteed to havekneighbors for each observation.
- to_WSP()[source]¶
Generate a
WSPobject.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 4See also
-
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_symmetric : bool¶
Whether or not to remove symmetric entries. If the
Wis 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, aWcreated 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_islands : bool¶
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_joins : bool¶
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
networkxgraph.- Return type:¶
A
networkxgraph representation of theWobject.
-
to_sparse(fmt=
'coo')[source]¶ Generate a
scipy.sparsearray object from a pysal W.- Parameters:¶
- fmt : {'bsr', 'coo', 'csc', 'csr'}¶
scipy.sparse format
- Returns:¶
A scipy.sparse array with a format of fmt.
- Return type:¶
scipy.sparse array
Notes
The keys of the w.neighbors are encoded to determine row,col in the sparse array.
- property transform[source]¶
Getter for transform property.
- Returns:¶
transformation – Valid transformation value. See the
transformparameters inset_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