Title: Further Capabilities in Geographic Information Science
Version: 1.0-2
Date: 2024-10-03
Maintainer: Binbin Lu <binbinlu@whu.edu.cn>
License: GPL-2 | GPL-3 [expanded from: GPL (≥ 2)]
Repository: CRAN
Description: Mapping and spatial data manipulation tools - in particular drawing thematic maps with nice looking legends, and aggregation of point data to polygons.
Depends: R (≥ 3.5.0),sf, sp
Imports: RColorBrewer, MASS,methods
NeedsCompilation: no
Packaged: 2024-10-02 17:01:39 UTC; Lenovo
Author: Chris Brunsdon [aut], Binbin Lu [aut, cre], Hongyan Chen [aut]
Date/Publication: 2024-10-02 20:00:05 UTC

GISTools

Description

In this package, a number of utilities for handling and visualising geographical data of a “Spatial” or “sf” object - for example choropleth mapping with 'nice' legends.

Details

Package: GISTools
Type: Package
Version: 1.0-2
Date: 2024-10-03
License: GPL (>=2)
LazyLoad: yes

Draw a mask around a Grid Based Image

Description

Takes an ‘mask’ type polygon object - basically a rectangle with a polygon hole cut through it - and draws this over an image. This has the effect of only showing the image inside the hole. This is useful for plotting surfaces defined over a study area, but masking the values outside of the area.

Usage

add.masking(maskPoly,color)

Arguments

maskPoly

A masking polygon of a “Spatial” or “sf” class as described above.

color

Colour of the mask. Defaults to white, but for example, sea could be shown as blue.

Details

Returns no value, but draws a mask on the current graphics device as a side effect

Value

None

Author(s)

Chris Brunsdon, Binbin Lu

See Also

poly.outer, kde.points.

Examples

  
# Data for New Haven to use in example
data(newhaven)
# Do the KDE
breach.dens = kde.points(breach,lims=tracts)
# Plot the result
level.plot(breach.dens)
# Block out the part outside the study area
masker = poly.outer(breach.dens,tracts,extend=100); add.masking(masker)
add.masking(masker,"blue")

Bootstrap and Kernel Bootstrap from Points

Description

Operations for bootstrapping and kernel bootstrapping based on point data. bstrap.points sample n points with replacement from a sample - and jitter.points adds a Gaussian displacement to each point in a data set. Applying a jitter to a bootstrap effectively creates a kernel bootstrap operation.

Usage

jitter.points(pts,scl)
bstrap.points(pts)

Arguments

pts

A SpatialPointsDataFrame or sf - POINT object

scl

A scale parameter - basically the standard deviation of the random Gaussian displacement

Value

A SpatialPointsDataFrame - with either a sample without replacement or a replica of the input data with displacements.

Author(s)

Chris Brunsdon, Binbin Lu

Examples


data(newhaven)
plot(blocks)
for (i in 1:20) plot(jitter.points(breach,150),add=TRUE,pch=1,col='red')

Add transparency to a hex-defined colour

Description

Takes a colour defined in hex format as #XXXXXX and adds a two transparency bytes XX based on a number from 0 to 1. Its main use is to make RColorBrewer palettes transparent.

Usage

add.alpha(hex.color.list,alpha)

Arguments

hex.color.list

A list of strings defining solid colors in six byte format.

alpha

A value (or list of values) from 0 to 1 specifying transparency.

Value

A list of strings defining transparent colours in eight byte format.

Author(s)

Chris Brunsdon

Examples

# Make a list of semi-transparent RColorBrewer colours,  based on Brewer's Red palette with 5 shades
require(RColorBrewer)
add.alpha(brewer.pal(5,'Reds'),0.5)

Create a masking polygon to block out graphics outside a region.

Description

Takes a polygon object and creates a new polygon whose outline is rectangular, but has a hole shaped like the input polygon cut into it. This is useful for plotting surfaces defined over a study area, but masking the values outside of the area. It is designed to work with pixel images, so that the mask covers up all parts of the image not in the input polygon.

Usage

poly.outer(exo.object,input.poly,extend=0)

Arguments

exo.object

The object extending beyond input.poly that is to be masked. This is required to ensure that the external rectangle of the mask will be large enough.

input.poly

The polygon used to make the hole in the mask.

extend

A buffer used to extend the mask if it is required to be larger than exo.object

Value

A polygon object whose outline is rectangular, but having holes cut into it in the shape of input.poly

Author(s)

Chris Brunsdon, Binbin Lu

See Also

add.masking, kde.points.

Examples

  
# Data for New Haven to use in example
data(newhaven)
# Do the KDE
breach.dens = kde.points(breach,lims=tracts)
# Plot the result
level.plot(breach.dens)
# Block out the part outside the study area
masker = poly.outer(breach.dens,tracts,extend=100); add.masking(masker)
# Plot census tract boundaries
plot(tracts,add=TRUE)

Kernel Density Estimates

Description

Given a set of points, a bandwidth, a grid density and a frame, produce a kernel density estimate

Usage

kde.points(pts,h,n=200,lims=NULL)

Arguments

pts

A SpatialPoints or SpatialPointsDataFrame object or sf - POINT object.

h

A real number - the bandwidth of the KDE

n

An integer, the output grid density - ie result is nxn grid

lims

A spatial object - the KDE grid will cover this, if provided

Value

A SpatialPixelsDataFrame containing the KDE.

Author(s)

Chris Brunsdon, Binbin Lu

Examples

  
# Data for New Haven to use in example
data(newhaven)
# Do the KDE
breach.dens = kde.points(breach,lims=tracts)
# Plot the result
level.plot(breach.dens)
# Block out the part outside the study area
masker = poly.outer(breach.dens,tracts,extend=100); add.masking(masker)
# Plot census tract boundaries
plot(tracts,add=TRUE)

Add a north arrow to a map

Description

Draws a north arrow on a map.

Usage

north.arrow(xb,yb,len,lab='NORTH',cex.lab=1,tcol='black',...)

Arguments

xb

The x-centre (in map units) of the arrow base.

yb

The y-centre (in map units) of the arrow base.

len

The length (in map units) of the arrow base.

lab

The label for the arrow.

cex.lab

Scale factor for the label for the arrow.

tcol

The colour of the label text.

...

Other graphical parameters passed to the drawing of the arrow.

Details

Draws a north arrow on a map. The arrow itself is drawn using polygon and any extra parameters are passed to this call.

Value

None.

Author(s)

Chris Brunsdon

See Also

map.scale

Examples

# Read in map data for New Haven
data(newhaven)
# Plot census block boundaries
plot(blocks)
# Add a north arrow
north.arrow(534750,152000,miles2ft(0.5),col='cyan')
# ... and a title
title('New Haven (CT)')

Number of Points in Each Polygon

Description

Given a set of points, and a set of polygons, computes the number of points in each polygon.

Usage

poly.counts(pts, polys)

Arguments

pts

A SpatialPoints or SpatialPointsDataFrame sf - POINT object .

polys

A SpatialPolygons or SpatialPolygonsDataFrame or sf -POLYGON or - MULTIPOLYGON object.

Value

A list of integers of the same length as the number of polygons in polys, giving the number of points from pts.

Author(s)

Chris Brunsdon, Binbin Lu

Examples

# Data for New Haven to use in example
data(newhaven)
# How many breaches of peace in each census block?
n.breach = poly.counts(breach,blocks)
blocks@data$Count.per <- n.breach/poly.areas(blocks)
# Compute densities and map them
choropleth(blocks,"Count.per")

Area of Each Polygon

Description

Given a set of polygons, returns the area of each polygon.

Usage

poly.areas(polys)

Arguments

polys

A SpatialPolygons or SpatialPolygonsDataFrame or sf -POLYGON or - MULTIPOLYGON object.

Value

A list of areas of the same length as the number of polygons in polys.

Author(s)

Chris Brunsdon, Binbin Lu

Examples

# Data for New Haven to use in example
data(newhaven)
# What is the area each census block?
poly.areas(blocks)

Number of Points in Each Polygon

Description

Given a set of polygons, returns the label point for each polygon in a SpatialPoints or a sf POINT object.

Usage

poly.labels(polys)

Arguments

polys

A SpatialPolygons or SpatialPolygonsDataFrame or sf -POLYGON or - MULTIPOLYGON object.

Value

SpatialPoints or sf POINT object containing the label point for each polygon, respectively.

Author(s)

Chris Brunsdon, Binbin Lu

Distance Units Conversion

Description

Convert between different distance units - all functions take the form xx2yy where xx is the unit to be converted from and yy is the unit to be converted to.

Usage

ft2miles(x)
miles2ft(x)
ft2km(x)
km2ft(x)

Arguments

x

A quantity in units to be converted from

Value

The value of x converted to the new units. In the example below the conversions are from feet to miles and feet to kilometers (hence functions are ft2miles and ft2km).

Author(s)

Chris Brunsdon

Examples

# How many miles is 10,000 feet?
ft2miles(10000)
# How about in kilometers?
ft2km(10000)

Data sets of Wuhan

Description

Four geographic data sets of Wuhan are incoporated in this package

Usage

data(WHData)

Format

Examples

# Read in the data
data(WHData)
choropleth(WHHP,"Avg_HP_avg")

auto.shading

Description

Creates an object of class shading automatically, given a choropleth variable to be mapped.

Usage

auto.shading(x, digits = 2, cutter = quantileCuts, n = 5, 
	params = NA, cols = brewer.pal(n, "Reds"))

Arguments

x

The variable to be mapped.

digits

The number of significant digits to round the class limits to.

cutter

Function used to create the break points. Can be user defined or a supplied cut function.

n

The number of classes. The should be one more than the number of break points.

params

Other parameters to be passed to the cut function.

cols

List of colours for shading each class. length(cols) should be equal to n.

Details

Returns an object of class shading, as set out below:

Value

An object of class shading, having the following list elements:

breaks

Break points between choropleth classes. length(cols)

cols

Colours to shade in each class. length(cols) should be one more than length(breaks)

Author(s)

Chris Brunsdon, Binbin Lu

See Also

choropleth,shading,choro.legend.

Examples

# Read in map data and compute a rate for mapping
# Try the sf class
data(WHData)
shades = auto.shading(WHHP[["Avg_HP_avg"]],n=7)
dev.new(width = 16, height = 12)
choropleth(sp = WHHP,v="Avg_HP_avg",shading=shades)
choro.legend(548871.4, 3377000, shades,title='Average house price')
#Try the Spatial object
shades = auto.shading(whp_sp@data[["Avg_HP_avg"]],n=6)
dev.new(width = 16, height = 12)
choropleth(sp = whp_sp,v="Avg_HP_avg",shading=shades)
choro.legend(548871.4, 3377000,  shades,title='Average house price')

choro.legend

Description

Draw a legend for a choropleth map.

Usage

choro.legend(px, py, sh, under = "under", over = "over", 
  between = "to", fmt = "%g", cex=1, ...)

Arguments

px

x coordinate of legend location

py

y coordinate of legend location

sh

Shading scheme object used as basis for the legend

under

What to write in front of the lowest choropleth class upper limit.

over

What to write in front of the highest choropleth class lower limit.

between

What to write between the upper and lower limits of intermediate chropleth classes.

fmt

C style format for values stated in above choroplth class limits.

cex

Relative size of text in the legend.

...

Other arguments, passed on to the generic legend function.

Details

Returns no value, but draws a choropleth map legend on the current graphics device as a side effect

Value

None (see above)

Author(s)

Chris Brunsdon

See Also

choropleth, auto.shading, shading.

Examples

# Read in map data and compute a rate for mapping
# Try the sf class
data(WHData)
shades = auto.shading(WHHP[["Avg_HP_avg"]],n=7)
dev.new(width = 16, height = 12)
choropleth(sp = WHHP,v="Avg_HP_avg",shading=shades)
choro.legend(548871.4, 3377000, shades,title='Average house price')
#Try the Spatial object
shades = auto.shading(whp_sp@data[["Avg_HP_avg"]],n=6)
dev.new(width = 16, height = 12)
choropleth(sp = whp_sp,v="Avg_HP_avg",shading=shades)
choro.legend(548871.4, 3377000,  shades,title='Average house price')

choropleth

Description

Draws a choropleth map given a spatialPolygons object, a variable and a shading scheme.

Usage

choropleth(sp, v, shading, ...)

Arguments

sp

A SpatialPolygonsDataFrame or sf -POLYGON or - MULTIPOLYGON object.

v

The variable name to be mapped and must included in the data.

shading

A shading scheme created by shading or auto.shading.

...

Additional parameters to be passed on to the plot method for sp.

Details

The function returns no value, but draws a choropleth map on the current graphics device as a side effect.

Value

None (see above).

Author(s)

Chris Brunsdon, Binbin Lu

See Also

choro.legend, auto.shading, shading.

Examples

# Read in map data and compute a rate for mapping
# Try the sf class
data(WHData)
shades = auto.shading(WHHP[["Avg_HP_avg"]],n=7)
dev.new(width = 16, height = 12)
choropleth(sp = WHHP,v="Avg_HP_avg",shading=shades)
choro.legend(548871.4, 3377000, shades,title='Average house price')
#Try the Spatial object
shades = auto.shading(whp_sp@data[["Avg_HP_avg"]],n=6)
dev.new(width = 16, height = 12)
choropleth(sp = whp_sp,v="Avg_HP_avg",shading=shades)
choro.legend(548871.4, 3377000,  shades,title='Average house price')

Cut functions

Description

Helper functions for auto.shading. Given a variable to be mapped, a number of classes and possibly some more params, returns a list of break values. There should be one less break value than the number of classes.

Usage

quantileCuts(x, n = 5, params = NA)
sdCuts(x, n = 5, params = NA)
rangeCuts(x, n = 5, params = NA)

Arguments

x

The variable to be mapped.

n

The number of classes.

params

Extra params for individual cut functions.

Value

An ordered list of the break values between classes

Note

The only cut function using params is quantileCuts, where it is used to specify a list of quantile values - useful if they are not evenly spaced.

Author(s)

Chris Brunsdon

See Also

auto.shading

generalize.polys

Description

Generalises a SpatialPolygons or SpatialPolygonsDataFrame or a sf -POLYGON or - MULTIPOLYGON object using the Douglas-Peuker algorithm

Usage

generalize.polys(sfo, preserveTopology, dTolerance)

Arguments

sfo

A SpatialPolygons or SpatialPolygonsDataFrame or a sf -POLYGON or - MULTIPOLYGON object.

preserveTopology

logical; carry out topology preserving simplification? May be specified for each, or for all feature geometries. Note that topology is preserved only for single feature geometries, not for sets of them.

dTolerance

numeric; tolerance parameter, specified for all or for each feature geometry.

Details

Returns an object of the same class as sp. Note that the algorithm is applied on a polygon-by-polygon, not edge-by-edge basis. Thus edges in generalised polygons may not match perfectly.

Value

An object of class SpatialPolygons or SpatialPolygonsDataFrame. Each polygon shape has been generalized using the Douglas-Peuker algorithm.

Author(s)

Chris Brunsdon, Binbin Lu

Examples

# Data for Georgia to use in example

data(WHData)
WH.outline <- st_union(WHHP)
WH.generalised <- generalize.polys(WH.outline,TRUE,0.1)
plot(st_geometry(WHHP))
plot(st_geometry(WH.generalised),add=TRUE,border='red',lwd=2)

Georgia Social and Economic Data by County

Description

Polygon Data Frame as used in the Brunsdon, Fotheringham & Charlton GWR book, with further variable median income (MedInc)

Usage

 data(georgia)

Format

Examples

# Read in the data
data(georgia)
# Make a map of median income
choropleth(georgia2,"MedInc")

Level plot for gridded data

Description

Draws a level plot given a SpatialPixelsDataFrame, an index and a shading scheme.

Usage

level.plot(grd, shades, index=1, add=FALSE)

Arguments

grd

A spatialPixelsDataFrame object.

shades

A shading scheme created by shading or auto.shading. If omitted, chosen automatically from grd.

index

Index giving the variable in grd to plot.

add

Whether to add the level plot to an existing plot.

Details

The function returns no value, but draws a level plot on the current graphics device as a side effect.

Value

None (see above).

Author(s)

Chris Brunsdon, Binbin Lu

Examples

  
# Data for New Haven to use in example
data(newhaven)
# Do the KDE
breach.dens = kde.points(breach,lims=tracts)
# Plot the result
level.plot(breach.dens)

map.scale

Description

Draws a scale bar on a map.

Usage

map.scale(xc,yc,len,units,ndivs,subdiv=1,tcol='black',scol='black',sfcol='black')

Arguments

xc

The x-centre (in map units) of the scale bar

yc

The y-centre (in map units) of the scale bar

len

The length (in map units) of the scale bar

units

String specifying the name of the units for the scale bar

ndivs

The number of divisions (units marked) on the scale

subdiv

The fraction of units used to step along the divisions

tcol

The colour of text on the scale bar.

scol

The colour of the scale bar itself.

sfcol

The colour of the filled rectangles in the scale bar.

Details

Draws an alternating bar scale on a map. Returns no value.

Value

None (see above)

Author(s)

Chris Brunsdon

See Also

choro.legend

Examples

# Read in map data for New Haven
data(newhaven)
# Plot census block boundaries
plot(blocks)
# Add a map scale
map.scale(534750,152000,miles2ft(2),"Miles",4,0.5,sfcol='red')
# ... and a title
title('New Haven (CT)')

New Haven, Connecticut: Crime data with contextual information

Description

Data set from New Haven (CT) crime web site containing point sources of some crimes, plus roads, railways and census block spatial data frames.

Usage

data(newhaven)

Format

Source

http://www.newhavencrimelog.org/

Examples

# Read in map data for New Haven
data(newhaven)
# Plot census block boundaries
plot(blocks)
# Add a map scale
map.scale(534750,152000,miles2ft(2),"Miles",4,0.5,sfcol='red')
# ... and a title
title('New Haven (CT)')

Phenology data for North American lilacs

Description

Data set from Schwartz, M.D. and J.M. Caprio, 2003, North American First Leaf and First Bloom Lilac Phenology Data, IGBP PAGES/World Data Center for Paleoclimatology Data Contribution Series # 2003-078. NOAA/NGDC Paleoclimatology Program, Boulder CO, USA.

Usage

 data(phenology)

Format

Source

http://www.ncdc.noaa.gov/paleo/phenology.html

Examples

# Read in the data
data(phenology)
# Split the plot in two
opar <- par(mfrow=c(2,1))
# Plot US states
plot(us_states2)
# Add Locations of observation stations
plot(chinensis2,add=TRUE,pch=16,col='red')
# Plot a histogram of year of observation next to this
hist(chinensis2$Year)
par(opar)

Shading

Description

Creates an object of class shading by directly specifying break values and (optionally) colours.

Usage

shading(breaks, cols = brewer.pal(length(breaks), "Reds"))

Arguments

breaks

The break points

cols

The shading colours - there should be one more of these than break points.

Value

An object of class shading.

Warning

At the moment, the it is assumed that the number of shading colours is one more than the break points, but this is not checked.

Author(s)

Chris Brunsdon

See Also

choropleth,choro.legend

thematic.map

Description

Draw thematic maps together with histograms with a Spatial or sf object, background layers according to variables and shading schemes.

Usage

thematic.map(data, var.names, colorStyle = NULL, na.pos = "bottomright", bglyrs, bgStyle,
                         scaleBar.pos = "bottomright", mtitle = NULL, htitle = NULL,
                         legend = "Legend", legend.pos = "topright", cuts = 5, 
                         cutter = quantileCuts, horiz = FALSE, digits=2,...)

Arguments

data

A Spatial or sf object.

var.names

A vector of variable names to be mapped

colorStyle

A vector of colors (including "red", "blue" and "green") or a color function, e.g. rainbow, heat.colors, hcl.colors, terrain.colors and colors

na.pos

A 2-D coordinate or character to define the position of north arrow, i.e. "topright", "topleft", "bottomright", "bottomleft"

bglyrs

A list of background layers of "Spatial" or "sf" objects

bgStyle

A list of parameters for define the styles of background layers, e.g. list(col="grey", cex=1, lwd=1, pch=16, lty=1)

scaleBar.pos

A 2-D coordinate or character to define the position of scale bar, i.e. "topright", "topleft", "bottomright", "bottomleft"

mtitle

Title of each map

htitle

Title of each histogram

legend

Title of each legend for each map

legend.pos

A 2-D coordinate or character to define the position of legend, i.e. "topright", "topleft", "bottomright", "bottomleft"

cuts

The number of classes.

cutter

Function used to create the break points. Can be user defined or a supplied cut function.

horiz

logical; if TRUE, set the legend horizontally rather than vertically

digits

Number of digits kept for legend

...

Arguments to be passed to methods

Details

The function returns no value, but draws thematic maps together with histograms on the current graphics device as a side effect.

Value

None (see above).

Author(s)

Binbin Lu

See Also

choropleth, choro.legend, auto.shading, shading.

Examples

data(newhaven)
# Single map
thematic.map(blocks, var.names="POP1990", horiz = FALSE, na.pos = "topleft", 
            scaleBar.pos = "bottomright", legend.pos = "bottomleft",
            colorStyle = "red")

#Multiple maps and different colors
thematic.map(blocks, var.names=c("P_35_44","P_25_34", "POP1990"), 
horiz =FALSE, na.pos = "topleft", scaleBar.pos = "bottomright", 

legend.pos = "bottomleft",colorStyle =hcl.colors)
thematic.map(blocks, var.names=c("P_35_44","P_25_34", "POP1990"), 

horiz =FALSE, na.pos = "topleft", scaleBar.pos = "bottomright",
 legend.pos = "bottomleft", colorStyle =c("red", "blue", "na"))
# Use coordinate to define the legend
data(WHData)
thematic.map(whp_sp, var.names="Avg_Green_", colorStyle ="red",
             na.pos = "topleft", scaleBar.pos = "bottomleft", 
             legend.pos = c(544000, 3380000),cuts=7, 
             cutter=rangeCuts)
thematic.map(WHHP, var.names=c("Avg_HP_avg", "Avg_Green_"), colorStyle =c("red", "blue"),
             na.pos = "topleft", scaleBar.pos = "bottomleft", 
             legend.pos = c(544000, 3380000),cuts=7, 
             cutter=rangeCuts)

US Tornado Touchdown Data

Description

Data set from NOAA's National Weather Service Indianapolis, IN Weather Forecast Office 6900 W. Hanna Ave.

Usage

 
data(tornados)

Format

Source

http://www.crh.noaa.gov/ind/?n=svrgis

Examples

# Read in the data
data(tornados)
# Split the plot in two
opar <- par(mfrow=c(2,1))
# Plot US states
plot(us_states)
# Add Locations of observation stations
plot(torn,add=TRUE,pch=16,col='red')
# Plot a histogram of year of observation next to this
hist(torn$YEAR)
par(opar)

Phenology data for North American lilacs

Description

Data set from Schwartz, M.D. and J.M. Caprio, 2003, North American First Leaf and First Bloom Lilac Phenology Data, IGBP PAGES/World Data Center for Paleoclimatology Data Contribution Series # 2003-078. NOAA/NGDC Paleoclimatology Program, Boulder CO, USA.

Usage

 data(vulgaris)

Format

Source

http://www.ncdc.noaa.gov/paleo/phenology.html

Examples

# Read in the data
data(vulgaris)
# Split the plot in two
opar <- par(mfrow=c(2,1))
# Plot US states
plot(us_states)
# Add Locations of observation stations
plot(vulgaris,add=TRUE,pch=16,col='red')
# Plot a histogram of year of observation next to this
hist(vulgaris$Year)
par(opar)