Package 'aoristic'

Title: Generates Aoristic Probability Distributions
Description: It can sometimes be difficult to ascertain when some events (such as property crime) occur because the victim is not present when the crime happens. As a result, police databases often record a 'start' (or 'from') date and time, and an 'end' (or 'to') date and time. The time span between these date/times can be minutes, hours, or sometimes days, hence the term 'Aoristic'. Aoristic is one of the past tenses in Greek and represents an uncertain occurrence in time. For events with a location describes with either a latitude/longitude, or X,Y coordinate pair, and a start and end date/time, this package generates an aoristic data frame with aoristic weighted probability values for each hour of the week, for each observation. The coordinates are not necessary for the program to calculate aoristic weights; however, they are part of this package because a spatial component has been integral to aoristic analysis from the start. Dummy coordinates can be introduced if the user only has temporal data. Outputs include an aoristic data frame, as well as summary graphs and displays. For more information see: Ratcliffe, JH (2002) Aoristic signatures and the temporal analysis of high volume crime patterns, Journal of Quantitative Criminology. 18 (1): 23-43. Note: This package replaces an original 'aoristic' package (version 0.6) by George Kikuchi that has been discontinued with his permission.
Authors: Jerry Ratcliffe
Maintainer: Jerry Ratcliffe <[email protected]>
License: GPL-3
Version: 1.1.1
Built: 2025-03-08 03:31:04 UTC
Source: https://github.com/jerryratcliffe/aoristic

Help Index

Check aoristic input data

Description

A function that flags datetime errors with aoristic input data.

Usage

aoristic.datacheck(data1, Xcoord, Ycoord, DateTimeFrom, DateTimeTo)

Arguments

data1

data.frame with a minimum of 4 columns with X, Y coords, Start and End date/time
Xcoord

a vector of the X coordinate or latitude (numeric object)
Ycoord

a vector of the Y coordinate or longitude (numeric object)
DateTimeFrom

a vector of the column name for FromDateTime (POSIXct date-time object)
DateTimeTo

a vector of the column name for ToDateTime (POSIXct date-time object)

Details

The aoristic.df function handles data with Start (or From) and End (or To) datetime objects. Sometimes these data can be messy or inaccurately recorded (such as crime data from some police departments). This function checks for common problems and reports the result in a column labeled 'aoristic_datacheck'.

Rows with missing 'End' information are flagged with '1' and counted in the console. Rows where the 'End' datetime occurs before the 'Start' datetime are flagged '2'.

Note that aoristic.df() will still run even with the data issues. Where the 'End' datetime is missing, the aoristic value will be assigned to the 'Start' datetime hour. When the 'End' datetime comes before the 'Start' datetime, the 'Start' datetime is only used and again, the aoristic value is assigned to the 'Start' datetime hour.

Value

A data frame flagging any problems or logical errors from an aoristic data check

References

Ratcliffe, J. H. (2002). Aoristic signatures and the spatio-temporal analysis of high volume crime patterns. Journal of Quantitative Criminology, 18(1), 23-43.

Examples

datacheck.df <- aoristic.datacheck(dcburglaries, 'X', 'Y', 'StartDateTime', 'EndDateTime')

Calculate aoristic weights

Description

Calculates aoristic proportional weights across 168 units representing each hour of the week (24 hours x 7 days). It is designed for situations when an event time is not know but could be spread across numerous hours or days, and is represented by a Start (or From) date and time, and an End (or To) date and time. The output retains the source data, and can be reimported into a GIS for spatial analysis. The output from this function is used in other aoristic library functions.

Usage

aoristic.df(data1, Xcoord, Ycoord, DateTimeFrom, DateTimeTo)

Arguments

data1

data frame with a minimum of 4 columns with X, Y coords, Start and End date/time
Xcoord

a vector of the event X coordinate or latitude (numeric object)
Ycoord

a vector of the event Y coordinate or longitude (numeric object)
DateTimeFrom

a vector of the column name for FromDateTime (POSIXct date-time object)
DateTimeTo

a vector of the column name for ToDateTime (POSIXct date-time object)

Details

NOTE: If an observation is missing the End/To datetime, the entire aoristic weight (1.0) will be assigned to the hour block containing the Start/From datetime. Events with start datetime events after the end datetime will also be assigned to the hour block containing the Start/From datetime. Events with time spans lasting more than one week (>168 hours) will default to a time span of 168 hours and a value of ~ 0.0059 (1/168) assigned to each day/hour.

Value

A data frame with aoristic values for each hour of the week for each observation

References

Ratcliffe, J. H. (2002). Aoristic signatures and the spatio-temporal analysis of high volume crime patterns. Journal of Quantitative Criminology, 18(1), 23-43.

Examples

df <- aoristic.df(dcburglaries, 'X', 'Y', 'StartDateTime', 'EndDateTime')

Create aoristic distribution chart

Description

Takes the output from the aoristic.summary() function and converts that data frame into a series of eight charts for each day of the week (and a total chart) based on the aggregate aoristic distribution of the events. Option (marks = TRUE) adds small tick marks showing the (y-axis adjusted) overall weekly distribution for comparison to the daily value.

Usage

aoristic.graph(data1, marks = FALSE)

Arguments

data1

a data frame output from the aoristic2.df function
marks

marks=FALSE. TRUE shows tick marks for week distribution. Default is FALSE.

References

Ratcliffe, J. H. (2002). Aoristic signatures and the spatio-temporal analysis of high volume crime patterns. Journal of Quantitative Criminology, 18(1), 23-43.

Examples

aoristic.graph(dcburgsum)
aoristic.graph(dcburgsum, TRUE)

Plot aoristic probabilities for one hour

Description

Creates a plot showing aoristic probability values for one hour of the week. The X, Y coordinate pair (or latitude and longitude) are used to create a plot that shows each event that could have occured in the user- selected hour. Each event is color coded to represent the aoristic weight, range >0 to 1. Events with weight 1 definitely occurred during that hour, while events with values at the lower end of the range could have occured at one of many hours. For guidance on which day/hour is represented by a number, use aoristic.ref()

Usage

aoristic.map(data1, AorHour = "1")

Arguments

data1

a data frame output from the aoristic.df function
AorHour

user-selected number for an hour in the week (range 1-168)

Value

A ggplot object

References

Ratcliffe, J. H. (2002). Aoristic signatures and the spatio-temporal analysis of high volume crime patterns. Journal of Quantitative Criminology, 18(1), 23-43.

Examples

## Not run: 

aor.plot <- aoristic.map(aor.df, 25)

## End(Not run)

Summarize weekly aoristic weights

Description

Summarizes the sum of aoristic weights for each hour of the week, based on output from an aoristic data frame (created by aoristic.df). This function returns a ggplot object.

NOTE: Be aware that the distribution of values is NOT the same as the aoristic.ref() output, because the summary charts and graphs move Sunday to the end of the week to keep the weekend together.

Usage

aoristic.plot(data1)

Arguments

data1

a data frame output from the aoristic.df function

Value

ggplot object

References

Ratcliffe, J. H. (2002). Aoristic signatures and the spatio-temporal analysis of high volume crime patterns. Journal of Quantitative Criminology, 18(1), 23-43.

Examples

## Not run: 
aoristic.plot(aor.df)  
p <- aoristic.plot(aor.df)

## End(Not run)

Hour of the week reference chart

Description

Creates and views a simple data frame with reference hour of the week. This is a reference for the aoristic.map function that requires a user-selected hour in order to map spatial distribution for the requested one hour time period.

Usage

aoristic.ref()

Details

NOTE: The jpg from aoristic.summary does not use the same day/hour layout. Sunday is moved to the end of the layout to make the weekend period clearer to the user.

Value

A data frame

References

Ratcliffe, J. H. (2002). Aoristic signatures and the spatio-temporal analysis of high volume crime patterns. Journal of Quantitative Criminology, 18(1), 23-43.

Summarize weekly aoristic weights

Description

Summarizes the sum of aoristic weights for each hour of the week, based on output from an aoristic data frame (created by aoristic.df). The function returns a data frame, with optional outputs. Option 'xlsx' sends the data frame to an Excel spreadsheet in the current working directory. Filenames increment to prevent overwriting previous analyses. Using option 'jpg' creates a color coded summary table in jpg format in the working directory. The filename is aoristic_distribution.jpg, adding incremental numbers as necessary to the filename.

NOTE: Be aware that the distribution of values is NOT the same as the aoristic.ref() output, because the summary charts and graphs move Sunday to the end of the week to keep the weekend together.

Usage

aoristic.summary(data1, output = "")

Arguments

data1

a data frame output from the aoristic.df function
output

output ='xlsx' for an Excel format output #' output ='jpg' for JPG grid, blank otherwise

Value

A data frame with aoristic values summed for each hour of the week

References

Ratcliffe, J. H. (2002). Aoristic signatures and the spatio-temporal analysis of high volume crime patterns. Journal of Quantitative Criminology, 18(1), 23-43.

Examples

## Not run: 

aor.summary <- aoristic.summary(aor.df)
aor.summary <- aoristic.summary(aor.df, 'xlsx')
aor.summary <- aoristic.summary(aor.df, 'jpg')

## End(Not run)

Burglaries, Washington DC, first six months of 2016

Description

A dataset containing the X and Y coordinates of burglaries, with the start and end date and times of the crimes. Sourced from Open Data Washington DC with start date in the first six months 2016. X, Y geometry for Washington DC is from FIPS 1900 (crs 7058).

Usage

dcburglaries

Format

A data frame with 1025 rows and 4 variables:

X

X coordinate of burglary location

Y

Y coordinate of burglary location

StartDateTime

Start date and time of the burglary in POSIXct format

EndDateTime

End date and time of the burglary in POSIXct format

Source

https://opendata.dc.gov/

Summary output from aoristic analysis of DC burglaries

Description

A dataset containing the summarized output generated by aoristic.summary() on the data frame produced by the aoristic function aoristic.df(dcburglaries, ...).

Usage

dcburgsum

Format

A data frame with 24 observations and 8 variables:

Range

The hour represented by the column, in 24 hour format

Mon

Sum of aoristic values for Mondays by hour

Tue

Sum of aoristic values for Tuesdays by hour

Wed

Sum of aoristic values for Wednesdays by hour

Thu

Sum of aoristic values for Thursdays by hour

Fri

Sum of aoristic values for Fridays by hour

Sat

Sum of aoristic values for Saturdays by hour

Sun

Sum of aoristic values for Sundays by hour

Residential burglaries, Manhattan borough, New York City, NY, 2019

Description

A dataset with a residential burglaries in the Borough of Manhattan, New York City, NY for 2019. Data include start and end date-times, and coordinates.

Usage

NYburg

Format

A data frame with 1233 rows and 6 variables:

CMPLNT_FR_DT

Crime from date in Date format

CMPLNT_FR_TM

Crime from time in number format

CMPLNT_TO_DT

Crime to date in Date format

CMPLNT_TO_TM

Crime to time in number format

X_COORD_CD

X coordinate of crime event in state plane format

Y_COORD_CD

Y coordinate of crime event in state plane format

Source

https://data.cityofnewyork.us/Public-Safety/NYPD-Complaint-Data-Current-Year-To-Date-/5uac-w243/data