weights.Contiguity — Contiguity based spatial weights

The weights.Contiguity. module provides for the construction and manipulation of spatial weights matrices based on contiguity criteria.

New in version 1.0.

class pysal.weights.Contiguity.Queen(polygons, method='binning', **kw)[source]
asymmetries

List of id pairs with asymmetric weights.

asymmetry(intrinsic=True)

Asymmetry check.

Parameters:intrinsic (boolean) –

default=True

intrinsic symmetry:
w_{i,j} == w_{j,i}
if intrisic is False:
symmetry is defined as i \in N_j \ AND \ j \in N_i where N_j is the set of neighbors for j.
Returns:asymmetries – empty if no asymmetries are found if asymmetries, then a list of (i,j) tuples is returned
Return type:list

Examples

>>> from pysal 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)]
cardinalities

Number of neighbors for each observation.

diagW2

Diagonal of WW.

See also

trcW2

diagWtW

Diagonal of W^{'}W.

See also

trcWtW

diagWtW_WW

Diagonal of W^{'}W + WW.

classmethod from_dataframe(df, geom_col='geometry', **kwargs)[source]

Construct a weights object from a pandas dataframe with a geometry column. This will cast the polygons to PySAL polygons, then build the W using ids from the dataframe.

Parameters:
  • df (DataFrame) – a :class: pandas.DataFrame containing geometries to use for spatial weights
  • geom_col (string) – the name of the column in df that contains the geometries. Defaults to geometry
  • idVariable (string) – the name of the column to use as IDs. If nothing is provided, the dataframe index is used
  • ids (list) – a list of ids to use to index the spatial weights object. Order is not respected from this list.
  • id_order (list) – an ordered list of ids to use to index the spatial weights object. If used, the resulting weights object will iterate over results in the order of the names provided in this argument.

See also

pysal.weights.W, pysal.weights.Queen

classmethod from_iterable(iterable, sparse=False, **kwargs)[source]

Construct a weights object from a collection of arbitrary polygons. This will cast the polygons to PySAL polygons, then build the W.

Parameters:
  • iterable (iterable) – a collection of of shapes to be cast to PySAL shapes. Must support iteration. Contents should at least implement a __geo_interface__ attribute or be able to be coerced to geometries using pysal.cg.asShape
  • **kw (keyword arguments) – optional arguments for pysal.weights.W

See also

pysal.weights.W, pysal.weights.Queen

classmethod from_shapefile(filepath, idVariable=None, full=False, **kwargs)[source]

Queen contiguity weights from a polygon shapefile.

Parameters:
  • shapefile (string) – name of polygon shapefile including suffix.
  • idVariable (string) – name of a column in the shapefile’s DBF to use for ids.
  • sparse (boolean) – If True return WSP instance If False return W instance
Returns:

w – instance of spatial weights

Return type:

W

Examples

>>> wq=Queen.from_shapefile(pysal.examples.get_path("columbus.shp"))
>>> "%.3f"%wq.pct_nonzero
'9.829'
>>> wq=Queen.from_shapefile(pysal.examples.get_path("columbus.shp"),"POLYID")
>>> "%.3f"%wq.pct_nonzero
'9.829'
>>> wq=Queen.from_shapefile(pysal.examples.get_path("columbus.shp"), sparse=True)
>>> pct_sp = wq.sparse.nnz *1. / wq.n**2
>>> "%.3f"%pct_sp
'0.098'

Notes

Queen contiguity defines as neighbors any pair of polygons that share at least one vertex in their polygon definitions.

See also

pysal.weights.W, pysal.weights.Queen

full()

Generate a full numpy array.

Returns:implicit – 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
>>> neighbors={'first':['second'],'second':['first','third'],'third':['second']}
>>> weights={'first':[1],'second':[1,1],'third':[1]}
>>> w=W(neighbors,weights)
>>> wf,ids=w.full()
>>> wf
array([[ 0.,  1.,  0.],
       [ 1.,  0.,  1.],
       [ 0.,  1.,  0.]])
>>> ids
['first', 'second', 'third']

See also

full

get_transform()

Getter for transform property.

Returns:transformation
Return type:string (or none)

Examples

>>> from pysal 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]
>>>
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.

Examples

>>> from pysal import lat2W
>>> w=lat2W()
>>> w.id_order_set
True
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.

neighbor_offsets

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

Returns:offsets of the id’s neighbors in id_order
Return type:list

Examples

>>> from pysal 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]
nonzero

Number of nonzero weights.

pct_nonzero

Percentage of nonzero weights.

remap_ids(new_ids)

In place modification throughout W of id values from w.id_order to new_ids in all

Parameters:new_ids (list) – /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.

Example

>>> import pysal as ps
>>> w = ps.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']
s0

s0 is defined as

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

s1

s1 is defined as

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

s2

s2 is defined as

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

s2array

Individual elements comprising s2.

See also

s2

sd

Standard deviation of number of neighbors.

set_shapefile(shapefile, idVariable=None, full=False)

Adding meta data for writing headers of gal and gwt files.

Parameters:
  • shapefile (string) – shapefile name used to construct weights
  • idVariable (string) – name of attribute in shapefile to associate with ids in the weights
  • full (boolean) – True - write out entire path for shapefile, False (default) only base of shapefile without extension
set_transform(value='B')

Transformations of weights.

Notes

Transformations are applied only to the value of the weights at instantiation. Chaining of transformations cannot be done on a W instance.

Parameters:transform (string) – not case sensitive)

:param .. table::: :widths: auto

transform string value
B Binary
R Row-standardization (global sum=n)
D Double-standardization (global sum=1)
V Variance stabilizing
O Restore original transformation (from instantiation)

Examples

>>> from pysal 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]
>>>
sparse

Sparse matrix object.

For any matrix manipulations required for w, w.sparse should be used. This is based on scipy.sparse.

to_WSP()

Generate a WSP object.

Returns:implicit – Thin W class
Return type:pysal.WSP

Examples

>>> import pysal as ps
>>> from pysal import W
>>> neighbors={'first':['second'],'second':['first','third'],'third':['second']}
>>> weights={'first':[1],'second':[1,1],'third':[1]}
>>> w=W(neighbors,weights)
>>> wsp=w.towsp()
>>> isinstance(wsp, ps.weights.weights.WSP)
True
>>> wsp.n
3
>>> wsp.s0
4

See also

WSP

towsp()

Generate a WSP object.

Returns:implicit – Thin W class
Return type:pysal.WSP

Examples

>>> import pysal as ps
>>> from pysal import W
>>> neighbors={'first':['second'],'second':['first','third'],'third':['second']}
>>> weights={'first':[1],'second':[1,1],'third':[1]}
>>> w=W(neighbors,weights)
>>> wsp=w.towsp()
>>> isinstance(wsp, ps.weights.weights.WSP)
True
>>> wsp.n
3
>>> wsp.s0
4

See also

WSP

transform

Getter for transform property.

Returns:transformation
Return type:string (or none)

Examples

>>> from pysal 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]
>>>
trcW2

Trace of WW.

See also

diagW2

trcWtW

Trace of W^{'}W.

See also

diagWtW

trcWtW_WW

Trace of W^{'}W + WW.

class pysal.weights.Contiguity.Rook(polygons, method='binning', **kw)[source]
asymmetries

List of id pairs with asymmetric weights.

asymmetry(intrinsic=True)

Asymmetry check.

Parameters:intrinsic (boolean) –

default=True

intrinsic symmetry:
w_{i,j} == w_{j,i}
if intrisic is False:
symmetry is defined as i \in N_j \ AND \ j \in N_i where N_j is the set of neighbors for j.
Returns:asymmetries – empty if no asymmetries are found if asymmetries, then a list of (i,j) tuples is returned
Return type:list

Examples

>>> from pysal 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)]
cardinalities

Number of neighbors for each observation.

diagW2

Diagonal of WW.

See also

trcW2

diagWtW

Diagonal of W^{'}W.

See also

trcWtW

diagWtW_WW

Diagonal of W^{'}W + WW.

classmethod from_dataframe(df, geom_col='geometry', **kwargs)[source]

Construct a weights object from a pandas dataframe with a geometry column. This will cast the polygons to PySAL polygons, then build the W using ids from the dataframe.

Parameters:
  • df (DataFrame) – a :class: pandas.DataFrame containing geometries to use for spatial weights
  • geom_col (string) – the name of the column in df that contains the geometries. Defaults to geometry
  • idVariable (string) – the name of the column to use as IDs. If nothing is provided, the dataframe index is used
  • ids (list) – a list of ids to use to index the spatial weights object. Order is not respected from this list.
  • id_order (list) – an ordered list of ids to use to index the spatial weights object. If used, the resulting weights object will iterate over results in the order of the names provided in this argument.

See also

pysal.weights.W, pysal.weights.Rook

classmethod from_iterable(iterable, sparse=False, **kwargs)[source]

Construct a weights object from a collection of arbitrary polygons. This will cast the polygons to PySAL polygons, then build the W.

Parameters:
  • iterable (iterable) – a collection of of shapes to be cast to PySAL shapes. Must support iteration. Contents should at least implement a __geo_interface__ attribute or be able to be coerced to geometries using pysal.cg.asShape
  • **kw (keyword arguments) – optional arguments for pysal.weights.W

See also

pysal.weights.W, pysal.weights.Rook

classmethod from_shapefile(filepath, idVariable=None, full=False, **kwargs)[source]

Rook contiguity weights from a polygon shapefile.

Parameters:
  • shapefile (string) – name of polygon shapefile including suffix.
  • sparse (boolean) – If True return WSP instance If False return W instance
Returns:

w – instance of spatial weights

Return type:

W

Examples

>>> wr=rook_from_shapefile(pysal.examples.get_path("columbus.shp"), "POLYID")
>>> "%.3f"%wr.pct_nonzero
'8.330'
>>> wr=rook_from_shapefile(pysal.examples.get_path("columbus.shp"), sparse=True)
>>> pct_sp = wr.sparse.nnz *1. / wr.n**2
>>> "%.3f"%pct_sp
'0.083'

Notes

Rook contiguity defines as neighbors any pair of polygons that share a common edge in their polygon definitions.

See also

pysal.weights.W, pysal.weights.Rook

full()

Generate a full numpy array.

Returns:implicit – 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
>>> neighbors={'first':['second'],'second':['first','third'],'third':['second']}
>>> weights={'first':[1],'second':[1,1],'third':[1]}
>>> w=W(neighbors,weights)
>>> wf,ids=w.full()
>>> wf
array([[ 0.,  1.,  0.],
       [ 1.,  0.,  1.],
       [ 0.,  1.,  0.]])
>>> ids
['first', 'second', 'third']

See also

full

get_transform()

Getter for transform property.

Returns:transformation
Return type:string (or none)

Examples

>>> from pysal 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]
>>>
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.

Examples

>>> from pysal import lat2W
>>> w=lat2W()
>>> w.id_order_set
True
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.

neighbor_offsets

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

Returns:offsets of the id’s neighbors in id_order
Return type:list

Examples

>>> from pysal 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]
nonzero

Number of nonzero weights.

pct_nonzero

Percentage of nonzero weights.

remap_ids(new_ids)

In place modification throughout W of id values from w.id_order to new_ids in all

Parameters:new_ids (list) – /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.

Example

>>> import pysal as ps
>>> w = ps.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']
s0

s0 is defined as

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

s1

s1 is defined as

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

s2

s2 is defined as

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

s2array

Individual elements comprising s2.

See also

s2

sd

Standard deviation of number of neighbors.

set_shapefile(shapefile, idVariable=None, full=False)

Adding meta data for writing headers of gal and gwt files.

Parameters:
  • shapefile (string) – shapefile name used to construct weights
  • idVariable (string) – name of attribute in shapefile to associate with ids in the weights
  • full (boolean) – True - write out entire path for shapefile, False (default) only base of shapefile without extension
set_transform(value='B')

Transformations of weights.

Notes

Transformations are applied only to the value of the weights at instantiation. Chaining of transformations cannot be done on a W instance.

Parameters:transform (string) – not case sensitive)

:param .. table::: :widths: auto

transform string value
B Binary
R Row-standardization (global sum=n)
D Double-standardization (global sum=1)
V Variance stabilizing
O Restore original transformation (from instantiation)

Examples

>>> from pysal 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]
>>>
sparse

Sparse matrix object.

For any matrix manipulations required for w, w.sparse should be used. This is based on scipy.sparse.

to_WSP()

Generate a WSP object.

Returns:implicit – Thin W class
Return type:pysal.WSP

Examples

>>> import pysal as ps
>>> from pysal import W
>>> neighbors={'first':['second'],'second':['first','third'],'third':['second']}
>>> weights={'first':[1],'second':[1,1],'third':[1]}
>>> w=W(neighbors,weights)
>>> wsp=w.towsp()
>>> isinstance(wsp, ps.weights.weights.WSP)
True
>>> wsp.n
3
>>> wsp.s0
4

See also

WSP

towsp()

Generate a WSP object.

Returns:implicit – Thin W class
Return type:pysal.WSP

Examples

>>> import pysal as ps
>>> from pysal import W
>>> neighbors={'first':['second'],'second':['first','third'],'third':['second']}
>>> weights={'first':[1],'second':[1,1],'third':[1]}
>>> w=W(neighbors,weights)
>>> wsp=w.towsp()
>>> isinstance(wsp, ps.weights.weights.WSP)
True
>>> wsp.n
3
>>> wsp.s0
4

See also

WSP

transform

Getter for transform property.

Returns:transformation
Return type:string (or none)

Examples

>>> from pysal 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]
>>>
trcW2

Trace of WW.

See also

diagW2

trcWtW

Trace of W^{'}W.

See also

diagWtW

trcWtW_WW

Trace of W^{'}W + WW.

pysal.weights.Contiguity.buildContiguity(polygons, criterion='rook', ids=None)[source]

This is a deprecated function.

It builds a contiguity W from the polygons provided. As such, it is now identical to calling the class constructors for Rook or Queen.

class pysal.weights.Contiguity.Queen(polygons, method='binning', **kw)[source]
asymmetries

List of id pairs with asymmetric weights.

asymmetry(intrinsic=True)

Asymmetry check.

Parameters:intrinsic (boolean) –

default=True

intrinsic symmetry:
w_{i,j} == w_{j,i}
if intrisic is False:
symmetry is defined as i \in N_j \ AND \ j \in N_i where N_j is the set of neighbors for j.
Returns:asymmetries – empty if no asymmetries are found if asymmetries, then a list of (i,j) tuples is returned
Return type:list

Examples

>>> from pysal 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)]
cardinalities

Number of neighbors for each observation.

diagW2

Diagonal of WW.

See also

trcW2

diagWtW

Diagonal of W^{'}W.

See also

trcWtW

diagWtW_WW

Diagonal of W^{'}W + WW.

classmethod from_dataframe(df, geom_col='geometry', **kwargs)[source]

Construct a weights object from a pandas dataframe with a geometry column. This will cast the polygons to PySAL polygons, then build the W using ids from the dataframe.

Parameters:
  • df (DataFrame) – a :class: pandas.DataFrame containing geometries to use for spatial weights
  • geom_col (string) – the name of the column in df that contains the geometries. Defaults to geometry
  • idVariable (string) – the name of the column to use as IDs. If nothing is provided, the dataframe index is used
  • ids (list) – a list of ids to use to index the spatial weights object. Order is not respected from this list.
  • id_order (list) – an ordered list of ids to use to index the spatial weights object. If used, the resulting weights object will iterate over results in the order of the names provided in this argument.

See also

pysal.weights.W, pysal.weights.Queen

classmethod from_iterable(iterable, sparse=False, **kwargs)[source]

Construct a weights object from a collection of arbitrary polygons. This will cast the polygons to PySAL polygons, then build the W.

Parameters:
  • iterable (iterable) – a collection of of shapes to be cast to PySAL shapes. Must support iteration. Contents should at least implement a __geo_interface__ attribute or be able to be coerced to geometries using pysal.cg.asShape
  • **kw (keyword arguments) – optional arguments for pysal.weights.W

See also

pysal.weights.W, pysal.weights.Queen

classmethod from_shapefile(filepath, idVariable=None, full=False, **kwargs)[source]

Queen contiguity weights from a polygon shapefile.

Parameters:
  • shapefile (string) – name of polygon shapefile including suffix.
  • idVariable (string) – name of a column in the shapefile’s DBF to use for ids.
  • sparse (boolean) – If True return WSP instance If False return W instance
Returns:

w – instance of spatial weights

Return type:

W

Examples

>>> wq=Queen.from_shapefile(pysal.examples.get_path("columbus.shp"))
>>> "%.3f"%wq.pct_nonzero
'9.829'
>>> wq=Queen.from_shapefile(pysal.examples.get_path("columbus.shp"),"POLYID")
>>> "%.3f"%wq.pct_nonzero
'9.829'
>>> wq=Queen.from_shapefile(pysal.examples.get_path("columbus.shp"), sparse=True)
>>> pct_sp = wq.sparse.nnz *1. / wq.n**2
>>> "%.3f"%pct_sp
'0.098'

Notes

Queen contiguity defines as neighbors any pair of polygons that share at least one vertex in their polygon definitions.

See also

pysal.weights.W, pysal.weights.Queen

full()

Generate a full numpy array.

Returns:implicit – 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
>>> neighbors={'first':['second'],'second':['first','third'],'third':['second']}
>>> weights={'first':[1],'second':[1,1],'third':[1]}
>>> w=W(neighbors,weights)
>>> wf,ids=w.full()
>>> wf
array([[ 0.,  1.,  0.],
       [ 1.,  0.,  1.],
       [ 0.,  1.,  0.]])
>>> ids
['first', 'second', 'third']

See also

full

get_transform()

Getter for transform property.

Returns:transformation
Return type:string (or none)

Examples

>>> from pysal 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]
>>>
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.

Examples

>>> from pysal import lat2W
>>> w=lat2W()
>>> w.id_order_set
True
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.

neighbor_offsets

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

Returns:offsets of the id’s neighbors in id_order
Return type:list

Examples

>>> from pysal 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]
nonzero

Number of nonzero weights.

pct_nonzero

Percentage of nonzero weights.

remap_ids(new_ids)

In place modification throughout W of id values from w.id_order to new_ids in all

Parameters:new_ids (list) – /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.

Example

>>> import pysal as ps
>>> w = ps.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']
s0

s0 is defined as

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

s1

s1 is defined as

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

s2

s2 is defined as

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

s2array

Individual elements comprising s2.

See also

s2

sd

Standard deviation of number of neighbors.

set_shapefile(shapefile, idVariable=None, full=False)

Adding meta data for writing headers of gal and gwt files.

Parameters:
  • shapefile (string) – shapefile name used to construct weights
  • idVariable (string) – name of attribute in shapefile to associate with ids in the weights
  • full (boolean) – True - write out entire path for shapefile, False (default) only base of shapefile without extension
set_transform(value='B')

Transformations of weights.

Notes

Transformations are applied only to the value of the weights at instantiation. Chaining of transformations cannot be done on a W instance.

Parameters:transform (string) – not case sensitive)

:param .. table::: :widths: auto

transform string value
B Binary
R Row-standardization (global sum=n)
D Double-standardization (global sum=1)
V Variance stabilizing
O Restore original transformation (from instantiation)

Examples

>>> from pysal 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]
>>>
sparse

Sparse matrix object.

For any matrix manipulations required for w, w.sparse should be used. This is based on scipy.sparse.

to_WSP()

Generate a WSP object.

Returns:implicit – Thin W class
Return type:pysal.WSP

Examples

>>> import pysal as ps
>>> from pysal import W
>>> neighbors={'first':['second'],'second':['first','third'],'third':['second']}
>>> weights={'first':[1],'second':[1,1],'third':[1]}
>>> w=W(neighbors,weights)
>>> wsp=w.towsp()
>>> isinstance(wsp, ps.weights.weights.WSP)
True
>>> wsp.n
3
>>> wsp.s0
4

See also

WSP

towsp()

Generate a WSP object.

Returns:implicit – Thin W class
Return type:pysal.WSP

Examples

>>> import pysal as ps
>>> from pysal import W
>>> neighbors={'first':['second'],'second':['first','third'],'third':['second']}
>>> weights={'first':[1],'second':[1,1],'third':[1]}
>>> w=W(neighbors,weights)
>>> wsp=w.towsp()
>>> isinstance(wsp, ps.weights.weights.WSP)
True
>>> wsp.n
3
>>> wsp.s0
4

See also

WSP

transform

Getter for transform property.

Returns:transformation
Return type:string (or none)

Examples

>>> from pysal 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]
>>>
trcW2

Trace of WW.

See also

diagW2

trcWtW

Trace of W^{'}W.

See also

diagWtW

trcWtW_WW

Trace of W^{'}W + WW.

class pysal.weights.Contiguity.Rook(polygons, method='binning', **kw)[source]
asymmetries

List of id pairs with asymmetric weights.

asymmetry(intrinsic=True)

Asymmetry check.

Parameters:intrinsic (boolean) –

default=True

intrinsic symmetry:
w_{i,j} == w_{j,i}
if intrisic is False:
symmetry is defined as i \in N_j \ AND \ j \in N_i where N_j is the set of neighbors for j.
Returns:asymmetries – empty if no asymmetries are found if asymmetries, then a list of (i,j) tuples is returned
Return type:list

Examples

>>> from pysal 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)]
cardinalities

Number of neighbors for each observation.

diagW2

Diagonal of WW.

See also

trcW2

diagWtW

Diagonal of W^{'}W.

See also

trcWtW

diagWtW_WW

Diagonal of W^{'}W + WW.

classmethod from_dataframe(df, geom_col='geometry', **kwargs)[source]

Construct a weights object from a pandas dataframe with a geometry column. This will cast the polygons to PySAL polygons, then build the W using ids from the dataframe.

Parameters:
  • df (DataFrame) – a :class: pandas.DataFrame containing geometries to use for spatial weights
  • geom_col (string) – the name of the column in df that contains the geometries. Defaults to geometry
  • idVariable (string) – the name of the column to use as IDs. If nothing is provided, the dataframe index is used
  • ids (list) – a list of ids to use to index the spatial weights object. Order is not respected from this list.
  • id_order (list) – an ordered list of ids to use to index the spatial weights object. If used, the resulting weights object will iterate over results in the order of the names provided in this argument.

See also

pysal.weights.W, pysal.weights.Rook

classmethod from_iterable(iterable, sparse=False, **kwargs)[source]

Construct a weights object from a collection of arbitrary polygons. This will cast the polygons to PySAL polygons, then build the W.

Parameters:
  • iterable (iterable) – a collection of of shapes to be cast to PySAL shapes. Must support iteration. Contents should at least implement a __geo_interface__ attribute or be able to be coerced to geometries using pysal.cg.asShape
  • **kw (keyword arguments) – optional arguments for pysal.weights.W

See also

pysal.weights.W, pysal.weights.Rook

classmethod from_shapefile(filepath, idVariable=None, full=False, **kwargs)[source]

Rook contiguity weights from a polygon shapefile.

Parameters:
  • shapefile (string) – name of polygon shapefile including suffix.
  • sparse (boolean) – If True return WSP instance If False return W instance
Returns:

w – instance of spatial weights

Return type:

W

Examples

>>> wr=rook_from_shapefile(pysal.examples.get_path("columbus.shp"), "POLYID")
>>> "%.3f"%wr.pct_nonzero
'8.330'
>>> wr=rook_from_shapefile(pysal.examples.get_path("columbus.shp"), sparse=True)
>>> pct_sp = wr.sparse.nnz *1. / wr.n**2
>>> "%.3f"%pct_sp
'0.083'

Notes

Rook contiguity defines as neighbors any pair of polygons that share a common edge in their polygon definitions.

See also

pysal.weights.W, pysal.weights.Rook

full()

Generate a full numpy array.

Returns:implicit – 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
>>> neighbors={'first':['second'],'second':['first','third'],'third':['second']}
>>> weights={'first':[1],'second':[1,1],'third':[1]}
>>> w=W(neighbors,weights)
>>> wf,ids=w.full()
>>> wf
array([[ 0.,  1.,  0.],
       [ 1.,  0.,  1.],
       [ 0.,  1.,  0.]])
>>> ids
['first', 'second', 'third']

See also

full

get_transform()

Getter for transform property.

Returns:transformation
Return type:string (or none)

Examples

>>> from pysal 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]
>>>
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.

Examples

>>> from pysal import lat2W
>>> w=lat2W()
>>> w.id_order_set
True
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.

neighbor_offsets

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

Returns:offsets of the id’s neighbors in id_order
Return type:list

Examples

>>> from pysal 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]
nonzero

Number of nonzero weights.

pct_nonzero

Percentage of nonzero weights.

remap_ids(new_ids)

In place modification throughout W of id values from w.id_order to new_ids in all

Parameters:new_ids (list) – /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.

Example

>>> import pysal as ps
>>> w = ps.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']
s0

s0 is defined as

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

s1

s1 is defined as

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

s2

s2 is defined as

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

s2array

Individual elements comprising s2.

See also

s2

sd

Standard deviation of number of neighbors.

set_shapefile(shapefile, idVariable=None, full=False)

Adding meta data for writing headers of gal and gwt files.

Parameters:
  • shapefile (string) – shapefile name used to construct weights
  • idVariable (string) – name of attribute in shapefile to associate with ids in the weights
  • full (boolean) – True - write out entire path for shapefile, False (default) only base of shapefile without extension
set_transform(value='B')

Transformations of weights.

Notes

Transformations are applied only to the value of the weights at instantiation. Chaining of transformations cannot be done on a W instance.

Parameters:transform (string) – not case sensitive)

:param .. table::: :widths: auto

transform string value
B Binary
R Row-standardization (global sum=n)
D Double-standardization (global sum=1)
V Variance stabilizing
O Restore original transformation (from instantiation)

Examples

>>> from pysal 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]
>>>
sparse

Sparse matrix object.

For any matrix manipulations required for w, w.sparse should be used. This is based on scipy.sparse.

to_WSP()

Generate a WSP object.

Returns:implicit – Thin W class
Return type:pysal.WSP

Examples

>>> import pysal as ps
>>> from pysal import W
>>> neighbors={'first':['second'],'second':['first','third'],'third':['second']}
>>> weights={'first':[1],'second':[1,1],'third':[1]}
>>> w=W(neighbors,weights)
>>> wsp=w.towsp()
>>> isinstance(wsp, ps.weights.weights.WSP)
True
>>> wsp.n
3
>>> wsp.s0
4

See also

WSP

towsp()

Generate a WSP object.

Returns:implicit – Thin W class
Return type:pysal.WSP

Examples

>>> import pysal as ps
>>> from pysal import W
>>> neighbors={'first':['second'],'second':['first','third'],'third':['second']}
>>> weights={'first':[1],'second':[1,1],'third':[1]}
>>> w=W(neighbors,weights)
>>> wsp=w.towsp()
>>> isinstance(wsp, ps.weights.weights.WSP)
True
>>> wsp.n
3
>>> wsp.s0
4

See also

WSP

transform

Getter for transform property.

Returns:transformation
Return type:string (or none)

Examples

>>> from pysal 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]
>>>
trcW2

Trace of WW.

See also

diagW2

trcWtW

Trace of W^{'}W.

See also

diagWtW

trcWtW_WW

Trace of W^{'}W + WW.