Add TopiaryResult wrapper with provenance tracking#112
Merged
Conversation
TopiaryResult bundles a predictions DataFrame with its metadata — model versions, source files, form (long/wide), filter/sort history — so that provenance survives through transformations and serialization round-trips. **TopiaryResult (topiary/result.py, new):** - Fields live directly on the result (no .metadata indirection): topiary_version, form, models, sources, filter_by_str/ast, sort_by_str/ast, extra. Plus `.metadata` compat property. - Delegates DataFrame operations (__len__, __iter__, __getitem__, __contains__, columns, shape, empty, head, tail, iterrows, itertuples) so existing DataFrame-style code keeps working. - `to_wide()` / `to_long()` — form conversion preserves metadata. - `to_tsv()` / `to_csv()` — writes comment-block metadata. - Construction: TopiaryResult(df, **kwargs) or TopiaryResult(df, metadata). **concat():** - Merges TopiaryResults, unioning models (warns on version conflicts), concatenating sources, preserving filter/sort only if all inputs agree. - Raises on mixed forms (long + wide). **IO provenance (topiary/io.py):** - Metadata gains `sources: list[str]` field; multiple #source= lines in the comment block. - read_tsv/read_csv return TopiaryResult (breaking change). - Both accept optional `tag=` to label the rows; defaults to filename. - Auto-populates a `source` column on the DataFrame if not present. **Legacy filter stringification (will be replaced by #111):** - EpitopeFilter/ColumnFilter/ExprFilter/RankingStrategy gained to_expr_string() producing parseable DSL syntax and to_ast_string() producing canonical structural form. These will be removed when the DSL refactor lands (see #111). **README/pyproject:** - Description updated: "Predict, filter, and rank MHC-presented peptides from any antigen source" - Removed obsolete mhctools version requirement line. Bump to 4.12.0 (breaking: read_tsv/read_csv return TopiaryResult instead of (df, Metadata) tuple). See #109 for the full wrapper design discussion and #111 for the follow-on DSL refactor.
- Add 26 tests for filter_by() and sort_by() covering string and DSL object inputs, history recording (AND for filter, replace for sort), empty-df noop, metadata preservation, TSV round-trip, and immutability. - Add 5 tests for concat()'s history-drop warning behavior. - concat() now warns via UserWarning when filter_by or sort_by metadata is discarded because inputs disagree. - Collapse duplicate .metadata / _as_metadata() into one public .metadata property. - Document pandas semantics of __contains__ / __iter__ in the class docstring (membership checks columns not rows; iteration yields column names). - Tighten filter_by_ast / sort_by_ast docstrings to describe the current types and the & contract. - Add CHANGELOG entry for 4.12.0 breaking read_tsv/read_csv return type.
In CI environments without mhcflurry package/model files, mhctools does not expose MHCflurry via inspect.getmembers. Skip rather than fail so the test is a no-op when the dependency is unavailable.
|
coverage: 84.431% (-2.9%) from 87.363% — topiary-result into master |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds
TopiaryResult— a wrapper that bundles a predictions DataFrame with its metadata (model versions, source files, form, filter/sort history) — plus aconcat()function for merging results with provenance preserved across the merge.read_tsv/read_csvreturnTopiaryResult(breaking: was(df, Metadata))sourcecolumn andMetadata.sourcesfrom the filename (overridable viatag=)concat([r1, r2])merges model maps (warns on version conflicts), concatenates sources, preserves filter/sort only if all inputs agree, raises on mixed formsto_expr_string()/to_ast_string()to legacy filter classes as a stopgap (see DSL refactor: unify filter leaves + vectorize eval #111 for the full DSL refactor that removes them)Bumps to 4.12.0. 760 tests pass.
See #109 for the wrapper design. Follow-on DSL cleanup in #111.
Test plan
test_result.pycover construction, delegation, form conversion, serialization, loader source-tracking, concat semantics (basic, sources-merged, models-union, version-conflict-warns, mixed-forms-raises, empty, single, roundtrip)