| Type: | Package |
| Title: | Spatial Temporal Analysis of Moving Polygons |
| Version: | 0.3.1 |
| Description: | Perform spatial temporal analysis of moving polygons; a longstanding analysis problem in Geographic Information Systems. Facilitates directional analysis, distance analysis, and some other simple functionality for examining spatial-temporal patterns of moving polygons. |
| URL: | https://github.com/jedalong/stampr |
| Depends: | R (≥ 4.0) |
| License: | GPL-3 |
| Imports: | sf, spdep, dplyr, graphics, grDevices, rlang, lwgeom,geosphere |
| RoxygenNote: | 7.2.3 |
| Encoding: | UTF-8 |
| NeedsCompilation: | no |
| Packaged: | 2024-01-09 16:19:51 UTC; jlong83 |
| Author: | Jed Long [aut, cre], Colin Robertson [aut] |
| Maintainer: | Jed Long <jed.long@uwo.ca> |
| Repository: | CRAN |
| Date/Publication: | 2024-01-09 17:10:02 UTC |
stampr: Spatial Temporal Analysis of Moving Polygons
Description
The Packagestampr provides tools for performing spatial temporal analysis of moving polygons.These tools allow the calculation of directional relationships, distance relations, and other basicfunctionality, such as global change metrics. More details about each of these functionscan be found in its help documentation.
Details
stampr's functions utilize thesf objects (as of version 0.3.0) from the packagesf. Polygon relationships are still understudied in the field of geographic information science, but hopefullystampr can provide users with aplatform for new developments and applied research looking at interesting geographical phenomena.
Author(s)
Jed Long and Colin Robertson
References
Robertson, C., Nelson, T., Boots, B., and Wulder, M. (2007) STAMP: Spatial-temporal analysis of moving polygonsJournal of Geographical Systems, 9:207-227.Long, J., Robertson, C., Nelson, T. (2018) stampr: Spatial-Temporal Analysis of Moving Polygons in RJournal of Statistical Software. Code Snippets, 84(1), 1–19.
Hurricane Katrina eye point dataset
Description
A dataset containing points representing the eye of Hurricane Katrina centroid from 21:00 26-AUG-2005 to 21:00 29-AUG-2005. Polygon contours were extracted from the US NOAA H*Wind product, downloadable from:https://www.aoml.noaa.gov/hrd/data_sub/wind.html
Format
Asf object with 33 records of the eye location of Hurricane Katrina, every 3 hrs, from 21:00 25-AUG-2005 to 21:00 29-AUG-2005. The date and time of each polygon is recorded in thecolumnDateTime.
Details
Theeyeshp dataset contains points that were derived from the raw NOAA H*Wind data. The data is included hereto provide a point-data comparison to the data in thekatrina dataset which is polygon data
Examples
data(eyeshp)plot(eyeshp)Forest Fire dataset
Description
A dataset containing fake forest fire polygons representing the movement of the forest fire from T1 (fire1) to T2 (fire2). The data is provided purely for demonstration purposes.
Format
fire1 — asf object with polygons representing the location of forest fire.
Source
Simulated data
Examples
data(fire1)plot(fire1)data(fire2)plot(fire2)## Not run: library(mapview)mapview(fire1) + mapview(fire2)## End(Not run)Forest Fire dataset
Description
see fire1
Format
fire2 — asf object
glob.change
Description
The functionglob.change computes a set of three global change metrics for comparisonbetween two polygon sets. These metrics are outlined in Robertson et al. (2007; Table 4).
Usage
glob.change(T1, T2)Arguments
T1 | a |
T2 | a |
Details
glob.change computes three change metrics, detailed below, that can be used to quantify changesbetween two polygon sets:NumRatio – ratio between the number of polygons inT2 andT1;
\mathtt{NumRatio} = \frac{\#(T1)}{\#(T2)}
AreaRatio – ratio between the areas of polygons in T2 and T1;
\mathtt{AreaRatio} = \frac{A(T2)}{A(T1)}
AvgAreaRatio – ratio between theAreaRatio andNumRatio;
\mathtt{AvgAreaRatio} = \frac{\mathtt{AreaRatio}}{\mathtt{NumRatio}} = \frac{\frac{A(T2)}{A(T1)}}{\frac{\#(T1)}{\#(T2)}}
Value
Alist object with three elements - Results for theNumRatio,AreaRatio, andAvgAreaRatio metrics.
Hurricane Katrina polygons dataset
Description
A dataset containing polygons representing the movement of Hurricane Katrina from 21:00 26-AUG-2005 to 21:00 29-AUG-2005. Polygon contours were extracted from the US NOAA H*Wind product, downloadable from:https://www.aoml.noaa.gov/hrd/data_sub/wind.html
Format
Asf object with 33 records of of the location of Hurricane Katrina, every 3 hrs, from 21:00 25-AUG-2005 to 21:00 29-AUG-2005. The date and time of each polygon is recorded in thecolumnDateTime.
Details
Thekatrina dataset contains polygons that were derived from the raw NOAA H*Wind data. The 39 mph isotach(contour of equal wind speed) was used to delineate, as a spatial polygon, the extent of Hurricane Katrina at a given time. Polygons were derived at 3 hr intervals; which means there are 33 different time points inthe dataset.
Source
https://www.aoml.noaa.gov/hrd/data_sub/wind.html
References
Powell, M.D., Murillo, S., Dodge, P., Uhlhorn, E., Gamache, J., Cardone, V., Cox, A., Otero, S., Carrasco, N., Annane, B., St. Fleur, R. (2010) Reconstruction of Hurricane Katrina's wind fields for storm surge and wave hindcasting.Ocean Engineering, 37, 26-36.
Powell, M.D., Houston, S.H. (1998) The HMD real-time hurricane wind analysis system.Journal of WindEngineering and Industrial Aerodynamics, 77/78, 53-64.
Examples
data(katrina)plot(katrina['Id'])MPB dataset
Description
A dataset containing polygons representing the location of mountain pine beetle hotspot polygons in Morice Forest District, British Columbia, Canada.
Format
mpb — asf object with 711 mountain pine beetle hotspot polygons that occurred over eight years. The temporal indicator is theTGROUP column. Another variableREGION indicates whether the hotspot was in the northern or southern regions, which experienced mostly independent outbreaks.
Details
These data were derived from helicopter-based GPS surveys during early years of large mountain pine beetle outbreak in Western Canada.
Source
Data obtained from Trisalyn Nelson (ASU)
References
Nelson TA, Boots B, Wulder MA, Carroll AL. Environmental characteristics of mountain pine beetle infestation hot spots.Journal of Ecosystems and Management. 2007 Mar 14;8(1).
Examples
data(mpb)plot(mpb['TGROUP'])Spatial temporal analysis of moving polygons
Description
This function generates asf polygons object that can be used for spatial temporal analysis of moving polygonsas described in the paper Robertson et al. (2007).
Usage
stamp(T1, T2, dc = 0, direction = FALSE, distance = FALSE, ...)Arguments
T1 | a |
T2 | a |
dc | spatial distance threshold for determining groupings (seeDetails) in appropriate units. |
direction | logical, whether or not to perform directional analysis. See documentation for |
distance | logical, whether or not to perform distance analysis. See documentation for |
... | additional parameters to be passed to functions if |
Details
Thestamp function can be used to perform spatial temporal analysis of moving polygons (STAMP)as outlined in the paper by Robertson et al., (2007). Polygon movement "groups" are delineated based onpolygon connectedness defined by the distance thresholddc. That is, if polygonboundaries (in T1 or T2) are within distancedc of one another they will be designatedto the same group. STAMP events are reported at four levels of increasing complexity:
LEV1 – disappearance (DISA), stable (STBL), and generation (GENA);
LEV2 – disappearance (DISA), contraction (CONT), stable (STBL),expansion (EXPN), and generation (GENR);
LEV3 – disappearance (DISA), T1 displacement (DISP1), convergence (CONV),concentration (CONC), contraction (CONT), stable (STBL),expansion (EXP), fragmentation (FRAG), divergence (DIV),T2 displacement (DISP2), and generation (GENR);
LEV4 – LEV4 is different from other levels. It is used to identify those groups whereunion (UNION), division (DIVISION), and both union and division(BOTH) events occur. These events occur when there are more than onestable event in a group. Groups with one or no stable events receive anNAvalue for LEV4.
See Robertson et al. (2007; especially Figure 1) for complete descriptions of all STAMP movementevent types.
Note also that there must be a unique ID of each polygon, the function uses the row.names of the polygon objects. Modify the row.names accordingly if you wish to use an alternative ID label.
Value
This function returns asf polygons object with the following data columns:
ID1 | Polygon ID from T1 polygons; |
ID2 | Polygon ID from T2 polygons; |
LEV1 | Level 1 STAMP designation, |
LEV2 | Level 2 STAMP designation, |
LEV3 | Level 3 STAMP designation, |
LEV4 | Level 4 STAMP designation, |
GROUP | Group ID signifying group membership, |
AREA | Polygon area in appropriate areal units, |
-- | (optional) Additional columns from directional analysis if |
-- | (optional) Additional columns from distance analysis if |
References
Robertson, C., Nelson, T., Boots, B., and Wulder, M. (2007) STAMP: Spatial-temporal analysis of moving polygons.Journal of Geographical Systems, 9:207-227.
See Also
stamp.direction stamp.distance stamp.map stamp.group.summary
Perform polygon directional analysis
Description
stamp.direction facilitates polygon directional analysis using a variety of methods.
Usage
stamp.direction(stmp, dir.mode = "CentroidAngle", ndir = 4, group = FALSE)Arguments
stmp | a |
dir.mode | a character item identifying which directional relations method is to be used. SeeDetailsfor information on each individual method. |
ndir | (optional) parameter identifying the number of directions to be computed. See individual methodDetails for appropriate usage. |
group | (optional) a logical value identifying whether direction should be computed on groups or individualevent polygons (only used with |
Details
Thestamp.direction function can be used to facilitate directional analysis on outputstamp.obj objects from functionstamp. Currently, four directional analysis methodsare available:
"CentroidAngle"– The centroid angle is simply the angle between the centroids of two polygons.The centroid angle method is computed on STAMP objects by first grouping all T1 polygons (by STAMP group)and computing their centroid. Then, the angle from each T1 group centroid, to the centroid of each STAMP eventwithin the group is calculated. Centroid angles are recorded in degrees, with North having a value of 0, East90, and so on."CentroidAngle"ignores thendirparameter."ConeModel"– The cone model method calculates areas of STAMP event polygons within cones radiating fromthe centroid of the origin polygon. The cone model method first computes the centroid of all T1 polygons in a STAMP grouping. It thencomputesndirequally spaced cones radiating outward from the T1 centroid. The first cone is alwayscentered on North, but there can be any number of cones. The area of each STAMP event, in each cone (specifying direction),is then calculated. See Peuquet and Zhang (1987) for more detailed information"MBRModel"– The minimum bounding rectangle (MBR) method first computes the MBR for all T1 eventsin a STAMP grouping. Then the lines of four edges of the MBR are extended outwards to infinity creatingsections for the eight cardinal directions around the MBR, along with the MBR itself. The areaof each stamp event within each of the nine sections is then computed. See Skiadopoulos et al. (2005) formore detailed information."MBRModel"ignores thendirparameter."ModConeModel"– The modified cone model first computes the centroid of the T1 events.Thenndir = 4 or 8cones are created outward from this centroid to the minimum bounding rectangleof the entire grouping. As described by Robertson et al. (2007) this approach is more accommodatingto polygon groups that are irregular in size or shape. The modified cone model method first computes the centroid of all T1 polygons in a STAMP grouping.It then computes the bounding box of ALL events in a STAMP grouping. Then,ndir=4or8cones are computed. In the case ofndir=4, cones radiate from the T1 centroid to the fourcorners of the bounding box. The result of the modified cone model method is that the conesare not equally spaced, but tailored to the individual STAMP groupings shape. See Robertson et al.(2007) for more detailed information. NOTE: This function has been altered slightly as of stampr v 0.3.
As of V 0.3 all operations are conducted using sf object classes, all directional (azimuth) and area calculations use WGS84.
Value
Appends the inputstamp object with appropriate columns for the directional analysis chosen, ifdir.mode is:
"CentroidAngle" | A single column with centroid angle results, in degrees (North = 0 degrees). If |
"ConeModel" |
|
"MBRModel" | 9 new columns with the area (m2) of the STAMP event in each direction,named appropriately as, for example, "MBR_SW","MBR_S",... etc. |
"ModConeModel" |
|
Note: STAMP events that are singular (i.e., only 1 polygon in the group)will haveNA's from directional analysis.
References
Robertson, C., Nelson, T., Boots, B., and Wulder, M. (2007) STAMP: Spatial-temporal analysis of moving polygons.Journal of Geographical Systems, 9:207-227.
Peuquet, D., Zhang, C.X. (1987) An algorithm to determine the directional relationship between arbitrarily-shapedpolygons in the plane.Pattern Recognition, 20:65-74.
Skiadopoulos, S. Giannoukos, C., Sarkas, N., Vassiliadis, P., Sellis, T., and Koubarakis, M. (2005) Computing andmanaging directional relations.IEEE Transactions on Knowledge and Data Engineering, 17:1610-1623.
See Also
stamp stamp.distance
stamp.distance
Description
The functionstamp.distance can be used to compute various measures of distance between polygon events and groups. In turn, distance measurements can be used to estimate the velocityof polygon movement.
Usage
stamp.distance(stmp, dist.mode = "Centroid", group = FALSE)Arguments
stmp | a |
dist.mode | Character determining the method by which polygon distances are computed. If |
group | logical indicating whether distances should be computed from the T1 polygon to each individual stamp event ( |
Details
stamp.distance computes distance between polygon sets based on either centroid orHausdorff distance calculations. Centroid distance is simply the distance from the centroidof all T1 polygons (combined) to each stamp event (group = FALSE), or to the union ofall T2 polygons within a group (group = TRUE), in the second case, all events within a groupare given an identical distance value.
The Hausdorff distance calculation uses the Hausdorff distance, asprogrammed in the functionst_distance. A value ofpar = 0.1 is usedto increase the precision of this measurement – seehelp(st_distance). The returned distanceis then the Hausdorff distance of all T1 polygons (combined) to each stamp event (group = FALSE),or to the union of all T2 polygons within a group (group = TRUE), in the second case, all events within a group are given an identical distance value.All distance calculations are computed in meters using the geographical projection WGS84.
Value
Appropriately named columns (e.g.,CENDIST orHAUSDIST) in the stampsfobject. Distances are in meters.
References
Hausdorff Distance:https://en.wikipedia.org/wiki/Hausdorff_distance
See Also
stamp stamp.direction
Compile stamp summary statistics by group
Description
The functionstamp.group.summary compiles summary statistics for each STAMP grouping.Specifically, it computes the area of each STAMP event type (e.g., generation, expansion, etc.)within each grouping. It also computes the number of events belonging to each event type.
Usage
stamp.group.summary(stmp, area = TRUE, count = TRUE)Arguments
stmp | a |
area | logical, whether or not to compute the STAMP event areas. |
count | logical, whether or not to compute the count of STAMP events within each group. |
Details
stamp.group.summary computes area and count summary statistics of STAMP output. Note that ifbotharea andcount are set toFALSE,stamp.group.summary returns adata.frame with just the group IDs as the only column.
Value
Adata.frame where rows are stamp groups and columns correspond to the STAMP event types (ID, areas, and counts).
Mapping (plotting) functionality forstamp output
Description
This function maps STAMP output for visual assessment of STAMP events and groupings.Choice of which aspect of the stamp output to be visualized is controlled by passingthe column name to thestamp.map function.
Usage
stamp.map(stmp, by = "LEV1", ...)Arguments
stmp | output from the |
by | tells the function which attribute to visualize, one of |
... | additional parameters to be passed to the sf plot function |
Details
Thestamp.map function can be used to visualize any of the stamp event designation levels(e.g.,"LEV1","LEV2","LEV3","LEV4", or the STAMP groupings(based off of parameterdc in thestamp function).
Value
stamp.map returns a map of thestamp output using theplot.sf functionality. It implements a pre-defined coloring scheme.
See Also
stampdata("fire1")data("fire2")ch <- stamp(fire1, fire2, dc=1, direction=FALSE, distance=FALSE)stamp.map(ch, "LEV1") stamp.map(ch, "LEV2") stamp.map(ch, "LEV3") stamp.map(ch, "LEV4")
run stamp function for multiple years of polygons at once
Description
The functionstamp.multichange is a wrapper function that makes multiple calls to the stamp function to ease spatial-temporal analysis of multiple years of polygon data
Usage
stamp.multichange(polys, changeByRow = TRUE, changeField = "", ...)Arguments
polys | a |
changeByRow | logical, whether or not each time period is a separate unique row of data (e.g., as per the |
changeField | string, name of the field which contains time period if changeByRow is FALSE |
... | list of paramater values to provide to the |
Details
stamp.multichange is a simple wrapper function for thestamp function. The two options for data structureare those in thekatrina data, where each time period is a row, and rows are time-ordered, and the structure of thempb data, where time period is specified by a column. Time periods should be ordered from 1 through T.
Value
Asf object which includes all outputs from the calls to thestamp function. If there are T time periods,there will be T-1 time periods in the resultingsf object.
See Also
stamp.stgroup.summary
Examples
## Not run: ## NOT RUN ##data("katrina")ch <- stamp.multichange(katrina, changeByRow = TRUE, dc = 0, distance = TRUE, direction = FALSE)STGroup <- stamp.stgroup.summary(ch)head(STGroup)## End(Not run)Compile stamp summary statistics by space-time group
Description
The functionstamp.stgroup.summary compiles summary statistics for each STAMP space-time grouping.Specifically, it computes the area of each STAMP event type (e.g., generation, expansion, etc.)within each grouping. It also computes the number of events belonging to each event type.
Usage
stamp.stgroup.summary(stmp, area = TRUE, count = TRUE)Arguments
stmp | a |
area | logical, whether or not to compute the STAMP event areas. |
count | logical, whether or not to compute the count of STAMP events within each group. |
Details
stamp.stgroup.summary computes area and count summary statistics of STAMP output derived from multi-time analysis using stamp.multichange.stamp.multichange is just a wrapper function for applying stamp to multiple time periods in the same dataset. Note that ifbotharea andcount are set toFALSE,stamp.stgroup.summary returns adata.frame with just the stgroup IDs as the only column.
Value
Adata.frame where rows are stamp groups and columns correspond to the STAMP event types (ID, areas, and counts).
See Also
stamp.multichange
Examples
## Not run: ##NOT RUN##library(sf)data("katrina")ch <- stamp.multichange(katrina, changeByRow = TRUE, dc = 0, distance = TRUE, direction = FALSE)STGroup <- stamp.stgroup.summary(ch)head(STGroup)## End(Not run)