merge-nearest-time-series

    1.0.1 • Public • Published

    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.

    Install

    npm i merge-nearest-time-series

    DownloadsWeekly Downloads

    3

    Version

    1.0.1

    License

    MIT

    Unpacked Size

    10.9 kB

    Total Files

    4

    Last publish

    Collaborators

    • travishorn