PIT Target Policy

alphaforge.pit.target

Target policy — release-selection logic for PIT series.

Provides :class:TargetPolicy and helpers for resolving target values from point-in-time release streams. The functions are generic and work with any :class:~alphaforge.pit.adapters.base.PITAdapter implementation.

TargetPolicy dataclass

Configuration for selecting a target value from available releases.

Attributes:

Name	Type	Description
mode	Literal['latest_available', 'nth_release', 'next_release']	Selection strategy. "latest_available" — pick the most recent non-null release. "nth_release" — pick exactly the n-th non-null release. "next_release" — signal the rank of the next expected release.
nth	int | None	Required when mode is "nth_release". Must be >= 1.
max_release_rank	int | None	Optional cap on the number of releases considered.

get_quarterly_release_observation_stream(adapter: PITAdapter, *, series_key: str, ref_quarter: str | pd.Period, asof_date: date, max_release_rank: int | None = None, obs_date_anchor: Literal['end', 'start'] = 'end') -> pd.DataFrame

Return a time-ordered observation stream of quarterly releases.

list_quarterly_target_releases_asof(adapter: PITAdapter, *, series_key: str, ref_quarter: str | pd.Period, asof_date: date, obs_date_anchor: Literal['end', 'start'] = 'end') -> pd.DataFrame

List available quarterly releases up to an as-of date.

Parameters:

Name	Type	Description	Default
adapter	PITAdapter	PIT adapter that supports list_pit_observations_asof.	required
series_key	str	PIT series key for the target series.	required
ref_quarter	str | Period	Quarterly reference in YYYYQn format or a pandas Period.	required
asof_date	date	Vintage cut-off date (treated as end-of-day UTC).	required
obs_date_anchor	Literal['end', 'start']	Observation date anchor policy.	'end'

Returns:

Type	Description
DataFrame	DataFrame sorted by asof_utc (ascending) with columns:
DataFrame	obs_date (quarter start/end per anchor), asof_utc (release timestamp),
DataFrame	and value.

list_quarterly_target_releases_asof_multi(adapter: PITAdapter, *, series_key: str, ref_quarters: Iterable[str | pd.Period], asof_date: date, obs_date_anchor: Literal['end', 'start'] = 'end') -> dict[str, pd.DataFrame]

Batch release lookup for multiple quarterly references at the same as-of date.

quarter_end_date(ref_quarter: str | pd.Period | RefPeriod) -> date

Return the quarter-end date for a reference quarter.

Parameters:

Name	Type	Description	Default
ref_quarter	str | Period | RefPeriod	Quarterly reference in YYYYQn format or a pandas Period (e.g., "2025Q1", pd.Period("2025Q1", freq="Q")).	required

Returns:

Type	Description
date	The calendar quarter-end date.

Raises:

Type	Description
ValueError	If the reference quarter does not match YYYYQn.

quarter_obs_date(ref_quarter: str | pd.Period | RefPeriod, obs_date_anchor: Literal['end', 'start'] = 'end') -> date

Return the quarter observation date under the configured anchor policy.

quarter_start_date(ref_quarter: str | pd.Period | RefPeriod) -> date

Return the quarter-start date for a reference quarter.

resolve_quarterly_final_target(adapter: PITAdapter, *, series_key: str, ref_quarter: str | pd.Period, evaluation_asof_date: date, policy: TargetPolicy = TargetPolicy(mode='nth_release', nth=3, max_release_rank=3), obs_date_anchor: Literal['end', 'start'] = 'end') -> tuple[float | None, dict]

Resolve a final target value for a quarterly reference.

Parameters:

Name	Type	Description	Default
adapter	PITAdapter	PIT adapter that supports list_pit_observations_asof.	required
series_key	str	PIT series key for the target series.	required
ref_quarter	str | Period	Quarterly reference in YYYYQn format or a pandas Period.	required
evaluation_asof_date	date	As-of date used to resolve the final target proxy.	required
policy	TargetPolicy	Target selection policy (defaults to nth_release=3 capped to 3 releases).	TargetPolicy(mode='nth_release', nth=3, max_release_rank=3)
obs_date_anchor	Literal['end', 'start']	Observation date anchor policy.	'end'

Returns:

Type	Description
tuple[float | None, dict]	Tuple of (value, metadata) from resolve_target_from_releases.

resolve_target_from_releases(releases: pd.DataFrame, policy: TargetPolicy) -> tuple[float | None, dict]

Resolve a target value from available releases.

Parameters:

Name	Type	Description	Default
releases	DataFrame	DataFrame containing obs_date, asof_utc, and value columns.	required
policy	TargetPolicy	Target policy configuration.	required

Returns:

Type	Description
float | None	Tuple of (value, metadata). value is None if the policy cannot select
dict	a release. Metadata includes:
tuple[float | None, dict]	policy_mode, selected_release_rank, selected_release_asof_utc,
tuple[float | None, dict]	target_release_rank, available_release_ranks, n_releases_available,
tuple[float | None, dict]	and obs_date. selected_* fields only describe an available release,
tuple[float | None, dict]	while target_release_rank is used to signal a future (next) release.

Raises:

Type	Description
ValueError	If the policy configuration is invalid.

resolve_target_obs_date_anchor(target_obs_date_anchor: Literal['auto', 'end', 'start'], *, target_series_key: str, catalog: SeriesCatalog | None) -> Literal['end', 'start']

Resolve the effective target observation anchor.

Resolution policy: 1. Explicit "start" or "end" is honored. 2. "auto" uses catalog metadata obs_date_anchor for the target series. 3. If metadata is missing/unknown, fallback is "end".