Frequency modeling v1

Methodology version key: hq_methodology_v1.0_2026

Effective: January 1, 2026

Scope

This document defines how HomeQuotr computes permit-issuance frequency at the city-trade level for consumption by the Enterprise tier /api/v1/frequency/[trade]/[city] endpoint. Frequency modeling is gated by the FEATURE_PERIL_FREQUENCY environment flag and surfaces only at Enterprise tier and above.

Source data

Frequency is derived from the same permits corpus used for severity statistics, restricted to permits with non-null issue_date and trade_id. The denominator is the date range covered by the pricing_aggregates row for that city-trade group: date_range_end - date_range_start.

Lambda estimation

For each city-trade group, the permit-issuance rate is modeled as a Poisson process with rate parameter lambda:

lambda_per_year = permit_count / years_in_range
years_in_range  = (date_range_end - date_range_start) / 365.25

Lambda is reported in two forms:

1. permits_per_year raw count, suitable for benchmarking against historical pipeline activity
2. events_per_insured_home_year decimal probability, normalized by the metro's owner-occupied housing unit count from the latest American Community Survey 5-year estimate

The second form is consistent with the units used in peril_trade_mappings.frequency_weight so claims-frequency models can compose peril probability x trade-weighted frequency without unit conversion.

Confidence

The 95 percent CI on lambda uses the chi-squared exact method appropriate for small Poisson counts:

lambda_low  = chi2_inv(0.025, 2 * n) / (2 * years_in_range)
lambda_high = chi2_inv(0.975, 2 * (n + 1)) / (2 * years_in_range)

Where n is permit_count and chi2_inv is the inverse chi-squared CDF. For n >= 100 the normal approximation is used as a faster alternative.

CI bounds are returned alongside the point estimate so Enterprise underwriters can stress-test their claims models against the lower bound when pricing reserves.

Time-series component

Frequency for the trailing 12 months is reported separately from the lifetime aggregate. This supports detection of structural shifts (a building code change that drives a surge of HVAC replacements, for example) without disturbing the long-run base rate. The 12-month figure is computed from permits rows with issue_date >= NOW() - INTERVAL '12 months'.

Stamping

Frequency endpoint responses include methodology_version = 'hq_methodology_v1.0_2026' and a link to this document.

Limitations

1. Lambda assumes permits are filed at the same rate they are completed; large municipalities with permit backlogs will understate true installation frequency in recent months.
2. Owner-occupied housing unit denominators come from ACS 5-year estimates and lag actual housing stock by 6 to 24 months.
3. The Poisson assumption breaks down when a single contractor or developer files a large block of permits on the same day; spatial-temporal clustering correction is a v2 candidate.
4. Frequency does not currently disaggregate by property type (single family detached vs multi-family); this disaggregation is a v2 candidate.
5. Frequency models permit issuance, not insurance claims. Translation to claims frequency requires combining lambda with peril_trade_mappings.frequency_weight.