2.1 Contiguity-Based Weights

Contiguity means that two spatial units share a common border of non-zero length. Operationally, we can further distinguish between a rook and a queen criterion of contiguity, in analogy to the moves allowed for the such-named pieces on a chess board.

The rook criterion defines neighbors by the existence of a common edge between two spatial units. The queen criterion is somewhat more encompassing and defines neighbors as spatial units sharing a common edge or a common vertex.

For more information, please read: https://geodacenter.github.io/workbook/4a_contig_weights/lab4a.html

CONTENTS

1. queen_weights()

2. rook_weights()

3. weights_astext()

4. save weights

queen_weights()

Synopsis

Short version:

bytea queen_weights(integer gid, geometry the_geom)

Full Version:

bytea queen_weights(integer gid, geometry the_geom,
    integer ord, 
    boolean include_lowerorder, 
    float precision_threshold)

queen_weights() is a WINDOW SQL function, which performs weights creation across a set of table rows. Unlike the regular AGGREGATE function, a WINDOW function does not cause rows to become grouped into a single output row -- the rows retain their separate identities. A WINDOW function call always contains an OVER() clause.

Arguments

Input Arguments	Type	Description
gid	integer	the feature id of geometry: e.g. gid, fid, ogcfid, cartodb_id
the_geom	geometry	the geometry (only points and polygons are supported)
ord	integer	order of contiguity. Default is 1.
include_lowerorder	boolean	boolean value indicates whether or not the lower order neighbors should be included in the weights structure. Default is FALSE.
precision_threshold	boolean	(for polygons only) the distance of precision to determine which polygons are neighbors when the underlying geometries are insufficient to allow for an exact match of coordinates. Default is 0.0.

Return

Value	Description
bytea	the weights structure for each observation in binary format, which is defined in table 2.1.

Examples

SELECT queen_weights(gid, the_geom) OVER() FROM natregimes;

                                                         queen_weights                                                          
--------------------------------------------------------------------------------------------------------------------------------
 \x7707000008002007000021070000740700001e070000c707000075070000c3070000c4070000
 \x7a0000000700680000004e0000005c0000007b0000008d0000009700000098000000
 \xeb0000000600ea000000cb000000ce000000020100000101000004010000
 \x510400000600ea030000e90300005204000050040000bc040000c1040000
 ...

Table 2.1: The binary format of weights structure

Bytes	Data Type	Length	Description
0-3	uint32_t	4 bytes	index of i-th observation/row
4-5	uint16_t	2 bytes	number of neighbors of i-th observation
6-9	uint32_t	4 bytes	index of first neighbor
10-13	float	4 bytes	weights value of first neighbor
...	...	...	index of n-th neighbor
...	...	...	weights value of n-th neighbor

rook_weights()

Synopsis

Short version:

bytea rook_weights(integer gid, geometry winset the_geom)

Full Version:

bytea rook_weights(integer gid, geometry winset the_geom,
    integer ord, 
    boolean include_lowerorder, 
    float precision_threshold)

weights_astext()

The help function to view the content of the weights information.

Synopsis

text weights_astext(bytea weights)

Examples

SELECT weights_astext(tmp.queen_weights) FROM (
    SELECT queen_weights(gid, the_geom) OVER(ORDER BY gid) FROM natregimes
) AS tmp;

                             weights_astext                             
--------------------------------------------------------------------------
 1:[23,31,41]
 2:[3,4,70]
 3:[2,5,63,70]
 4:[2,28,32,43,56,69,70]
...

Save Weights

To save the results of queen_weights(), the best practice is to save the results with the feature id, e.g. gid, in a new table. For example:

CREATE TABLE nat_queen_w AS (
    SELECT gid, queen_weights(gid, the_geom) AS queen_w OVER() 
    FROM natregimes
);
-- CREATE index on gid
-- CREATE INDEX natqueen_gid_idx ON nat_queen_w (gid)

Or, one can create a new bytea column, and update its values from the results of queen_weights() function. For example:

-- add column queen_w
ALTER TABLE natregimes ADD COLUMN IF NOT EXISTS queen_w bytea;
-- save weights 
UPDATE natregimes SET queen_w = tmp.queen_weights FROM (
    SELECT gid, queen_weights(gid, the_geom) OVER() natregimes
) AS tmp
WHERE natregimes.gid = tmp.gid;

The second approach is much slower than the first one when updating a large table, e.g. with millions of records.