Skip to content

atomref.transfer

Transfer models describe how missing target values may be restored from other sources.

In the current runtime the built-in models are:

  • direct substitution (SubstitutionTransfer),
  • one-predictor linear transfer (LinearTransfer).

A transfer source may be:

  • a packaged dataset reference,
  • a custom ElementScalarSet,
  • a generic ValuePolicy,
  • a wrapper policy that exposes as_value_policy().

LinearTransfer currently accepts exactly one predictor source at runtime, even though the public API stores predictors as a tuple for forward compatibility.

For policy-backed linear predictors, LinearTransfer separates two questions:

  • which nested predictor values may be used to fit the linear model (fit_sources, fit_max_depth), and
  • which nested predictor values may be used to predict the final requested element (prediction_sources, prediction_max_depth).

The defaults are intentionally conservative:

  • fit only on nested predictor values that came directly from base or override,
  • but allow one additional nested transfer step when evaluating the predictor for the requested element.

That default is meant for workflows such as a sparse X–H target set correlated against a partial covalent-radii policy that is itself completed from a broader support set.

atomref.transfer

Transfer-model configuration types for policy-based lookup.

TransferModel = SubstitutionTransfer | LinearTransfer module-attribute

Closed union of transfer models supported by the core resolver.

TransferValueSource = Literal['override', 'base', 'transfer_substitution', 'transfer_linear', 'fallback'] module-attribute

Source labels that may be admitted into nested linear-transfer workflows.

LinearFit dataclass

Summary statistics for a fitted linear transfer model.

Parameters are stored in a compact, serializable form so they can be attached to :class:atomref.policy.LookupResult objects and reused in reporting code.

LinearTransfer dataclass

Infer missing target values from one or more predictor datasets or policies.

In the current implementation the public API stores predictors as a tuple for forward compatibility, but the runtime intentionally accepts exactly one predictor source.

For nested policy predictors, two safeguards apply:

  • fit_sources / fit_max_depth control which predictor values may be used when fitting the linear model itself;
  • prediction_sources / prediction_max_depth control which nested predictor values may be used for the final requested element.

The defaults are intentionally conservative for fitting and permissive only enough to allow one additional completion step at prediction time.

__post_init__()

Validate obvious configuration errors eagerly.

SubstitutionTransfer dataclass

Use another dataset or policy directly when the base dataset is missing.

The selected value is copied from the source rather than inferred.

SupportsValuePolicy

Bases: Protocol

Protocol for wrapper objects that can expose a generic value policy.

as_value_policy()

Return the generic element-domain value policy.