AERSHED Platform

Appearance

Matching ​

Matching is the process of connecting emission data points to operator infrastructure (sites and equipment). When a data import completes, the platform runs automated matching to determine which company's sites are near each detected emission. The matching parameters depend on the data provider and are configured via the MatchingConfiguration model in Django Admin.

Each match creates an EmissionRecord linked to the company and an Event with an initial status of CREATED (when workflow automation is enabled) or NEW (when it is disabled). See Emission States for the full lifecycle.

Overview ​

Matching configuration ​

There is a single MatchingConfiguration instance per data provider. Matching configurations can be further split by secondary data source using MatchingConfigurationParams — each params instance applies different matching rules to different secondary data sources from the same provider.

Companies are added or excluded from a MatchingConfiguration via the companies many-to-many field. When company_opt_in is enabled (the default), any new company created in the platform is automatically added to all matching configurations that have this flag set.

To configure matching in Django Admin, navigate to Emission Matching → Matching Configurations.

MatchingConfiguration fields ​

FieldDescription
Data providerThis configuration will be used to match all data points for the given data provider
CompaniesA list of companies whose infrastructure will be matched to this provider's data points
Company opt-inIf enabled, each new company will automatically be added to this configuration
Is EPA matcherIf selected, this configuration uses the EPA matching algorithm (simplified, matches to all operators)

MatchingConfigurationParams fields ​

Each MatchingConfiguration has one or more MatchingConfigurationParams instances that control the matching behavior, optionally split by secondary data source:

FieldDescription
Is defaultIf enabled, this configuration will be used as a catch-all for secondary data sources not explicitly listed in any other params instance
Secondary data sourcesThe secondary data sources that use these matching parameters. Must not overlap with other params instances for the same configuration
Point distanceDistance in meters used to match emission points to site locations (centroids)
Enable polygon matchingIf enabled, the matcher will use site shapes (polygons) to determine matches
Distance to polygon matchingIf set to a value greater than 0, the matcher will also match emissions within this distance (in meters) from the site polygon's boundary
Enable plume outline matchingIf enabled, the matcher will use plume outlines to restrict matching. Also controlled by the plume_outline_matching waffle switch — see Flags and Switches
Disable matchingIf enabled, these parameters will not be used for matching. Useful when there are secondary data sources for a data provider that should not be matched

Adding a new params instance

Clicking "Add matching configuration params" opens a new inline form. The form must be populated with the required attributes, and at least one secondary data source must be selected. The secondary data sources in this form must not be present in any other MatchingConfigurationParams instance connected to the same data provider.

Deprecated parameters

The following parameters are deprecated and no longer used by the matching engine:

  • Enable children matching — previously controlled whether child equipment was considered during matching. Has no effect.
  • Near match tolerance — previously generated "near" matches with extra tolerance. Has no effect.

Matching runs ​

Matching runs can be triggered by three different contexts:

Data batch ​

This can be triggered either automatically or manually:

  • Automatically when a data import is completed
  • Manually from Django Admin on the data batches page by selecting one or more data batches and executing the re-run matchers action

Company ​

Triggered from Django Admin on the company edit form. This runs the matcher for all public data points and data points owned by this company against all sites owned by this company.

Specific sites ​

This is triggered by the infrastructure import upon a successful site create or update operation.

Additional operations can be set up by calling the matching function from the post-import hook of a custom import operation.

Run lifecycle ​

Each matching run is tracked as an EmissionMatchingRun with the following statuses:

StatusDescription
PENDINGRun has been created but not yet started
RUNNINGMatcher is actively processing data points
COMPLETEMatching finished successfully; notifications have been queued
FAILEDAn error occurred during matching
TIMED_OUTRun exceeded the 2-hour timeout and was automatically marked as failed

A run cannot be created if another run with the same parameters (data batch, company, or site IDs) is already in PENDING or RUNNING status. This prevents duplicate concurrent matching runs.

Failed or timed-out runs are reported to Slack. Runs older than 30 days are automatically cleaned up. An audit task runs every 15 minutes to detect and time out stuck runs.

Re-running matching ​

Matching runs can be re-run from Django Admin in two ways:

  1. From the Emission Matching Runs list view — select runs and use the Re-run matchers action
  2. From an individual run's detail page — click the Rerun button

Both create a new matching run with the same parameters and enqueue it. The original run's status is preserved for audit purposes.

Matching algorithm ​

The matching process depends on whether the data is public, self-reported, or EPA. The algorithm has two steps for public non-EPA batches, and a single step for other batch types.

Step 1: Polygon-contains matching (direct matches) ​

Step 1 only runs for public, non-EPA batches in the data batch context. It attempts to match data points to sites using a single criterion:

  • Is the data point location within the polygon (shape) of the site?

All sites belonging to all companies that have access to the data batch are considered. A company has access to a data batch if:

  • The data batch is public (no owner), or
  • The data batch is owned by the company

Once a data point is matched to a site in Step 1, it is marked as a direct match and will not be considered in Step 2. This ensures that a data point inside a site's polygon is definitively matched to that site, without being re-evaluated against other companies' nearby sites.

If multiple sites from different owners contain the same data point, separate emission records are created for each owner. If multiple sites from the same owner contain the same point, the first site is selected.

Step 2: Configuration-based matching ​

Step 2 runs for each company registered to the MatchingConfiguration. It excludes data points that already have emission records (from Step 1 direct matches or previous matching runs for this company).

Prior to applying the matching criteria, only sites within 10,000 meters of the data point are considered. This pre-filter reduces the matching duration by eliminating sites that are too far away.

The matching criteria depend on whether polygon matching and plume outline matching are enabled:

Both polygon and plume outline matching enabled (4 priority levels) ​

Matches are evaluated in priority order. The first level that produces matches is used; lower-priority levels are skipped:

  1. Site has a shape and the emission point is within the shape (polygon contains)
  2. Site has a shape and the emission point is within distance_to_polygon_matching meters of the shape's boundary
  3. Site has a shape, a plume outline is available, the site's center is within point_distance meters of the emission, and the site shape intersects the plume outline — or the site is a point within point_distance meters
  4. Site is a point within point_distance meters of the emission

Polygon matching enabled, plume outline matching disabled (2 priority levels) ​

  1. Site has a shape and the emission point is within the shape
  2. Site has a shape and the emission point is within distance_to_polygon_matching meters of the shape boundary — or the site is a point within point_distance meters

Polygon matching disabled, plume outline matching enabled (1 level) ​

When polygon matching is disabled, site shapes and plume outlines are not considered. Only one criterion is evaluated:

  1. Any site (point or shape) within point_distance meters of the emission

Both polygon and plume outline matching disabled (1 level) ​

  1. Any site (point or shape) within point_distance meters of the emission

Match assignment ​

When a data point is matched to exactly one site, that site is assigned directly as the emission record's site_id. When multiple sites match, the emission record's site_id is left unassigned and all matched sites are stored in the site_matches field. Events with multiple site matches require manual resolution by an operator in the platform UI.

EPA matching ​

When is_epa_matcher is enabled on the MatchingConfiguration, a simplified matching algorithm is used:

  • Matches by point distance (site center within point_distance of the emission)
  • If polygon matching is enabled, also matches by distance to polygon (within distance_to_polygon_matching meters)
  • Uses OR logic — either condition produces a match
  • Matches to all companies' sites, not just those registered to the configuration

EPA matching also creates additional EPA-specific notification records alongside the standard emission records and events.

Additional behaviors ​

  • CarbonMapper Tanager data: When the import-carbon-mapper-tanager switch is disabled, data points with the tan secondary data source are skipped during matching. See Flags and Switches.
  • Batch-running guard: When matching is triggered for a company or specific sites, data points belonging to batches that are currently in RUNNING status are skipped. This prevents re-matching data points that are still being processed by an active import.
  • New infrastructure matching: The new-infrastructure-emission-matching switch controls whether the new matching engine is used. See Flags and Switches.

Notifications ​

When a matching run completes successfully, notifications are queued according to the company's notification settings. For data batch runs, notifications are queued for the batch. For company runs, notifications are queued for the company covering the time window of the matching run.