Class Timeseries<T>

An immutable series of dates and values, representing a value that changes over time.

Type Parameters

T = NonNullable<unknown>

Hierarchy

Timeseries
- NonEmptyTimeseries

Index

Constructors

constructor

new Timeseries<T>(points: TimeseriesPoint<T>[]): Timeseries<T>
Type Parameters
- T = {}
Parameters
- points: TimeseriesPoint<T>[]
Returns Timeseries<T>
- Defined in src/metrics/Timeseries/Timeseries.ts:68

Properties

`Readonly` points

points: TimeseriesPoint<T>[]

Accessors

dates

get dates(): Date[]
The dates of the points in the timeseries.

Returns Date[]
- Defined in src/metrics/Timeseries/Timeseries.ts:130

first

get first(): undefined | TimeseriesPoint<T>
The first point in the timeseries, or undefined if the timeseries is empty.

You can use hasData to guard against the timeseries being empty and ensure this can't return undefined.

Returns undefined | TimeseriesPoint<T>
- Defined in src/metrics/Timeseries/Timeseries.ts:314

firstValue

get firstValue(): undefined | T
The first value in the timeseries, or undefined if the timeseries is empty.

You can use hasData to guard against the timeseries being empty and ensure this can't return undefined.

Returns undefined | T
- Defined in src/metrics/Timeseries/Timeseries.ts:325

last

get last(): undefined | TimeseriesPoint<T>
The last point in the timeseries or undefined if the timeseries is empty.

You can use hasData to guard against the timeseries being empty and ensure this can't return undefined.

Returns undefined | TimeseriesPoint<T>
- Defined in src/metrics/Timeseries/Timeseries.ts:336

lastValue

get lastValue(): undefined | T
The last value in the timeseries or undefined if the timeseries is empty.

You can use hasData to guard against the timeseries being empty and ensure this can't return undefined.

Returns undefined | T
- Defined in src/metrics/Timeseries/Timeseries.ts:347

length

get length(): number
The length of the timeseries.

Returns number
- Defined in src/metrics/Timeseries/Timeseries.ts:114

maxDate

get maxDate(): undefined | Date
The maximum (latest) date in the timeseries.

You can use hasData to guard against the timeseries being empty and ensure this can't return undefined.

Returns undefined | Date
- Defined in src/metrics/Timeseries/Timeseries.ts:367

maxValue

get maxValue(): undefined | T
The maximum value in the timeseries.

You can use hasData to guard against the timeseries being empty and ensure this can't return undefined.

Returns undefined | T
- Defined in src/metrics/Timeseries/Timeseries.ts:387

minDate

get minDate(): undefined | Date
The minimum (earliest) date in the timeseries.

You can use hasData to guard against the timeseries being empty and ensure this can't return undefined.

Returns undefined | Date
- Defined in src/metrics/Timeseries/Timeseries.ts:357

minValue

get minValue(): undefined | T
The minimum value in the timeseries.

You can use hasData to guard against the timeseries being empty and ensure this can't return undefined.

Returns undefined | T
- Defined in src/metrics/Timeseries/Timeseries.ts:377

sum

get sum(): number
Returns the sum of all numeric values in the timeseries.

Returns number
- Defined in src/metrics/Timeseries/Timeseries.ts:394

values

get values(): T[]
The values of the points in the timeseries.

Returns T[]
- Defined in src/metrics/Timeseries/Timeseries.ts:135

Methods

assertBoolean

assertBoolean(): Timeseries<boolean>
Throws an exception if any values in the timeseries are not boolean.

The returned timeseries will cast to Timeseries<boolean> so any subsequent code doesn't need to deal with non-boolean values.

Returns Timeseries<boolean>
- Defined in src/metrics/Timeseries/Timeseries.ts:260

assertFiniteNumbers

assertFiniteNumbers(): Timeseries<number>
Throws an exception if any values in the timeseries are not finite numbers (e.g. strings, null, undefined, infinity, NaN).

The returned timeseries will cast to Timeseries<number> so any subsequent code doesn't need to deal with non-number values.

Returns Timeseries<number>
- Defined in src/metrics/Timeseries/Timeseries.ts:242

assertStrings

assertStrings(): Timeseries<string>
Throws an exception if any values in the timeseries are not of type string.

The returned timeseries will cast to Timeseries<string> so any subsequent code doesn't need to deal with non-string values.

Returns Timeseries<string>
- Defined in src/metrics/Timeseries/Timeseries.ts:278

`Private` cast

cast<R>(): Timeseries<R>
Internal helper to cast the timeseries values to a new type. Should only be used after verifying all values match the new type.
Type Parameters
- R
Returns Timeseries<R>
- Defined in src/metrics/Timeseries/Timeseries.ts:404

computeDeltas

computeDeltas(opts?: {
keepInitialValue?: boolean;
minDeltaToKeep?: number;
}): Timeseries<number>
Computes deltas between each point in the timeseries.

Returns
A timeseries made up of the deltas between timeseries points.
Parameters
- Optional opts: {
  keepInitialValue?: boolean;
  minDeltaToKeep?: number;
  }
  - Optional keepInitialValue?: boolean
    
    Whether to include the initial value in the series as a delta (with an assumed prior value of 0).
  - Optional minDeltaToKeep?: number
    
    The minimum delta to keep. By default all deltas are kept, but can be set to 0 to drop negative deltas or 1 to only keep positive deltas.
Returns Timeseries<number>
- Defined in src/metrics/Timeseries/Timeseries.ts:418

filter

filter(filterFn: ((val: TimeseriesPoint<T>) => boolean)): Timeseries<T>
Filters the timeseries by calling the provided filterFn on each point in the timeseries.

Returns
A new timeseries with the filtered points.
Parameters
- filterFn: ((val: TimeseriesPoint<T>) => boolean)
  
  The function to call on each point in the timeseries. If it returns true, the point will be kept, else discarded.
  - - (val: TimeseriesPoint<T>): boolean
    - Parameters
      
      val: TimeseriesPoint<T>
      
      Returns boolean
Returns Timeseries<T>
- Defined in src/metrics/Timeseries/Timeseries.ts:147

filterByValues

filterByValues(filterFn: ((val: T) => boolean)): Timeseries<T>
Filters the timeseries by calling the provided filterFn on each value in the timeseries.

Returns
A new timeseries with the filtered points.
Parameters
- filterFn: ((val: T) => boolean)
  
  The function to call on each value in the timeseries. If it returns true, the point will be kept, else discarded.
  - - (val: T): boolean
    - Parameters
      
      val: T
      
      Returns boolean
Returns Timeseries<T>
- Defined in src/metrics/Timeseries/Timeseries.ts:176

filterToDateRange

filterToDateRange(range: DateRange): Timeseries<T>
Filters the timeseries down to the specified date range, specified using either inclusive or exclusive endpoints.

Returns
A new timeseries with the filtered points.
Parameters
- range: DateRange
  
  The date range to keep.
Returns Timeseries<T>
- Defined in src/metrics/Timeseries/Timeseries.ts:158

findNearestDate

findNearestDate(date: Date): undefined | TimeseriesPoint<T>
Returns the point with the date closest to the provided date, or undefined if the timeseries is empty.

You can use hasData to guard against the timeseries being empty and ensure this can't return undefined.

Returns
The point with the date closest to the provided date or undefined if the timeseries is empty.
Parameters
- date: Date
  
  The date to find the closest point to.
Returns undefined | TimeseriesPoint<T>
- Defined in src/metrics/Timeseries/Timeseries.ts:301

hasData

hasData(): this is NonEmptyTimeseries<T>
Returns whether the timeseries has any data.

You can use this method as a type guard before calling last() or findNearestDate() to ensure last() won't return undefined. See NonEmptyTimeseries for details.

Returns this is NonEmptyTimeseries<T>
- Defined in src/metrics/Timeseries/Timeseries.ts:125

map

map<R>(mapFn: ((point: TimeseriesPoint<T>) => undefined | TimeseriesPoint<R>)): Timeseries<R>
Returns a new timeseries with the points in the timeseries mapped to new points using the provided mapFn function. Points can be discarded by returning undefined.

Returns
A new timeseries with the mapped points.
Type Parameters
- R = T
Parameters
- mapFn: ((point: TimeseriesPoint<T>) => undefined | TimeseriesPoint<R>)
  
  The function to call on each point in the timeseries. The return value is used as the point's value in the new timeseries. Undefined can be returned to drop the point.
  - - (point: TimeseriesPoint<T>): undefined | TimeseriesPoint<R>
    - Parameters
      
      point: TimeseriesPoint<T>
      
      Returns undefined | TimeseriesPoint<R>
Returns Timeseries<R>
- Defined in src/metrics/Timeseries/Timeseries.ts:190

mapValues

mapValues<R>(mapFn: ((val: T) => R)): Timeseries<R>
Returns a new timeseries with the values in the timeseries mapped to new values using the provided mapFn function.

Returns
A new timeseries with the mapped points.
Type Parameters
- R = T
Parameters
- mapFn: ((val: T) => R)
  
  The function to call on each value in the timeseries. The return value is used as the point's value in the new timeseries.
  - - (val: T): R
    - Parameters
      
      val: T
      
      Returns R
Returns Timeseries<R>
- Defined in src/metrics/Timeseries/Timeseries.ts:211

rollingAverage

rollingAverage(opts: {
days: number;
treatMissingDatesAsZero?: boolean;
}): Timeseries<number>
Computes a rolling average of the timeseries where each point represents the average of the prior opts.days days of data points.

Returns
A new timeseries containing the rolling average of the original one.
Parameters
- opts: {
  days: number;
  treatMissingDatesAsZero?: boolean;
  }
  - days: number
    
    The number of days to average over.
  - Optional treatMissingDatesAsZero?: boolean
    
    Whether to treat missing dates as 0. This is typically what you want for "incidence" metrics (like "daily new cases") but not "current" metrics (like "% of beds in use").
Returns Timeseries<number>
- Defined in src/metrics/Timeseries/Timeseries.ts:497

slice

slice(start: number, end?: number): Timeseries<T>
Returns a new Timeseries from the slice of data points indicated by the provided start and end indices.

Example
```
ts.slice(2, 4); // Returns a Timeseries with the 3rd and 4th points.
```
Returns
A new Timeseries with the sliced data points.
Parameters
- start: number
  
  The first index to be included in the new Timeseries.
- Optional end: number
  
  The first index not to be included in the new Timeseries.
Returns Timeseries<T>
- Defined in src/metrics/Timeseries/Timeseries.ts:231

toJSON

toJSON(): TimeseriesPointJSON[]
Convert Timeseries instance into serialized JSON format.

Returns
Timeseries points serialized as JSON.

Returns TimeseriesPointJSON[]
- Defined in src/metrics/Timeseries/Timeseries.ts:561

windowed

windowed(opts: {
days: number;
}): Timeseries<TimeseriesWindow<T>>
Breaks the timeseries into overlapping windows of the specified size and makes a new timeseries from them. Handy for computing aggregations like a rolling average.

Returns
A new timeseries that has a point for every point in the original timeseries, but contains a TimeseriesWindow object containing the window of points leading up to that point.
Parameters
- opts: {
  days: number;
  }
  - days: number
    
    The number of days to include in each window. Note that the points at the beginning of the timeseries will have a smaller window due to no prior history.
Returns Timeseries<TimeseriesWindow<T>>
- Defined in src/metrics/Timeseries/Timeseries.ts:450

`Static` `Private` assertDatesHaveNoTimeComponent

assertDatesHaveNoTimeComponent(points: TimeseriesPoint<unknown>[]): void
Internal helper to verify all dates are pure dates with no time component.
Parameters
- points: TimeseriesPoint<unknown>[]
Returns void
- Defined in src/metrics/Timeseries/Timeseries.ts:518

`Static` `Private` assertPointsHaveNoNils

assertPointsHaveNoNils(points: TimeseriesPoint<unknown>[]): void
Internal helper to verify there are no nil points in the timeseries.
Parameters
- points: TimeseriesPoint<unknown>[]
Returns void
- Defined in src/metrics/Timeseries/Timeseries.ts:532

`Static` fromDateRange

fromDateRange<T>(startDate: Date, endDate: Date, valueProvider: T[] | ((date: Date, index: number) => T)): Timeseries<T>
Static constructor to help create a timeseries from a range of dates and some values.

Returns
A new timeseries.
Type Parameters
- T
Parameters
- startDate: Date
- endDate: Date
- valueProvider: T[] | ((date: Date, index: number) => T)
  
  An array of values or iteratee function that returns values for the dates in the date range.
Returns Timeseries<T>
- Defined in src/metrics/Timeseries/Timeseries.ts:88

`Static` fromJSON

fromJSON(jsonPoints: TimeseriesPointJSON[]): Timeseries<unknown>
Construct a Timeseries instance from JSON timeseries points.

Returns
The constructed timeseries.
Parameters
- jsonPoints: TimeseriesPointJSON[]
  
  Serialized timeseries points from which to construct a Timeseries.
Returns Timeseries<unknown>
- Defined in src/metrics/Timeseries/Timeseries.ts:549

Class Timeseries<T>

Type Parameters

T = NonNullable<unknown>

Hierarchy

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Type Parameters

T = {}

Parameters

points: TimeseriesPoint<T>[]

Returns Timeseries<T>

Properties

Readonly points

Accessors

dates

Returns Date[]

first

Returns undefined | TimeseriesPoint<T>

firstValue

Returns undefined | T

last

Returns undefined | TimeseriesPoint<T>

lastValue

Returns undefined | T

length

Returns number

maxDate

Returns undefined | Date

maxValue

Returns undefined | T

minDate

Returns undefined | Date

minValue

Returns undefined | T

sum

Returns number

values

Returns T[]

Methods

assertBoolean

Returns Timeseries<boolean>

assertFiniteNumbers

Returns Timeseries<number>

assertStrings

Returns Timeseries<string>

Private cast

Type Parameters

R

Returns Timeseries<R>

computeDeltas

Returns

Parameters

Optional opts: { keepInitialValue?: boolean; minDeltaToKeep?: number; }

Optional keepInitialValue?: boolean

Optional minDeltaToKeep?: number

Returns Timeseries<number>

filter

Returns

Parameters

filterFn: ((val: TimeseriesPoint<T>) => boolean)

Parameters

val: TimeseriesPoint<T>

Returns boolean

Returns Timeseries<T>

filterByValues

Returns

Parameters

filterFn: ((val: T) => boolean)

Parameters

val: T

Returns boolean

Returns Timeseries<T>

filterToDateRange

Returns

Parameters

`Readonly` points

`Private` cast

`Optional` opts: {
keepInitialValue?: boolean;
minDeltaToKeep?: number;
}

`Optional` keepInitialValue?: boolean

`Optional` minDeltaToKeep?: number

opts: {
days: number;
treatMissingDatesAsZero?: boolean;
}

`Optional` treatMissingDatesAsZero?: boolean

`Optional` end: number

opts: {
days: number;
}

`Static` `Private` assertDatesHaveNoTimeComponent

`Static` `Private` assertPointsHaveNoNils

`Static` fromDateRange

`Static` fromJSON