Skip to content

Distance Functions#

Distance functions measure how "different" two sessions are along a specific dimension. The Void & Cluster algorithm uses these to select captures that maximize diversity.

Overview#

The cgr.scheduling.distance module provides type-specific distance metrics that can be combined into composite functions.

Usage Pattern#

import capturegraph_recipes as cgr
from datetime import timedelta

# Single type-specific distance
solar_dist = cgr.scheduling.distance.solar(sigma_deg=2.0)

# Combine multiple distance functions via attribute names
distance_fn = cgr.scheduling.distance.combine(
    solar_angle=cgr.scheduling.distance.solar(sigma_deg=2.0),
    location=cgr.scheduling.distance.location(sigma_m=100.0),
)

# Mix type-specific and primitive functions
distance_fn = cgr.scheduling.distance.combine(
    solar_angle=cgr.scheduling.distance.solar(sigma_deg=2.0),
    weather=cgr.scheduling.distance.weather(sigma_cloud_cover_ratio=0.3),
    date=cgr.scheduling.distance.time_of_day(sigma=timedelta(hours=2)),
)

Available Functions#

Type-Specific#

Function Operating Type Description
solar(sigma_deg) cgr.scheduling.forecast.SolarPosition Angular separation on celestial sphere
shadow(sigma_heights, courtyard_heights) cgr.scheduling.forecast.SolarPosition Separation of where an upright pin's shadow ends, in pin heights; long, fast morning and evening shadows count for more. With courtyard_heights, the pin stands in a square courtyard that many pin heights wide, and a shadow that reaches a wall climbs it, so the distance stays defined through sunset and into the night
location(sigma_m) cg.Location Geographic separation in meters
weather(...) cg.Weather Multi-dimensional weather difference

Weather dimensions are opt-in: pass one sigma_<field> per cg.Weather field you care about — for example weather(sigma_cloud_cover_ratio=0.3). The keywords are checked against the fields cg.Weather marks with a cg.Quantity, so a typo raises instead of silently measuring nothing. Cloud cover and humidity are expressed as 0–1 ratios, not percentages.

Primitive#

Function Operating Type Description
scalar(sigma) float Simple absolute difference
angle_degrees(sigma_deg) float Circular difference (0-360°)
angle_radians(sigma_rad) float Circular difference (0-2π)
time_of_day(sigma) datetime Circular 24-hour difference

Combining Functions#

The combine() function creates a Euclidean combination of distance functions. The keyword argument specifies which session attribute to extract:

import capturegraph_recipes as cgr

# Keys match session attribute names
distance_fn = cgr.scheduling.distance.combine(
    solar_angle=cgr.scheduling.distance.solar(sigma_deg=2.0),
    location=cgr.scheduling.distance.location(sigma_m=50.0),
    weather=cgr.scheduling.distance.weather(sigma_cloud_cover_ratio=0.3),
)

# Use with sessions
d = distance_fn(session_a, session_b)

# Or every pair at once
matrix = distance_fn.matrix(potential_sessions, previous_sessions)

Coverage#

coverage(points, captures, weights=None) scores how well the captures so far cover each candidate: the best weighted Gaussian of its distance to any capture, 1 at a capture and falling off over a sigma. It is a best rather than a sum, so a burst of captures in one place covers it no more than one does — and 1 - coverage is what a candidate still needs. Either argument may be values or features already extracted, such as a grid over a chart's axes.

sun = cgr.scheduling.distance.solar(sigma_deg=4.0)
coming = cgr.scheduling.forecast.solar_position(site, cgr.scheduling.forecast.times())
need = 1.0 - sun.coverage(coming, photographed)

Missing data#

One rule covers absence, wherever it comes from — a session that never recorded a field, a forecast a provider does not report, a nan reading:

  • A term whose value is missing on either side drops out of the combination, so the pair is scored on the dimensions it does have.
  • A pair with no term left has no distance, and select_sessions never offers such a candidate — it cannot be compared to anything, so it is not a slot worth prompting for.

A metric that fails is not missing data: the error surfaces rather than scoring the pair as identical.

See Also#