npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

karaul

v0.1.0

Published

Lightweight changepoint detection for time series

Readme

karaul

Lightweight PELT changepoint detection for TypeScript. No dependencies. Pluggable cost functions.

npm install karaul

Quick start

import { detectChangepoints } from 'karaul';

const dailyCalls = [820, 835, 791, 810, /* ... */ 1240, 1280, 1195]; // call volumes
const changepoints = detectChangepoints(dailyCalls);
// → [59] — volume spike starts at day 59

Pluggable cost functions

karaul ships two cost functions and accepts any custom implementation.

GaussianCost

For real-valued series where noise is approximately normally distributed — temperature readings, latency measurements, stock prices.

import { detectChangepoints, GaussianCost } from 'karaul';

const changepoints = detectChangepoints(series, new GaussianCost());

PoissonCost

For non-negative integer count data — daily call volumes, event counts, incident tallies. The Poisson model is the correct generative assumption for count data and outperforms Gaussian on series where values are bounded at zero.

import { pelt, estimatePenalty, PoissonCost } from 'karaul';

const costFn = new PoissonCost();
const penalty = estimatePenalty(series);
const changepoints = pelt(series, penalty, costFn);

Custom cost functions

Implement the CostFunction interface:

import type { CostFunction, TimeSeries } from 'karaul';

class ExponentialCost implements CostFunction {
    compute(series: TimeSeries, start: number, end: number): number {
        // negative log-likelihood for your distribution
        const n = end - start;
        let sum = 0;
        for (let i = start; i < end; i++) sum += series[i]!;
        const lambda = sum / n; // MLE for rate parameter
        return 2 * n * lambda - 2 * sum * Math.log(lambda + 1e-9);
    }
}

const changepoints = detectChangepoints(series, new ExponentialCost());

API

pelt(series, penalty, costFn)

Core algorithm. Returns an array of changepoint indices.

| parameter | type | description | |-----------|----------------|------------------------------------------------| | series | number[] | Time series values | | penalty | number | BIC penalty per changepoint (use estimatePenalty) | | costFn | CostFunction | Cost function instance |

estimatePenalty(series)

Estimates the BIC penalty from the series using robust sigma estimation (MAD of first differences, divisor 0.6745 × √2). Works well for most real-world series. Returns log(n) × log(max(σ², 1)).

detectChangepoints(series, costFn?)

Convenience wrapper: calls estimatePenalty then pelt. Defaults to GaussianCost if costFn is omitted.

Performance

karaul uses in-place active set pruning (splice, backwards iteration) instead of Array.filter(). This eliminates one temporary array allocation per outer loop iteration — n allocations avoided at n=5000. Raw throughput on structured series with real changepoints:

| series length | time | |---------------|---------| | 365 points | ~3ms | | 1000 points | ~11ms | | 5000 points | ~124ms |

Performance degrades to O(n³) for truly stationary white-noise series where no pruning occurs. This is a property of PELT, not an implementation bug — on real data with structural shifts, the active set stays bounded.

Demo and Examples

See demo/ for a full call analytics pipeline using karaul on synthetic Glados Therapeutics call center data: topic extraction, daily volume aggregation, changepoint detection with PoissonCost, Jira correlation, and LLM causal reasoning.