air-monitor-algorithms

Algorithms for processing hourly time series data, with an initial focus on air quality monitoring applications.

This package supports the air-monitor ecosystem, which works with air quality monitoring data archives hosted by the US Forest Service.

Note: All time series data are assumed to be on a regular hourly axis with no gaps. Missing values should be represented as null.

🚨 Important: All timestamp inputs must be Luxon DateTime objects in the UTC timezone. All timestamp outputs are also returned as DateTime objects in UTC.

Features

High-level analysis functions:

• dailyStats(datetime, x, timezone, qc = "keep") Returns local-time daily statistics (min, max, mean, count) from hourly data.

• diurnalStats(datetime, x, timezone, dayCount = 7, qc = "keep") Returns local-time hourly averages from the most recent dayCount days.

• pm_nowcast(pm) Calculates EPA-style NowCast values from hourly PM2.5 or PM10 data.

• trimDate(datetime, x, timezone) Trims input to full local-time days (midnight to midnight).

Both dailyStats and diurnalStats accept an optional qc argument (default "keep") controlling how negative values are handled before statistics are computed (see QC_negativeValues below).

Array utility functions:

• arrayCount(x) — Count of valid numeric values (non-null, non-NaN)
• arraySum(x) — Sum of valid values
• arrayMin(x) — Minimum valid value
• arrayMean(x) — Mean of valid values
• arrayMax(x) — Maximum valid value

Quality-control and cleanup utilities:

• QC_negativeValues(x, type) — Apply a negative-value QC pass. With type = "keep", small negatives in [-10, 0) are clamped to 0 and values below -10 become null; with type = "drop", all negatives become null.
• useNull(x) — Replace non-numeric / missing values (NaN, undefined, null) with null.
• roundAndUseNull(x, digits) — Round valid values to digits decimal places (default 1) and convert invalid values to null.

Examples

This package includes runnable browser-based examples in the examples/ directory. Load these files directly in your browser to explore the library:

• examples/basic.html — Basic example showing how to use dailyStats and pm_nowcast with sample data.
• examples/visual.html — Visual demonstration of the algorithms with interactive data visualization.

Installation

To install the latest stable release from npm:

npm install air-monitor-algorithms

To install the latest development version directly from GitHub:

npm install github:MazamaScience/air-monitor-algorithms

Usage

This ES module can be used in modern JavaScript projects, including Svelte and Vue apps. You must use Luxon DateTime objects in UTC as input timestamps.

import {
  dailyStats,
  pm_nowcast
} from "air-monitor-algorithms";
import { DateTime } from "luxon";

// Generate fake hourly data for 3 days
const datetime = [];
const x = [];

const start = DateTime.fromISO("2023-07-01T00:00:00Z"); // UTC
for (let i = 0; i < 72; i++) {
  datetime.push(start.plus({ hours: i }));       // UTC Luxon DateTime
  x.push(50 + Math.sin(i / 3) * 10);             // sinusoidal variation
}

// Calculate daily statistics in the 'America/Los_Angeles' timezone
const daily = dailyStats(datetime, x, "America/Los_Angeles");
console.log(daily.mean); // → [meanDay1, meanDay2, meanDay3]

// Apply NowCast to the hourly data
const nowcast = pm_nowcast(x);
console.log(nowcast.slice(-5)); // → last 5 hourly NowCast values

Related Packages

• air-monitor
• air-monitor-plots

For Developers

Instructions for contributors who build, test, document, and publish this package.

Test

npm test

Tests use uvu and live in tests/, one file per source module. New or changed behavior should be accompanied by tests.

Build

npm run build

The published bundles in dist/ are generated by Rollup (dist/air-monitor-algorithms.esm.js and dist/air-monitor-algorithms.umd.js). Do not hand-edit files in dist/ — they are build artifacts.

Document

npm run docs

API documentation is generated with JSDoc into docs/, using this README.md as the landing page.

Publish

npm run publish:public

Publishes the package to npm. You need an npm account with publish rights. package.json is the single source of truth for the version number; bump it and add a NEWS.md entry before publishing.

License

GPL-3.0-or-later © 2024–2025 Jonathan Callahan / USFS AirFire