positron
positron copied to clipboard
posit-dev
Notebooks: Option to send output to console and not print out in notebook
RStudio users can choose whether to have their notebook output go to the console or get printed out in their notebook space. We'll want to support this option in Positron as well, and it will pretty much be the first time Python users can set up their work this way. (Spoiler alert: they want this option a lot.)
I also think "send output to console" isn't a "sticky" option in RStudio, i.e. I have to select it for every Rmd I create. I have a feeling we can probably fix that here.
I think some of us have also discussed our desire for "send output to console" to be the default behavior in notebooks, so we should think about that too
Just x-posting that we probably want to avoid some of the more surprising behavior, albeit most of that may only be present for R users: https://github.com/posit-dev/positron/issues/1418
@juliasilge Do you think this is still relevant after discussions at work week? i.e. do we want a "send to console" mode for .ipynb files?
It does seem possible that Python users will want to do this, but having lived in a world where there are two different modes (console/inline) for Rmd/Qmd files in RStudio, it has lead to quite a lot of confusion, complexity, and unforeseen edge cases, so much so that there is widespread rejoicing that we are moving away from having two modes for those files in Positron. Do we want to introduce this feature for .ipynb files?
For context, this feedback came out of the Oct 2023 session of our internal monthly Python OSS sync, and was one of about a half dozen specific requests for a desired notebook experience (I'll share the doc with you, @jmcphers).
It does seem possible that Python users will want to do this
I think this is not only possible but just plain the actual situation.
However, I am on board with us deciding it's not the right choice for us. We can decline based on our experience supporting .Rmd as notebooks in the RStudio IDE and affirm we believe this gives users a better experience:
- If you want an inline experience, use
.ipynb - If you want a send-to-console experience, use
.qmd
Converting is quite straightforward. It's never fun to say 🚫NO🚫 to something users want, but for sure this is an area where we have experience to draw from.
I think we can leave this as we collect additional feedback, but for reference, here are some of the things that have made this hard in RStudio:
- Where does one express the desire for inline output vs. console output? Is this an attribute of (a) the document, (b) the user's personal preferences, or (c) some complication of both?
- What are the differences in computational environment expectations for code executed "inline" vs "in the console"? For example, code executed inline usually uses the working directory of the document, whereas the console uses whatever the current working directory is. Is it OK for these different modes to return different computational results?
- If a chunk has inline output (from a previous execution or via saved output in the .ipynb), but then is run in the console, is the previous result destroyed? (it's confusing to let it stay, but also jarring to remove it)
- Other issues captured in https://github.com/posit-dev/positron/issues/1418
I wouldn't say "we'd never do this" but I would say that before we did it we'd want to comb over all these issues and convince ourselves we have a design that learns from them.
This came up in private beta here: https://github.com/posit-dev/positron-beta/discussions/59
Another one
- If Quarto documents weren't attached to a Console and only did inline output, they would also need a way to accept inline input from the user, i.e. through
readline(), which doesn't seem great.
I was sent here by @juliasilge's comment in a different issue: https://github.com/posit-dev/positron/discussions/3718#discussioncomment-9938783 I'd like to comment on:
As of today,
- If you want an inline experience, use .ipynb
- If you want a send-to-console experience, use .qmd
I feel there are two separate issues here that are muddled together. One is the notebook file format and the other is where and how code gets executed and results are shown. I'd like to use the better file format (.qmd) together with the better execution model (inline, I'll explain below why it's objectively better in my opinion). I don't understand why the file format should be tied to the execution model.
More importantly, however, I've always felt that the notebook implementation in RStudio was broken. It mixes actions and outputs inside the notebook with actions and outputs in the console, and that confuses users and leads at times to unexpected results. You have the opportunity with Positron to fix this and I hope you'll do so.
A simple way to fix the issue is to just send everything to the console, but does this make sense? In particular in a multi-language environment (which Quarto explicitly is as far as I understand), the only way to do this correctly would be to have one console for each language. If I mix five languages in my notebook I need five separate consoles and need to somehow be able to keep track of where they are, what has happened in them, which output I'm currently seeing, etc. By contrast, if output is always shown inline then this problem doesn't exist. I don't need consoles at all. (That's how Jupyter works, and that's why I believe the inline execution model is objectively superior.)
Therefore, I believe the better model for .qmd files would be to separate them completely from the console. Run a separate R process in the console if you like, but have it not be affected by what happens in the notebook and vice versa. This is a logical and consistent approach, and most other parts of the development experience work this way. If I open a terminal whatever I do there doesn't impact the notebook or vice versa either. And if I start R (or python) in that terminal it also is completely separate.
Finally, if you want to have the option of sending commands from the .qmd to the console, you could consider two alternative modes:
- Console mode. All commands are send to the console, all output is shown in the console.
- Notebook mode. Nothing is sent to the console, no results are shown in the console, and the console runs a separate R process.
I think both of these modes can be useful and are logically consistent. Any mix between the two modes is not. And I would predict that if you offered notebook mode as an option many users would pick it over console mode.
I don't understand why the file format should be tied to the execution model.
I agree that having the behavior depend on the file format is confusing as a user. Particularly between file formats that are supposed to be cross-compatible (.qmd and .ipynb) I think it's reasonable to expect the interface for editing them should be consistent. And if there are strong camps of users who prefer console vs inline I feel that should be accommodated as a user-level option rather than forcing users into a different file format. Otherwise, if I'm working on a notebook with a colleague and I prefer in-line and they prefer console does one of us need to convert the file format back and forth each time we open it?
I'd also like to add some more support and hopefully helpful user context for having output displayed inline in notebooks. My personal process when editing a qmd notebook is to frequently jump between sections, using insights from later outputs to readjust how I approach earlier parts of the notebook. Rarely do I find an analysis progresses linearly from start to end, which I think is consistent with the Foggy Garden of Forking Paths metaphor for analysis. Having all the outputs shown inline as I scroll back is hugely useful in this process. True, this does require a bit more cognitive management of the state of the session, but frequent use of the "run all previous chunks" button in RStudio largely addresses this. Personally I only actually render the full document when I'm done editing and am ready to share it.
A point that I haven't seen brought up in some of the other discussions around this issue is whether you as a user are looking for a more WYSIWYG editing experience or something more like a traditional LaTeX experience where you frequently re-render the content to check your work. RStudio has made incremental steps towards supporting a more WYSIWYG style in notebooks, especially with the Visual editor mode. In my mind inline output is vital to a WYSIWYG experience as otherwise all the plots and other output are off somewhere else and you don't see them integrated with the write-up until you render. As someone who frequently uses Visual mode, I hope to see a similar experience available eventually at least as an option in Positron. And on the other side I suspect some of the distaste for inline execution is from folks who are not looking for a WYSIWYG experience.
Therefore, I believe the better model for .qmd files would be to separate them completely from the console. Run a separate R process in the console if you like, but have it not be affected by what happens in the notebook and vice versa. This is a logical and consistent approach, and most other parts of the development experience work this way. If I open a terminal whatever I do there doesn't impact the notebook or vice versa either. And if I start R (or python) in that terminal it also is completely separate.
I disagree with this (separate processes in notebook and console by default) , this make really hard working with data and iterating, one of main reasons editor like Rstudio or (Spyder) were appealing to the users ( to scientists, maybe less for programmers) was that they can write code in notebook, preview the variables in the data viewer and try to manipulate it within the same environment/userspace) ;
Where the output should be displayed (separate console vs inline) is a separate question
Sooo, as I can see from @clauswilke comment above, this is a rather contentious topic. And I get it, we all get used to particular workflows.
In the beginning, there was sweave. And there, the text editing was decoupled from the generation of the final document.
Then, Yihui brought us knitr. And again, text editing was still mostly decoupled from the generation of the final document.
At some point, ipython came along, with their notebooks that were really neat, but also somehow bundled the javascript for display with the underlying computations, and everything was kept together, with no way to access the kernel outside of the notebook environment.
Then RStudio brought us inline editing, which was a neat way to be still editing a raw text document, but see the results next to the code. Unfortunately, it came with assumptions about where execution was starting from, and how to access things in the file path. I (and I'm sure @clauswilke) started coding in R so long ago, having the console coupled to the text editing was a revelation. I somehow never really grew out of that, and always preferred my output in the console, because I felt like inline never gave me the flexibility I wanted to query the data I was generating, and try different things out without writing in the text document.
Which is weird, because I often start working in a qmd document than a straight R script when I need to prototype something (maybe because it's easier to send an html doc or word doc when I have graphs to share? I don't know).
And now of course we have visual editing, which feels like a very close analogue to a notebook.
As much as it pains me to think about (and probably is a pain to support), I think that qmd files should continue to have the options of either output to console, or output inline (similar to notebook). Users should be able to use either one. Either that, or bring back the "notebook" format that is powered by qmd underneath, but everything is shunted to the kernel driving it.
Some people really like notebooks / inline output, with all the output shown in the notebook editing area. Some of us are not fans, and want all the outputs elsewhere while we are writing. I know the options to support both of us make your all jobs more complicated, and that sucks.
Just to add that on a purely ergonomic note, it is hugely valuable to have chunk output sitting around in a quarto document as I work. I can refer back to tables, figures, plots etc. as I work in other parts of the document.
Having this available in qmd files is useful because (unlike in ipynb files)
- this output does not show up in git diffs or get otherwise included in the document
- I want to be developing my code inside the same quarto file which will then be rendered using the layout, styling etc. that Quarto allows
This makes the qmd format with inline output more practical to me than Jupyter Notebooks (and why I am so far sticking to RStudio over Positron) - so the logic of "if you want inline experience, use ipynb" does not really work for me.
Whether or not that output also turns up in the console is not that big of a deal to me. Having a console ready with the same environment is helpful but not essential - rather something I appreciate and got used to because of how RStudio works with Rmd/qmd docs, but I see how that can be confusing coming from Jupyter.
To my mind, it is appropriate to have behavior tied to file format. Interactive inline output is the essence of a notebook, whereas .qmd files are mere code, akin to .md files (or LaTeX)---with both the advantages and disadvantages of code. The previous comments describe well the advantages of working in a notebook. But expecting a notebook workflow without the notebook format designed to represent it asks too much of the IDE.
There are solutions for some of the concerns about .ipynb files, unless I'm misunderstanding them.
Having this available in qmd files is useful because (unlike in ipynb files)
- this output does not show up in git diffs or get otherwise included in the document
This can be achieved with .ipynb files by running a script to clean up output and other git-problematic metadata. This can be automated with pre-commit.
- I want to be developing my code inside the same quarto file which will then be rendered using the layout, styling etc. that Quarto allows
You can render .ipynb files with Quarto just as you would a .qmd.
[I]f I prefer in-line and they prefer console does one of us need to convert the file format back and forth each time we open it?
You would, but the conversion before and after editing could be automated. (More should perhaps be done to make a quarto convert round-trip (qmd -> ipynb -> qmd) preserve the original, but that's a Quarto issue rather than a Positron issue.)
I think that while it makes sense to have file-specific behavior, it should be up to the user to decide whether or not the plots are displayed inline or in the plots section. I use quarto a lot and that forces the plots to show up in the plots section. That would be fine, but the plot section is quite small and especially when using code such as facet_wrap the plots are virtually unreadable. I think the best option is to allow the user to toggle inline vs plot section output.
I mean, zoomable plots are coming (here??), you can choose to set a different device, and you can even write a function to send a plot to a file so you can open it in an editor window and it is almost infinitely zoomable.
Yes, for more info on popping plots out of the Plots pane, see https://github.com/posit-dev/positron/discussions/5073!
I'd add one more reason in favour of inline output, it actually shows the accurate resolution of your plot as it will be after rendering, meaning the proportion of text size vs plot panel so you can see if you need to increase the fig-width and fig-height because your text is too big, without the need of constantly re-rendering.
If you don't want to provide inline output, at least you should offer an alternative to that, like storing a temp file of that output via chache: true or have the viewer pane show how it would look like at the set , because if you have to render a notebook each time just to know if a plot has the right size it won't really be a code-first data science solution... Try making a ComplexHeatmap, for example.
In theory rendering should be reserved for "I am ready to deliver this", specially for large and complex data science projects that aren't just 3 plots.
I'd also like to chime in support for inline rendering. Consistent with some of the views above, I find that a notebook format in which tables, computational results and plots are rendered in-line makes the workflow a more pleasant, but more importantly, less cognitively demanding experience. The ability to refer to previous outputs and computations in the same space in which you edit the code makes working on complex projects that require extensive exploration much easier. The LaTeX-style cycle of write-render-write-render adds an extra layer of complexity. Despite caching and freezing of computations, rendering still takes considerable time, especially with documents composed of many chunks.
While it is true that you could work with a jupyter notebook, the problems with version control are well known. Yes, you can covert notebooks from one format to another, and you can setup tools to version control just the code, but this again adds even more layers of abstraction and complicates the entire workflow.
Reproducible science is already difficult enough when you put into place the many moving pieces of git + renv + quarto + targets + a ton of other things, that every layer of abstraction that we can get rid of will make it easier for people to adopt these tools.
Aside from personal preference, I teach students and have seen first hand how much more easily they take to things like Google Colab, where so much of the annoying busy work that has nothing to do with actual science and data analysis is hidden from them.
And now with tools like webR and the increasing support for it in Quarto we have this strange situation that I can make a Quarto website with interactive code sections which can be run and edited and their results displayed inline in a published document on the web. And at the same time not able to do the same with regular local development of .qmd documents.
It is of course up to the team to decide what features to support. But the more we can reduce friction when working towards reproducibility, the better it is for everyone.
- If a chunk has inline output (from a previous execution or via saved output in the .ipynb), but then is run in the console, is the previous result destroyed? (it's confusing to let it stay, but also jarring to remove it)
May I counter with a question? Aren't you creating objects in your environment by running notebooks chunks and aren't you rewriting ('destroying') your objects if you rerun that same chunk on the console?
We have the render option for when we want the 'true' result, anything else is actual testing.
- What are the differences in computational environment expectations for code executed "inline" vs "in the console"? For example, code executed inline usually uses the working directory of the document, whereas the console uses whatever the current working directory is. Is it OK for these different modes to return different computational results?
Code inline 100% should use the same working environment as the working environment of the notebook because you're testing the notebook behaviour before doing a full render as a sort of a 'debugger mode'. It should be akin to a partial rendering.
IMO console can behave differently because you don't have a dedicated 'Notebook console' and you can switch between notebooks and even R scripts, so it makes sense to be different and I think most users know that and new users can get used to that.
Adding to this thread, it would also be nice to have both from Jupyter Notebook without having to use Quarto. Working on a use case where I just push notebooks to a GitHub repo with actions set up to build a book. Other people are contributing as well.
But it would be nice to have it print to the Notebook as it's already done while also being sent to the console so it can be referred back to after writing 50 more cells.
Bonus if clicking on the plot would allow to scroll back to the code that generated it.
Adding my two cents in favour of inline results. As several people said, being able to see all the plots and tables in context is incredibly useful (dare I say, vital) when writing research papers.
I have to admit that I don't really understand why output location is tied to environment execution in this discussion. My preference would be to be able run code both interactively in console and as chunks in the same environment.
