Nearest-neighbor distance and local support

Define similarity for the decision

A dispatch desk wants to flag likely missed handoffs using intake backlog and available crew. Two shipments are neighbors only because the chosen feature representation and distance say so. Backlog counts and crew counts have different units; fit their centers and scales on training cases, then reuse those values for every query. A feature recorded after handoff cannot become a distance coordinate. The feature clock comes first.

Count support before trusting a vote

The code finds the three nearest past shipments and uses a majority vote. It returns their distances as well as the class, because a three-to-zero vote among very distant cases is weak local evidence. With one neighbor, an odd label can change a decision; with too many, the neighborhood can cross distinct operating regimes. Select neighbor count and distance policy on development folds. Group and time boundaries matter because repeated scans make near duplicates.

Plan for distance ties and missing values

Equal distances need a deterministic tie rule. This teaching code orders by distance and training-row position, then gives class zero the tie if votes split. A deployed policy should state how duplicates, missing crew counts and mixed numeric/categorical attributes are handled. Encoding a warehouse name as an arbitrary integer creates fictional geometry. The scaling lesson explains why one large-range field can dominate.

Recognize the high-dimensional limit

With many weak or redundant features, distances may become less useful and exact neighbor lookup can approach a scan of the training set. Feature selection, dimensionality reduction or a different model may be preferable. Do not assume a spatial index always helps. Compare a simple logistic model and tree on the same future cohort. The logistic lesson gives one baseline with cheaper serving.

Keep local labels and privacy in scope

Nearest-neighbor serving may retain every labeled training row, including records that should be deleted or restricted. Store an approved feature representation, access controls and a deletion policy. A neighbor explanation should not reveal another shipment’s private details. Review local error by site and prevalence; a nearby majority from the wrong class mix can conceal rare failures. Rare-event evaluation still applies.

Implementation

from math import sqrt

past_shipments = [
    (11, 8, 0), (14, 7, 0), (17, 6, 0),
    (24, 5, 1), (28, 4, 1), (31, 3, 1),
]
query_backlog, query_crew = 26, 5

def training_scale(rows):
    means = [sum(row[column] for row in rows) / len(rows) for column in (0, 1)]
    spreads = [sqrt(sum((row[column] - means[column]) ** 2 for row in rows) / len(rows))
               for column in (0, 1)]
    if any(spread == 0 for spread in spreads):
        raise ValueError("constant distance feature")
    return means, spreads

means, spreads = training_scale(past_shipments)
neighbors = sorted(
    (sqrt(((backlog - query_backlog) / spreads[0]) ** 2
          + ((crew - query_crew) / spreads[1]) ** 2), index, missed)
    for index, (backlog, crew, missed) in enumerate(past_shipments)
)[:3]
votes_for_miss = sum(missed for _, _, missed in neighbors)
predicted_miss = int(votes_for_miss > len(neighbors) / 2)
assert predicted_miss == 1
assert len(neighbors) == 3
assert all(distance >= 0 for distance, _, _ in neighbors)

Performance and operating cost

For N stored rows and F numeric features, this brute-force query costs O(NF + N log N) time because it sorts all distances, with O(NF) retained training storage. A size-k heap can reduce the selection step. Index performance depends on dimension and metric; test the actual serving workload.

Common Mistakes

• Do not compute a new scale from each query or from the final test set.
• Do not interpret a unanimous but distant neighborhood as strong evidence.
• Do not use arbitrary integer codes for categories as distances.

Read next

• Naive Bayes smoothing and dependent features
• Fold-local feature selection and stability
• Distance scaling before clustering
• Handoff triage model review project

Continue the workflow: Embedding retrieval recall and collapse checks.