Help for package aion

Title:

Archaeological Time Series

Version:

1.5.0

Maintainer:

Nicolas Frerebeau <nicolas.frerebeau@u-bordeaux-montaigne.fr>

Description:

A toolkit for archaeological time series and time intervals. This package provides a system of classes and methods to represent and work with archaeological time series and time intervals. Dates are represented as "rata die" and can be converted to (virtually) any calendar defined by Reingold and Dershowitz (2018) <doi:10.1017/9781107415058>. This packages offers a simple API that can be used by other specialized packages.

License:

GPL (≥ 3)

URL:

https://codeberg.org/tesselle/aion, https://packages.tesselle.org/aion/

BugReports:

https://codeberg.org/tesselle/aion/issues

Depends:

R (≥ 3.3)

Imports:

arkhe (≥ 1.10.0), graphics, grDevices, methods, stats, utils

Suggests:

folio (≥ 1.5.0), knitr, markdown, rsvg, svglite, tinysnapshot, tinytest

VignetteBuilder:

knitr

Encoding:

UTF-8

LazyData:

true

RoxygenNote:

7.3.2

X-schema.org-applicationCategory:

Archaeological Science

X-schema.org-isPartOf:

https://www.tesselle.org

X-schema.org-keywords:

time-series, r-package, archaeology, archaeological-science, chronology, r-package

Collate:

'AllClasses.R' 'AllGenerics.R' 'aion-internal.R' 'aion-package.R' 'axis.R' 'calendar-gregorian.R' 'calendar-julian.R' 'calendar.R' 'coerce.R' 'convert.R' 'data.R' 'format.R' 'intervals.R' 'mutators.R' 'operators.R' 'overlap.R' 'plot.R' 'series.R' 'show.R' 'span.R' 'subset.R' 'time.R' 'validate.R' 'year.R' 'zzz.R'

NeedsCompilation:

Packaged:

2025-04-29 15:45:05 UTC; nfrerebeau

Author:

Nicolas Frerebeau

[aut, cre], Joe Roe

[aut], Brice Lebrun

[art] (Logo designer), Université Bordeaux Montaigne

[fnd], CNRS

[fnd]

Repository:

CRAN

Date/Publication:

2025-04-29 16:10:02 UTC

aion: Archaeological Time Series

Description

A toolkit for archaeological time series and time intervals. This package provides a system of classes and methods to represent and work with archaeological time series and time intervals. Dates are represented as "rata die" and can be converted to (virtually) any calendar defined by Reingold and Dershowitz (2018) doi:10.1017/9781107415058. This packages offers a simple API that can be used by other specialized packages.

Details

Package:	aion
Type:	Package
Version:	1.5.0
License:	GPL-3
Zenodo:	doi:10.5281/zenodo.8032278

Package options

aion uses the following options() to configure behaviour:

aion.verbose: a logical scalar. Should R report extra information on progress? Defaults to interactive().

Author(s)

Full list of authors and contributors (alphabetic order):

Nicolas Frerebeau	Université Bordeaux Montaigne, France
Brice Lebrun	Université Bordeaux Montaigne, France
Joe Roe	Universität Bern, Switzerland

Package maintainer

Nicolas Frerebeau
nicolas.frerebeau@u-bordeaux-montaigne.fr

Archéosciences Bordeaux (UMR 6034)
Maison de l'Archéologie
Université Bordeaux Montaigne
F-33607 Pessac cedex
France

GregorianCalendar

Description

An S4 class to represent a Gregorian calendar.

Author(s)

N. Frerebeau

JulianCalendar

Description

An S4 class to represent a Julian calendar.

Author(s)

N. Frerebeau

RataDie

Description

An S4 class to represent a vector of rata die.

Details

Rata die (fixed date) are represented as the number of days since 01-01-01 (Gregorian), with negative values for earlier dates.

It is intended that the date should be an integer value, but this is not enforced in the internal representation.

Slots

.Data: A numeric vector giving the rata die values.

Note

This class inherits from numeric.

Author(s)

N. Frerebeau

TimeIntervals

Description

An S4 class to represent time intervals.

Slots

.Id: A character vector specifying the identifier/name of intervals. Duplicated values are interpreted as disjoint intervals referring to the same event.
.Start: A RataDie object giving the start time of the intervals.
.End: A RataDie object giving the end time of the intervals.

Author(s)

N. Frerebeau

TimeScale

Description

A virtual S4 class to represent a calendar.

Slots

label: A character string specifying the abbreviated label of the time scale.
name: A character string specifying the name of the time scale.
epoch: A numeric value specifying the epoch year from which years are counted (starting date of the calendar, in years). Allows to define multiple era of a calendar.
fixed: A numeric value specifying the reference date of the calendar (in rata die).
direction: An integer specifying if years are counted backwards (-1) or forwards (1) from epoch.
year: A numeric value giving the average length of the year in solar days.

Author(s)

N. Frerebeau

TimeSeries

Description

An S4 class to represent time series.

Details

A time series object is an n x m x p array, with n being the number of observations, m being the number of series and with the p columns of the third dimension containing extra variables for each series.

Slots

.Data: A n x m x p numeric array giving the observed time-series values.
.Time: A length-n RataDie object.

Note

This class inherits from array.

Author(s)

N. Frerebeau

Arithmetic Operators

Description

Operators performing arithmetic operations.

Usage

## S4 method for signature 'RataDie,RataDie'
Arith(e1, e2)

## S4 method for signature 'numeric,RataDie'
Arith(e1, e2)

## S4 method for signature 'RataDie,numeric'
Arith(e1, e2)

Arguments

e1, e2

A RataDie object or a numeric vector.

Details

Rata die will be converted to a plain numeric vector if a computation no longer makes sense in temporal terms.

Value

A logical vector.

Author(s)

N. Frerebeau

Examples

## Vectors of years
x <- fixed(c(-350, 31, 1072, 576, 1130), calendar = CE())
y <- fixed(c(1494, 1645, -869, 1440, 1851), calendar = CE())

## Move forward in time
x + y

## Move backward in time
x - y

## Not rata die anymore
x * y

Coerce to a Data Frame

Description

Coerce to a Data Frame

Usage

## S4 method for signature 'TimeSeries'
as.data.frame(x, ..., calendar = NULL)

## S4 method for signature 'TimeIntervals'
as.data.frame(x, ..., calendar = NULL)

Arguments

x

A TimeSeries or a TimeIntervals object.

...

Further parameters to be passed to data.frame().

calendar

A TimeScale object specifying the target calendar (see calendar()). If NULL (the default), rata die are returned.

Value

A data.frame.

Methods (by class)

as.data.frame(TimeSeries): Returns a long data.frame with the following columns:

time
The (decimal) years at which the time series was sampled.

series
The name of the time series.

variable
The name of the variables.

value
The observed value.
as.data.frame(TimeIntervals): Returns a data.frame with the following columns:

label
The name of the intervals.

start
The start time of the intervals, in (decimal) years.

end
The end time of the intervals, in (decimal) years.

Author(s)

N. Frerebeau

Examples

## Create time-series of 20 observations

## Univariate
## Sampled every years starting from 1029 BCE
(X <- series(rnorm(30), time = 1029:1000, calendar = BCE()))

## Terminal and sampling times (returns rata die)
start(X)
end(X)
time(X)
span(X)

## Multivariate
## Sampled every century starting from 1000 CE
(Y <- series(matrix(rnorm(90), 30, 3), time = 1000:1029, calendar = CE()))

## Terminal and sampling times (returns Gregorian Common Era years)
start(Y, calendar = CE())
end(Y, calendar = CE())
time(Y, calendar = CE())
span(Y, calendar = CE())

## Coerce to data frame
df <- as.data.frame(Y, calendar = BP())
head(df)

Date Conversion from Rata Die

Description

Date Conversion from Rata Die

Usage

as_date(object, calendar)

## S4 method for signature 'numeric,GregorianCalendar'
as_date(object, calendar)

## S4 method for signature 'numeric,JulianCalendar'
as_date(object, calendar)

Arguments

object

A RataDie object (see fixed()).

calendar

A TimeScale object specifying the target calendar (see calendar()).

Value

A numeric vector of (decimal) years.

Author(s)

N. Frerebeau

References

Reingold, E. M. and Dershowitz, N. (2018). Calendrical Calculations: The Ultimate Edition. Cambridge University Press. doi:10.1017/9781107415058.

Examples

## R 1.0.0
(y <- fixed(year = 2000, month = 02, day = 29, calendar = CE()))
as_date(y, calendar = CE())
as_year(y, calendar = CE())

## Create a vector of years BP (Gregorian)
## (every two years starting from 2000 BP)
(years <- seq(from = 2000, by = -2, length.out = 10))
## Convert years to rata die
(rd <- fixed(years, calendar = BP()))
## Convert back to Gregorian years BP
as_year(rd, calendar = BP())

## More convenient
(rd <- fixed_from_BP(years))
fixed_to_BP(rd)

Converts a Date to a Decimal of its Year

Description

Converts a Date to a Decimal of its Year

Usage

as_decimal(year, month, day, calendar)

## S4 method for signature 'numeric,numeric,numeric,GregorianCalendar'
as_decimal(year, month, day, calendar)

## S4 method for signature 'numeric,numeric,numeric,JulianCalendar'
as_decimal(year, month, day, calendar)

Arguments

year

A numeric vector of years. If month and day are missing, decimal years are expected.

month

A numeric vector of months.

day

A numeric vector of days.

calendar

A TimeScale object specifying the calendar of year, month and day (see calendar()).

Value

A numeric vector of (ecimal years.

Author(s)

N. Frerebeau

Examples

## R 1.0.0
(y <- fixed(year = 2000, month = 02, day = 29, calendar = CE()))
as_date(y, calendar = CE())
as_year(y, calendar = CE())

## Create a vector of years BP (Gregorian)
## (every two years starting from 2000 BP)
(years <- seq(from = 2000, by = -2, length.out = 10))
## Convert years to rata die
(rd <- fixed(years, calendar = BP()))
## Convert back to Gregorian years BP
as_year(rd, calendar = BP())

## More convenient
(rd <- fixed_from_BP(years))
fixed_to_BP(rd)

Coerce to Rata Die

Description

Coerce to Rata Die

Usage

as_fixed(from)

## S4 method for signature 'numeric'
as_fixed(from)

Arguments

from

A numeric vector of rata die.

Value

A RataDie object.

Author(s)

N. Frerebeau

References

Reingold, E. M. and Dershowitz, N. (2018). Calendrical Calculations: The Ultimate Edition. Cambridge University Press. doi:10.1017/9781107415058.

Examples

## R 1.0.0
(y <- fixed(year = 2000, month = 02, day = 29, calendar = CE()))
as_date(y, calendar = CE())
as_year(y, calendar = CE())

## Create a vector of years BP (Gregorian)
## (every two years starting from 2000 BP)
(years <- seq(from = 2000, by = -2, length.out = 10))
## Convert years to rata die
(rd <- fixed(years, calendar = BP()))
## Convert back to Gregorian years BP
as_year(rd, calendar = BP())

## More convenient
(rd <- fixed_from_BP(years))
fixed_to_BP(rd)

Year Conversion from Rata Die

Description

Year Conversion from Rata Die

Usage

as_year(object, calendar, ...)

## S4 method for signature 'numeric,GregorianCalendar'
as_year(object, calendar, decimal = TRUE, ...)

## S4 method for signature 'numeric,JulianCalendar'
as_year(object, calendar, decimal = FALSE, ...)

Arguments

object

A RataDie object (see fixed()).

calendar

A TimeScale object specifying the target calendar (see calendar()).

...

Currently not used.

decimal

A logical scalar: should decimal years be returned? If FALSE, the decimal part is dropped.

Value

A numeric vector of (decimal) years.

Author(s)

N. Frerebeau

References

Reingold, E. M. and Dershowitz, N. (2018). Calendrical Calculations: The Ultimate Edition. Cambridge University Press. doi:10.1017/9781107415058.

Examples

## R 1.0.0
(y <- fixed(year = 2000, month = 02, day = 29, calendar = CE()))
as_date(y, calendar = CE())
as_year(y, calendar = CE())

## Create a vector of years BP (Gregorian)
## (every two years starting from 2000 BP)
(years <- seq(from = 2000, by = -2, length.out = 10))
## Convert years to rata die
(rd <- fixed(years, calendar = BP()))
## Convert back to Gregorian years BP
as_year(rd, calendar = BP())

## More convenient
(rd <- fixed_from_BP(years))
fixed_to_BP(rd)

Calendar

Description

Calendar

Usage

calendar(object)

## S4 method for signature 'character'
calendar(object)

Arguments

object

A character string specifying the abbreviated label of the time scale (see details).

Details

The following time scales are available:

label	era	calendar
`BP`	Before Present	Gregorian
`BC`	Before Christ	Gregorian
`BCE`	Before Common Era	Gregorian
`AD`	Anno Domini	Gregorian
`CE`	Common Era	Gregorian
`b2k`	Years before 2000	Gregorian
`julian`		Julian

Value

A TimeScale object.

Note

Inspired by era::era() by Joe Roe.

Author(s)

N. Frerebeau

Examples

## Define time scales
calendar("BP")
calendar("AD")
calendar("julian")

## Shortcuts
BP()
AD()
J()

Calendar Parameters

Description

Calendar Parameters

Usage

calendar_label(object)

calendar_name(object)

calendar_unit(object)

calendar_epoch(object)

calendar_fixed(object)

calendar_direction(object)

calendar_year(object)

## S4 method for signature 'TimeScale'
calendar_label(object)

## S4 method for signature 'TimeScale'
calendar_name(object)

## S4 method for signature 'TimeScale'
calendar_unit(object)

## S4 method for signature 'TimeScale'
calendar_epoch(object)

## S4 method for signature 'TimeScale'
calendar_fixed(object)

## S4 method for signature 'TimeScale'
calendar_direction(object)

## S4 method for signature 'NULL'
calendar_direction(object)

## S4 method for signature 'TimeScale'
calendar_year(object)

Arguments

object

A TimeScale object.

Value

calendar_label() returns a character string giving the abbreviated label of the time scale.
calendar_name() returns a character string giving the name of the time scale.
calendar_unit() returns a character string giving the unit of the calendar.
calendar_fixed() returns a length-one numeric vector giving the reference date of the calendar (in rata die).
calendar_epoch() returns a length-one numeric vector giving the epoch year from which years are counted (starting date of the calendar, in years).
calendar_direction() returns a length-one integer vector specifying if years are counted backwards (-1) or forwards (1) from epoch. Only the sign of calendar_direction() is relevant.
calendar_year() returns a length-one numeric vector giving the average length of the year in solar days.

Author(s)

N. Frerebeau

Examples

## Define time scales
calendar("BP")
calendar("AD")
calendar("julian")

## Shortcuts
BP()
AD()
J()

Calendar Converter

Description

Interconverts dates in a variety of calendars.

Usage

convert(from, to, ...)

## S4 method for signature 'character,character'
convert(from, to)

## S4 method for signature 'TimeScale,TimeScale'
convert(from, to)

Arguments

from

A TimeScale object describing the source calendar.

to

A TimeScale object describing the target calendar.

...

Currently not used.

Value

A function that when called with a single numeric argument (factional years) converts years from one calendar to another.

Author(s)

N. Frerebeau

Examples

## Define time scales
BP <- calendar("BP")
AD <- calendar("AD")

## Make conversion functions
BP_to_AD <- convert(BP, AD)
AD_to_BP <- convert(AD, BP)

## Convert years
BP_to_AD(0)
AD_to_BP(1950)

Sample Data from Reingold and Dershowitz (2018)

Description

A dataset of 33 dates from the years -1000 to 2100 with their equivalents on differents calendars.

Usage

dates

Format

A data.frame with 33 rows and 14 variables:

rata_die: Rata die.
weekday: Week day.
jd: Julian day.
mjd: Modified Julian day.
unix: Unix.
gregorian_year, gregorian_month, gregorian_day: Gregorian date.
julian_year, julian_month, julian_day: Julian date.
egyptian_year, egyptian_month, egyptian_day: Egyptian date.

References

Reingold, E. M. and Dershowitz, N. (2018). Calendrical Calculations: The Ultimate Edition. Cambridge University Press. doi:10.1017/9781107415058.

Rata Die (Fixed Date)

Description

Rata Die (Fixed Date)

Usage

fixed(year, month, day, calendar, ...)

## S4 method for signature 'numeric,missing,missing,GregorianCalendar'
fixed(year, calendar, scale = 1)

## S4 method for signature 'numeric,numeric,numeric,GregorianCalendar'
fixed(year, month, day, calendar)

## S4 method for signature 'numeric,missing,missing,JulianCalendar'
fixed(year, calendar, scale = 1)

## S4 method for signature 'numeric,numeric,numeric,JulianCalendar'
fixed(year, month, day, calendar)

Arguments

year

A numeric vector of years. If month and day are missing, decimal years are expected.

month

A numeric vector of months.

day

A numeric vector of days.

calendar

A TimeScale object specifying the calendar of year, month and day (see calendar()).

...

Currently not used.

scale

A length-one integer vector specifying the number of years represented by one unit. It should be a power of 10 (i.e. 1000 means ka).

Details

Rata die are represented as the number of days since 01-01-01 (Gregorian), with negative values for earlier dates.

Value

A RataDie object.

Author(s)

N. Frerebeau

References

Reingold, E. M. and Dershowitz, N. (2018). Calendrical Calculations: The Ultimate Edition. Cambridge University Press. doi:10.1017/9781107415058.

Examples

## R 1.0.0
(y <- fixed(year = 2000, month = 02, day = 29, calendar = CE()))
as_date(y, calendar = CE())
as_year(y, calendar = CE())

## Create a vector of years BP (Gregorian)
## (every two years starting from 2000 BP)
(years <- seq(from = 2000, by = -2, length.out = 10))
## Convert years to rata die
(rd <- fixed(years, calendar = BP()))
## Convert back to Gregorian years BP
as_year(rd, calendar = BP())

## More convenient
(rd <- fixed_from_BP(years))
fixed_to_BP(rd)

Rata Die Conversion to and from Gregorian Years

Description

Convenient functions for conversion from and to rata die for a given Gregorian era.

Usage

fixed_from_BP(year, month, day)

fixed_to_BP(object)

fixed_from_BC(year, month, day)

fixed_to_BC(object)

fixed_from_BCE(year, month, day)

fixed_to_BCE(object)

fixed_from_AD(year, month, day)

fixed_to_AD(object)

fixed_from_CE(year, month, day)

fixed_to_CE(object)

fixed_from_b2k(year, month, day)

fixed_to_b2k(object)

Arguments

year

A numeric vector of years. If month and day are missing, decimal years are expected.

month

A numeric vector of months.

day

A numeric vector of days.

object

A RataDie object (see fixed()).

Details

The astronomical notation is used for Gregorian years (there is a year 0).

Value

⁠fixed_from_*()⁠ returns a RataDie object.
⁠fixed_to_*()⁠ returns a numeric vector of Gregorian years.

Author(s)

N. Frerebeau

References

Reingold, E. M. and Dershowitz, N. (2018). Calendrical Calculations: The Ultimate Edition. Cambridge University Press. doi:10.1017/9781107415058.

Examples

## R 1.0.0
(y <- fixed(year = 2000, month = 02, day = 29, calendar = CE()))
as_date(y, calendar = CE())
as_year(y, calendar = CE())

## Create a vector of years BP (Gregorian)
## (every two years starting from 2000 BP)
(years <- seq(from = 2000, by = -2, length.out = 10))
## Convert years to rata die
(rd <- fixed(years, calendar = BP()))
## Convert back to Gregorian years BP
as_year(rd, calendar = BP())

## More convenient
(rd <- fixed_from_BP(years))
fixed_to_BP(rd)

Rata Die Conversion to and from Julian Years

Description

Convenient functions for conversion from and to rata die.

Usage

fixed_from_julian(year, month, day)

fixed_to_julian(object)

Arguments

year

A numeric vector of years. If month and day are missing, decimal years are expected.

month

A numeric vector of months.

day

A numeric vector of days.

object

A RataDie object (see fixed()).

Value

fixed_from_julian() returns a RataDie object.
fixed_to_julian() returns a numeric vector of Julian years.

Author(s)

N. Frerebeau

References

Reingold, E. M. and Dershowitz, N. (2018). Calendrical Calculations: The Ultimate Edition. Cambridge University Press. doi:10.1017/9781107415058.

Examples

## R 1.0.0
(y <- fixed(year = 2000, month = 02, day = 29, calendar = CE()))
as_date(y, calendar = CE())
as_year(y, calendar = CE())

## Create a vector of years BP (Gregorian)
## (every two years starting from 2000 BP)
(years <- seq(from = 2000, by = -2, length.out = 10))
## Convert years to rata die
(rd <- fixed(years, calendar = BP()))
## Convert back to Gregorian years BP
as_year(rd, calendar = BP())

## More convenient
(rd <- fixed_from_BP(years))
fixed_to_BP(rd)

Date Conversion to Character

Description

Date Conversion to Character

Usage

## S4 method for signature 'TimeScale'
format(x, ...)

## S4 method for signature 'RataDie'
format(
  x,
  prefix = c("a", "ka", "Ma", "Ga"),
  label = TRUE,
  calendar = get_calendar(),
  ...
)

Arguments

x

A RataDie object.

...

Currently not used.

prefix

A character string specifying the prefix. It should be one of "a", "ka", "Ma" or "Ga". If TRUE, a good guess for an appropriate format is made.

label

A logical scalar: should the label of the calendar be displayed?

calendar

A TimeScale object specifying the target calendar (see calendar()).

Value

A character vector representing the date.

Author(s)

N. Frerebeau

Examples

## R 1.0.0
(y <- fixed(year = 2000, month = 02, day = 29, calendar = CE()))
as_date(y, calendar = CE())
as_year(y, calendar = CE())

## Create a vector of years BP (Gregorian)
## (every two years starting from 2000 BP)
(years <- seq(from = 2000, by = -2, length.out = 10))
## Convert years to rata die
(rd <- fixed(years, calendar = BP()))
## Convert back to Gregorian years BP
as_year(rd, calendar = BP())

## More convenient
(rd <- fixed_from_BP(years))
fixed_to_BP(rd)

Get or Set the Default Calendar

Description

Get or Set the Default Calendar

Usage

get_calendar(which = c("default", "current"))

set_calendar(x, which = c("default", "current"))

Arguments

which

A character string specifying the calendar to be set. It must be one of "default" or "current". Note that "current" is automatically set by plot() or image() and should not be changed manually.

x

A character string specifying the abbreviated label of the time scale (see calendar()) or an object from which to extract the time scale.

Value

A TimeScale object.

Author(s)

N. Frerebeau

Examples

## Define time scales
calendar("BP")
calendar("AD")
calendar("julian")

## Shortcuts
BP()
AD()
J()

Gregorian Calendar

Description

Gregorian Calendar

Usage

BP(...)

b2k(...)

BC(...)

BCE(...)

AD(...)

CE(...)

Arguments

...

Currently not used.

Value

A GregorianCalendar object.

Author(s)

N. Frerebeau

Examples

## Define time scales
calendar("BP")
calendar("AD")
calendar("julian")

## Shortcuts
BP()
AD()
J()

Heat Map

Description

Heat Map

Usage

## S4 method for signature 'TimeSeries'
image(x, calendar = get_calendar(), k = 1, ...)

Arguments

x

A TimeSeries object.

calendar

A TimeScale object specifying the target calendar (see calendar()).

k

An integer specifying the slice of x along the third dimension to be plotted.

...

Further parameters to be passed to graphics::image().

Value

image() is called for its side-effects: it results in a graphic being displayed. Invisibly returns x.

Author(s)

N. Frerebeau

Examples

## Create 6 time-series of 50 observations
## Sampled every two years starting from 2000 BP
X <- series(
  object = matrix(rnorm(300), nrow = 50, ncol = 6),
  time = seq(2000, by = -2, length.out = 50),
  calendar = BP()
)

## Image
image(X, calendar = CE())

Create Time Intervals

Description

An Interval is elapsed time in seconds between two specific years.

Usage

intervals(start, end, calendar, ...)

## S4 method for signature 'RataDie,RataDie,missing'
intervals(start, end, names = NULL)

## S4 method for signature 'numeric,numeric,TimeScale'
intervals(start, end, calendar, scale = 1, names = NULL)

Arguments

start

A numeric vector of (decimal) years or a RataDie object (see fixed()) giving the beginning of the time intervals.

end

A numeric vector of (decimal) years or a RataDie object (see fixed()) giving the end of the time intervals.

calendar

A TimeScale object specifying the calendar of time (see calendar()). If missing, time must be a RataDie object.

...

Currently not used.

names

A character string specifying the names of the time series.

scale

A length-one numeric vector specifying the number of years represented by one unit. It should be a power of 10 (i.e. 1000 means ka).

Value

A TimeIntervals object.

Author(s)

N. Frerebeau

Examples

## Create time intervals
int <- intervals(
  start = c(625, 700, 1200, 1225, 1250, 500, 1000, 1200,
            1325, 1375, 1200, 1300, 1375, 1275, 1325),
  end = c(750, 825, 1250, 1275, 1325, 700, 1300, 1325,
          1400, 1500, 1300, 1375, 1500, 1325, 1425),
  calendar = CE()
)

## Plot intervals
plot(int) # Default calendar

## Overlap
overlap(int, calendar = CE())

Is an Object a Calendar?

Description

Test inheritance relationships between an object and a calendar class.

Usage

is_calendar(object)

is_gregorian(object)

is_julian(object)

Arguments

object

Any R object.

Value

A logical scalar.

Author(s)

N. Frerebeau

Julian Calendar

Description

Julian Calendar

Usage

J(...)

Arguments

...

Currently not used.

Value

A JulianCalendar object.

Author(s)

N. Frerebeau

Examples

## Define time scales
calendar("BP")
calendar("AD")
calendar("julian")

## Shortcuts
BP()
AD()
J()

Labels

Description

Find a suitable set of labels from an object.

Usage

## S4 method for signature 'TimeSeries'
labels(object, ...)

## S4 method for signature 'TimeIntervals'
labels(object, ...)

Arguments

object

An R object.

...

Currently not used.

Value

A character vector.

Author(s)

N. Frerebeau

Length

Description

Get the length of an object.

Usage

## S4 method for signature 'TimeIntervals'
length(x)

Arguments

x

An R object.

Value

A length-one integer vector.

Author(s)

N. Frerebeau

Time Overlap

Description

Computes the length of overlap of time intervals.

Usage

overlap(x, ...)

## S4 method for signature 'TimeIntervals'
overlap(x, calendar = NULL, aggregate = TRUE)

Arguments

x

A TimeIntervals object.

...

Currently not used.

calendar

A TimeScale object specifying the target calendar (see calendar()). If NULL (the default), rata die are returned.

aggregate

A logical scalar: should disjoint intervals referring to the same event be aggregated?

Details

The overlap of two time intervals is a difference between the minimum value of the two upper boundaries and the maximum value of the two lower boundaries, plus 1.

Value

A symmetric numeric matrix of years.

Author(s)

N. Frerebeau

Examples

## Create time intervals
int <- intervals(
  start = c(625, 700, 1200, 1225, 1250, 500, 1000, 1200,
            1325, 1375, 1200, 1300, 1375, 1275, 1325),
  end = c(750, 825, 1250, 1275, 1325, 700, 1300, 1325,
          1400, 1500, 1300, 1375, 1500, 1325, 1425),
  calendar = CE()
)

## Plot intervals
plot(int) # Default calendar

## Overlap
overlap(int, calendar = CE())

Plot Time Series and Time Intervals

Description

Plot Time Series and Time Intervals

Usage

## S4 method for signature 'TimeIntervals,missing'
plot(
  x,
  calendar = get_calendar(),
  groups = NULL,
  sort = TRUE,
  decreasing = FALSE,
  xlab = NULL,
  ylab = NULL,
  main = NULL,
  sub = NULL,
  ann = graphics::par("ann"),
  axes = TRUE,
  frame.plot = axes,
  panel.first = NULL,
  panel.last = NULL,
  ...
)

## S4 method for signature 'TimeSeries,missing'
plot(
  x,
  facet = c("multiple", "single"),
  calendar = get_calendar(),
  panel = graphics::lines,
  flip = FALSE,
  ncol = NULL,
  xlab = NULL,
  ylab = NULL,
  main = NULL,
  sub = NULL,
  ann = graphics::par("ann"),
  axes = TRUE,
  frame.plot = axes,
  panel.first = NULL,
  panel.last = NULL,
  ...
)

Arguments

x

A TimeSeries or a TimeIntervals object.

calendar

A TimeScale object specifying the target calendar (see calendar()).

groups

A character vector specifying the group each interval belongs to.

sort

A logical scalar: should the data be sorted in chronological order?

decreasing

A logical scalar: should the sort order be decreasing? Only used if sort is TRUE.

xlab, ylab

A character vector giving the x and y axis labels.

main

A character string giving a main title for the plot.

sub

A character string giving a subtitle for the plot.

ann

A logical scalar: should the default annotation (title and x and y axis labels) appear on the plot?

axes

A logical scalar: should axes be drawn on the plot?

frame.plot

A logical scalar: should a box be drawn around the plot?

panel.first

An expression to be evaluated after the plot axes are set up but before any plotting takes place. This can be useful for drawing background grids.

panel.last

An expression to be evaluated after plotting has taken place but before the axes, title and box are added.

...

Further parameters to be passed to panel (e.g. graphical parameters).

facet

A character string specifying whether the series should be plotted separately (with a common time axis) or on a single plot? It must be one of "multiple" or "single". Any unambiguous substring can be given.

panel

A function in the form ⁠function(x, y, ...)⁠ which gives the action to be carried out in each panel of the display. The default is graphics::lines().

flip

A logical scalar: should the y-axis (ticks and numbering) be flipped from side 2 (left) to 4 (right) from series to series when facet is "multiple"?

ncol

An integer specifying the number of columns to use when facet is "multiple". Defaults to 1 for up to 4 series, otherwise to 2.

Value

plot() is called for its side-effects: it results in a graphic being displayed. Invisibly returns x.

Author(s)

N. Frerebeau

Examples

## Create 6 time-series of 50 observations
## Sampled every two years starting from 2000 BP
X <- series(
  object = matrix(rnorm(300), nrow = 50, ncol = 6),
  time = seq(2000, by = -2, length.out = 50),
  calendar = BP()
)

## Multiple
plot(X) # Default calendar
plot(X, calendar = BP(), flip = TRUE) # BP
plot(X, calendar = b2k(), ncol = 1) # b2k

## Single
plot(X, facet = "single") # CE
plot(X, facet = "single", calendar = BP()) # BP

## Create 6 x 3 time-series of 50 observations
## Sampled every two years starting from 2000 BP
X <- series(
  object = array(rnorm(900), dim = c(50, 6, 3)),
  time = seq(2000, by = 2, length.out = 50),
  calendar = BP()
)
plot(X, calendar = BP(), flip = TRUE) # BP
plot(X, calendar = b2k(), ncol = 1) # b2k

## Graphical parameters
plot(X, lwd = c(1, 2, 3), col = c("#004488", "#DDAA33", "#BB5566"))
plot(X, type = "b", pch = 16, col = c("#004488", "#DDAA33", "#BB5566"))
plot(X, type = "p", pch = c(16, 17, 18), cex = c(1, 2, 3))

Pretty Breakpoints

Description

Pretty Breakpoints

Usage

## S4 method for signature 'RataDie'
pretty(x, calendar = get_calendar(), ...)

Arguments

x

A RataDie object.

calendar

A TimeScale object specifying the target calendar (see calendar()).

...

Further parameters to be passed to base::pretty().

Details

pretty() computes a vector of increasing numbers which are "pretty" in decimal notation of calendar. Pretty breakpoints are then converted to rata die.

Value

A RataDie object.

Create Time Series

Description

Create Time Series

Usage

series(object, time, calendar, ...)

## S4 method for signature 'array,RataDie,missing'
series(object, time, names = NULL)

## S4 method for signature 'array,numeric,TimeScale'
series(object, time, calendar, scale = 1, names = NULL)

## S4 method for signature 'matrix,numeric,TimeScale'
series(object, time, calendar, scale = 1, names = NULL)

## S4 method for signature 'matrix,RataDie,missing'
series(object, time, names = NULL)

## S4 method for signature 'numeric,numeric,TimeScale'
series(object, time, calendar, scale = 1, names = NULL)

## S4 method for signature 'numeric,RataDie,missing'
series(object, time, names = NULL)

## S4 method for signature 'data.frame,numeric,TimeScale'
series(object, time, calendar, scale = 1, names = NULL)

## S4 method for signature 'data.frame,RataDie,missing'
series(object, time, names = NULL)

Arguments

object

A numeric vector, matrix or array of the observed time-series values. A data.frame will be coerced to a numeric matrix via data.matrix().

time

A numeric vector of (decimal) years or a RataDie object (see fixed()).

calendar

A TimeScale object specifying the calendar of time (see calendar()). If missing, time must be a RataDie object.

...

Currently not used.

names

A character string specifying the names of the time series.

scale

A length-one numeric vector specifying the number of years represented by one unit. It should be a power of 10 (i.e. 1000 means ka).

Details

Data will be sorted in chronological order.

Value

A TimeSeries object.

Author(s)

N. Frerebeau

Examples

## Create time-series of 20 observations

## Univariate
## Sampled every years starting from 1029 BCE
(X <- series(rnorm(30), time = 1029:1000, calendar = BCE()))

## Terminal and sampling times (returns rata die)
start(X)
end(X)
time(X)
span(X)

## Multivariate
## Sampled every century starting from 1000 CE
(Y <- series(matrix(rnorm(90), 30, 3), time = 1000:1029, calendar = CE()))

## Terminal and sampling times (returns Gregorian Common Era years)
start(Y, calendar = CE())
end(Y, calendar = CE())
time(Y, calendar = CE())
span(Y, calendar = CE())

## Coerce to data frame
df <- as.data.frame(Y, calendar = BP())
head(df)

Duration

Description

Get the duration of time series or intervals.

Usage

span(x, ...)

## S4 method for signature 'TimeSeries'
span(x, calendar = NULL)

## S4 method for signature 'TimeIntervals'
span(x, calendar = NULL)

Arguments

x

A TimeSeries or a TimeIntervals object.

...

Currently not used.

calendar

A TimeScale object specifying the target calendar (see calendar()). If NULL (the default), rata die are returned.

Value

A numeric vector of years.

Author(s)

N. Frerebeau

Examples

## Create time intervals
int <- intervals(
  start = c(625, 700, 1200, 1225, 1250, 500, 1000, 1200,
            1325, 1375, 1200, 1300, 1375, 1275, 1325),
  end = c(750, 825, 1250, 1275, 1325, 700, 1300, 1325,
          1400, 1500, 1300, 1375, 1500, 1325, 1425),
  calendar = CE()
)

## Get time durations
span(int, calendar = CE())

Terminal Times

Description

Get the times the first and last observations were taken.

Usage

## S4 method for signature 'TimeSeries'
start(x, calendar = NULL, ...)

## S4 method for signature 'TimeIntervals'
start(x, calendar = NULL, ...)

## S4 method for signature 'TimeSeries'
end(x, calendar = NULL, ...)

## S4 method for signature 'TimeIntervals'
end(x, calendar = NULL, ...)

Arguments

x

A TimeSeries object.

calendar

A TimeScale object specifying the target calendar (see calendar()). If NULL (the default), rata die are returned.

...

Currently not used.

Value

A numeric vector of decimal years (if calendar is not NULL).

Author(s)

N. Frerebeau

Examples

## Create time-series of 20 observations

## Univariate
## Sampled every years starting from 1029 BCE
(X <- series(rnorm(30), time = 1029:1000, calendar = BCE()))

## Terminal and sampling times (returns rata die)
start(X)
end(X)
time(X)
span(X)

## Multivariate
## Sampled every century starting from 1000 CE
(Y <- series(matrix(rnorm(90), 30, 3), time = 1000:1029, calendar = CE()))

## Terminal and sampling times (returns Gregorian Common Era years)
start(Y, calendar = CE())
end(Y, calendar = CE())
time(Y, calendar = CE())
span(Y, calendar = CE())

## Coerce to data frame
df <- as.data.frame(Y, calendar = BP())
head(df)

Extract or Replace Parts of an Object

Description

Operators acting on objects to extract or replace parts.

Usage

## S4 method for signature 'RataDie'
x[i]

## S4 method for signature 'TimeIntervals'
x[i]

## S4 method for signature 'TimeSeries'
x[i, j, k, drop = FALSE]

Arguments

x

An object from which to extract element(s) or in which to replace element(s).

i, j, k

Indices specifying elements to extract or replace.

drop

A logical scalar: should the result be coerced to the lowest possible dimension? This only works for extracting elements, not for the replacement.

Value

A subsetted object.

Author(s)

N. Frerebeau

Sampling Times

Description

Get the sampling times:

time() creates the vector of times at which a time series was sampled.
frequency() returns the mean number of samples per unit time.

Usage

## S4 method for signature 'TimeSeries'
time(x, calendar = NULL, ...)

## S4 method for signature 'TimeSeries'
frequency(x, ...)

Arguments

x

A TimeSeries object.

calendar

A TimeScale object specifying the target calendar (see calendar()). If NULL (the default), rata die are returned.

...

Currently not used.

Value

A numeric vector of decimal years (if calendar is not NULL).

Author(s)

N. Frerebeau

Examples

## Create time-series of 20 observations

## Univariate
## Sampled every years starting from 1029 BCE
(X <- series(rnorm(30), time = 1029:1000, calendar = BCE()))

## Terminal and sampling times (returns rata die)
start(X)
end(X)
time(X)
span(X)

## Multivariate
## Sampled every century starting from 1000 CE
(Y <- series(matrix(rnorm(90), 30, 3), time = 1000:1029, calendar = CE()))

## Terminal and sampling times (returns Gregorian Common Era years)
start(Y, calendar = CE())
end(Y, calendar = CE())
time(Y, calendar = CE())
span(Y, calendar = CE())

## Coerce to data frame
df <- as.data.frame(Y, calendar = BP())
head(df)

Time Windows

Description

Extracts the subset of the object x observed between the times start and end (expressed in rata die).

Usage

## S4 method for signature 'TimeSeries'
window(x, start = NULL, end = NULL, ...)

Arguments

x

A TimeSeries object.

start

A length-one numeric vector specifying the start time of the period of interest.

end

A length-one numeric vector specifying the end time of the period of interest.

...

Currently not used.

Value

A TimeSeries object.

Author(s)

N. Frerebeau

Examples

## Create 3 time-series of 100 observations
## Sampled every years starting from 1000 CE
(x <- series(matrix(rnorm(300), 100, 3), time = 1000:1099, calendar = CE()))

## Subset between 1025 and 1050 CE
(y <- window(x, start = 374009, end = 383140))

Time Series Plotting Functions

Description

Time Series Plotting Functions

Usage

year_axis(
  side,
  at = NULL,
  format = c("a", "ka", "Ma", "Ga"),
  labels = TRUE,
  calendar = get_calendar("current"),
  current_calendar = get_calendar("current"),
  ...
)

Arguments

side

An integer specifying which side of the plot the axis is to be drawn on. The axis is placed as follows: 1=below, 2=left, 3=above and 4=right.

at

A numeric vector giving the points at which tick-marks are to be drawn. If NULL, tickmark locations are computed.

format

A character string specifying the prefix. It should be one of "a", "ka", "Ma" or "Ga". If TRUE, a good guess for an appropriate format is made.

labels

A logical scalar specifying whether annotations are to be made at the tickmarks, or a vector of character strings to be placed at the tickpoints.

calendar

A TimeScale object specifying the target calendar (see calendar()).

current_calendar

A TimeScale object specifying the calendar used by the last call to plot().

...

Further parameters to be passed to graphics::axis(). (e.g. graphical parameters).

Value

year_axis() is called it for its side-effects.

Author(s)

N. Frerebeau

Examples

## Create a time-series of 300 observations
## Sampled every two years starting from 2000 BP
X <- series(
  object = rnorm(300),
  time = seq(2000, by = -2, length.out = 300),
  calendar = BP()
)

## Axis
plot(X, axes = FALSE, calendar = BP()) # Remove axes
year_axis(side = 1) # Same calendar as last plot
year_axis(side = 3, calendar = CE()) # Specific calendar
mtext(format(CE()), side = 3, line = 3)

## Grid
plot(X, panel.first = graphics::grid())

aion: Archaeological Time Series

Description

Details

Package options

Author(s)

See Also

GregorianCalendar

Description

Author(s)

See Also

JulianCalendar

Description

Author(s)

See Also

RataDie

Description

Details

Slots

Note

Author(s)

See Also

TimeIntervals

Description

Slots

Author(s)

See Also

TimeScale

Description

Slots

Author(s)

See Also

TimeSeries

Description

Details

Slots

Note

Author(s)

See Also

Arithmetic Operators

Description

Usage

Arguments

Details

Value

Author(s)

See Also

Examples

Coerce to a Data Frame

Description

Usage

Arguments

Value

Methods (by class)

Author(s)

See Also

Examples

Date Conversion from Rata Die

Description

Usage

Arguments

Value

Author(s)

References

See Also

Examples

Converts a Date to a Decimal of its Year

Description

Usage

Arguments

Value

Author(s)

See Also

Examples

Coerce to Rata Die

Description

Usage

Arguments

Value

Author(s)

References