Package 'aion'

Title: Archaeological Time Series
Description: A toolkit for archaeological time series. This package provides a system of classes and methods to represent and work with archaeological time series. 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.
Authors: Nicolas Frerebeau [aut, cre] (<https://orcid.org/0000-0001-5759-4944>, Université Bordeaux Montaigne), Joe Roe [aut] (<https://orcid.org/0000-0002-1011-1244>, Universität Bern), Brice Lebrun [ctb] (<https://orcid.org/0000-0001-7503-8685>, Logo designer), Université Bordeaux Montaigne [fnd], CNRS [fnd]
Maintainer: Nicolas Frerebeau <[email protected]>
License: GPL (>= 3)
Version: 1.0.3
Built: 2024-07-03 04:01:11 UTC
Source: https://github.com/tesselle/aion

Help Index

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

See Also

Other fixed date tools: as_date(), as_decimal(), as_fixed(), as_year(), fixed(), fixed_gregorian, fixed_julian, format(), pretty()

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

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.

See Also

Other fixed date tools: arithmetic, as_decimal(), as_fixed(), as_year(), fixed(), fixed_gregorian, fixed_julian, format(), pretty()

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,TimeScale'
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

See Also

Other fixed date tools: arithmetic, as_date(), as_fixed(), as_year(), fixed(), fixed_gregorian, fixed_julian, format(), pretty()

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.

See Also

Other fixed date tools: arithmetic, as_date(), as_decimal(), as_year(), fixed(), fixed_gregorian, fixed_julian, format(), pretty()

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)

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.

See Also

Other fixed date tools: arithmetic, as_date(), as_decimal(), as_fixed(), fixed(), fixed_gregorian, fixed_julian, format(), pretty()

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) or an object from which to extract the time scale.

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

See Also

Other calendar tools: calendar_get, convert(), gregorian, is(), julian()

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)

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

Arguments

object

A TimeScale object.

Value

  • calendar_label() returns a character string specifying the abbreviated label of the time scale.

  • calendar_name() returns a character string specifying the name of the time scale.

  • calendar_unit() returns a character string specifying the name of the calendar.

  • calendar_fixed() returns a length-one numeric vector specifying the reference date of the calendar (in rata die).

  • calendar_epoch() returns a length-one numeric vector specifying 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-1) or forwards (11) from epoch. Only the sign of calendar_direction() is relevant.

Author(s)

N. Frerebeau

See Also

Other calendar tools: calendar(), convert(), gregorian, is(), julian()

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

See Also

Other calendar tools: calendar(), calendar_get, gregorian, is(), julian()

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)

Coerce to a Data Frame

Description

Coerce to a Data Frame

Usage

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

Arguments

x

A TimeSeries 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 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.

Author(s)

N. Frerebeau

See Also

Other time series tools: series(), span(), start(), time(), window()

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)

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,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.

See Also

Other fixed date tools: arithmetic, as_date(), as_decimal(), as_fixed(), as_year(), fixed_gregorian, fixed_julian, format(), pretty()

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.

See Also

Other fixed date tools: arithmetic, as_date(), as_decimal(), as_fixed(), as_year(), fixed(), fixed_julian, format(), pretty()

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.

See Also

Other fixed date tools: arithmetic, as_date(), as_decimal(), as_fixed(), as_year(), fixed(), fixed_gregorian, format(), pretty()

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 = getOption("aion.calendar")
)

Arguments

x

A RataDie object.
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

See Also

Other fixed date tools: arithmetic, as_date(), as_decimal(), as_fixed(), as_year(), fixed(), fixed_gregorian, fixed_julian, pretty()

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)

Gregorian Calendar

Description

Gregorian Calendar

Usage

BP(...)

b2k(...)

BC(...)

BCE(...)

AD(...)

CE(...)

Arguments

...

Currently not used.

Value

A GregorianCalendar object.

Author(s)

N. Frerebeau

See Also

calendar()

Other calendar tools: calendar(), calendar_get, convert(), is(), julian()

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 = getOption("aion.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

See Also

graphics::image()

Other plotting tools: plot(), year_axis()

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

Is an Object a Calendar?

Description

Test inheritance relationships between an object and a calendar class.

Usage

is_gregorian(object)

is_julian(object)

## S4 method for signature 'ANY'
is_gregorian(object)

## S4 method for signature 'ANY'
is_julian(object)

Arguments

object

Any R object.

Value

A logical vector.

Author(s)

N. Frerebeau

See Also

Other calendar tools: calendar(), calendar_get, convert(), gregorian, julian()

Julian Calendar

Description

Julian Calendar

Usage

J(...)

Arguments

...

Currently not used.

Value

A JulianCalendar object.

Author(s)

N. Frerebeau

See Also

calendar()

Other calendar tools: calendar(), calendar_get, convert(), gregorian, is()

Examples

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

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

Plot Time Series

Description

Plot Time Series

Usage

## S4 method for signature 'TimeSeries,missing'
plot(
  x,
  facet = c("multiple", "single"),
  calendar = getOption("aion.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 object.
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.
calendar

A TimeScale object specifying the target calendar (see calendar()).
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.
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).

Value

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

Author(s)

N. Frerebeau

See Also

graphics::plot()

Other plotting tools: image(), year_axis()

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 = getOption("aion.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.

See Also

Other fixed date tools: arithmetic, as_date(), as_decimal(), as_fixed(), as_year(), fixed(), fixed_gregorian, fixed_julian, format()

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

See Also

Other classes: AD-class, BC-class, BCE-class, BP-class, CE-class, GregorianCalendar-class, JulianCalendar-class, TimeScale-class, TimeSeries-class, b2k-class

Other time classes: TimeSeries-class

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

See Also

Other time series tools: data.frame, span(), start(), time(), window()

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 of Time Series

Description

Get the duration.

Usage

span(x, ...)

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

Arguments

x

A TimeSeries 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.

Author(s)

N. Frerebeau

See Also

Other time series tools: data.frame, series(), start(), time(), window()

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)

Terminal Times of Time Series

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 'TimeSeries'
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.

Value

A numeric vector.

Author(s)

N. Frerebeau

See Also

Other time series tools: data.frame, series(), span(), time(), window()

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 '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 of Time Series

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.

Value

A numeric vector.

Author(s)

N. Frerebeau

See Also

Other time series tools: data.frame, series(), span(), start(), window()

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)

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

See Also

Other classes: AD-class, BC-class, BCE-class, BP-class, CE-class, GregorianCalendar-class, JulianCalendar-class, RataDie-class, TimeSeries-class, b2k-class

Other calendar classes: GregorianCalendar-class, JulianCalendar-class

TimeSeries

Description

An S4 class to represent time series.

Details

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

Slots

.Data

A nxmxpn x m x p numeric array giving the observed time-series values.

.Time

A length-nn RataDie object.

Note

This class inherits from array.

Author(s)

N. Frerebeau

See Also

Other classes: AD-class, BC-class, BCE-class, BP-class, CE-class, GregorianCalendar-class, JulianCalendar-class, RataDie-class, TimeScale-class, b2k-class

Other time classes: RataDie-class

Time Series 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.

Value

A TimeSeries object.

Author(s)

N. Frerebeau

See Also

Other time series tools: data.frame, series(), span(), start(), time()

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 = getOption("aion.last_calendar"),
  current_calendar = getOption("aion.last_calendar"),
  ...
)

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

See Also

Other plotting tools: image(), plot()

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