Getting Started with Positron: A Quick Tour

Hi everyone, my name is Isabella Velazquez. Today I'm going to be showing you how to set up and navigate Positron, Posit's new IDE for data science. I'm going to be showing you how to install and download all the things that you need to get started with Positron. If you already have these things installed, just sit tight because afterwards I'm going to go into a quick layout tour where I'm going to show you the different components of Positron's layout that can help you with your data science workflow. Finally, I'm going to go into a very quick glimpse into Positron Assistant, which is an AI client that can help you look at your data, look at your plots, and so on, provide suggestions for your data science workflows.

If Positron's AI capabilities are what mostly interest you, I highly recommend that you sign up for the end-to-end workflow next month, which is going to primarily focus on that. Stick around for Q&A after the presentation, and with that, let's get started.

Installing Positron

First, start off on the Positron documentation page. To download Positron, I go hit download, agree to the Positron license, search for my platform, and hit download. Move this into my applications. I'm going to open up Positron.

So this is a completely fresh installation of Positron. If you notice down here, it'll let me know that no interpreters have been found because I don't have R or Python installed. I can hit the get started documentation to figure out what to do next. Let's do the Python setup. Notice we have a few options. We can download Python with UV, PyEnv, PyEnv for Windows. I'm going to hit UV.

And reading this, I can see to install the latest Python version, I can run UV Python install. But first things first, I need to install UV, so I'm going to hit installation. I'm on a Mac, so I'm going to go ahead and use cURL to download the script and execute it. I'm going to go back to Positron, terminal, paste, enter, and this will download UV. And then I can go back to installing Python, and then run UV Python install.

So this is going to install Python 3.13.7 onto my computer. The next time that we reload Windows or open Positron back up, hit start session, and now I will have Python enabled. And that's it. That's all I had to do to get Positron and Python installed on my computer.

Installing R

I also want to install R. Go back, hit R setup, and then it says, if you plan to use R with Positron, ensure you have R 4.2 installed. And to install R, follow the instructions for our operating system at this address. So I can go ahead, quick download R for macOS again. I believe I have this one. We've been completed. I'm going to go through the installation steps. Three, install. Install.

Once it's been successfully installed, I can, once again, close out of Positron, open it back up. And when I hit start session, I'll have not only Python, but also R available.

Managing Python versions with UV

The UV documentation also mentions that if I want to install a specific Python version, I can go ahead and run UV Python install on the version that I want. So say I want 3.2, 3.12. Go back to Positron. Type UV Python install 3.12. Enter. Reopen Positron. And then in the command palette, type Python select interpreter. Hit enter. We have not only 3.13.7, but also 3.12.11. So let's say I want to go with the latest and greatest. I'm going to hit Python 3.13.7.

Opening a demo project

Now we are ready to get started with our project. For PositConf this year, we created a demo that explored different data sets depending on whether we were looking at R or Python. So for Python folks, we were taking a look at the species at the Georgia Aquarium. And for R users, we were looking at different metrics from the Falcons football team.

So let's say that we want to explore this demo a bit more. Here we are on the GitHub repository. We scroll down. Gives us a bit of an intro. Some of the setup, which is what we just did. And are just about to do. And then instructions for the demo. So I'm going to hit code. I'm going to copy this URL to the clipboard. Going back to Positron. And go over to the activity bar. And you notice it says Git is not installed or otherwise not available. Install Git or fix your Git installation. Let's return to the Positron documentation.

Here we can hit Git version control, where it mentions a little bit about Git, which is a distributed version control system that tracks changes in your boss over time. And it mentions before you can use Git in Positron, you need to have Git installed on your computer. To do so, we can go to git-ccm.com and download Git. Here are the instructions for macOS. It says install Homebrew if you don't already have it, which I do not have on this computer. So first, I'm going to install Homebrew by running this script. Return to Positron. Open up the terminal. Hit paste. Enter.

And let's go back and type install Git. So let's reload the window. Now if we hit clone repository, we can clone from and select as a repository destination. Then open it up. I'm going to say I trust all the authors in this parent folder. And here we go. Now we have our project open.

Layout tour

So let's briefly talk about each section of Positron that we see here. So first up is the activity bar on the far left, which provides quick access between core views such as explore, search, source control, and extensions, among others.

The primary sidebar is on the explorer by default, and it shows you different views depending on what you have chosen in the activity bar. So right now it's on the explorer icon, which provides the file explorer to navigate the project directory in the outline. If we choose the assistant icon, this pane provides access to Positron assistant. The editor is in the center by default, and this is where you write your code.

The panel is below the editor by default. It contains the fully interactive integrated console as well as the terminal. You can also access logs from the output channel in the panel. The second view sidebar is on the right by default. You can switch between the sessions pane, and this is where you can explore the variables you have defined and the plots you have created. The connections pane, the help pane, and the viewer pane.

The title bar at the very top of the window shows the active file project along with the window controls. Below it, the top bar provides global flow of information about the project. The title bar at the very top of the window controls. Below it, the top bar provides global project tools such as file search, the project switcher, and the interpreter selector with the ability to start, stop, and switch interpreters. And the status bar at the bottom of the window displays details such as your git branch, language mode, portal version, and cursor position.

If you are ever in this setup and you find yourself wanting to return to the default, these icons can help you do so. So if you click on here, you'll be able to customize your layout and move things around. Say if you prefer side-by-side layout, a notebook layout, or I like the default layout, which is the stack layout, clicking that returns me to my original view.

The explorer is the first and foremost view in the activity bar. It's like a file explorer for your project. And the sidebar expands to show a tree of all the files and folders in your current workspace. So you can easily browse and open any file in your project. You can also create new files, new folders, refresh, explore, and collapse all the folders. It will also change the colors and the icons if something has been added or modified or staged for commit.

Running the Python demo

So let's say we want to run our Python demo. I'm going to switch my interpreter because it selected R for me. So now I am in Python. You can see R is still open. Since I'm not going to need it right now, I'm going to go ahead and close it and just stay with Python. And then I'm going to open up my python-demo.py. If you notice here, plot 9, it has a squiggly line underneath. And hovering over it shows me what the error is. It says import plot 9 cannot be resolved. What that means is that I'm missing plot 9. It has not been installed.

Similarly with pullers, it is also missing. In my file explorer, there is a requirements.txt file. These are all the files that I need for my project. So I can actually go ahead and install all of those libraries using UV. I want to create a virtual environment, which is a self-contained way of managing all of my Python dependencies. I highly recommend always creating a virtual environment if you are running a Python project.

So I'm going to run, in the terminal, uvvamp to create my virtual environment. You notice it's going to say creating virtual environment at .vamp, activate source, vamp bin, activate. And at the bottom, it's going to say we notice a new environment has been created. Do you want to select it for the workspace folder? So I'm going to hit yes. Now, both the console and the new terminals will reflect the new project-specific virtual environment. If I click my interpreter here, I can confirm because it has the directory for my demo. And then it also says vamp in Python. Now I can install all the dependencies by running this in the terminal. First, I'm going to source my virtual environment. Enter. And now I can install all of the libraries I need by running uvpipinstall-r requirements.txt. And super quick, UV installed all of the packages that I need.

Okay. Now, when I return to my Python-demo.py script, plotline and pollers are no longer underlined. And I can hit run cell. It's going to import all the modules and then also read in this GeorgiaAquariumSpecies.csv data set and then store it in an object called species. Let's quickly take a look at the rest of the script. So up here, we have loading libraries. The next chunk of code has a summarizing the number of species by conservation status. And we can see there are a few options, critically endangered, endangered, vulnerable, and so on. This next section is creating a summary table. And then the very last part is creating a plot using the plot9 package.

The console and variable viewer

Since we ran this chunk up here, we also got an output in our console. So let's open that up a little bit more. If you notice, it printed the species object that we created up in the Python-demo.py file. So the console provides a direct command line to the Python-demo.py file. So the console provides a direct command line interface for interacting with R or Python. So you can type a single line or block of code directly into the console, press enter to execute it immediately. And like we just did when you run a script in the editor, the output, like any results, plots, or warnings are displayed in the console. We can take a quick look at the species data set. It's a bit abbreviated here, but we can see some of the animals, some of the information contained about them, and so on.

But one thing to note is that the console is meant to view these variables in the objects, but it's meant to be temporary. Any commands we type into the console are not saved, and we want to make sure that we do that in our script. So while having this printed out is very helpful, it's a little bit hard to see. And for that, Positron has the viewer pane. Located up here, it displays any objects and data sets that we have imported. Opening this up, we can take a closer look at our CSV. You can see the names of the various columns. We can see the data type, in this case string, across all of them. And then opening them up, we can see the first few values. So this helps provide a quick look as to what is contained within our data set.

The data explorer

If we want an even more granular view, we can hit this icon to open up the data grid. The data grid is the primary display of the Data Explorer in Positron, with a spreadsheet-like cell-by-cell view. And it's meant to scale efficiently to relatively large in-memory data sets, up to millions of rows or columns. So opening that up, each column header has the column name above the data type, which is dependent on the back-end type.

At the top right of each column, there is a context menu to control sorting or add a filter for the selected column. You can resize the columns by clicking and dragging the column's borders. The row labels default to the observed row index. And we can also sort the data by column's value by opening up that menu and then clicking Sort Ascending or Sort Descending.

Another aspect of the Data Explorer is called the Summary Panel. And this displays a scrolling list of all the column names and an icon representing their respective type. So in this case, this column is called Name. Hovering over, we can see it is a string. It also displays a sparkline histogram or frequency table of that column's data and the amount of data that is missing as both an inline graph and an increasing percentage. If you click on the caret symbol for a column, it will expand to show additional summary statistics and a larger sparkline. And the summary sparkline charts and missing data indicator also provide tooltips when you hover over them.

Above the Summary Panel are the filters. So by hitting this plus sign, I can create an ephemeral filter where I can take a quick look at the data if I were to apply certain filters without actually changing the data set itself. So for example, let's say I want to select conservation status. It's not equal to least concerned. Apply the filter. And then we can take a quick look at the other categories and how much, how many counts they have and how many things have changed. I can continue adding more filters if I want, or I can remove them. And again, these are ephemeral filters. They don't modify anything within your data set.

These are ephemeral filters. They don't modify anything within your data set.

Running the full script and the plots pane

Let's return to our file. So I could go through and run all of this code line by line or chunk by chunk, but I can also hit this play button and it will run the whole script from top to bottom. Doing so, you can see that my plot has now populated. It shows a quick histogram by conservation status and that summary table that was created within the script.

So let's take a look at how this works. So I'm going to go ahead and create a script. Something I may have noticed is that the font size to me seems a little bit small. And for me, personally, my favorite theme in plot nine is theme minimal. So per se, I am wondering if I could edit the theme and the font size at the same time. If I go to the console, I can run help and then run p9, which stands for plot nine, and then theme minimal. Hit enter. And the help documentation for plot nine is available within Positron itself. And taking a quick look, I can see indeed within theme minimal, I can change the base size, which is the base font size, as an argument itself. So I can scroll down and add that to my code. Also add the base size. I'm going to do 16. Hit run cell. Now I can see the theme minimal has been applied and the font size is bigger.

In the plots pane, I can also look at my plot history. So say I wanted to compare how it looks now to my previous plot, I can click back and forth. There are various other things I can do in the plots pane. From here, I can save my plot and also provide a specific width and height, if I so choose. I can copy the plot to my clipboard. I can also change dimensions of the plot depending on what I am interested in. So say I want a square plot. The other thing I can do is apply a dark filter and save this version, if I prefer, and then also clear all plots.

One other thing I want to note, if we look back on the editor, on the side, you'll see that on the line 68, where I have changed the theme, there is this green bar, which indicates that I have made a modification. So quick recap, we've taken a look at the file explorer, the editor, the console, the variable, the viewer pane, along with the data grid, the summary panel, and the filter bar. And we've also taken a look at the plots pane.

Positron Assistant

Now let's take a look at the Positron Assistant. I click Positron Assistant, open this up. If we go back to the Positron documentation, features, and then Positron Assistant, you can learn more about Positron Assistant. If you notice, we need to opt into Positron Assistant enable setting to enable it. So by hitting this and hitting open link, it's going to take us to our settings in Positron, and then I can hit enable. Next up, we'll have to go to our command palette and reload the window.

Going back to Positron Assistant, we can hit add a topic as a chat provider, paste our interopic key. After we hit sign in, hit close, and now Positron Assistant is now enabled. Positron Assistant, as noted in the sidebar, is an AI coding companion designed to accelerate and enhance your data science projects. So let's try a few examples.

So if you notice here, we are in ask mode. This is the default mode with Positron Assistant. Ask is for questions and help, edit is for collaborative code modifications, and agent is for autonomous task execution like file management and code execution.

First, let's ask Positron Assistant to please summarize the species data table. It lets us know the species data table from the Georgia Aquarium contains 154 species across 11 columns. Overview, key columns, conservation, status, distribution. All right, so we can see this could be very helpful for beginning your analyses.

Let's try another question. We can ask Positron Assistant, what do you see in the current plot? Positron Assistant has let us know, looking at the current plot, I can see a horizontal bar chart that visualizes the conservation status and we have the Georgia Aquarium species. Here's what the plot shows. So we can see that the current plot is showing us the Positron Assistant has let us know, looking at the current plot, I can see a horizontal bar chart that visualizes the conservation status and we have the Georgia Aquarium species. Here's what the plot shows. Let's know it's a flip bar chart. All right, this is very helpful and can help us like figure out how we best want to explain the things that we've seen in our dataset.

Let's ask Positron Assistant one more question. Based on data tables in my session, please suggest some starter code for interesting analyses. I'm just letting it run. So we can see it has a lot of ideas. So it suggests some geographic distribution analyses that we could do, size distribution by conservation status, diet diversity analysis, habitat complexity analysis, conservation status heat map, and fun fact text analysis.

So from here we have a few options. So as opposed to the answers from before, this time Positron Assistant actually gave us some code. So if we hover over the code chunks, we have a few options. Here we can run in console. So as you recall, the console provides a temporary workspace for our code. So if we want to take a quick look at what Positron Assistant provided us, we can hit that. We can also apply in the editor. Let's say we want to check out the size distribution by conservation status. I can hit this play button, and then it will show me the plot that it came up with. And with that, I'll stop there. I hope that you enjoyed this quick Positron setup and layout tour, as well as a brief glimpse into Positron Assistant. If Positron's AI capabilities are what interests you, including Positron Assistant's different modes, and DataBot and AI Assistant for exploratory data analysis, I highly encourage you to sign up for Ryan Johns' workflow demo happening at the same time next month. With that, thank you, and stick around for Q&A!