openquant.availability

Pure Python. Signatures are as written in the source; descriptions are the docstrings. All Python modules.

Examples and interpretation: availability.

Find an API by task

Audit supplied source-availability and label-maturity clocks before fitting.

This module is implemented using only the Python standard library. The package's normal openquant import still initializes its native extension and other existing dependencies; direct-file tests do not establish full-package readiness.

The helper is a conservative historical-vintage filter, not a cross-validation splitter. It cannot reconstruct revisions, authenticate timestamps, establish statistical independence, or replace purging, embargo or fold-local preprocessing.

Classes

AvailabilitySelection

class AvailabilitySelection(NamedTuple)

Immutable original-row selection and explicit exclusion reasons.

candidate_indices and eligible_indices preserve supplied candidate order. exclusions contains (original_index, reasons) tuples in that same relative order. Every candidate occurs in exactly one output partition. A row can have multiple reasons. fit_time_ns is exact UTC Unix nanoseconds.

Functions

select_available_training

select_available_training(
    decision_times: Iterable[Timestamp],
    label_end_times: Iterable[Timestamp | None],
    label_available_times: Iterable[Timestamp | None],
    feature_available_times: Iterable[Timestamp | None],
    *,
    fit_time: Timestamp,
    clock: Clock,
    label_end_inclusive: bool = False,
    candidate_indices: Iterable[int] | None = None,
) -> AvailabilitySelection

Filter original sample indices using declared information-availability clocks.

Parameters

decision_times

Historical sample decisions. Missing decisions are invalid. Ties and arbitrary row order are allowed; this function does not sort or split.

label_end_times

End of each label's information span; None means unresolved/unknown. Known ends cannot precede their decisions. Zero-length spans are valid.

label_available_times

Actual usable publication time of the finalized label; None means unknown/unreleased. Known publication cannot precede decision or known label end. A resolution timestamp alone is not a publication timestamp.

feature_available_times

Latest actual source/revision availability needed for ALL exact historical raw/source feature values in each row, BEFORE fold-local learned transforms. None means unknown/missing information. This is not a batch computed_at time: deterministic reconstruction from past-only inputs can run later. The caller must preserve source metadata, align it with the retained rows, and fit learned transforms only within training folds. A scaler or PCA fitted at fit_time on eligible training rows can legitimately depend on later training rows relative to an individual historical decision. Do not pass that transform's fitted_at as source availability. Audit historical source snapshots, intersect the splitter's training indices, then fit learned transforms/model on those training rows and apply them to held-out rows. This helper inspects no feature values or learned preprocessing state.

fit_time

Cutoff at which information published at that exact time is already usable. Sample decisions must be strictly earlier than this cutoff.

clock

Required explicit clock domain. unix_ns accepts exact integer UTC Unix nanoseconds in int64 range, excluding the NaT sentinel. utc accepts aware builtin datetime or extended ISO strings with seconds, at most six fractional digits, and Z or a known ±HH:MM offset. Naive clocks, unknown -00:00, submicrosecond strings, offset seconds in strings, datetime subclasses, floating epoch seconds and implicit bar positions are not converted. Builtin aware datetime objects may carry valid subminute/fractional timezone offsets, normalized exactly here. Use explicit integer nanoseconds for finer observation clocks.

label_end_inclusive

False by default: label end must be strictly before fit. This conservative boundary excludes a closed label span ending exactly where a test window starts at fit. True permits equality under an after-observation maturity convention. Label publication still must be at or before fit in both modes. Neither convention replaces purging against actual test intervals.

candidate_indices

Optional pre-existing splitter's train indices. The result is only a subset of these indices in their supplied order, never a replacement split. Indices must be unique and in range. None audits all rows.

Returns

AvailabilitySelection

Immutable original indices and explicit reasons, suitable for indexing the same aligned feature/label arrays. None clocks cause row exclusions; malformed clocks, length mismatches and known chronology inconsistencies raise ValueError, including on noncandidate rows. Inputs are not mutated.

Notes

clean_ohlcv currently discards extra metadata and emits UTC-naive microseconds. Preserve availability and stable row identity separately before cleaning; explicitly attach UTC only when that upstream contract is verified. Never reconstruct source availability from event time or silently realign by position after cleaning dropped or sorted rows. CV's t1 is label resolution, and its integer input may mean bars; callers must explicitly convert actual UTC clocks here. Passing arbitrary integers cannot prove their physical units.