BonitoBook: Displaying Stdout Output In Notebooks

Are you new to BonitoBook and the Makie stack and wondering why your stdout displays aren't working as expected? You're not alone! Many users, especially those transitioning from Jupyter notebooks, have encountered this issue. In this comprehensive guide, we'll delve into the intricacies of how BonitoBook handles stdout output, explore the differences compared to Jupyter notebooks, and provide practical solutions to ensure your output sticks around during cell execution.

Understanding the stdout Display Issue in BonitoBook

When diving into BonitoBook, one of the initial surprises for users is the behavior of standard output (stdout) displays. Unlike Jupyter notebooks where println(...) and display(...) seamlessly show output directly beneath the cell, BonitoBook presents a slightly different approach. Specifically, the challenge arises because simple displays to stdout might not work as intuitively as expected. For instance, while display(...) might not show anything immediately, println(...) might briefly display output within the cell, only to have it disappear moments later. This behavior, as noted in issue #16, can be quite perplexing, especially when you're accustomed to the persistent output in Jupyter notebooks.

The Key Difference: In BonitoBook, the environment handles output in a manner that prioritizes the final returned object from a cell for permanent display. This is a departure from Jupyter's approach, where both explicit stdout prints and returned objects are persistently displayed. While objects returned from a cell are displayed permanently, standard output streams like those from println(...) are treated differently. This distinction is crucial for understanding how to effectively manage and display information during cell execution in BonitoBook.

Why This Matters: This behavior is significant because it affects how you debug, monitor, and present results during a BonitoBook session. In scenarios where you need to track progress, display intermediate values, or provide real-time feedback from your code, relying solely on the final returned object can be limiting. Therefore, mastering alternative methods to display stdout or similar outputs becomes essential for a smooth and productive workflow in BonitoBook.

To effectively use BonitoBook, it's important to grasp these fundamental differences and adapt your strategies for displaying output. This ensures you can maintain clear visibility of your code's execution and results, which is crucial for both development and presentation purposes.

Exploring the Discrepancy: BonitoBook vs. Jupyter Notebooks

The difference in how BonitoBook and Jupyter Notebooks handle standard output (stdout) can be a significant hurdle for newcomers. In Jupyter Notebooks, the paradigm is straightforward: anything sent to stdout via print() or similar functions appears directly below the cell and remains visible. This makes it easy to track intermediate results, debug code, and provide real-time feedback during execution. The simplicity of this approach is one of the reasons why Jupyter Notebooks are so widely adopted in data science and research environments.

In contrast, BonitoBook operates under a different philosophy. While it does capture stdout during cell execution, the display of this output is not persistent by default. As highlighted in the initial problem description, println(...) might show something momentarily, but the output vanishes shortly after execution completes. This behavior is not a bug but rather a design choice rooted in BonitoBook's architecture, which prioritizes the display of the final returned object from a cell.

Why the Discrepancy?

1. Execution Model: BonitoBook's execution model is tailored to integrate deeply with the reactive programming paradigm of the Makie ecosystem. This means that the notebook environment is optimized for rendering complex, interactive visualizations and managing the state of reactive components. As a result, the handling of stdout is streamlined to avoid cluttering the display with transient information that might not be relevant in the final output.
2. Display Priorities: BonitoBook places a higher emphasis on displaying the end result of a computation rather than the intermediate steps. This is particularly useful when dealing with visualizations or complex data transformations, where the final rendered output or transformed data structure is the primary focus. The design reduces the noise from less critical outputs that are often a byproduct of the calculation process.
3. State Management: Jupyter Notebooks manage state in a more imperative fashion, where each cell's output is appended to the notebook's display. BonitoBook, on the other hand, tends to handle state more declaratively, with a focus on the final state or result. This difference in state management also influences how outputs are handled, with BonitoBook preferring to display the conclusive state.

For users transitioning from Jupyter Notebooks, this difference in behavior can be initially confusing. The expectation that stdout prints should be persistently displayed is natural, given the ubiquity of Jupyter in many scientific computing workflows. However, understanding the design rationale behind BonitoBook's approach is the first step in adapting to this new environment and exploring effective alternatives for displaying output.

Practical Solutions for Displaying Output in BonitoBook

Given the nuances of how BonitoBook handles stdout, it's crucial to explore alternative methods for displaying output that sticks around during a cell run. Fortunately, there are several effective strategies you can employ to ensure your output is visible and persistent.

1. Returning Objects from Cells

The most straightforward approach in BonitoBook is to ensure that the information you want to display is the final object returned from the cell. BonitoBook is designed to permanently display the last evaluated expression or object in a cell. This method works seamlessly for simple values, data structures, and even complex visualizations.

Example:

x = 10
y = 20
result = x + y
result # This will be displayed

In this example, the value of result will be displayed because it is the last expression in the cell. This is a simple and effective way to show the final outcome of your computations.

2. Using Display Functions for Rich Output

For more complex output, such as plots, tables, or formatted text, you can use display functions explicitly. The display() function in Julia can handle a variety of types and render them appropriately in BonitoBook.

Example:

using Plots

x = 1:10
y = rand(10)
plot(x, y)
display(plot!(x, y)) # This plot will be displayed

Here, we explicitly use display() to ensure that the plot generated by Plots.jl is rendered in the output. This is particularly useful when you want to display multiple outputs or control exactly what is shown.

3. Leveraging Logging and Status Messages

For tracking progress or debugging during long-running computations, logging and status messages can be invaluable. BonitoBook can capture and display logs effectively. You can use Julia's built-in logging facilities or specialized packages like LoggingExtras.jl for more advanced logging setups.

Example using Julia's built-in Logging:

using Logging

@info "Starting a long computation..."
for i in 1:10
 @info "Progress: ", i
 sleep(1) # Simulate a long computation
end
@info "Computation completed."

In this example, @info messages will be displayed in the BonitoBook output, allowing you to monitor the progress of the loop. For more complex scenarios, you might use a dedicated logging framework to manage different levels of log messages (e.g., debug, info, warn, error) and direct them to various outputs.

4. Utilizing Reactive Outputs

BonitoBook's strength lies in its reactive capabilities, making it ideal for creating interactive dashboards and applications. You can use reactive variables and display them within your notebook to create dynamic outputs that update in real-time.

Example using Observables from the Observables.jl package:

using Observables
using WGLMakie

x = Observable(1:10)
y = Observable(rand(10))

f = Figure()

lines!(f[1, 1], x, y)

display(f)

# Later, update the observables to change the plot
x[] = 1:10 .^ 1.2
y[] = rand(10)

In this snippet, we create reactive Observables x and y. The plot updates automatically whenever the values of x or y change. This approach is perfect for building interactive visualizations and reactive applications directly within BonitoBook.

5. Creating Custom Display Functions

For specialized output needs, you can define custom display functions that handle your specific data types or structures. By implementing the show method for your types, you can control how they are displayed in BonitoBook.

Example:

struct MyCustomType
 data::Dict{String, Any}
end

import Base.show
function show(io::IO, ::MIME"text/plain", obj::MyCustomType)
 println(io, "MyCustomType with data:")
 for (key, value) in obj.data
 println(io, " - ", key, ": ", value)
 end
end

my_object = MyCustomType(Dict("name" => "Example", "value" => 42))
display(my_object)

Here, we define a custom type MyCustomType and implement a show method to display its contents in a formatted manner. This is a powerful way to ensure that your custom types are displayed clearly and informatively in BonitoBook.

By employing these strategies, you can effectively manage and display output in BonitoBook, ensuring that your results and progress are always visible during your coding sessions.

Best Practices for Debugging in BonitoBook

Debugging in BonitoBook requires a slightly different approach compared to more traditional environments like Jupyter notebooks, primarily due to the way it handles stdout. However, by adopting some best practices, you can efficiently identify and resolve issues in your code. Here are some strategies to help you debug effectively in BonitoBook:

1. Strategic Use of Logging

One of the most reliable methods for debugging in BonitoBook is to strategically use logging. Unlike simple println statements that might disappear, logging provides a persistent record of your program's execution. Julia's built-in Logging module allows you to insert log messages at various levels (e.g., @info, @warn, @error) that can help you track the flow of your code and identify potential issues.

Example:

using Logging

function my_function(x)
 @info "Entering my_function with x = $x"
 if x < 0
 @warn "x is negative!"
 return nothing
 end
 result = x * 2
 @info "Result is $result"
 return result
end

my_function(-5)
my_function(10)

In this example, log messages provide insight into the function's execution, including input values and potential warnings. This is invaluable for tracing errors and understanding the state of your program at different points.

2. Leveraging the Debugger

Julia has a powerful built-in debugger that you can use within BonitoBook. The debugger allows you to step through your code line by line, inspect variables, and set breakpoints. This can be particularly useful for complex code where the source of an issue is not immediately obvious.

To use the debugger, you can insert the using Debugger statement in your cell and then use the @enter macro to start debugging a function call. Alternatively, you can set breakpoints using the breakpoint() function.

Example:

using Debugger

function complicated_function(a, b)
 c = a + b
 d = c * 2
 return d
end

@enter complicated_function(5, 10)

When you run this cell, the debugger will activate, allowing you to step through complicated_function and examine the values of a, b, c, and d at each step.

3. Inspecting Variables Directly

Since BonitoBook displays the last evaluated expression in a cell, you can use this to your advantage by explicitly inspecting variables at different points in your code. Simply add the variable name as the last line in a cell to display its value.

Example:

x = 10
y = x * 2
z = y + 5
z # Display the value of z

This technique is particularly useful for quickly checking intermediate values and ensuring that your calculations are proceeding as expected.

4. Breaking Down Complex Operations

When debugging, it's often helpful to break down complex operations into smaller, more manageable steps. This makes it easier to isolate the source of an error. Instead of performing a series of operations in a single line, break them up into multiple lines and inspect the result of each step.

Example:

Instead of:

result = (a + b) * c / d

Do:

sum_ab = a + b
product_c = sum_ab * c
result = product_c / d
result # Display the value of result

This way, if there's an issue, you can quickly identify which operation is causing the problem.

5. Writing Unit Tests

While not a direct debugging technique, writing unit tests can significantly reduce the number of bugs in your code. Unit tests allow you to verify that individual functions or components of your code are working correctly. Julia has a built-in testing framework (Test module) that makes it easy to write and run tests.

Example:

using Test

function add(a, b)
 return a + b
end

@test add(2, 3) == 5
@test add(-1, 1) == 0
@test add(0, 0) == 0

By writing tests, you can catch errors early in the development process and ensure that your code behaves as expected.

6. Utilizing Error Messages

Julia's error messages are often quite informative and can provide valuable clues about the cause of a bug. Pay close attention to the error messages and stack traces, as they can often point you directly to the line of code where the error occurred.

7. Reproducible Examples

When encountering a bug, try to create a minimal, reproducible example that demonstrates the issue. This makes it easier to isolate the problem and share it with others if needed. A reproducible example should include all the necessary code and data to replicate the bug.

By incorporating these debugging practices into your BonitoBook workflow, you can efficiently troubleshoot your code and ensure that your applications are robust and reliable.

Conclusion

Mastering output display in BonitoBook requires understanding its unique approach compared to traditional notebooks like Jupyter. While stdout display might seem initially challenging, the strategies discussed—returning objects, using display functions, logging, reactive outputs, and custom display functions—offer robust alternatives. By embracing these methods and adopting best debugging practices, you can fully leverage BonitoBook's capabilities for creating interactive and dynamic applications.

To further explore related topics, you might find helpful information on Julia's official documentation, which provides in-depth explanations and examples of various functionalities.