Validate recorded rows

The account walkthrough calculates balances from trades. When a statement already contains those balances, use WindowValidator.iter_results to check each posting against its recorded predecessor.

The ledger in examples.accounting_breaks starts with 40, buys two shares at 10 each, then sells one for 10. The sale should leave 30 in cash, but the statement records 29. Its cash and share balances obey

\[\widehat C_n = C_{n-1} + \Delta C_n, \qquad \widehat Q_n = Q_{n-1} + \Delta Q_n.\]

The cash residual is \(e_n=C_n-\widehat C_n\), here \(29-30=-1\).

Cash columns from the ledger

Event

Cash

Cash movement

Valid

Why

opening

40

0

Assumed

Opening balance is assumed.

purchase

20

-20

Yes

sale

29

10

No

Expected 30; shortfall 1.

repurchase

19

-10

Yes

Uses the recorded sale balance.

Find an accounting break

iter_results maintains the rolling history and yields one result per row. Collect the results to inspect the full sequence:

>>> from examples.accounting_breaks import EVENTS, Ledger, accounting_rows
>>> from modello.contrib.validation import WindowValidator
>>> rows = accounting_rows()
>>> validator = WindowValidator(Ledger, "rows")
>>> results = list(validator.iter_results(rows, labels=EVENTS))
>>> [result.valid for result in results]
[None, True, False, True]
>>> [result.index for result in results if result.invalid]
['sale']

Use invalid for proven failures; not result.valid also includes assumed or undecidable rows, whose valid is None. Checks before a law’s start are assumed. An order-\(p\) law normally starts at position \(p\), using \(p+1\) rows. first_test_position and fully_testable_position expose the earliest and latest declared starts. Later checks use recorded predecessors, so the repurchase passes after the sale fails.

What a result contains

A ValidationResult contains the zero-based position, the supplied index label (defaulting to the position), and a tuple of CheckResult objects in checks. Inspect the sale’s failing check:

>>> sale = next(result for result in results if result.invalid)
>>> sale.position, sale.index
(2, 'sale')
>>> problem = next(check for check in sale.checks if check.invalid)
>>> problem.field, problem.rule, problem.kind
('cash', 'posting', 'recurrence')
>>> problem.observed, problem.expected, problem.residual
(29, 30, -1)
>>> problem.reason
'observed differs from expected'

checks includes passing, failing, assumed, and undecidable checks. complete means every check reached a decision, including failures:

Row outcomes

Outcome

valid

invalid

assumed

complete

All checks pass

True

False

False

True

A check fails

False

True

False

Varies

Only assumed history

None

False

True

False

Undecided with no failure

None

False

False

False

Each CheckResult identifies its field, named rule, and kind (domain, definition, alias, or recurrence). valid, invalid, and assumed describe that check; start is its first applicable position. The containing result supplies the row’s position and label.

Equation residuals are observed minus expected. Assumed checks have no expected value or residual; unresolved dependencies can also leave them unknown. Domain checks report a numeric set as expected and no residual, while checking all field assumptions. observed captures accepted values as SymPy scalars when read; malformed cells retain their supplied value for inspection.

Audit coverage

For a finite job, audit scans all rows and summarises their coverage:

>>> audit = validator.audit(rows, labels=EVENTS)
>>> audit.row_count, audit.valid_rows, audit.invalid_rows, audit.assumed_rows, audit.unknown_rows
(4, 2, 1, 1, 0)
>>> audit.valid, audit.complete
(False, False)
>>> audit.first_invalid == sale
True

The four row counts partition the input and sum to row_count. first_invalid is a ValidationResult or None if no failure was proven; the summary stores no other row results. complete requires every check in a nonempty interval to be decided, so the assumed opening keeps it false here.

audit.valid is False for a proven failure, True only for a nonempty interval of passing rows, and otherwise None. A policy that trusts initial history can instead require no invalid or unknown rows and at least one valid row; empty and history-only inputs do not qualify.

To reuse collected results, call ValidationSummary.from_results(results). Positions must be contiguous from zero, or from an explicit start_position for a later interval. stop_position is the exclusive end.

Input and numerical values

Supply flat mappings keyed by validator.fields, or row tuples in that order. Convert framework-specific nulls to None; numeric NaN also means missing. Parse numeric text before validation. Symbolic values cannot prove numeric validity, but their assumptions can prove a domain violation. See the DataFrame recipes for pandas, Polars, and MultiIndex columns.

Validation checks the row schema’s domains, definitions, aliases, and fixed causal laws. Put per-event inputs in that schema: other vectors and parent aggregate or boundary constraints are outside its scope. Missing values and parameters are never inferred or filled.

Calculus and row-local series or process queries use the core model’s operator semantics. Ordinary equations use recorded field values.

Integers, Decimal, Fraction, and exact SymPy numbers retain exact arithmetic. Equation tolerances use abs(observed-expected) <= atol + rtol*abs(expected); domains remain strict. Scalar parameters must be independent model fields with valid domains and consistent aliases; omit the row-vector size, which comes from the input. Resolvable scalar definitions, including unused constants, are checked too. Conflicting or undecidable alias definitions are rejected.

Streams and manual windows

Consume iter_results directly for a stream. Flatten non-overlapping batches into one row iterator before calling it: each call resets history and starts at position zero. Batch sizes are independent of window_size; independent accounts need separate histories.

For externally managed windows or checkpoints, call the validator with the required history and absolute position. For example, recheck the sale:

>>> position = sale.position
>>> window = rows[max(0, position + 1 - validator.window_size):position + 1]
>>> validator(window, position=position, index=sale.index) == sale
True

Each call checks only the final row. Supply an oldest-first window of exactly min(position+1, validator.window_size) rows, including short initial windows. position is a nonnegative Python integer counting rows from the stream’s start; index labels and gaps do not change it.

API

Check recorded rows with WindowValidator, without solving missing values.

class modello.contrib.validation.WindowValidator(model, rows, *, parameters=None, atol=0, rtol=0)

Check a model’s observed row vector against its schema and causal laws.

rows names a model_vector on model. Use iter_results for a stream or call the validator for one window. Rows are mappings keyed by fields or sequences in that order. Convert framework-specific nulls to None; numeric NaN also means missing.

Parameters:
  • model – Model class declaring the row vector and its causal laws.

  • rows – Name of the model_vector to validate.

  • parameters – Independent scalar model fields needed by the laws, keyed by flat field name. Omit the vector size; input supplies it.

  • atol – Finite, nonnegative absolute equation tolerance; default zero.

  • rtol – Finite, nonnegative relative equation tolerance; default zero.

Raises:

ModelInputError – The model, parameters, tolerances, or causal laws cannot be prepared for window validation.

property fields: tuple[str, ...]

Flat mapping keys, in the required order for row tuples.

property field_paths: tuple[tuple[str, ...], ...]

Nested paths for selecting source columns, in fields order.

property order: int

Largest fixed lag referenced by the prepared laws.

property window_size: int

Required rolling-window width: order plus one.

property first_test_position: int

Earliest declared law start; often equal to order.

property fully_testable_position: int

Earliest position where all laws apply; values may still be undecidable.

__call__(window: ~collections.abc.Sequence[~collections.abc.Mapping[str, object] | ~collections.abc.Sequence[object]], *, position: int, index: ~collections.abc.Hashable = <object object>) → ValidationResult

Check the final row of an oldest-first window, without storing history.

position is a nonnegative Python integer counting rows from zero. Supply exactly min(position + 1, window_size) rows; preceding rows supply observations but are not checked. index defaults to position.

Bad row/window sizes, missing keys, invalid positions, and unhashable labels raise ModelInputError. Malformed scalars fail applicable domains.

iter_results(rows: Iterable[Mapping[str, object] | Sequence[object]], *, labels: Iterable[Hashable] | None = None) → Iterator[ValidationResult]

Yield one result per row, retaining at most window_size rows.

Each call starts at position zero; chain non-overlapping batches to keep history. Rows are converted once when read. Labels default to positions; supplied labels must be hashable and match the row count (ValueError on count mismatch).

audit(rows: Iterable[Mapping[str, object] | Sequence[object]], *, labels: Iterable[Hashable] | None = None) → ValidationSummary

Summarise the finite input, including its first invalid row and coverage.

class modello.contrib.validation.ValidationResult(position: int, index: Hashable, checks: tuple[CheckResult, ...])

Row position, index label, and checks, including assumed or undecided ones.

position: int

Absolute row position, counting from zero regardless of labels.

index: Hashable

Supplied row label, or position when no label was supplied.

checks: tuple[CheckResult, ...]

All field checks, including passing, failing, assumed, and undecided ones.

property invalid: bool

Whether any check proves this row invalid.

property complete: bool

Whether the row has checks and each reached a decision.

property assumed: bool

Whether the row contains only initial-history assumptions.

property valid: bool | None

False for a proven violation, True for complete success, otherwise None.

class modello.contrib.validation.CheckResult(field: str, rule: str, observed: object, expected: Basic | None, residual: Expr | None, valid: bool | None, reason: str = '', start: int = 0, kind: Literal['domain', 'definition', 'alias', 'recurrence'] = 'recurrence', assumed: bool = False)

One row’s check of a field domain, definition, alias, or recurrence.

valid is True for a pass, False for a proven violation, otherwise None. Row position and label belong to the containing ValidationResult.

field: str

Flat field name, matching a key in WindowValidator.fields.

rule: str

Declared recurrence name, or domain, definition, or alias.

observed: object

Recorded SymPy scalar, or the original cell when conversion failed.

expected: Basic | None

Expected expression or domain set; None for assumed or missing dependencies.

residual: Expr | None

Observed minus expected; None for domains, assumptions, or unresolved values.

valid: bool | None

True for a pass, False for a proven violation, otherwise None.

reason: str = ''

Explanation of a failure, assumption, or undecided check; empty for a pass.

start: int = 0

First absolute row position where this check applies.

kind: Literal['domain', 'definition', 'alias', 'recurrence'] = 'recurrence'

Whether this checks a domain, definition, alias, or recurrence.

assumed: bool = False

True when the row precedes start and this check was skipped.

property invalid: bool

Whether the check proves a violation.

class modello.contrib.validation.ValidationSummary(valid_rows: int, invalid_rows: int, assumed_rows: int, unknown_rows: int, complete: bool, first_invalid: ValidationResult | None, start_position: int = 0)

Disjoint row counts, coverage, and the first invalid row of an interval.

Assumed rows contain only initial-history checks. Unknown rows have no proven failure but remain undecided. Invalid rows can have undecided checks too; complete requires a nonempty interval with every check decided.

valid_rows: int

Rows whose checks all passed.

invalid_rows: int

Rows with at least one proven violation, including otherwise undecided rows.

assumed_rows: int

Rows containing only initial-history assumptions.

unknown_rows: int

Other undecided rows without a proven violation.

complete: bool

Whether the interval is nonempty and every check reached a decision.

first_invalid: ValidationResult | None

First row proving a violation, or None when none was proven.

start_position: int = 0

Inclusive start of the audited interval, counting from zero.

classmethod from_results(results: Iterable[ValidationResult], *, start_position: int = 0) → ValidationSummary

Summarise every position from start_position in order; default zero.

Gaps, duplicates, or reordering raise ModelInputError. Preceding history is outside the audited interval.

property row_count: int

Total rows in the audited interval.

property stop_position: int

Exclusive end of the audited interval.

property invalid: bool

Whether the audited interval contains a proven invalid row.

property valid: bool | None

False for any violation, True for nonempty all-valid input, otherwise None.