basic logging for main verbs (#138)

* basic logging for select, mutate, and transmute

* unit testing for logs

* remove deepdiffs dependency

* adds tests for logs on the rest of the functions

* typo fix

* add mutate numbers to log

* adds join logging, fix cov x

* Fix esedge case for logging with grouped data frames.

* :newsize mode logs correct type

* add detail for row_change and col_change

* add brief docs, bump v, up news

* fixes log when grouped mutate, adds fillmissing, dropmissing log support

* fixed fxn call

* fix join log if stmnt, bump cov attempt w 2tests

* add slice log support

* change slice_min_max to not use`@filter` bc of logging msg dupes

* adds unite, sep, sep_rows

* adds logging for nests

* minor docs edits for settings

* exclude log.jl from code coverage for now

---------

Co-authored-by: Daniel Rizk <[email protected]>
Co-authored-by: Karandeep Singh <[email protected]>

Author: 3 people

NEWS.md

@@ -1,5 +1,9 @@
 # TidierData.jl updates
 
+## v.0.17.0 - 2025-03-24
+- Adds logging ability to track changes to data frames with `TidierData_set("log", true)`
+- Adds docs describing logging and code printing
+
 ## v0.16.5 - 2025-01-11
 - Bugfix: Corrected bug when using `Module.function()` syntax within expressions, which was previously causing errors due to the module being escaped.
 

Project.toml

@@ -1,7 +1,7 @@
 name = "TidierData"
 uuid = "fe2206b3-d496-4ee9-a338-6a095c4ece80"
 authors = ["Karandeep Singh"]
-version = "0.16.5"
+version = "0.17.0"
 
 [deps]
 Chain = "8be319e6-bccf-4806-a6f7-6fae938471bc"

docs/examples/UserGuide/settings.jl

@@ -0,0 +1,44 @@
+# TidierData.jl comes with two settings that make it easier to understand the transformations that are being applied to a data frame and to troubleshoot errors. These settings are `log` and `code`. The `log` setting outputs information about the data frame after each transformation, including the number of missing values and the number of unique values in each column. The `code` setting outputs the code that is being executed by the TidierData.jl macros. By default, both settings are set to `false`. This page will review the `log` and `code` settings using the movies dataset.
+# 
+# We recommend setting the `log` setting to `true` in general, and especially when you are first learning TidierData.jl. This will help you understand how the data frame is being transformed at each step. The `code` setting is useful for debugging errors in TidierData.jl chains.
+
+using TidierData
+using RDatasets
+
+movies = dataset("ggplot2", "movies");
+
+# ## `log`
+# Logging is set to `false` by default but can enabled as follows:
+
+TidierData_set("log", true)
+
+# When enabled, each macro called will show information about its transformation of the data. Logging can be especially useful to catch silent bugs (those that do not result in an error). 
+# 
+# When column values are changed, it will report the number new missing values, the percentage of missing values, and the number of unique values.
+
+@chain movies begin 
+    @filter(Year > 2000)
+    @mutate(Budget_cat = case_when(Budget > 18000 => "high",
+                                   Budget > 2000  => "medium",
+                                   Budget > 100 => "low",
+                                    true => missing))
+    @filter(!ismissing(Budget))
+    @group_by(Year, Budget_cat)
+    @summarize(Avg_Budget = mean(Budget), n = n())
+    @ungroup
+    @arrange(n)
+end
+
+TidierData_set("log", false) # disable logging
+
+# ## `code`
+# Code printing is set to `false` by default. Enabling this setting prints the underlying DataFrames.jl code created by TidierData.jl macros. It can be useful for debugging, especially for users who understand DataFrames.jl syntax, or for filing bug reports.
+
+TidierData_set("code", true) # enable macro code output
+
+@chain movies begin 
+    @select(Title, Year, Budget)
+    @slice_sample(n = 10)
+end
+
+TidierData_set("code", false) # disable macro code output

docs/mkdocs.yml

@@ -117,6 +117,7 @@ plugins:
 nav:
   - "Home": "index.md"
   - "Movies dataset" : "examples/generated/UserGuide/dataset_movies.md"
+  - "Setting Options" : "examples/generated/UserGuide/settings.md"
   - "@select" : "examples/generated/UserGuide/select.md"
   - "@rename" : "examples/generated/UserGuide/rename.md"
   - "@mutate" : "examples/generated/UserGuide/mutate_transmute.md"