Global

Methods

arrayMean(arr) → {number|null}

Computes the arithmetic mean of an array of numbers, ignoring non-numeric values.

Parameters:
Name Type Description
arr Array.<*>

The input array (may contain nulls, strings, or other types).
Source:
Returns:

The mean of valid numbers, or null if none are found.

Type
number | null

assert()

Browser-safe assert function. Throws an Error if the condition is false.

Source:

assertIsMonitor(result, methodName)

Asserts that the value is a Monitor instance. Useful for verifying return types of public methods.

Parameters:
Name Type Description
result *

The value to check.
methodName string

Name of the method returning the value (for error messages).
Source:

internal_collapse(monitor, deviceID, FUN, FUN_arg) → {Object}

Collapse a Monitor object into a single time series.

Collapses data from all time series into a single time series using the function provided in the FUN argument (typically 'mean'). The single time series result will be located at the mean longitude and latitude.

When FUN === "quantile", the FUN_arg argument specifies the quantile probability.

Available function names are those defined at: https://uwdata.github.io/arquero/api/op#aggregate-functions

Parameters:
Name Type Description
monitor Monitor

The Monitor instance to collapse.
deviceID string

The name of the resulting time series column.
FUN string

The aggregate function name (e.g. "mean", "sum", "quantile").
FUN_arg number

An optional argument for the aggregator (e.g. quantile prob).
Source:
Returns:

A Monitor object with a single time series.

Type
Object

internal_combine(monitorA, monitorB) → {Object}

Combines two Monitor objects by merging their metadata and time series data. If any deviceDeploymentIDs in monitorB are already present in monitorA, they will be dropped from monitorB before merging.

Data are combined with 'join_full' to guarantee that all times from either Monitor object will be retained.

Parameters:
Name Type Description
monitorA Monitor

The base Monitor instance.
monitorB Monitor

The Monitor instance to merge in.
Source:
Returns:

A combined monitor object.

Type
Object

internal_createGeoJSON(monitor) → {Object}

Convert the current metadata table to a GeoJSON FeatureCollection.

Parameters:
Name Type Description
monitor Monitor

The Monitor instance.
Source:
Returns:

A GeoJSON FeatureCollection object.

Type
Object

internal_dropEmpty(monitor) → {Object}

Drops time series from the monitor that contain only missing values.

A value is considered missing if it is null, undefined, NaN, or an invalid string (e.g. 'NA'). The resulting monitor object includes only the deviceDeploymentIDs with at least one valid observation.

Parameters:
Name Type Description
monitor Monitor

The Monitor instance containing metadata and data.
Source:
Returns:

A new monitor object with empty time series removed.

Type
Object

internal_filterByValue(monitor, columnName, value) → {Object}

Filters a monitor object to include only records where a given metadata field equals the specified value.

Parameters:
Name Type Description
monitor Monitor

The Monitor instance containing metadata and data.
columnName string

Name of the metadata column to filter on.
value string | number

Value to match in the specified column.
Source:
Throws:

If the specified column does not exist in monitor.meta.

Type
Error
Returns:

A filtered monitor object.

Type
Object

internal_filterDatetime(monitor, startdate, enddate, timezoneopt) → {Object}

Filter a Monitor's time-series data to an explicit datetime range.

Assumptions:

  • monitor.data.datetime contains Luxon DateTime objects in UTC.
  • Rows in monitor.data are sorted in ascending datetime order.

Inputs:

  • startdate and enddate may be:
    • Luxon DateTime objects (any zone) – timezone is optional.
    • Strings or native Date objects – a valid IANA timezone is required.

Behavior:

  • For string/Date inputs, parseDatetime() interprets them in timezone.
  • For date-only strings (e.g. "2025-02-10"), enddate is promoted to the end of that local day so that whole-day ranges are inclusive.
  • Both parsed datetimes are converted to UTC and used to find the inclusive index range within monitor.data.

Note:

  • This function does NOT construct a new Monitor instance. It returns plain { meta, data } tables; the public Monitor#filterDatetime() method is responsible for wrapping the result into a Monitor and validating it.
Parameters:
Name Type Attributes Description
monitor Monitor

The source monitor object.
startdate DateTime | string | Date

Start of the range.
enddate DateTime | string | Date

End of the range.
timezone string <optional>

IANA timezone when using string/Date inputs.
Source:
Throws:

If datetime column is missing/empty, inputs cannot be parsed, timezone is missing when required, or the range is inverted.

Type
Error
Returns:

Subset of the monitor.

Type
Object

internal_getCurrentStatus(monitor) → {aq.Table}

Compute the most recent valid timestamp and value for each deviceDeploymentID, and append them to the metadata table.

Parameters:
Name Type Description
monitor Monitor

The Monitor instance.
Source:
Returns:

An enhanced metadata table with last valid datetime and value.

Type
aq.Table

internal_getDailyStats(monitor, id) → {Object}

Calculates daily statistics for the time series identified by id after the time series has been trimmed to local-time day boundaries. The starting hour of each local time day and statistics derived from that day's data are returned in an object with datetime, count, min, mean and max properties.

Parameters:
Name Type Description
monitor Monitor

The Monitor instance containing parsed time-series data.
id string | Array.<string>

A single deviceDeploymentID or array of length 1.
Source:
Returns:

Object with datetime, count, min, mean and max properties.

Type
Object

internal_getDiurnalStats(monitor, id, dayCount) → {Object}

Calculates hour-of-day statistics for the time series identified by id after the time series has been trimmed to local-time day boundaries. An array of local time hours and hour-of-day statistics derived from recent data are returned in an object with hour, count, min, mean and max properties.

Parameters:
Name Type Description
monitor Monitor

The Monitor instance containing parsed time-series data.
id string

The deviceDeploymentID identifying the desired time series.
dayCount number

Number of most recent days to use.
Source:
Returns:

Object with hour, count, min, mean and max properties.

Type
Object

internal_getNowcast(monitor, id) → {number|null}

Computes the NowCast PM2.5 value for a specified device.

Parameters:
Name Type Description
monitor Monitor

The Monitor instance containing parsed time-series data.
id string | Array.<string>

A single deviceDeploymentID or array of length 1.
Source:
Throws:

If the device ID is not found or is not a string.

Type
Error
Returns:

The NowCast PM2.5 value, or null if input data is invalid or missing.

Type
number | null

internal_getPM25(monitor, id) → {Array.<(number|null)>}

Retrieves and rounds the PM2.5 time series for a given device ID. Ensures all non-null values are numeric before applying rounding.

Parameters:
Name Type Description
monitor Monitor

The Monitor instance containing time-series data.
id string | Array.<string>

A single deviceDeploymentID or array of length 1.
Source:
Throws:

If the device ID is not found or is not a string.

Type
Error
Returns:

Cleaned PM2.5 values rounded to 1 decimal place.

Type
Array.<(number|null)>

internal_getTimezone(monitor, id) → {string}

Returns the Olson timezone string for a single deviceDeploymentID.

Parameters:
Name Type Description
monitor object

Monitor instance with .meta table.
id string | Array.<string>

A single deviceDeploymentID or array of length 1.
Source:
Throws:

If ID is not found or is invalid.

Type
Error
Returns:

Olson timezone.

Type
string

(async) internal_loadAnnual(monitor, year, baseUrl) → {Promise.<void>}

Asynchronously loads 'annual' Monitor objects from USFS AirFire repositories for 'airnow', 'airsis' or 'wrcc' data.

This function replaces the 'meta' and 'data' properties of the Monitor object with the latest available data. Data cover an entire year or year-to-date. Current year data are updated daily.

Parameters:
Name Type Description
monitor Monitor

Monitor object.
year string

Year of interest.
baseUrl string

Base URL for monitoring v2 data files.
Source:
Throws:

If there's an issue loading the data.

Type
Error
Returns:

Resolves when the monitor's .meta and .data fields have been populated.

Type
Promise.<void>

(async) internal_loadCustom(monitor, baseName, baseUrl, useAllColumns) → {Promise.<void>}

Asynchronously loads custom monitoring data.

Two files will be loaded from :

  1. _data.csv
  2. _meta.csv
Parameters:
Name Type Description
monitor Monitor

Monitor object.
baseName string

File name base.
baseUrl string

URL path under which data files are found.
useAllColumns boolean

Whether to retain all available columns in the metadata.
Source:
Throws:

If there's an issue loading the data.

Type
Error
Returns:

Resolves when the monitor's .meta and .data fields have been populated.

Type
Promise.<void>

(async) internal_loadDaily(monitor, provider, baseUrl) → {Promise.<void>}

Asynchronously loads 'daily' Monitor objects from USFS AirFire repositories for 'airnow', 'airsis' or 'wrcc' data.

This function replaces the 'meta' and 'data' properties of the Monitor object with the latest available data. Data cover the most recent 45 days and are updated once per day around 10:00 UTC (2am US Pacific Time).

Parameters:
Name Type Description
monitor Monitor

Monitor object.
provider string

One of "airnow|airsis|wrcc".
baseUrl string

Base URL for monitoring v2 data files.
Source:
Throws:

If there's an issue loading the data.

Type
Error
Returns:

Resolves when the monitor's .meta and .data fields have been populated.

Type
Promise.<void>

(async) internal_loadLatest(monitor, provider, baseUrl) → {Promise.<void>}

Asynchronously loads 'latest' Monitor objects from USFS AirFire repositories for 'airnow', 'airsis' or 'wrcc' data.

This function replaces the 'meta' and 'data' properties of the Monitor object with the latest available data. Data cover the most recent 10 days and are updated every few minutes.

Parameters:
Name Type Description
monitor Monitor

Monitor object.
provider string

One of "airnow|airsis|wrcc"
baseUrl string

Base URL for monitoring v2 data files.
Source:
Throws:

If there's an issue loading the data.

Type
Error
Returns:

Resolves when the monitor's .meta and .data fields have been populated.

Type
Promise.<void>
Example
await internal_loadLatest(monitor, 'airnow'); * @async

internal_select(monitor, ids) → {Object}

Subsets and reorders time series columns and corresponding metadata for the specified deviceDeploymentIDs.

Ensures that the returned meta rows appear in the same order as ids, and that all specified columns are included in the data table.

Parameters:
Name Type Description
monitor Monitor

The Monitor instance containing metadata and data.
ids Array.<string>

An array of deviceDeploymentIDs to select and order.
Source:
Throws:

If ids is not a non-empty array.

Type
Error
Returns:

A subset of the monitor with selected columns.

Type
Object

internal_trimDate(monitor, timezone, trimEmptyDaysopt) → {Object}

Trims time-series data to full local-time days (00:00–23:00), and optionally removes full days with no data at the start or end.

Parameters:
Name Type Attributes Default Description
monitor Monitor

The Monitor instance with datetime-sorted, hourly-interval data.
timezone string

An IANA timezone string (e.g., "America/New_York").
trimEmptyDays boolean <optional>
 true

Whether to remove fully-missing days at edges.
Source:
Throws:

If the datetime column is missing, empty, or timezone is invalid.

Type
Error
Returns:

A subset of the monitor with trimmed data.

Type
Object

(async) loadWithRetry(url, maxAttemptsopt) → {Promise.<aq.Table>}

Attempts to load a CSV file using aq.loadCSV(), retrying on failure.

Parameters:
Name Type Attributes Default Description
url string

The URL of the CSV file to load.
maxAttempts number <optional>
 2

The maximum number of attempts to try loading the file.
Source:
Throws:

If all attempts to load the CSV fail.

Type
Error
Returns:

A promise that resolves to an Arquero Table if loading succeeds.

Type
Promise.<aq.Table>

parseData(dt) → {aq.Table}

Parses and cleans a time-series measurement table.

  • Skips the first column (assumed to be datetime)
  • Replaces string 'NA' with null
  • Converts all values to floats
  • Replaces negative values with zero
  • Replaces non-finite values (e.g. NaN, Infinity) with null
  • Validates the final table using validateDataTable()
Parameters:
Name Type Description
dt aq.Table

Raw Arquero table from CSV.
Source:
Throws:

If validation fails after cleaning.

Type
Error
Returns:

Cleaned data table suitable for use in a Monitor object.

Type
aq.Table

parseDatetime(value, timezoneopt, isEndopt) → {DateTime}

Parse a user-provided datetime into a Luxon DateTime.

Accepted inputs:

  • A Luxon DateTime object → returned unchanged.
  • A native JS Date → interpreted in the supplied timezone.
  • A string → parsed using ISO, SQL, or "yyyy-MM-dd" formats, interpreted in the supplied timezone.

Requirements:

  • If value is NOT a Luxon DateTime, then a valid timezone (IANA string) MUST be provided.

Behavior:

  • If isEnd === true and the input is a date-only string (e.g. "2025-02-10"), the returned DateTime is promoted to the end of that day in the given timezone (23:59:59.999).

Note:

  • This function does NOT convert to UTC. Conversions should be performed by the caller (e.g., via .toUTC()), since different utilities may require local-time or UTC interpretations depending on context.
Parameters:
Name Type Attributes Default Description
value DateTime | string | Date

The datetime input to parse.
timezone string <optional>

Required for string and native Date inputs. Must be a valid IANA timezone (e.g., "America/Los_Angeles").
isEnd boolean <optional>
 false

If true and the input is a date-only string, expand to end-of-day.
Source:
Throws:

If timezone is missing when required, or if parsing fails.

Type
Error
Returns:

A Luxon DateTime in the interpreted timezone.

Type
DateTime

parseMeta(dt, useAllColumnsopt, metadataNamesopt) → {aq.Table}

Parses and cleans a metadata table.

  • Replaces string 'NA' values with null
  • Converts longitude, latitude, and elevation to floats
  • Restricts output columns to metadataNames unless useAllColumns is true
Parameters:
Name Type Attributes Default Description
dt aq.Table

Raw Arquero table from CSV.
useAllColumns boolean <optional>
 false

Whether to retain all columns.
metadataNames Array.<string> <optional>
 []

Subset of columns to keep if useAllColumns is false.
Source:
Returns:

Cleaned and optionally filtered metadata table.

Type
aq.Table

(async) providerLoad(monitor, provider, timespan, archiveBaseUrl)

Loads metadata and data CSVs for the specified provider and timespan, and updates the given Monitor object in place.

Parameters:
Name Type Description
monitor Monitor

The Monitor instance to populate.
provider string

One of "airnow", "airsis", or "wrcc".
timespan string

One of "latest" or "daily".
archiveBaseUrl string

Base URL to retrieve files from.
Source:

(async) providerLoadAnnual(monitor, year, archiveBaseUrl)

Loads annual metadata and data CSVs for a given year and updates the given Monitor object in place.

Parameters:
Name Type Description
monitor Monitor

The Monitor instance to populate.
year string

Four-digit year string.
archiveBaseUrl string

Base URL to retrieve files from.
Source:

round1(table) → {aq.Table}

round1

Round all numeric columns (except 'datetime') to 1 decimal place. Converts non-finite values (NaN, Infinity, undefined) to null.

Parameters:
Name Type Description
table aq.Table

Input table with 'datetime' as the first column.
Source:
Returns:
  • New table with rounded numeric values and nulls.
Type
aq.Table

validateDataTable(table)

Validates a Monitor data table with the following requirements:

  • Must contain a 'datetime' column with only valid Luxon UTC DateTime objects
  • Datetimes must be in strictly increasing order, spaced exactly 1 hour apart
  • All other columns must be numeric
Parameters:
Name Type Description
table aq.Table

The Arquero table to validate.
Source:
Throws:

If validation fails.

Type
Error

validateDeviceID(monitor, id) → {string}

Validates and resolves a deviceDeploymentID. Accepts either a string or a single-element string array. Verifies that the resolved ID exists in monitor.data.

Parameters:
Name Type Description
monitor Monitor

The Monitor instance containing time-series data.
id string | Array.<string>

A single string or a single-element array.
Source:
Throws:

If input is invalid or the ID does not exist in monitor.data.

Type
Error
Returns:

A validated deviceDeploymentID string.

Type
string