Package {aoristic}

Type: Package
Title: Generates Aoristic Probability Distributions
Version: 2.0.0
Author: Jerry Ratcliffe [aut, cre]
Maintainer: Jerry Ratcliffe <jerryr@sas.upenn.edu>
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 described by 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.
License: GPL-3
Encoding: UTF-8
URL: https://github.com/jerry-ratcliffe/aoristic
BugReports: https://github.com/jerry-ratcliffe/aoristic/issues
Imports: openxlsx, ggplot2, grid, lubridate, scales, tidyr, dplyr, stats
LazyData: true
RoxygenNote: 7.3.3
Depends: R (≥ 2.10)
Suggests: testthat (≥ 3.0.0)
Config/testthat/edition: 3
NeedsCompilation: no
Packaged: 2026-08-10 01:44:38 UTC; jerryr
Repository: CRAN
Date/Publication: 2026-09-09 07:30:09 UTC

Council district (spatial polygon data frame)

Description

This function is defunct

Usage

CouncilDistrict(...)

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

Creating a kml file with aoristic graph

Description

This function is defunct

Usage

aoristic.all.graph(...)

Check aoristic input data

Description

Flags missing End/To values with '1' and End/To values before Start/From with '2'. The function also reports missing or zero coordinates.

Usage

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

Arguments

data1

Data frame containing coordinates and date-time columns.

Xcoord

Name of the numeric X coordinate or latitude column.

Ycoord

Name of the numeric Y coordinate or longitude column.

DateTimeFrom

Name of the Start/From POSIXct column.

DateTimeTo

Name of the End/To POSIXct column.

Value

A data frame containing the checked fields, elapsed duration, and an 'aoristic_datacheck' flag.

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"
)

Aoristic graph by grid count

Description

This function is defunct

Usage

aoristic.density(...)

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 known but could be spread across numerous hours or days, represented by Start/From and End/To date-times.

Usage

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

Arguments

data1

Data frame containing coordinates and date-time columns.

Xcoord

Name of the numeric X coordinate or latitude column.

Ycoord

Name of the numeric Y coordinate or longitude column.

DateTimeFrom

Name of the Start/From POSIXct column.

DateTimeTo

Name of the End/To POSIXct column.

Details

If an observation is missing the End/To date-time, or its End/To precedes its Start/From, the entire weight is assigned to the hour containing the Start/From date-time. Durations of at least one week receive a uniform probability of '1/168' in every hour.

Value

A data frame with source fields, duration in whole elapsed minutes, and aoristic probabilities for every 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

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)

Aoristic graph by grid count

Description

This function is defunct

Usage

aoristic.grid(...)

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.

Aoristic graph by shapefile boundary

Description

This function is defunct

Usage

aoristic.shp(...)

Creating a spatial.polygon.data.frame for aoristic analysis

Description

This function is defunct

Usage

aoristic.spdf(...)

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)

Arlington burglary incident data

Description

This function is defunct

Usage

arlington(...)

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