Backup

Author: raffaelemancuso

README.md

@@ -16,8 +16,8 @@ API Reference
 ## Highlights
 
 - **STATA-like logging** — wrap a pandas/polars pipeline in `startlog()` / `endlog()`
-  and get a log line describing how many rows, columns, or cell values changed (and
-  optionally how long it took).
+  and get a log line describing how many rows, columns, or cell values changed (plus
+  the new shape when rows or columns are added/removed, and optionally how long it took).
 - **`.docx` export** — write any DataFrame straight to a Word table with `to_docx()`.
 - **Frequency & cross tables** — `freq()` and `crosstab()` accessors for quick
   tabulations.
@@ -79,7 +79,7 @@ df = pd.DataFrame(
 
 # Shape changes are logged automatically
 _ = df.raffa.startlog().dropna(subset=["bill_depth_mm"]).raffa.endlog(timeit=False)
-# -> Removed 2/6 (33.33%) rows.
+# -> Removed 2/6 (33.33%) rows. New shape: (4, 3).
 
 # Pass clone=True to also detect value-level changes when the shape is unchanged
 _ = df.raffa.startlog(clone=True).fillna(0).raffa.endlog(timeit=False)
@@ -104,7 +104,7 @@ df = pl.DataFrame(
 )
 
 _ = df.raffa.startlog().filter(pl.col("species") == "Adelie").raffa.endlog(timeit=False)
-# -> Removed 3/6 (50.00%) rows.
+# -> Removed 3/6 (50.00%) rows. New shape: (3, 3).
 ```
 
 Both backends share the same `startlog(clone=False)` / `endlog(custom_msg=None, timeit=True)`

docs/source/examples.rst

@@ -19,7 +19,8 @@ change logging to a Series or DataFrame.
 
 The pattern is always the same: call ``startlog()`` before an operation and
 ``endlog()`` after it. ``endlog`` logs how the data changed — rows or columns
-added/removed or, when the shape is unchanged, how many cell values changed.
+added/removed (followed by the resulting shape) or, when the shape is unchanged,
+how many cell values changed.
 
 ``startlog(clone=False)``
    Snapshots the current shape (and a timestamp). Pass ``clone=True`` to also
@@ -85,17 +86,17 @@ Removing rows, filtering, or dropping columns changes the shape, which is
 logged automatically:
 
 >>> _ = df.raffa.startlog().dropna(subset=["bill_depth_mm"]).raffa.endlog(timeit=False)
-Removed 2/10 (20.00%) rows.
+Removed 2/10 (20.00%) rows. New shape: (8, 8).
 >>> _ = df.raffa.startlog().query("species=='Adelie'").raffa.endlog(timeit=False)
-Removed 5/10 (50.00%) rows.
+Removed 5/10 (50.00%) rows. New shape: (5, 8).
 >>> _ = df.raffa.startlog().drop(["bill_length_mm", "bill_depth_mm"], axis=1).raffa.endlog(timeit=False)
-Removed 2/8 (25.00%) columns.
+Removed 2/8 (25.00%) columns. New shape: (10, 6).
 
 With the default ``timeit=True``, ``endlog`` appends the elapsed time on a
 second line (the duration varies from run to run):
 
 >>> _ = df.raffa.startlog().dropna(subset=["bill_depth_mm"]).raffa.endlog()
-Removed 2/10 (20.00%) rows.
+Removed 2/10 (20.00%) rows. New shape: (8, 8).
 Took: ...
 
 Operations that change values but not the shape need ``clone=True`` so the
@@ -110,7 +111,7 @@ The same accessor is available on a Series:
 
 >>> s = df["bill_length_mm"]
 >>> _ = s.raffa.startlog().dropna().raffa.endlog(timeit=False)
-Removed 2/10 (20.00%) values.
+Removed 2/10 (20.00%) values. New shape: (8,).
 >>> _ = s.raffa.startlog(clone=True).fillna(0).raffa.endlog(timeit=False)
 Changed 2/10 (20.00%) values.
 
@@ -264,17 +265,17 @@ Removing rows with nulls, filtering values, or selecting columns changes the
 shape, which is logged:
 
 >>> _ = df.raffa.startlog().drop_nulls(subset=["bill_depth_mm"]).raffa.endlog(timeit=False)
-Removed 2/10 (20.00%) rows.
+Removed 2/10 (20.00%) rows. New shape: (8, 8).
 >>> _ = df.raffa.startlog().filter(pl.col("species")=="Adelie").raffa.endlog(timeit=False)
-Removed 5/10 (50.00%) rows.
+Removed 5/10 (50.00%) rows. New shape: (5, 8).
 >>> _ = df.raffa.startlog().select(pl.exclude(["bill_length_mm", "bill_depth_mm"])).raffa.endlog(timeit=False)
-Removed 2/8 (25.00%) columns.
+Removed 2/8 (25.00%) columns. New shape: (10, 6).
 
 As with pandas, the default ``timeit=True`` appends the elapsed time on a second
 line (the duration varies from run to run):
 
 >>> _ = df.raffa.startlog().filter(pl.col("species")=="Adelie").raffa.endlog()
-Removed 5/10 (50.00%) rows.
+Removed 5/10 (50.00%) rows. New shape: (5, 8).
 Took: ...
 
 Operations that change values but not the shape need ``clone=True``:

docs/source/index.rst

@@ -47,7 +47,7 @@ A taste
        }
    )
    df = df.raffa.startlog().dropna(subset=["bill_depth_mm"]).raffa.endlog()
-   # -> Removed 2/6 (33.33%) rows.
+   # -> Removed 2/6 (33.33%) rows. New shape: (4, 3).
    # -> Took: 0.01 seconds
 
 New here? Start with :doc:`quickstart`, then browse the :doc:`examples` for the

docs/source/quickstart.rst

@@ -46,9 +46,9 @@ to log how the data changed:
 ...         "body_mass_g": [3750.0, 3800.0, np.nan, 4500.0, 5700.0, 3500.0],
 ...     }
 ... )
->>> # Row/column count changes are logged automatically
+>>> # Row/column count changes are logged automatically, with the resulting shape
 >>> _ = df.raffa.startlog().dropna(subset=["bill_depth_mm"]).raffa.endlog(timeit=False)
-Removed 2/6 (33.33%) rows.
+Removed 2/6 (33.33%) rows. New shape: (4, 3).
 >>> # Pass clone=True to also detect value-level changes when the shape is unchanged
 >>> _ = df.raffa.startlog(clone=True).fillna(0).raffa.endlog(timeit=False)
 Changed 3/18 (16.67%) values.
@@ -65,7 +65,7 @@ The polars accessor works identically:
 ...     }
 ... )
 >>> _ = df.raffa.startlog().filter(pl.col("species") == "Adelie").raffa.endlog(timeit=False)
-Removed 3/6 (50.00%) rows.
+Removed 3/6 (50.00%) rows. New shape: (3, 3).
 
 Timing each step
 ----------------
@@ -75,7 +75,7 @@ the default ``timeit=True``, ``endlog`` appends the wall-clock time the step too
 on a second line (the duration varies from run to run):
 
 >>> _ = df.raffa.startlog().filter(pl.col("species") == "Adelie").raffa.endlog()
-Removed 3/6 (50.00%) rows.
+Removed 3/6 (50.00%) rows. New shape: (3, 3).
 Took: ...
 
 Next steps

src/raffalib/_logutils.py

@@ -75,24 +75,61 @@ def count_delta(delta: int, total: int, unit: str) -> str:
     return ""
 
 
+def new_shape(shape: tuple[int, ...]) -> str:
+    """
+    Report the shape a DataFrame or Series has after rows or columns were
+    added or removed.
+
+    :param shape: The shape tuple after the operation (``(n,)`` for a Series,
+        ``(n_rows, n_cols)`` for a DataFrame).
+    :type shape: tuple[int, ...]
+    :return: A message like ``"New shape: (8, 6)."``.
+    :rtype: str
+    """
+    return f"New shape: {shape}."
+
+
+def series_shape_delta(initial_shape: tuple[int], final_shape: tuple[int]) -> str:
+    """
+    Describe how a Series' length changed and report its new shape.
+
+    :param initial_shape: ``(n,)`` before the operation.
+    :type initial_shape: tuple[int]
+    :param final_shape: ``(n,)`` after the operation.
+    :type final_shape: tuple[int]
+    :return: The value-count change followed by the new shape, or an empty
+        string when the length did not change.
+    :rtype: str
+    """
+    delta = count_delta(initial_shape[0] - final_shape[0], initial_shape[0], "values")
+    if not delta:
+        return ""
+    return f"{delta} {new_shape(final_shape)}"
+
+
 def dataframe_shape_delta(
     initial_shape: tuple[int, int], final_shape: tuple[int, int]
 ) -> str:
     """
-    Describe how a DataFrame's row and column counts changed.
+    Describe how a DataFrame's row and column counts changed and report its
+    new shape.
 
     :param initial_shape: ``(n_rows, n_cols)`` before the operation.
     :type initial_shape: tuple[int, int]
     :param final_shape: ``(n_rows, n_cols)`` after the operation.
     :type final_shape: tuple[int, int]
-    :return: The concatenated row and column change messages.
+    :return: The concatenated row and column change messages followed by the
+        new shape, or an empty string when neither changed.
     :rtype: str
     """
     nrow0, ncol0 = initial_shape
     nrow1, ncol1 = final_shape
-    return count_delta(nrow0 - nrow1, nrow0, "rows") + count_delta(
+    delta = count_delta(nrow0 - nrow1, nrow0, "rows") + count_delta(
         ncol0 - ncol1, ncol0, "columns"
     )
+    if not delta:
+        return ""
+    return f"{delta} {new_shape(final_shape)}"
 
 
 def changed_cells(nchanged: int, ntotal: int) -> str:

src/raffalib/pandas.py

@@ -94,8 +94,7 @@ def endlog(self, custom_msg: str | None = None, timeit: bool = True):
         initial_shape = self._series._initial_shape
         final_shape = self._series.shape
         if final_shape != initial_shape:
-            dr = initial_shape[0] - final_shape[0]
-            msg += _logutils.count_delta(dr, initial_shape[0], "values")
+            msg += _logutils.series_shape_delta(initial_shape, final_shape)
         else:
             if self._series._initial_series is not None:
                 nchanged = self._series != self._series._initial_series
@@ -311,9 +310,9 @@ def join(self, df2: pd.DataFrame, *args, keep_row_index: bool = False, **kwargs)
         n_both = joined_both.shape[0]
         n_left_dups = int(joined_both[left_col].duplicated(keep=False).sum())
         n_right_dups = int(joined_both[right_col].duplicated(keep=False).sum())
-        n_left_only = joined[
-            joined[left_col].notna() & joined[right_col].isna()
-        ].shape[0]
+        n_left_only = joined[joined[left_col].notna() & joined[right_col].isna()].shape[
+            0
+        ]
         n_right_only = joined[
             joined[left_col].isna() & joined[right_col].notna()
         ].shape[0]

src/raffalib/polars.py

@@ -109,8 +109,7 @@ def endlog(self, custom_msg: str | None = None, timeit: bool = True) -> pl.Serie
         new_shape = self._series.shape
 
         if new_shape != old_shape:
-            dr = old_shape[0] - new_shape[0]
-            msg += _logutils.count_delta(dr, old_shape[0], "values")
+            msg += _logutils.series_shape_delta(old_shape, new_shape)
         else:
             old_series = self._series.config_meta.get_metadata()["old_series"]
             if old_series is None:

tests/test_logutils.py

@@ -36,20 +36,45 @@ def test_count_delta_thousands_separator():
 
 def test_dataframe_shape_delta_rows_and_columns():
     msg = _logutils.dataframe_shape_delta((10, 5), (8, 6))
-    assert msg == "Removed 2/10 (20.00%) rows.Added 1/5 (20.00%) columns."
+    assert msg == (
+        "Removed 2/10 (20.00%) rows.Added 1/5 (20.00%) columns. New shape: (8, 6)."
+    )
 
 
 def test_dataframe_shape_delta_rows_only():
-    assert (
-        _logutils.dataframe_shape_delta((10, 5), (7, 5))
-        == "Removed 3/10 (30.00%) rows."
+    assert _logutils.dataframe_shape_delta((10, 5), (7, 5)) == (
+        "Removed 3/10 (30.00%) rows. New shape: (7, 5)."
     )
 
 
 def test_dataframe_shape_delta_no_change_is_empty():
     assert _logutils.dataframe_shape_delta((10, 5), (10, 5)) == ""
 
 
+def test_new_shape_dataframe():
+    assert _logutils.new_shape((8, 6)) == "New shape: (8, 6)."
+
+
+def test_new_shape_series():
+    assert _logutils.new_shape((8,)) == "New shape: (8,)."
+
+
+def test_series_shape_delta_removed():
+    assert _logutils.series_shape_delta((5,), (3,)) == (
+        "Removed 2/5 (40.00%) values. New shape: (3,)."
+    )
+
+
+def test_series_shape_delta_added():
+    assert _logutils.series_shape_delta((3,), (5,)) == (
+        "Added 2/3 (66.67%) values. New shape: (5,)."
+    )
+
+
+def test_series_shape_delta_no_change_is_empty():
+    assert _logutils.series_shape_delta((5,), (5,)) == ""
+
+
 def test_ratio_basic():
     assert _logutils.ratio(1, 4) == "1/4 (25.00%)"
 

tests/test_pandas.py

@@ -47,7 +47,10 @@ def test_endlog_logs_removed_rows(caplog):
         df.raffa.startlog()
         df = df[df["a"] > 1]
         df.raffa.endlog()
-    assert any("Removed 1/4 (25.00%) rows." in r.message for r in caplog.records)
+    assert any(
+        "Removed 1/4 (25.00%) rows. New shape: (3, 1)." in r.message
+        for r in caplog.records
+    )
 
 
 def test_endlog_logs_value_changes(caplog):
@@ -73,7 +76,10 @@ def test_series_endlog_removed_values(caplog):
         s.raffa.startlog()
         s = s[s > 2]
         s.raffa.endlog()
-    assert any("Removed 2/5 (40.00%) values." in r.message for r in caplog.records)
+    assert any(
+        "Removed 2/5 (40.00%) values. New shape: (3,)." in r.message
+        for r in caplog.records
+    )
 
 
 def test_join_inner_drops_source_columns(caplog):
@@ -128,7 +134,9 @@ def test_endlog_add_rows_to_empty_frame_is_guarded(caplog):
         df.raffa.startlog()
         df = df.reindex(range(3))
         df.raffa.endlog(timeit=False)
-    assert any("Added 3/0 (N/A) rows." in r.message for r in caplog.records)
+    assert any(
+        "Added 3/0 (N/A) rows. New shape: (3, 1)." in r.message for r in caplog.records
+    )
 
 
 def test_join_empty_output_does_not_divide_by_zero(caplog):

tests/test_polars.py

@@ -40,7 +40,10 @@ def test_endlog_removed_rows(caplog):
         df.raffa.startlog()
         df = df.filter(pl.col("a") > 1)
         df.raffa.endlog(timeit=False)
-    assert any("Removed 1/4 (25.00%) rows." in r.message for r in caplog.records)
+    assert any(
+        "Removed 1/4 (25.00%) rows. New shape: (3, 1)." in r.message
+        for r in caplog.records
+    )
 
 
 def test_series_endlog_matches_pandas_format(caplog):
@@ -49,7 +52,10 @@ def test_series_endlog_matches_pandas_format(caplog):
         s.raffa.startlog()
         s = s.filter(s > 2)
         s.raffa.endlog(timeit=False)
-    assert any("Removed 2/5 (40.00%) values." in r.message for r in caplog.records)
+    assert any(
+        "Removed 2/5 (40.00%) values. New shape: (3,)." in r.message
+        for r in caplog.records
+    )
 
 
 def test_endlog_timeit_appends_duration(caplog):
@@ -84,7 +90,9 @@ def test_endlog_add_rows_to_empty_frame_is_guarded(caplog):
         df.raffa.startlog()
         df = df.vstack(pl.DataFrame({"a": [1.0, 2.0, 3.0]}))
         df.raffa.endlog(timeit=False)
-    assert any("Added 3/0 (N/A) rows." in r.message for r in caplog.records)
+    assert any(
+        "Added 3/0 (N/A) rows. New shape: (3, 1)." in r.message for r in caplog.records
+    )
 
 
 def test_join_empty_output_does_not_divide_by_zero(caplog):