Input panel

The shared dataframe contract

One row contains one source’s value for a subject at one availability time. A subject is identified by entity, period and target together.

Column Type Required Meaning
entity string Yes Company or series identifier
period string Yes Opaque fiscal-period label
period_end UTC datetime Yes Period ordering date
target string Yes Quantity being estimated
source string Yes Observation source
value numeric Yes Value in common input units
known_at UTC datetime Yes When the observation became available
estimate_count numeric No Consensus contributor count
dispersion numeric No Consensus standard deviation in level units

Validation

  • Entry point: validate_estimates returns the validated panel in canonical subject, source and availability order, with a fresh index.
  • Numeric types: value, estimate_count and dispersion come back as float64, so a prepared frame carries one dtype per column at every reading moment.
  • Timestamps: known_at and period_end must be UTC-aware. Convert from the known source timezone before calling; naive or non-UTC timestamps are refused.
  • Keys: Subject keys, source and timestamps cannot be missing.
  • Uniqueness: A subject and source cannot have two rows at the same known_at.
  • Period consistency: Every row for a subject must agree on period_end.
  • Errors: Malformed data raises PanelError. Valid data with unusable values is handled according to the chosen method’s eligibility rules.

Reading moments

validate_readings(readings, panel) checks a frame that asks for one read per row, as prepare_anchored_subjects_each and prepare_bayesian_subjects_each take it.

  • Columns: entity, period, target, period_end and as_of. Other columns are dropped.
  • Moments: as_of is a UTC-aware datetime, never missing. It keeps its own resolution, so a reading finer than the panel’s timestamps is never truncated.
  • Dtypes: Subject keys and period_end are converted to the panel’s dtypes, so readings built apart from the panel join against it.
  • Uniqueness: A subject can be read at most once per as_of.
  • Period consistency: A reading’s period_end must agree with the panel.
  • Errors: Every problem with the frame itself is reported in one PanelError.

Sources and availability

  • actual: Reported outcomes used for Bayesian history.
  • consensus: The default analyst-consensus source; both main methods allow a different consensus source name.
  • Forecast sources: Other identifiers belong to the caller. Pass the intended one explicitly as forecast_source.
  • Reading cutoff: as_of is UTC-aware. Preparation reads only known_at < as_of.
  • Age: Observation age is measured from known_at, not period_end.
  • Revisions: Retain availability timestamps for every revision. Actual-release selection differs between APIs; see the posterior contract.

The input-panel tutorial demonstrates validation failures.