,
Matouš Eibich [ctb]| Title: | Add Logging To Functions |
|---|---|
| Description: | Decorate functions to make them return enhanced output. The enhanced output consists in an object of type 'chronicle' containing the result of the function applied to its arguments, as well as a log detailing when the function was run, what were its inputs, what were the errors (if the function failed to run) and other useful information. Tools to handle decorated functions are included, such as a forward pipe operator that makes chaining decorated functions possible. |
| Authors: | Bruno Rodrigues [aut, cre, cph]
,
Matouš Eibich [ctb] |
| Maintainer: | Bruno Rodrigues <[email protected]> |
| License: | GPL (>= 3) |
| Version: | 0.2.2.9999 |
| Built: | 2025-03-06 04:49:34 UTC |
| Source: | https://github.com/b-rodrigues/chronicler |
Pipe a chronicle object to a decorated function.
.c %>=% .f.c %>=% .f
.c |
A value returned by record. |
.f |
A chronicle function to apply to the returning value of .c. |
A chronicle object.
r_sqrt <- record(sqrt) r_exp <- record(exp) 3 |> r_sqrt() %>=% r_exp()r_sqrt <- record(sqrt) r_exp <- record(exp) 3 |> r_sqrt() %>=% r_exp()
Coerce an object to a chronicle object.
as_chronicle(.x, .log_df = data.frame())as_chronicle(.x, .log_df = data.frame())
.x |
Any object. |
.log_df |
Used internally, the user does need to interact with it. Defaults to an empty data frame. |
Returns a chronicle object with the object as the $value.
as_chronicle(3)as_chronicle(3)
A non-tidy dataset from EUROSTAT which can be found here.
aviaavia
A data frame with 1,434 rows and 332 columns.
Evaluate a decorated function; used to chain multiple decorated functions.
bind_record(.c, .f, ...)bind_record(.c, .f, ...)
.c |
A chronicle object. |
.f |
A chronicle function to apply to the returning value of .c. |
... |
Further parameters to pass to .f. |
A chronicle object.
r_sqrt <- record(sqrt) r_exp <- record(exp) 3 |> r_sqrt() |> bind_record(r_exp)r_sqrt <- record(sqrt) r_exp <- record(exp) 3 |> r_sqrt() |> bind_record(r_exp)
Check the output of the diff column
check_diff(.c, columns = c("ops_number", "function"))check_diff(.c, columns = c("ops_number", "function"))
.c |
A chronicle object. |
columns |
Columns to select for the output. Defaults to c("ops_number", "function"). |
diff is an option argument to the record() function. When diff = "full",
a diff of the input and output of the decorated function gets saved, and if
diff = "summary" only a summary of the diff is saved.
A data.frame with the selected columns and column "diff_obj".
r_subset <- record(subset, diff = "full") result <- r_subset(mtcars, select = am) check_diff(result) # <- this is the data frame listing the operations and the accompanying diffs check_diff(result)$diff_obj # <- actually look at the diffsr_subset <- record(subset, diff = "full") result <- r_subset(mtcars, select = am) check_diff(result) # <- this is the data frame listing the operations and the accompanying diffs check_diff(result)$diff_obj # <- actually look at the diffs
Check the output of the .g function
check_g(.c, columns = c("ops_number", "function"))check_g(.c, columns = c("ops_number", "function"))
.c |
A chronicle object. |
columns |
Columns to select for the output. Defaults to c("ops_number", "function"). |
.g is an option argument to the record() function. Providing this optional
function allows you, at each step of a pipeline, to monitor interesting characteristics
of the value object. See the package's Readme file for an example with data frames.
A data.frame with the selected columns and column "g".
r_subset <- record(subset, .g = dim) result <- r_subset(mtcars, select = am) check_g(result)r_subset <- record(subset, .g = dim) result <- r_subset(mtcars, select = am) check_g(result)
Flatten nested chronicle objects
flatten_record(.c)flatten_record(.c)
.c |
A nested chronicle object, where the $value element is itself a chronicle object |
Returns .c where value is the actual value, and logs are concatenated.
r_sqrt <- record(sqrt) r_log <- record(log) a <- as_chronicle(r_log(10)) a flatten_record(a)r_sqrt <- record(sqrt) r_log <- record(log) a <- as_chronicle(r_log(10)) a flatten_record(a)
Evaluate a non-chronicle function on a chronicle object.
fmap_record(.c, .f, ...)fmap_record(.c, .f, ...)
.c |
A chronicle object. |
.f |
A non-chronicle function. |
... |
Further parameters to pass to |
Returns the result of .f(.c$value) as a new chronicle object.
as_chronicle(3) |> fmap_record(sqrt)as_chronicle(3) |> fmap_record(sqrt)
Checks whether an object is of class "chronicle"
is_chronicle(.x)is_chronicle(.x)
.x |
An object to test. |
TRUE if .x is of class "chronicle", FALSE if not.
Retrieve an element from a chronicle object.
pick(.c, .e)pick(.c, .e)
.c |
A chronicle object. |
.e |
Element of interest to retrieve, one of "value" or "log_df". |
The value or log_df element of the chronicle object .c.
r_sqrt <- record(sqrt) r_exp <- record(exp) 3 |> r_sqrt() %>=% r_exp() |> pick("value")r_sqrt <- record(sqrt) r_exp <- record(exp) 3 |> r_sqrt() %>=% r_exp() |> pick("value")
Print method for chronicle objects.
## S3 method for class 'chronicle' print(x, ...)## S3 method for class 'chronicle' print(x, ...)
x |
A chronicle object. |
... |
Unused. |
chronicle object are, at their core, lists with the following elements:
"$value": a an object of type maybe containing the result of the computation (see the "Maybe monad" vignette for more details on maybes).
"$log_df": a data.frame object containing the printed object’s log information.
print.chronicle() prints the object on screen and shows:
the value using its print() method (for example, if the value is a data.frame, print.data.frame() will be used)
a message indicating to the user how to recuperate the value inside the chronicle object and how to read the object’s log
No return value, called for side effects (printing the object on screen).
Capture all errors, warnings and messages.
purely(.f, strict = 2)purely(.f, strict = 2)
.f |
A function to decorate. |
strict |
Controls if the decorated function should catch only errors (1), errors and warnings (2, the default) or errors, warnings and messages (3). |
A function which returns a list. The first element of the list, $value,
is the result of the original function .f applied to its inputs. The second element, $log is
NULL in case everything goes well. In case of error/warning/message, $value is NA and $log
holds the message. purely() is used by record() to allow the latter to handle errors.
purely(log)(10) purely(log)(-10) purely(log, strict = 1)(-10) # This produces a warning, so with strict = 1 nothing gets captured.purely(log)(10) purely(log)(-10) purely(log, strict = 1)(-10) # This produces a warning, so with strict = 1 nothing gets captured.
Reads the log of a chronicle.
read_log(.c)read_log(.c)
.c |
A chronicle object. |
The log of the object.
## Not run: read_log(chronicle_object) ## End(Not run)## Not run: read_log(chronicle_object) ## End(Not run)
chronicle.Decorates a function to output objects of type chronicle.
record(.f, .g = (function(x) NA), strict = 2, diff = "none")record(.f, .g = (function(x) NA), strict = 2, diff = "none")
.f |
A function to decorate. |
.g |
Optional. A function to apply to the intermediary results for monitoring purposes. Defaults to returning NA. |
strict |
Controls if the decorated function should catch only errors (1), errors and warnings (2, the default) or errors, warnings and messages (3). |
diff |
Whether to show the diff between the input and the output ("full"), just a summary of the diff ("summary"), or none ("none", the default) |
To chain multiple decorated function, use bind_record() or %>=%.
If the diff parameter is set to "full", diffobj::diffObj()
(or diffobj::summary(diffobj::diffObj(), if diff is set to "summary")
gets used to provide the diff between the input and the output.
This diff can be found in the log_df element of the result, and can be
viewed using check_diff().
A function which returns objects of type chronicle. chronicle objects carry several
elements: a value which is the result of the function evaluated on its inputs and a second
object called log_df. log_df contains logging information, which can be read using
read_log(). log_df is a data frame with columns: outcome, function, arguments, message, start_time, end_time, run_time, g and diff_obj.
record(sqrt)(10)record(sqrt)(10)
record_ggplot takes a ggplot_expression and an optional strict argument as input and does the following steps:
Records the ggplot_fun function with the given strict argument using the record function from chronicler
Passes the ggplot_expression to the recorded ggplot_fun function
Returns the result of the recorded ggplot_fun function
record_ggplot(ggplot_expression, strict = 2)record_ggplot(ggplot_expression, strict = 2)
ggplot_expression |
A ggplot expression. |
strict |
An optional integer argument controlling the behavior of the record() function from chronicler. Default is 2. |
A chronicler object.
## Not run: library(ggplot2) # Unsuccessful example x <- record_ggplot(ggplot(data = mtcars) + geom_point(aes(y = hp, x = mpgg))) print(x) # Successful example z <- record_ggplot(ggplot(data = mtcars) + geom_point(aes(y = hp, x = mpg))) print(z) ## End(Not run)## Not run: library(ggplot2) # Unsuccessful example x <- record_ggplot(ggplot(data = mtcars) + geom_point(aes(y = hp, x = mpgg))) print(x) # Successful example z <- record_ggplot(ggplot(data = mtcars) + geom_point(aes(y = hp, x = mpg))) print(z) ## End(Not run)
Decorate a list of functions
record_many(list_funcs, .g = (function(x) NA), strict = 2, diff = "none")record_many(list_funcs, .g = (function(x) NA), strict = 2, diff = "none")
list_funcs |
A list of function names, as strings. |
.g |
Optional. Defaults to a function which returns NA. |
strict |
Controls if the decorated function should catch only errors (1), errors and warnings (2, the default) or errors, warnings and messages (3). |
diff |
Whether to show the diff between the input and the output ("full"), just a summary of the diff ("summary"), or none ("none", the default) |
Functions must be entered as strings of the form "function" or "package::function".
The code gets generated and copied into the clipboard. The code can then be pasted
into the text editor. On GNU/Linux systems, you might get the following error
message on first use: "Error in : Clipboard on X11 requires that the DISPLAY envvar be configured".
This is an error message from clipr::write_clip(), used by record_many() to put
the generated code into the system's clipboard.
To solve this issue, run echo $DISPLAY in the system's shell.
This command should return a string like ":0". Take note of this string.
In your .Rprofile, put the following command: Sys.setenv(DISPLAY = ":0") and restart
the R session. record_many() should now work.
Puts a string into the systems clipboard.
## Not run: list_funcs <- list("exp", "dplyr::select", "exp") record_many(list_funcs) ## End(Not run)## Not run: list_funcs <- list("exp", "dplyr::select", "exp") record_many(list_funcs) ## End(Not run)