Posit Cloud Essentials | Ep 4: Usage analytics and space management with library(rscloud)

Happy Halloween everyone. My name is Alex Chisholm. I am the product manager for Posit Cloud here at Posit. I really appreciate you taking the time and joining us today as we get together for the fourth installment of Posit Cloud Essentials. At this point through the first three we've been able to create accounts, set up different workspaces, collaborate on data projects with other people. Today we're going to focus on a lesser known tool that can give you programmatic access to specific things within Posit Cloud and we'll see some use cases for that.

As we've defined what Posit Cloud is, it's essentially a SaaS online platform with certainly a free tier that you can play around with today that is centered around this notion of space. And within a space you can have projects, you can have collaborators, you can have data connections, and you can kind of monitor and manage who's collaborating across all of these entities.

Space member roles

One thing we haven't talked about before in detail is this notion of space member and the role associated with them. So I just wanted to go broadly over this today because it's going to be important when we start looking at what this package can do for us in terms of understanding the analytics and some of the member management behind it. So there are four levels. If you were to create your own space, you would be what's known as an admin. And as an admin you're able to manage users, so you can bring people on, you can boot them off, you can set the role that they're going to have within the space. You also have the unique ability to archive and delete that specific space so you can get rid of it forever. And of course as an admin you're going to have control over your content and anybody else's content that's on the system, so viewing and editing and the like. And then finally you're going to be able to view analytics and usage data based upon what people are doing in that space.

Typically if we're thinking like in an education organization, institution, the instructor would be the admin in the space and maybe they bring on someone like a TA. And the TA might often get assigned the role of moderator, which has some of the more advanced functionality that the admin has. They can control all access and they can view usage data. So they're able to see what people put together, they're able to get in there and work on it and also edit and delete things that might need to be cleaned up for that space.

And then the contributor is typically aligned with this student role, so we might have more of them and they can view any shared content that the admin or the moderator or actually other contributors have made public to that space. And they're also able to control their own content, so they can look at something the professor has put together, they can maybe turn that into their own copy and start doing work, and they can also create random projects to start learning data science in that way. And then finally a viewer, and a viewer has the least amount of roles by default, and really all they can do is view shared content that someone else has released to that space.

And if you think across like all of these four user groups, there are different levels of interaction between everything that's going on within that space. So you've got content visibility, we're going to be able to either see your own stuff certainly or other things that have been shared, we need to have some element of membership management because we have all these different people with different privileges and permissions, and then underlying all this because we are an online platform, we have the ability to tie back what everybody is doing from a usage point of view to see what content they're engaging with and how many compute hours have been used within a given space.

Introducing the rscloud package

So what I want to do today is take a quick look to a package that is up on GitHub that we're going to go through. It's called rscloud and it's going to give you the ability to interact with your Posit Cloud account, especially at that space level that we just we just saw. So we'll drop this this link into the chat for you to play around.

And from within this package we're going to look at two kind of streams of work that we could do. We could do space management and we're going to look at being able to go out and like find the spaces that you own, be able to see who's in there, be able to invite people, remove people, and that's one of the main benefits here actually. Like everything we're going to see today you can access via the UI, but sometimes you might have a space, whether you are a university and you've got a big course of 300 people that are in there, or you're at an organization, you have a bunch of people that are collaborating on a data science project, and you want to bring in a lot of people at one time or remove a lot of people, you're going to be able to do that programmatically through some of these functions. And then finally we're going to take a look at the analytics that comes from it. So this is primarily what you see on your usage tab, but if you've got a lot of content and a lot of people and a lot of spaces, this makes it easy to get that into kind of a you know a data ready format for you to do subsequent analysis.

So this is primarily what you see on your usage tab, but if you've got a lot of content and a lot of people and a lot of spaces, this makes it easy to get that into kind of a you know a data ready format for you to do subsequent analysis.

If you have any questions along the way please drop them into the chat. If I don't catch them as I'm going along and giving this presentation we'll be able to get to them at the end. So let's get started. I'm going to go in and switch my tab to Posit Cloud.

Tour of the Posit Cloud space

Great. Now from here I'm going to use a free account today, and again if you don't have an account already go to posit.cloud, create an account, and you'll be able to see all the functionality that I'm demoing today. So I'm going to log in just with Google. This is just a free dummy account that we set up, and you can see when I arrive in here that I am Professor Adams. I've got a personal workspace which we've described in the past. Right now I don't have any content in there, and you can also see that I have a stat 250 space, and by clicking on it we can see everything that's in here. So right away you see we have a fair amount of content to begin with. You can see because I'm on this free account that it says this space is full, so I'm not able to have more than 10 projects within this given space, but that's okay for today for our demo.

So even though today we're not focusing specifically on the features within a space to help this content management, I'll show just a few things to help out. One is along the lines of filtering. So you can see we have these 10 pieces of content. I can go and see what type of content piece this is. Right now they're all projects. If I go to access, I can be like, well, what of these are available to space members? And we can see that all of these six which I designated as an assignment for each project are now viewable. And I can do basic things like sorting based on the create date and the name as well. The last thing that I'll show is just how to create a list. So if you have a lot of content and you want to organize it maybe a little bit better, you can go to new list and you can type in, you know, the name that you want for this list and you can make it available for just for admins and moderators or for anybody in your space. And you can see here I've grouped those six core assignments into unit one where we're talking about data visualization and exploratory analysis. In unit two, I've got significant testing. And then in unit three, I've got regression analysis and some machine learning basics.

So we have content. We have our space. We even have members already. So right now I've got myself, Professor Adams, and I've got three students, Pugsley, Gomez, and Morticia here. And you can see that their level is at that role of contributor that I mentioned earlier on. That is the typical one we associate with students if we're thinking through an education example.

You can refine even further the permissions for contributors or viewers depending on what you want to do. And then we also have a usage tab where you can see at a high level how many compute hours have been associated with this space, the number of active members, and the amount of active content that is within this period. And you can segment this out by usage period.

Setting up the rscloud package

And what I want to do through this rscloud package is set up a way, again, programmatically to get some of these data points more quickly and then to help with those bulk operations about bringing people in or maybe booting them out of a space without having to go one by one, you know, delete, delete, delete. So for this, because I am using this free account and I can't add another project here, I'm going to go ahead and click on my personal workspace and we'll create a new project.

And we're going to have to do a few things here. The first thing that we're going to want to do is bring in some packages that we're looking for, including rscloud, which you will not find on CRAN, but we're going to be able to get from GitHub directly. Okay. So we have our blank session. I'm going to create a new file. We're going to call this just rscloud, maybe. And I'm just going to type in the libraries that I know that I'm going to use for this. So I know I'm going to want the tidyverse at some point. I know I'm going to want remotes. I'm also going to want use this. And we don't have any of these because it's the first time that we've opened this project. We haven't created a template with these packages. So I'm going to go ahead and install all of this.

And while that's going in, I'll remind you about what is different maybe from operating in RStudio on your desktop versus in this environment. The biggest difference is most likely going to be about how you can control the resources associated with your project. So if you click on the gear and then go up to resources, you have the ability to control your RAM and your CPU and the amount of background execution time, which means the amount of time that your session will stay active if you have code running in the background. This is a freemium tool. I've mentioned several times you can create a free account today. If you go to a professional plan or if you're on an education plan, you're going to have a bigger number, a larger level of entitlements for you to increase things like RAM and compute.

All right. So while this is going in, I'm going to go and copy in some code, which is going to bring in the package we need from rscloud.

Generating and storing credentials

In fact, why don't I hop over now to GitHub while that's finishing up. So you can see that the package is here. A lot of these instructions for getting going are going to be described within the documentation. The main thing we're going to have to do that's different from how we typically operate in Posit Cloud is we're going to have to first generate some credentials for us, and then we're going to store them as an environmental variable. And then we're going to use this to interact specifically with our account through the package.

So if I back over here now, we're going to see that we can go ahead and get rscloud installed. Now I've got it. Let me make sure because it's saying I don't have to use this. Let's check for sure if we don't have it. No, that is there. All right. So we should have everything that we need right now to get started. So the first thing that we're going to have to do, I mentioned we need to go out and get credentials to be able to make this secure connection to our accounts information to be able to run some of these functions. For this, there's a function called edit our environment. And when I run this, it's going to open up a new tab and it's blank. And what we have to do is we have to create credentials and then bring them in here to store it. So I'm going to go to my name. I'm going to right click on credentials and open this in a new tab.

I can see already that I neglected to switch tabs on that. You were still looking at GitHub. Sorry about that. All we did here was bring in the libraries that we're going to use. We brought in rscloud and then we ran this command, edit our environment, which gave us this blank file for which now we're going to go to a different screen and grab our credentials. So I went to my name. I went to credentials. I right clicked and I opened and it brought me here.

So you can see right now in this setting area, we have client credentials and right now we don't have any to use. All you need to do is click on new credentials and I'll just call this demo. And it's going to give me a set of credentials. I'll delete this after the workshop. We're going to go ahead and copy the rscloud client ID and the client secret, which is what the package uses to authenticate us, to give us access essentially to the data we're working with.

So now that we're here, I'm going to hop back, share this tab, and now we're back with this blank file. I'm going to go ahead and delete this. I'm going to go ahead and copy the rscloud file. I'm going to go ahead and save that. And now we should have the information we need to start pulling data from our account. So I'm going to close this. The other thing I need to do once I've added those environmental variables is restart my R session. This will be pretty quick.

And now just to make sure we're going to go out, we don't need remotes anymore, but use this in the tiny version of what we are looking for. And then I also want to bring in now that we have it, library rscloud. Perfect. So I'll move this to the top because we don't need it anymore.

Exploring spaces and projects

All right. So we've gone out. We have all the libraries we need. We've got our credentials in there. And now we can start using functions from the rscloud library to start understanding what our environment looks like. So maybe the first one I'll do, what is called My Spaces. And there's a function called rscloud spacelist. But I don't need to pass anything into this. I'm going to go ahead and run this.

And it'll take a few moments to come back. And what it's doing is it's going out to the systems and saying how many spaces are associated with my account that we use as credentials to get through. And we can see if we look at it, we've got five records that come back. And this might be a little bit interesting because if you look to my left of my screen, you can see that I only have one space right now. So it's a little bit curious why these other ones are coming back. And the reasons are these are spaces that I've either been a part of as a contributor or ones that I have either archived or deleted that are still in here for which I can see historic data. But looking in here, we can see that stat 250 is the one that we're interested in. And I've got a space ID associated with it. So I'm going to copy that space ID.

And now I'm going to go back into code. And I want to be able to start setting a target. So maybe like the target space that we're interested in. And from this, I'm going to do rscloud space and pass in that space ID, which I think is okay to do as a numeric variable. Let's go ahead and find out. Perfect. So we can see that the command worked. If I click on target space and see what this is, we have an object here that's giving us a high level summary. We've got four users, and we've got 10 projects in total.

I can use a function called space info on my target space to get a little bit more information. And maybe I'll turn this into a table so we can see it better. I'll call it space info. So we can see a little bit more about our space, right? So we know it's private. It's protected. We have an account ID associated with it. We have a long description, which is actually set up through the UI when the professor started the account, just describing what the course is. We can see that there are no current default project settings, and we've got user counts. We're able to have up to five. We've got four. We've got limitations. So we know a lot about what we can and can't do within the space, but we can also monitor based upon how much we currently have in terms of membership or content, how close we're getting to those limits. Again, this is all on a free plan. And if you were an educator using an instructor plan or a student using a student plan, the rights and the ability to do more are present.

Okay, so we see a little bit more about our space. Within a space, we've talked a lot about this notion of having projects or having content. So we can dig into what content is available, again, by taking that target space that we created, that object. And now we're just going to say space project list. And if I run space project list, you can see that we have these 10 projects that we mentioned. Again, just so it's easier to see for everyone, I'll go ahead and make this into a data frame. I'll store this into a data frame, and I'll click on it. And we can see that we have first who is the name associated with the project. So we had everything that me, the professor, put together. And then we had students in the class who went ahead and made copies of those. And now we see that they have their own sort of standalone copies from this. We can tell the last time that they were updated, what type of project that it is. And we have more information on the metadata behind the name and the description and the like. So a quick way to see what projects you have. And imagine if you had, again, many spaces and many, many students, the ability to go through and do this for each one of your spaces and see kind of like a comprehensive view of usage and engagement, I think is a useful benefit.

Managing space membership

Okay, so we've gone through the space project list. Let's look then at membership. So if I go once again, starting with my target space, and I pass to that space member list, I can see that there are four unique records for unique users, including myself. And then I've got student one, two, and three. And I can get whatever information is in the system about them, you know, first name, last name, when they joined, and all that. So we already knew that these four people were here. We saw that from our initial member list.

One thing you might want to be able to do is programmatically invite people to this specific space. And for this one, I'm going to take target space, I'm going to say space member add. And now I'm going to pass through an email address. And there are other options that we could add to this. Let me show you what those look like. So this is an invite user function, we can go through and we can put in one or I'll show you the way to bring in multiple users in a few seconds. You can also change the default email message that is going out to people. And you can change the role that you want the person who is invited to be able to get. And if I enroll this person now, or if I invite this person, I'm going to go ahead and send that out. You can see we didn't get any error messages. So what it did was it sent out an email to this email address, asking them to join this space.

You can actually see who's still waiting and like how many invitations you might have out there by looking at the space invitation list function. So if I run this, I'm going to see who's still waiting. It would have been empty a few moments ago, but now I can see that I have one record with this unique ID to a specific person that is still outstanding. So I'm going to hop off screen now for a second. And I'm going to find that invitation in my other account. Okay, I got the invitation, I'm now following it in Posit Cloud. All right, and I'm in over there. So now if I run this same command, space invitation list, it returns no invitations found. Because the invitation was out, it was accepted by this new user, and they were brought into the space. And if I were to run again space member list, which initially had four people, now you can see that we have five people that are within this space, including our new person, student number four.

If I were to go to my workspace, I'm sorry, to course space, I'm going to open this in a new tab. I'm going to follow it over and share this tab. Now we're back within our course space for STAT 250. If I click on membership, you can again see that we had this new person, student number four, her name is Wednesday. She's also a contributor. And we can see that our class has grown based upon what we did from the command line or from code.

Viewing usage analytics

Okay, so we're back now in our course management project. We've just gone out and we invited people. The last thing that I want to show you is how you can understand who's doing what within your space from analytics. So the way to do this is to click again on target space as where we're starting. We're going to go out and say space member usage. And running space member usage, you can see in the console that it only returns one row. It gives us the total compute time, the number of active accounts, the number of active users, the number of active projects, but it's not giving us anything at that user level. If you want more specifics, you're going to again do target space, space member usage, and then I need to pass a few more variables in here. So I'm going to do filters. I'm going to say list group by. I'm going to group it by user ID, and then I also need to tell it how long we want this usage data to come from. So if you remember, or maybe you don't remember, I'll show it to you in a second. Again, I'm going to say right now I want it from seven days. So it's going to go back to my space. It's going to say group everybody by their user ID and return analytics data specifically for the last seven days.

And we can see that I've messed up something here. The from is still within the filters call. This should work. There we go. And we can see now again within our one space, all the five people, three of them have compute hours associated with them. If you looked deeper into the columns here, you would also see the number of active content items. And you can see specifically what each person is doing. So two of our people haven't even come in and done any compute at all, Morticia and Wednesday.

So we've done a fair amount here. Let me hop over, keeping this open, I'm going to hop to a different tab. I'm going to tie back that usage data we just looked at. And you can see it here kind of like in the UI form where you have a little bit less control over what period we're looking at in terms of usage. So one thing that rscloud gives you is a more refined kind of time horizon for what you want those analytics periods to look like. Here we just show you a usage period or calendar month, and then you can pick a specific day. But either way within this space, you can see kind of what we saw in that data frame that came from rscloud, these specific people. And then if I went to Punctually and I looked at the content that they have, you can see that here are the total hours that they used so far in this period. And you can see it broken down by content item as well.

Removing members in bulk

Now, the last thing that I'll show before we get into Q&A is our membership again. So let's think about it's like the end of maybe a consulting project with a bunch of people, or maybe it's the end of the semester, and your students, you no longer need them in the space for whatever reason. Now, you could go through here and delete everybody or remove them, but that could be time consuming if you're dealing with a lot of students. So the last thing we'll look at here, I believe I can also kick out the person we just added. So let's do target space. I'm going to say space member remove. And I'll put through the same email of the person we invited.

Oh, and I need a content action. Probably a good idea to go to the help function on this, right? So it's looking for a space which we're passing through, the user which I put in, and then a content action. This is saying if this user has anything specifically within the space, what do you want to do with it? I'm just going to move it to trash if it's there. At this moment, there's nothing there, but let's go ahead. It's going to give you a prompt to say, are you really sure you want to remove this member? I'm going to say yes.

So we did all this. I think there was a lag on the screen again. My apologies for that. All we've done here is we've added a new function, space member remove, pass through the email address, and we had to put through a content action saying, well, what do you want to do when you remove this specific user from the space? What do you want to happen with all the content for this person? And we're going to send it to the trash. The command line prompt us to say, are you sure you want to remove member 12244, et cetera? I said yes. We removed that person. And now if I go back over to the user tab and refresh this page, you can see that Wednesday is no longer a student or a member of the Stat 250 space held by Professor Adams.

Inviting multiple users at once

So I think we're almost ready for Q&A. I do want to show one more thing that I skipped over a few moments ago. So the last thing that I'll share back within the course management one is, well, what if you wanted to invite many people to your space? And what the function requires is that you have a data frame to be able to do this. So what we can do is we can create a new data frame, let's say new users, and maybe you're pulling this from a course list that your university provided you, email1 at gmail.com, email2 at gmail.com. So we can go ahead and we have our new users. And then what we're going to want to be able to do is bring in a bunch of them by doing this.

So we're going to turn this into a new students table. We have what's called our user email. It's going to be equal to users. So if I pull up right now new students, now you can imagine a spreadsheet or a CSV file that you brought in. Once you have that list, all you have to do is pass it through, and it'll go through, take those two email addresses, send out those emails again. Both people will receive an invitation. You can track their invitation through that view space invitation function that we looked at earlier. And then you're going to be able to tell who has been invited and who is still waiting to join.

Once you have that list, all you have to do is pass it through, and it'll go through, take those two email addresses, send out those emails again. Both people will receive an invitation. You can track their invitation through that view space invitation function that we looked at earlier. And then you're going to be able to tell who has been invited and who is still waiting to join.

So I think with that, I'm going to hop back in and see if I can see any questions coming in. And today, once again, we have Hannah here who's going to help coordinate the Q&A session.

Q&A

Hey, everyone. Thanks, Alex. So just a reminder that we've set aside time for Q&A. So if you have any, there's still time to either drop them in the YouTube chat, or we have the Slido link that was shared, and I'll share it on the screen now. We don't have any questions yet, so I'll just use the space as a reminder that we host these every month on the last Tuesday of the month. And you can add the events to your calendar with the link that I'll share in the chat in just a second. So we'll wait a couple minutes if any questions come in. If not, I'll be happy to if any questions come in. If not, Alex, you've covered every question there could be.

Well, I guess so. And we will share with you the link to the GitHub repo. You can also dig into the functions there. But pretty much everything that we shared was coming straight from what you're able to do within these functions. So both on the space management side, the analytics side. And it's not that the vast majority of this functionality can't be accessed from the UI, but we find that some teachers especially like the efficiency of being able to do it through the command line when they're setting up and when they're closing down their courses at the end of the semester. And speaking of education, next month, our topic is going to be kind of like educational use cases to see, you know, what are the most effective and efficient ways that instructors can kind of bring students into Posit Cloud to teach, you know, short or long term courses. A lot of it applies also to corporate training and individual setting up sort of like data workshops and bringing people into a unified space. One of the main benefits, of course, is that you don't need to deal with everybody being on their desktop trying to set up and align, you know, their IDE environments. You're able to do it in one place with templates to help you out and a stable server environment provided by Posit Cloud.

Awesome. So no questions yet. So I'll give it a couple more seconds, but if there aren't any questions for today, we can wrap up early and give a little bit of time back. But also another reminder is that all of the past Posit Cloud Essential events are in a YouTube playlist all together, so you can watch them at any time. This is the fourth installment, so be sure to check back on the last month's episodes.

Cool. So I guess we did have a question come in, so I can ask that now. Someone asked, can a removed user's content also be archived with the command that was demonstrated? Yes, you've got four different options that it was pulling from. Let's see. You can archive or trash, and then they can take it with them. So archive, trash. I think two options come from that natively. If you go to the package and you look at the help for the function that a space member removed, you'll be able to see all the full options there. Awesome. We had another question.

Alex asked, how does web integration work, for instance, if each student must make a blog with independent examples? Can I integrate with BlogDown? That's an interesting question. When you say integrate with BlogDown, are you trying to get people to publish specific things within Posit Cloud? And if we can't have an easy back and forth here, I'm happy to jump on a call or an email conversation with you as well.

And while we're waiting for Alex, oh, Alex got back to us. So email later would be great. Alex.Chisholm at Posit.co. Awesome. And then a follow-up question from Robert. He asked, what is the difference between archive and take it with them? An archive will go within the space's archive directory. A take it with them will bring it to their personal workspace.

Okay. So we've run through the questions for today. So thank you all so much for joining. Thank you, Alex, for walking us through it. And we'll see you next month for another episode of Posit Cloud Essentials. Thank you all for joining in your questions. Yeah. Thanks, Anna. Thanks, everybody.