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
The cash residual is \(e_n=C_n-\widehat C_n\), here \(29-30=-1\).
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:
Outcome |
|
|
|
|
|---|---|---|---|---|
All checks pass |
|
|
|
|
A check fails |
|
|
|
Varies |
Only assumed history |
|
|
|
|
Undecided with no failure |
|
|
|
|
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.
rowsnames a model_vector onmodel. Useiter_resultsfor a stream or call the validator for one window. Rows are mappings keyed byfieldsor sequences in that order. Convert framework-specific nulls toNone; 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 field_paths: tuple[tuple[str, ...], ...]
Nested paths for selecting source columns, in fields 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.
positionis a nonnegative Python integer counting rows from zero. Supply exactlymin(position + 1, window_size)rows; preceding rows supply observations but are not checked.indexdefaults 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).
- class modello.contrib.validation.ValidationResult(position: int, index: Hashable, checks: tuple[CheckResult, ...])
Row position, index label, and checks, including assumed or undecided ones.
- checks: tuple[CheckResult, ...]
All field checks, including passing, failing, assumed, and undecided ones.
- 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.
validis True for a pass, False for a proven violation, otherwise None. Row position and label belong to the containingValidationResult.- field: str
Flat field name, matching a key in
WindowValidator.fields.
- 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.
- 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;
completerequires a nonempty interval with every check decided.- first_invalid: ValidationResult | None
First row proving a violation, or None when none was proven.
- 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.