igl.metrics

Cross-task dimension comparison and elbow-detection backends.

igl.metrics.dimension.d_eff_from_curve(curve, *, ratio=2.0)

Discovered effective dimension. Alias of :func:igl.detect_elbow.

igl.metrics.dimension.compare_d_eff(*, ratio=2.0, **curves)

Compute and compare d_eff for multiple task curves.

Pass each task's dimension curve as a keyword argument; the key is the task name. The function returns a :class:DimensionComparison containing each task's discovered effective dimension and a boolean indicating whether the values appear in non-decreasing order (the canonical IGL hierarchy).

Example::

from igl import compare_d_eff
report = compare_d_eff(
    cls=classifier.dimension_curve_,
    reg=regressor.dimension_curve_,
    recon=autoencoder.dimension_curve_,
)
assert report.hierarchy_holds  # 1 <= 2 <= 2 on swiss roll

Parameters:

Name	Type	Description	Default
ratio	float	Forwarded to :func:igl.detect_elbow for each curve.	2.0
**curves	DimensionCurve	Task name → dimension curve.	{}

Returns:

Name	Type	Description
A	DimensionComparison

igl.metrics.dimension.DimensionComparison dataclass

Result of :func:compare_d_eff.

Attributes:

Name	Type	Description
d_effs	Mapping[str, int]	Mapping from task name to its discovered effective dimension.
hierarchy_holds	bool	True iff iterating the task names in insertion order yields non-decreasing d_eff values — i.e. the cls ≤ reg ≤ recon ordering is satisfied. The check uses the insertion order of d_effs.

igl.metrics.elbow.detect_elbow_log_ratio(curve, *, ratio=2.0)

Log-scale first-derivative elbow detector. Default, scipy-free.

igl.metrics.elbow.detect_elbow_kneedle(curve, *, sensitivity=1.0)

Kneedle elbow detector. Requires the [elbow] extra.

Parameters:

Name	Type	Description	Default
curve	DimensionCurveMapping	{k: loss} dict.	required
sensitivity	float	Sensitivity parameter forwarded to KneeLocator.	1.0

Raises:

Type	Description
IGLDependencyError	If the kneed package is not installed.
IGLConfigError	If the curve is empty.