updates to user guide

Author: MariusMerkleQC

docs/guides/features/data/current_load.csv

@@ -4,9 +4,9 @@ TXN-002,2024-03-01T09:15:00.000000,S1,R1,Bread,1,2.8,0.0,2.8,
 TXN-003,2024-03-01T10:02:00.000000,S1,R2,Eggs,1,3.2,0.0,3.1999999999,LC-1003
 TXN-004,2024-03-01T10:30:00.000000,S1,R2,Butter,3,1.9,0.1,5.6,LC-9999
 TXN-005,2024-03-01T11:00:00.000000,S1,R1,Cheese,1,4.5,0.0,4.5,
-TXN-006,2024-03-01T11:20:00.000000,S2,R4,Apples,4,1.5,0.2,5.8,LC-2001
-TXN-007,2024-03-01T11:45:00.000000,S2,R4,Chicken,2,10.8,1.0,20.6,LC-2002
-TXN-008,2024-03-01T12:10:00.000000,S2,R4,Rice,1,4.2,0.1,4.1,
+TXN-006,2024-03-01T11:20:02.000000,S2,R4,Apples,4,1.5,0.2,5.8,LC-2001
+TXN-007,2024-03-01T11:45:03.000000,S2,R4,Chicken,2,10.8,1.0,20.6,LC-2002
+TXN-008,2024-03-01T12:10:02.000000,S2,R4,Rice,1,1.5,0.2,1.3,
 TXN-009,2024-03-01T13:00:00.000000,S1,R1,Yogurt,2,1.2,0.0,2.4000000001,LC-1006
 TXN-010,2024-03-01T13:30:00.000000,S1,R2,Juice,3,3.0,0.0,9.0,
 TXN-013,2024-03-01T14:00:00.000000,S1,R1,Coffee,1,6.5,0.0,6.5,LC-1008

docs/guides/features/data/previous_load.csv

@@ -6,7 +6,7 @@ TXN-004,2024-03-01T10:30:00.000000,S1,R2,Butter,3,1.9,0.1,5.6,LC-1004
 TXN-005,2024-03-01T11:00:00.000000,S1,R1,Cheese,1,4.5,0.0,4.5,
 TXN-006,2024-03-01T11:20:00.000000,S2,R4,Apples,4,0.75,0.0,3.0,LC-2001
 TXN-007,2024-03-01T11:45:00.000000,S2,R4,Chicken,2,5.4,0.5,10.3,LC-2002
-TXN-008,2024-03-01T12:10:00.000000,S2,R4,Rice,1,2.1,0.0,2.1,
+TXN-008,2024-03-01T12:10:00.000000,S2,R4,Rice,1,0.75,0.0,0.75,
 TXN-009,2024-03-01T13:00:00.000000,S1,R1,Yogurt,2,1.2,0.0,2.4,LC-1006
 TXN-010,2024-03-01T13:30:00.000000,S1,R2,Juice,3,3.0,0.0,9.0,
 TXN-011,2024-03-01T08:00:00.000000,S2,R3,Soap,1,2.5,0.0,2.5,LC-2004

docs/guides/features/investigating.ipynb

@@ -1,10 +1,10 @@
 # Testing Utilities
 
-`diffly` provides assertion functions that print detailed summaries when DataFrames differ, making test failures easier to debug.
+`diffly` provides assertion functions that print detailed summaries when data frames differ, making test failures easier to debug.
 
 ## Asserting equality of frames
 
-Use {func}`~diffly.testing.assert_frame_equal` to compare two Polars DataFrames or LazyFrames in your tests:
+Use {func}`~diffly.testing.assert_frame_equal` to compare two Polars data frames or lazy frames in your tests:
 
 ```python
 from diffly.testing import assert_frame_equal

docs/guides/features/summary.ipynb

@@ -1,6 +1,6 @@
 # Diffly
 
-A utility package for comparing Polars DataFrames.
+A utility package for comparing `polars` data frames.
 
 ```{toctree}
 :maxdepth: 2
@@ -12,31 +12,31 @@ API Reference <api/modules>
 
 ## What is Diffly?
 
-Diffly is a utility package for comparing Polars DataFrames and LazyFrames with detailed analysis capabilities. It identifies differences between datasets including:
+Diffly is a utility package for comparing `polars` data frames and lazy frames with detailed analysis capabilities. It identifies differences between datasets including:
 
-- **Schema differences**: Columns that exist only in one DataFrame
-- **Row-level mismatches**: Rows that are different between DataFrames
-- **Missing rows**: Rows that exist only in one DataFrame
+- **Schema differences**: Columns that exist only in one data frame
+- **Row-level mismatches**: Rows that are different between data frames
+- **Missing rows**: Rows that exist only in one data frame
 - **Column value changes**: Detailed analysis of which columns differ and by how much
 
 ## Key Features
 
-- **Primary key-based comparison**: Join DataFrames on specified primary keys for row-by-row comparison
+- **Primary key-based comparison**: Join data frames on specified primary keys for row-by-row comparison
 - **Rich summaries**: Generate detailed, visually formatted comparison reports
-- **Lazy evaluation**: Uses Polars LazyFrames internally for efficient computation
 - **Tolerance-based equality**: Configure absolute and relative tolerances for floating point comparisons
+- **Lazy evaluation**: Uses `polars` lazy frames internally for efficient computation
 - **Temporal tolerance**: Support for comparing temporal types (dates, datetimes) with configurable tolerances
 - **Per-column tolerances**: Fine-grained control over comparison tolerances for each column
 - **Method caching**: Automatically caches comparison results to avoid recomputation
-- **Testing utilities**: Built-in assertion functions for DataFrame and Collection equality in tests
+- **Testing utilities**: Built-in assertion functions for data frame and collection equality in tests
 
 ## Quick Example
 
 ```python
 import polars as pl
 from diffly import compare_frames
 
-# Create two DataFrames to compare
+# Create two data frames to compare
 left = pl.DataFrame({
     "id": ["a", "b", "c"],
     "value": [1.0, 2.0, 3.0],
@@ -47,22 +47,55 @@ right = pl.DataFrame({
     "value": [1.0, 2.5, 4.0],
 })
 
-# Compare the DataFrames
+# Compare the data frames
 comparison = compare_frames(left, right, primary_key="id")
 
 # Check if they're equal
 if not comparison.equal():
     # Display a detailed summary
     summary = comparison.summary(
         top_k_column_changes=1,
-        show_sample_primary_key_per_change=True
+        show_sample_primary_key_per_change=True,
     )
     print(summary)
 ```
 
+This prints a rich summary showing schema differences, row counts, match rates, and top value changes:
+
+```
+┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+┃                                     Diffly Summary                                     ┃
+┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+   Primary key: id
+
+ Schemas
+ ▔▔▔▔▔▔▔
+   Schemas match exactly (column count: 2).
+
+ Rows
+ ▔▔▔▔
+   Left count             Right count
+       3      (no change)      3
+
+   ┏━┯━┯━┯━┯━┓
+   ┃-│-│-│-│-┃                1  left only   (33.33%)
+   ┠─┼─┼─┼─┼─┨╌╌╌┏━┯━┯━┯━┯━┓╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╮
+   ┃ │ │ │ │ ┃ = ┃ │ │ │ │ ┃  1  equal       (50.00%)  │
+   ┠─┼─┼─┼─┼─┨╌╌╌┠─┼─┼─┼─┼─┨╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌├╴  2  joined
+   ┃ │ │ │ │ ┃ ≠ ┃ │ │ │ │ ┃  1  unequal     (50.00%)  │
+   ┗━┷━┷━┷━┷━┛╌╌╌┠─┼─┼─┼─┼─┨╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╯
+                 ┃+│+│+│+│+┃  1  right only  (33.33%)
+                 ┗━┷━┷━┷━┷━┛
+
+ Columns
+ ▔▔▔▔▔▔▔
+   ┌───────┬────────┬───────────────────────────┐
+   │ value │ 50.00% │ 2.0 -> 2.5 (1x, e.g. "b") │
+   └───────┴────────┴───────────────────────────┘
+```
+
 ## Next Steps
 
-- Follow the [Quickstart Guide](guides/quickstart.ipynb) for a comprehensive introduction
-- Explore [Examples](guides/examples/index.md) for common use cases
-- Learn about advanced [Features](guides/features/index.md) like tolerances and custom summaries
+- Follow the [Quickstart Guide](guides/quickstart.ipynb) for a hands-on introduction
+- Learn about [Features](guides/features/index.md) like summaries, tolerances, and investigation tools
 - Check the [API Reference](api/modules.rst) for detailed function documentation