capturegraph.scheduling.distance

Distance - Statistical Similarity Between Sessions

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

All distance functions operate on their specific data type (e.g., SolarPosition, Weather, Location). The combine() function handles attribute extraction via keyword arguments.

Available Distance Functions

Type-specific: - solar(sigma_deg): Angular separation on the celestial sphere. Operates on cg.SolarPosition objects. - location(sigma_m): Geographic separation in meters. Operates on cg.Location objects. - weather(...): Multi-dimensional weather difference. Operates on cg.Weather objects.

Primitive: - scalar(sigma): Simple absolute difference. - angle_degrees(sigma_deg): Circular angle distance in degrees. - angle_radians(sigma_rad): Circular angle distance in radians. - time_of_day(sigma): Circular 24-hour time distance.

Combination: - combine(**kwargs): Euclidean combination of distance functions. The key specifies the attribute path to extract from each session.

Example

import capturegraph.scheduling as cgsh
from datetime import timedelta

# Single type-specific distance (for use with combine)
solar_dist = cgsh.distance.solar(sigma_deg=2.0)

# Combine multiple distance functions via attribute paths
dist_fn = cgsh.distance.combine(
    solar_angle=cgsh.distance.solar(sigma_deg=2.0),
    location=cgsh.distance.location(sigma_m=100.0),
)

# Mix type-specific and primitive functions
dist_fn = cgsh.distance.combine(
    solar_angle=cgsh.distance.solar(sigma_deg=2.0),
    weather=cgsh.distance.weather(sigma_cloud_cover_pct=30.0),
    date=cgsh.distance.time_of_day(sigma=timedelta(hours=2)),
)

Modules:

Name	Description
angle	Angle Distance - Circular Angular Distance
batch	Batch Distance Computation
combination	Distance Function Combination
location	Location Distance - Geographic Separation
scalar	Scalar Distance - Simple Numeric Distance
solar	Solar Distance - Angular Separation on the Celestial Sphere
time	Time Distance - Circular Time-of-Day Distance
weather	Weather Distance - Difference in Weather Conditions