fs.diff()

When to Use It

Use before retraining a machine learning model. If a new version of the training dataset contains removed columns or severe missing value regressions, this function catches them before a model training run is initiated.

Parameters

• old: Dataset | str | DataFrame. The older snapshot path or object.
• new: Dataset | str | DataFrame. The newer snapshot path or object.
• target_column: str | None (default None). The target column for target-aware leakage comparisons.
• max_correlation_columns: int (default 100). Cap limit for correlation computations during snapshot profiling.
• max_frequency_table_size: int (default 1000). Frequency table size limit.

Return Value

Returns a frozen DatasetDiffResult dataclass containing:

• version: str (currently "0.2.0").
• schema: SchemaDiff containing columns added, removed, renamed, and data type changes.
• structure: StructureDiff showing row/column deltas.
• missing_values: Per-column missingness deltas (MissingValueDiff), each classified as new, resolved, regressed, improved, or unchanged.
• duplicates: Duplicate rows count and percentage shifts.
• constant_columns: Newly constant and no longer constant columns.
• cardinality: Per-column cardinality changes.
• statistics: Deltas for basic numeric metrics (mean, median, std_dev, minimum, maximum).
• distributions: Significant mean shifts.
• leakage: Target leakage deltas (new, removed, escalated, or de-escalated patterns).
• summary: DatasetDiffSummary showing counts and overall health (regressed, improved, or unchanged).
• overall_summary: One-line templated summary.

SDK Example

1import featuresmith as fs
2
3result = fs.diff("v1.csv", "v2.csv", target_column="churn")
4
5print(result.overall_summary)
6print(f"Status: {result.summary.overall_health}")
7print(f"Recommendation: {result.summary.recommendation}")

Output Example

1# result.overall_summary
2'Rows 0 removed, 100 added; columns 0 removed, 1 added; overall health: improved.'
3
4# result.summary.recommendation
5'Dataset improved: missingness reduced in 2 column(s). No blocking regressions detected.'

Common Workflows

• Retraining Pipeline Gates: Programmatically diff input versions before initiating a training loop, rejecting the job if the overall health returns "regressed".
• Schema Drift Detection: Verify that no data types were silently modified or key features dropped during upstream extraction updates.

Diff Helper Functions

The featuresmith package re-exports two public helper functions for working with DatasetDiffResult:

1import featuresmith as fs
2
3# 1. Extract RuleFinding objects from a DatasetDiffResult
4findings = fs.diff_findings(result)
5
6# 2. Render console text report for a DatasetDiffResult
7report_text = fs.render_diff(result, target="console")

• fs.diff_findings(result: DatasetDiffResult) -> list[RuleFinding]: Converts diff status changes (such as dropped columns, missingness regressions, and leakage status changes) into standard RuleFinding objects for severity-based filtering and CI gating.
• fs.render_diff(result: DatasetDiffResult, target: str = "console") -> str: Renders a formatted string report for terminal display or text export.

Notes and Limitations

• Integrated Diff Reviewer: The Dataset Diff Engine is also available as the review.diff reviewer inside the Review Engine. Calling fs.review(previous=...) activates the DiffReviewer, which attaches the DatasetDiffResult to result.diff.
• Advisory Recommendations: Findings and overall health recommendations are purely advisory and do not automatically mutate data or abort processes unless coded into your caller logic.
• Diff Findings Accessor: Use fs.diff_findings(result) to derive standard RuleFinding objects from a diff result. The CLI's diff command consumes these findings for severity-based exit-code gating.

Related Documentation

See the CLI counterpart featuresmith diff and the review reference fs.review().