Class: Monitor

Monitor(meta, data)

Class representing a set of air quality time series and associated metadata.

Stores two dataframes:

  • meta: instrument deployment metadata (rows = device-deployments)
  • data: UTC time-series data (rows = datetime, columns = deviceDeploymentIDs)

Constructor

new Monitor(meta, data)

Constructs a new Monitor instance with 'meta' and 'data' tables.

Parameters:
Name Type Description
meta aq.Table

Metadata table with one row per deviceDeploymentID.
data aq.Table

Time series data table with a datetime column and one column per deviceDeploymentID.
Source:

Methods

collapse(deviceID, FUN, FUN_argopt) → {Monitor}

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.

Accepted values for FUN: "count", "valid", "invalid", "sum", "product", "mean", "average", "mode", "median", "min", "max", "quantile", "stdev", "stdevp", "variance", "variancep", "array_agg", "array_agg_distinct".

Parameters:
Name Type Attributes Default Description
deviceID string

Base name for the collapsed series. The resulting deviceDeploymentID will be {deviceID}_{geohash} where the geohash encodes the mean location of the input monitors.
FUN string

Name of an aggregation function (e.g., "mean", "max").
FUN_arg number <optional>
 0.8

Quantile probability (0–1); only used when FUN is "quantile".
Source:
Returns:

New Monitor with a single time series.

Type
Monitor

combine(monitor) → {Monitor}

Combines this Monitor object with another, dropping duplicate deviceDeploymentIDs from the second monitor to avoid collisions.

Parameters:
Name Type Description
monitor Monitor

Another Monitor instance to combine with this one.
Source:
Returns:

New Monitor with combined time series.

Type
Monitor

count() → {number}

Returns the number of individual time series found in a Monitor object.

Source:
Returns:

Number of metadata rows.

Type
number

createGeoJSON() → {Object}

Returns a GeoJSON FeatureCollection representing deployment locations.

Source:
Returns:

GeoJSON FeatureCollection.

Type
Object

dropEmpty() → {Monitor}

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

A value is considered missing if it is null; all other values are finite numbers (guaranteed by parseData at load time). The resulting monitor object includes only the deviceDeploymentIDs with at least one valid observation.

Source:
Returns:

New Monitor with empty time series removed.

Type
Monitor

filterByValue(column, value) → {Monitor}

Filters time series based on matching values in the 'meta' dataframe. The returned Monitor object will contain only those records where monitor.meta.columnName === "value".

Parameters:
Name Type Description
column string

Name of the column used for filtering.
value string | number

Value to match.
Source:
Returns:

New Monitor with filtered time series.

Type
Monitor

filterDatetime(startdate, enddate, timezoneopt) → {Monitor}

Filter time series to an explicit datetime range.

The returned Monitor object will contain only those records whose datetime values fall within the requested range when interpreted in the specified timezone.

Internally, startdate and enddate are interpreted in timezone and compared against the UTC data.datetime column.

Parameters:
Name Type Attributes Description
startdate DateTime | string | Date

Inclusive start of the time range, interpreted in timezone.
enddate DateTime | string | Date

Inclusive end of the time range, interpreted in timezone.
timezone string <optional>

IANA timezone (e.g. "America/Los_Angeles"). Required when inputs are strings or Date objects; not needed for Luxon DateTime inputs (which already carry timezone info).
Source:
Returns:

New Monitor with meta unchanged and data restricted to the specified range.

Type
Monitor

getCurrentStatus() → {aq.Table}

Augments and returns 'meta' with current status information derived from 'data'.

Source:
Returns:

An enhanced version of monitor.meta.

Type
aq.Table

getDailyStats(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
id string | Array.<string>

The deviceDeploymentID (or single-element array) of the time series to select.
Source:
Returns:

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

Type
Object

getDatetime() → {Array.<DateTime>}

Returns the array of Luxon DateTime objects that define this Monitor object's time axis.

Source:
Returns:

Array of Luxon DateTime objects in UTC.

Type
Array.<DateTime>

getDiurnalStats(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
id string | Array.<string>

The deviceDeploymentID (or single-element array) of the time series to select.
dayCount number

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

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

Type
Object

getIDs() → {Array.<string>}

Returns an array of unique identifiers (deviceDeploymentIDs) found in a Monitor object.

Source:
Returns:

Array of deviceDeploymentIDs.

Type
Array.<string>

getMetaObject(id) → {Object}

Returns all metadata properties for the time series identified by id.

Parameters:
Name Type Description
id string | Array.<string>

The deviceDeploymentID.
Source:
Throws:

If id is not a valid single string or not found.

Type
Error
Returns:

Object with all metadata properties.

Type
Object

getMetadata(id, fieldName) → {string|number}

Returns the named metadata field for the time series identified by id.

Parameters:
Name Type Description
id string | Array.<string>

The deviceDeploymentID.
fieldName string

Name of the metadata field to retrieve.
Source:
Throws:

If id is not a valid single string or not found.

Type
Error
Returns:

The value of the metadata field.

Type
string | number

getNowcast(id) → {number|null}

Returns the NowCast PM2.5 value for the specified device.

Parameters:
Name Type Description
id string | Array.<string>

The deviceDeploymentID (or single-element array) of the time series to select.
Source:
Returns:

NowCast value, or null if there are insufficient recent observations.

Type
number | null

getPM25(id) → {Array.<(number|null)>}

Returns the PM2.5 time series for the specified device.

Parameters:
Name Type Description
id string | Array.<string>

The deviceDeploymentID (or single-element array) of the time series to select.
Source:
Throws:

If the device ID is not found.

Type
Error
Returns:

PM2.5 values, with null for missing observations.

Type
Array.<(number|null)>

getTimezone(id) → {string}

Returns the timezone for the specified device.

Parameters:
Name Type Description
id string | Array.<string>

The deviceDeploymentID (or single-element array) of the time series to select.
Source:
Returns:

Olson timezone.

Type
string

(async) loadAnnual(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 'this' 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
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 this monitor's .meta and .data have been populated.

Type
Promise.<void>

(async) loadCustom(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 Default Description
baseName string

File name base.
baseUrl string

URL path under which data files are found.
useAllColumns boolean true

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

If there's an issue loading the data.

Type
Error
Returns:

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

Type
Promise.<void>

(async) loadDaily(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 'this' 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
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 this monitor's .meta and .data have been populated.

Type
Promise.<void>

(async) loadLatest(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 'this' monitor object with the latest available data. Data cover the most recent 10 days and are updated every few minutes.

Parameters:
Name Type Description
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 this monitor's .meta and .data have been populated.

Type
Promise.<void>

select(ids) → {Monitor}

Subset and reorder time series within the Monitor.

Parameters:
Name Type Description
ids string | Array.<string>

Single ID or array of IDs to select.
Source:
Returns:

New Monitor with selected/reordered time series.

Type
Monitor

trimDate(timezone) → {Monitor}

Returns a modified Monitor object with the records trimmed to full local time days. Any partial days are discarded.

Parameters:
Name Type Description
timezone string

Olson timezone identifier (e.g., "America/Los_Angeles").
Source:
Returns:

New Monitor with data trimmed by timezone-aware ranges.

Type
Monitor