Merge Nearest Time Series

Pulls data from one time series into another based on the nearest timestamp.

Say you have a series of data like this:

const series1 = [
  { date: new Date("2021-04-03T13:17Z"), description: "Event A" },
  { date: new Date("2021-04-03T13:34Z"), description: "Event B" },
  { date: new Date("2021-04-03T13:51Z"), description: "Event C" },
  { date: new Date("2021-04-03T14:08Z"), description: "Event D" },
  { date: new Date("2021-04-03T14:25Z"), description: "Event E" },
];

And you have another series like this:

const series2 = [
  { date: new Date("2021-04-03T13:00Z"), value: 8 },
  { date: new Date("2021-04-03T13:06Z"), value: 1 },
  { date: new Date("2021-04-03T13:09Z"), value: 9 },
  { date: new Date("2021-04-03T13:12Z"), value: 3 },
  { date: new Date("2021-04-03T13:18Z"), value: 1 },
  { date: new Date("2021-04-03T13:24Z"), value: 6 },
  { date: new Date("2021-04-03T13:30Z"), value: 2 },
  { date: new Date("2021-04-03T13:36Z"), value: 8 },
  { date: new Date("2021-04-03T13:42Z"), value: 7 },
  { date: new Date("2021-04-03T13:48Z"), value: 10 },
  { date: new Date("2021-04-03T13:54Z"), value: 4 },
  { date: new Date("2021-04-03T14:00Z"), value: 10 },
  { date: new Date("2021-04-03T14:06Z"), value: 9 },
  { date: new Date("2021-04-03T14:09Z"), value: 9 },
  { date: new Date("2021-04-03T14:12Z"), value: 4 },
  { date: new Date("2021-04-03T14:18Z"), value: 10 },
  { date: new Date("2021-04-03T14:24Z"), value: 5 },
  { date: new Date("2021-04-03T14:30Z"), value: 3 },
  { date: new Date("2021-04-03T14:36Z"), value: 6 },
  { date: new Date("2021-04-03T14:42Z"), value: 8 },
];

If you want to pull in the values from series2 into series1, you can use this utility. It will find the nearest object in time and assign it to a key in your original series.

const merged = merge(series1, series2);

The resulting array will look like this:

[
  {
    date: new Date("2021-04-03T13:17Z"),
    description: "Event A",
    nearest: { date: new Date("2021-04-03T13:18Z"), value: 1 },
  },
  {
    date: new Date("2021-04-03T13:34Z"),
    description: "Event B",
    nearest: { date: new Date("2021-04-03T13:36Z"), value: 8 },
  },
  {
    date: new Date("2021-04-03T13:51Z"),
    description: "Event C",
    nearest: { date: new Date("2021-04-03T13:48Z"), value: 10 },
  },
  {
    date: new Date("2021-04-03T14:08Z"),
    description: "Event D",
    nearest: { date: new Date("2021-04-03T14:09Z"), value: 9 },
  },
  {
    date: new Date("2021-04-03T14:25Z"),
    description: "Event E",
    nearest: { date: new Date("2021-04-03T14:24Z"), value: 5 },
  },
];

If multiple dates are equally distant, the first object found in the array will be used.

Installation

npm install merge-nearest-time-series

Usage

const merge = require("merge-nearest-time-series");

const series1 = [
  { date: new Date("2021-04-03T13:17Z"), description: "Event A" },
  { date: new Date("2021-04-03T13:34Z"), description: "Event B" },
  { date: new Date("2021-04-03T13:51Z"), description: "Event C" },
  { date: new Date("2021-04-03T14:08Z"), description: "Event D" },
  { date: new Date("2021-04-03T14:25Z"), description: "Event E" },
];

const series2 = [
  { date: new Date("2021-04-03T13:00Z"), value: 8 },
  { date: new Date("2021-04-03T13:06Z"), value: 1 },
  { date: new Date("2021-04-03T13:09Z"), value: 9 },
  { date: new Date("2021-04-03T13:12Z"), value: 3 },
  { date: new Date("2021-04-03T13:18Z"), value: 1 },
  { date: new Date("2021-04-03T13:24Z"), value: 6 },
  { date: new Date("2021-04-03T13:30Z"), value: 2 },
  { date: new Date("2021-04-03T13:36Z"), value: 8 },
  { date: new Date("2021-04-03T13:42Z"), value: 7 },
  { date: new Date("2021-04-03T13:48Z"), value: 10 },
  { date: new Date("2021-04-03T13:54Z"), value: 4 },
  { date: new Date("2021-04-03T14:00Z"), value: 10 },
  { date: new Date("2021-04-03T14:06Z"), value: 9 },
  { date: new Date("2021-04-03T14:09Z"), value: 9 },
  { date: new Date("2021-04-03T14:12Z"), value: 4 },
  { date: new Date("2021-04-03T14:18Z"), value: 10 },
  { date: new Date("2021-04-03T14:24Z"), value: 5 },
  { date: new Date("2021-04-03T14:30Z"), value: 3 },
  { date: new Date("2021-04-03T14:36Z"), value: 6 },
  { date: new Date("2021-04-03T14:42Z"), value: 8 },
];

const merged = merge(series1, series2);

The value of merged will be:

[
  {
    date: new Date("2021-04-03T13:17Z"),
    description: "Event A",
    nearest: { date: new Date("2021-04-03T13:18Z"), value: 1 },
  },
  {
    date: new Date("2021-04-03T13:34Z"),
    description: "Event B",
    nearest: { date: new Date("2021-04-03T13:36Z"), value: 8 },
  },
  {
    date: new Date("2021-04-03T13:51Z"),
    description: "Event C",
    nearest: { date: new Date("2021-04-03T13:48Z"), value: 10 },
  },
  {
    date: new Date("2021-04-03T14:08Z"),
    description: "Event D",
    nearest: { date: new Date("2021-04-03T14:09Z"), value: 9 },
  },
  {
    date: new Date("2021-04-03T14:25Z"),
    description: "Event E",
    nearest: { date: new Date("2021-04-03T14:24Z"), value: 5 },
  },
];

Configuration

You can pass a configuration object as the third parameter.

const config = {
  dateKey1: "t",
  dateKey2: "timestamp",
  insertedKey: "series2Data",
};

const merged = merge(series1, series2, config);

dateKey1

The object key for the date in the first series.

Default: date

Example: If your first series looks like this:

const series1 = [
  { t: new Date("2021-04-03T13:17Z"), description: "Event A" },
  // ... snip ...
];

You can set configuration like so:

const config = { dateKey1: "t" };

dateKey2

The object key for the date in the second series. This identical to dateKey1 except that it works on the second series instead of the first.

Default: date

insertedKey

The name of the key where the second series's object should be stored in the merged array.

Default: nearest

Example: If you want to store the second series data in a key called series2Data instead of the default nearest, you can set configuration like so:

const config = { insertedKey: "series2Data" };

This will result in an array like this:

[
  {
    date: new Date("2021-04-03T13:17Z"),
    description: "Event A",
    series2Data: { date: new Date("2021-04-03T13:18Z"), value: 1 },
  },
  // ... snip ...
];

Development

Clone the repository.

git clone https://github.com/travishorn/merge-nearest-time-series.git

Change into the directory.

cd merge-nearest-time-series.git

Install dependencies

npm install

Write tests using Jest in ./test.

Modify source code in ./src.

Tests

Run tests.

npm test

Run tests and see coverage information.

npm run test:coverage

List

Lint all JavaScript files.

npm run lint

Automatically fix linting issues if possible.

npm run lint:fix

License

The MIT License

Copyright 2021 Travis Horn

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.