base
base
#
What a distance function is: extract features, compare them pairwise.
Every metric implements two vectorized steps — extract turns values into
numeric features, pairwise turns two feature sets into a matrix of
distances — and inherits the scalar __call__, the full matrix and
coverage (how well captures cover each point) from them.
Missing data has one rule, applied here: an absent value extracts as nan
features, so every pair involving it has nan distance. A combination drops
its nan terms, and is itself nan only when no term survives;
select_sessions never offers a candidate whose distance is nan.
COVERAGE_CHUNK = 4096
module-attribute
#
How many points coverage scores at once, bounding its distance matrix.
DistanceFunction
#
Bases: ABC
A statistical distance between two values along one dimension.
Source code in capturegraph-recipes/capturegraph_recipes/scheduling/distance/base.py
__call__(a, b)
#
The distance between two values (nan when they cannot be compared).
coverage(points, captures, weights=None)
#
How well captures cover each point: the best weighted Gaussian of a distance.
A point's score is max(weight · exp(-d² / 2)) over every capture,
d the distance in sigmas — a best rather than a sum, so a burst of
captures in one place covers it no more than one capture does.
sun = cgr.scheduling.distance.solar(sigma_deg=4.0)
need = 1.0 - sun.coverage(coming_suns, photographed_suns)
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
points
|
Array | ndarray
|
The values to score — or their features, already extracted. |
required |
captures
|
Array | ndarray
|
The captured values — or their features. |
required |
weights
|
ndarray | None
|
How much each capture counts, 0–1; every capture fully when omitted. |
None
|
Returns:
| Type | Description |
|---|---|
ndarray
|
One 0–1 score per point; 0 where no capture can be compared with it. |
Source code in capturegraph-recipes/capturegraph_recipes/scheduling/distance/base.py
defined(values)
#
Which values this metric can compare at all, as a boolean mask.
extract(values)
abstractmethod
#
The numeric features of each value, one row each (nan when absent).
matrix(values_a, values_b=None)
#
The pairwise distances between two value sets (values_a against itself).
Source code in capturegraph-recipes/capturegraph_recipes/scheduling/distance/base.py
pairwise(features_a, features_b)
abstractmethod
#
The len(a) × len(b) distances between two extracted feature sets.
as_distance(function)
#
function as a [DistanceFunction][], wrapping a plain callable as one.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
function
|
Callable[[T, T], float]
|
A metric, or a plain |
required |
Returns:
| Type | Description |
|---|---|
DistanceFunction[T]
|
The metric itself, or the callable wrapped to evaluate pair by pair. |
Source code in capturegraph-recipes/capturegraph_recipes/scheduling/distance/base.py
field(row, name)
#
row.name, else row[name] on a mapping, else None (absent).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
row
|
object
|
A session — a |
required |
name
|
str
|
The attribute (or key) to read. |
required |
Returns:
| Type | Description |
|---|---|
object
|
The attribute's value, or |
Source code in capturegraph-recipes/capturegraph_recipes/scheduling/distance/base.py
numeric(values, *fields)
#
Each value's fields as a row of floats — the value itself when none are named.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
values
|
Array
|
The values to read. |
required |
fields
|
str
|
The field names to read from each value, in column order. |
()
|
Returns:
| Type | Description |
|---|---|
ndarray
|
A |
ndarray
|
reads |