fips.Exponential#

class fips.Exponential(levels, scale, *, within=None, metric='euclidean')[source]#

Bases: _Decay

An exponential correlation, \(\exp(-d / \ell)\) at a distance \(d\).

Parameters:

  • levels (str | Sequence[str]) – The levels the distance is measured along: one datetime or timedelta level (a time), numeric levels (a straight line), or latitude and longitude with metric="haversine" or "chordal".

  • scale (float | str | Timedelta) – The length scale \(\ell\), positive: a time ("30D") for a datetime or timedelta level, else a number in the levels’ units (km on the Earth).

  • within (str | Sequence[str] | None) – Correlate only labels that are the same on these levels (the matrix is then sparse). "level.attribute" is an attribute of a datetime level: "obs_time.date" cuts the correlation at midnight, and "time.hour" keeps it to the same hour of day.

  • metric (str) – How the distance is measured. "haversine" (great-circle) and "chordal" (through the Earth) read the levels as latitude and longitude in degrees, in that order, and give kilometers.

Raises:

ValueError – If the scale is not positive, a level is named twice, or the metric is unknown or on the Earth with other than two levels or a time.

Examples

A prior error correlated over 30 days in time and 20 km in space, kept as the two factors:

>>> from fips import Exponential, Kronecker
>>> model = Kronecker(
...     Exponential("time", "30D"),
...     Exponential(["lat", "lon"], 20.0, metric="haversine"),
... )

Errors correlated over 2.8 hours at one site, never across midnight:

>>> mdm = Exponential("obs_time", "2.8h", within=["site", "obs_time.date"])

Attributes

metric

How the distance is measured, "euclidean", "haversine" or "chordal".

scale

The length scale, a time for a datetime or timedelta level, else in the levels' units (km on the Earth).

within

The levels on which two labels must be the same to be correlated ("time.hour" is an attribute of a datetime level).

Methods

correlation(coords)

Return the correlation between the rows of coords, zero between groups (see CorrelationModel.correlation()).

Inherited

From CorrelationModel: levels, with_std