Sharing SimBiology Simulations with MATLAB Web Apps
See how systems pharmacology or PK/PD modelers can create web apps to share SimBiology® model simulations or any algorithm based on MATLAB® with collaborators. You can host these apps at your organization using MATLAB Web App Server™ and allow your colleagues to run their own simulations of your model by sharing a URL. They can then access and run web apps in their browser without installing any software. Highlights include:
- Developing a user interface with App Designer
- Integrating the simulation of a SimBiology model
- Deploying an app as a web app using MATLAB Web App Server
- Allowing access to apps for specific groups or people
Published: 16 Aug 2021
Hi, my name is Jérémy Huard, and I'm an application engineer at The MathWorks. And today, I'd like to talk about how to share SimBiology simulations using MATLAB web apps. But let's first consider reasons to share a QSP model. Let's assume Sarah is a modeler, and she's built a model in SimBiology.
Scenario number 1, she might want to share that model with Pablo, who is also a modeler. And because he is a modeler, he might want to modify that model. He might want to recalibrate it using new data. He might want to write his own analysis. And maybe Sarah has developed the first version of that model, but maybe Pablo will be the one who is going to maintain it over time.
Scenario number 2, Sarah might want to share that model with someone who's not a modeler, like Hiro, who is a pharmacologist, the idea being that the Hiro could make use of the knowledge that has been gathered in that model. He could run simulations of predefined scenarios to predict the outcome of experiments. And here, he does not need to modify the model. So maybe Sarah could hide the complexity of that model. She could even want to protect her IP as well.
So the solution to scenario number 1 is pretty straightforward. Sarah could share the SimBiology project file directly with Pablo, so the sbproj file would contain the model, the data she used for calibration, and any program she's developed for analysis. So Pablo, as a SimBiology user, could just load that file into SimBiology and will be able to reproduce all the results that Sarah has produced. And he would be able to modify the model and run his own analysis. So that's great if he is a SimBiology user. If not, Sarah can export the model to sbml. This sbml file will only contain the model definition.
So again, scenario number 1 is pretty straightforward. But what would be the best solution for scenario number 2? Hiro is not a modeler, so he doesn't know any modeling software. So what would be the best solution for Sarah to share a model with Hiro? And this is what I'd like to focus on today in scenario number 2-- to share a model with someone who's not a modeler. But let's first think about the scenario where Sarah would share the sbproj file with Hiro.
So again, she sent this file to Hiro, who is not a modeler, so he doesn't know how to run simulations. But even before that, he doesn't have MATLAB or SimBiology installed, so he would probably need help from IT to get it on his computer. So he would submit a request. Klaus from IT would get the request and would try to help him. But he would need first to know, what licenses, what software is needed for Hiro? What needs to be installed on his computer? So he would probably get back to Sarah to ask for explanations and get more information.
Once this is done, once the software is installed on his computer and Hiro has now the sbproj file, but he still doesn't know how to run simulations, really. He doesn't know SimBiology, so he might probably get back to Sarah to ask for help. So Sarah will need to spend time with him to explain to him how SimBiology works, maybe, what kind of stipulations he can run, how to interpret the results.
So this is really not a straightforward workflow here. There's a lot of difficulties for everyone involved. Sarah has multiple communications with Hiro, as an end user, and Klaus from IT. She needs to spend time with Hiro to explain to him and teach him how to use the software. Hiro needs to first wait probably to get the software installed on his computer. He will need to learn a new piece of software, even though he's not a modeler. And Klaus had to be involved as well. He had to install software on Hiro's computer.
But what happens if someone else comes over and wants to use Sarah's model as well? And this person might be using another operating system. So he needs, again, to figure it out and install it on this person's computer. So there's really difficulties for everyone involved here. So what if the solution could look like this? Sarah could just send an email to Hiro, saying, "Hi Hiro. I granted you access to my web app to simulate different scenarios of SGLT2 therapy. Just click on this link to access it."
So Hiro would go ahead and click on the link, and this would open an app in his browser that is tailored to the kind of scenarios that might make sense for him to simulate. So here, this is a web app that Sarah has created to simulate SGLT2 therapy using a glucose-insulin model. So Sarah has predefined some parameters that might make sense for Hiro to modify and to tweak for a simulation.
So there's a couple of sliders that Hiro can tweak. He can change, for instance, the dosing amount of the SGLT2 inhibitor therapy. That would run the simulation, update the plots that shows him the direct concentration in the plasma over time here in a period of a week. That would show him, also, the plasma glucose concentration, as well as the plasma glucose concentration AUC over a 24-hour period. That's the yellow curve you see on the right side.
She has also included a table on the left side that summarizes the different runs with the parameter values or the slider values, as well as the metrics as outcome of the treatment, that is the glucose reduction between a case with treatment and a case without treatment.
So here we can go ahead and modify those values-- change the IC50, for instance, of the compound and have a look at the metric at the glucose reduction. We can also simulate a patient that has a higher glomular filtration rate by moving the slider or maybe just typing the value in this text field here and click on Simulate. And you would see that you would get a glucose reduction of about 16% of the 24 AUC.
So that's really great for Hiro, and easy to change those parameters. Those parameters are parameters that Hiro can interpret, that Hiro understand. Doesn't need to see the equations, but Sarah has included a tab to show the SimBiology model diagram for Hiro to see what kind of processes are involved in or included in that model.
She also included an hyperlink to the paper she used as a reference to develop and-- or implement that model. That's here-- the Dalla Man model from the Cobelli group, so Hiro can go ahead and open the PDF and read about the paper and the model. And we have a look at the equations as well, if he's interested. So that's really great for Hiro to render simulations, have a look at the plots.
It has the results in the table as well, but maybe he wants to document this and archive also those results. So Sarah has included a button here to export the results to an Excel sheet, and that downloads a file locally on Hiro's computer, so an Excel file that contains the exact same results we have in the table of this web app. So here, this file is saved locally on Hiro's computer, and Hiro can just archive it or he can maybe use the results for post processing.
So that's really a great workflow here. Sarah doesn't have to teach Hiro how to use this app, because this is tailored to the kind of simulations that make sense for him to simulate. The result's also easy to interpret as well. Hiro doesn't need to learn a complicated software or to develop models because he is not a modeler-- he can just run the simulations he wants to run. And that's also great for Klaus, because Klaus didn't need to install anything on Hiro's computer here. This is running in Hiro's browser. Nothing has to be installed locally on his computer.
So in the rest of the talk, I'd like to guide you through the workflow to convert your SimBiology model or integrate it into such a web app. So let's have a look at the complete workflow. Step number one is the creation of a SimBiology model and its conversion to a SimFunction. SimFunction is a function-like interface to run simulations with predefined inputs and predefined outputs, and this can be integrated in any MATLAB code or in an app that you can develop in App Designer. And App Designer is a tool included in MATLAB to build and develop such applications.
Then you would compile this app using the MATLAB Compiler into a MATLAB web app, and once you have packaged and compiled this application, you can host it on the MATLAB Web App Server. Once this is hosted on the server, then your end users can open their browser, go to the URL you send them, and they can just run this app without having to install anything on their local computer.
So let's now talk about the personas involved in this workflow. So step number one will be done by the modeler, by you, as a SimBiology user, and you'd probably also not only create the model, but also create the SimFunction. The app development would be done either by someone else who is really dedicated or has a lot of experience in app development. Could also be done by you as a SimBiology MATLAB user as well. This person will only require-- needs the SimFunction that has been generated in step number one.
Once the app has been packaged, this would be hosted on a MATLAB web server that is installed and administered by IT. This is a one-time installation, and IT can then just maintain it and make updates when needed to that server. But they really only focus on the installation of the MATLAB Web App Server. And at the end, users would just open their browsers. They really don't need to install anything. They could be non-modelers, but they could obviously also be modelers and make use of that model.
So now in the rest of this presentation, I'd like to talk into more details about the different steps here. So step number one is the creation of a SimFunction, and for this you would need to write a couple of lines of code to first load the project or load the model with sbioloadproject, and you will need to create a SimFunction. There is a data get method called createSimFunction for that. And then you would save it into a MAT file, and that is a MATLAB-specific format that can contain anything in the MATLAB workspace, including a SimFunction.
So let's have a look at how it's done. So we would first here load a model from a project, and we'll here load a TMDD model. This model is then available in the MATLAB workspace, and you can manipulate it to have a look at parameters, pieces, or get the equations generated by SimBiology out of this model. For instance, you can also extract informations like variance and dosing information.
So here, we might want to simulate our model using the estimated parameter values that are saved in a variant with the name Estimated values. I can use the getVariant method and get that variant from the model. I can do the same with the dosing information. So I use the getDose method to get the dose schedule I'd like to use for a stimulation. That is here a daily dose.
So then we can have a look at the properties of this dose by quoting the method getTable, and this will generate a table with the properties of this dosing. And we see here that the dosing amount is specified by a parameter in my model called doseAmount.
So maybe I just want the end user to be able to check that parameter and run the stimulation. So the input of my SimFunction would be this doseAmount parameter, so I define this as the input of my SimFunction and the output. might be the Receptor Occupancy because we are here simulating a TMDD model.
So now I can create a SimFunction. It would take the model first, then the input parameters, the outputs, and it would generate the dosing information used for simulation as well as the variance, the baseline variance that I used for simulation. And that's it. So now I can even accelerate it the same way I would do it in the model analyzer app.
So I can run this code. But really here, the call to createSimFunction, that's the backbone of this whole workflow here. This is what we need to integrate a SimBiology model into a web app. So we can now save this SimFunction into a MAT file, along with the dosing information for this dose table. And those two things, that's what I would need to run simulations in the app.
So we can test this first in a script. So the first thing I'd like to do is check the time unit that's been defined in the config set of that model. That would help me define the stop time. So here it's in hours, so I can define the stop time to 240, if I want to simulate for 10 days. Now I can define the dose amount I'd like to simulate, so that would be 150 nanomole.
And I can now call my SimFunction, and I would call it the same way I would call any MATLAB function. It behaves like a MATLAB function, It takes dose amount, it has input-- that's the input we defined for the SimFunction. It takes then the stop time as second argument and finally takes the dosing information for this dose table. And that's basically it. I can just run this code now and it's going to run my simulation using the accelerated SimFunction.
Now I can do postprocess the results like, for instance, create a plot. So I can generate a plot out of the Sim data object I got from the SimFunction. And we have here the Receptor Occupancy and we see the daily dose that's been given during seven days. Can also add labels, of course, and add some other annotations to make it easier for end users to interpret the results. So that's basically it. So we have created the SimFunction and we can now start developing an app.
So to create an app, I would use the App Designer, and App Designer is a development environment that is included in MATLAB for you to create an app or a user interface. So it provides really an interface where you can drag and drop components. So let's have a look by first creating a blank app.
And we get an empty canvas here, where we can drag and drop components from the Component Library that you can see on the left side. So we have axes, buttons, sliders, tables, and really a lot of different components, interactive components that we can drag and drop on this diagram to layout the app.
So the first thing I'll do is I'll take a grid layout and split my app between two panels, so the left panel and the right panel, and the left panel will contain the sliders and the right panel the axis. So I can now drag and drop an axis and put it on the right side of this app.
And I-- on the right side, you see the Component Browser. That's where I see all the properties of this component, and I can add things like titles, labels, and all those things. So I really have access to all properties, including grades and any color I'd like to change, for instance. So I can do this here. I can also do it programmatically in the app dynamically.
So now I'll add a panel to the left side, and his panel is going to contain my controls. So my sliders, for instance. So here in this specific example, I'd like to change the dose amount, so I'll add only one single slider. I might want to change the limits of that slider, so here maybe have a minimum dose of 15 nanomole and a maximum of 300. And I'll set the default value to 150. So that's really it for the layout. I can just click around and see how this app behaves.
So this app is up and running. But if I move the slider, nothing happens, because I haven't defined any action. So I can add an action by adding a callback. A callback is a function that is triggered when I do some action that is here when I change the value of the sliders. So now I can copy and paste the code I had previously written in my script to test the SimFunction, and I can just adapt it to my app.
So the dose amount is the value of the slider. I can maybe fix the stop time to 240 here, and dose table, well, that's saved in the MAT file along with the SimFunction. To make sure the plot's going to appear in my app, I just specify the axis handle, or the axis, and the name of this axis is specified in the Properties block of the app. So that's basically it. This callback is here done, almost.
The other thing that we need is to make sure that the app is loading the SimFunction and dose table, and this is what I do in a startup function. That's a function that is triggered only once when I start the application. And I want to save the SimFunction and the dose table in my app to share it between the different functions.
So I'll create new properties in this app. So doseInfos, for instance, that will contain the dose table, and SimFunction that will contain the simFun. Those variables would be available in the different callbacks of my application. So I just need to save simFun now in app.simFunction and dose table in app.doseInfos. Then, of course, I will need to adapt the callback of my slider, so I just need to change here simFun to app.simFunction and dose table to app.doseInfos.
And that's really it. My app is now ready. I can click on Run and test its behavior. Now, if I move this slider, we'll see that the simulation is run and the plot is updated. The only thing that is not really great is the y-axis is changing the limits of this axis, so I can maybe fix it to something around 0 and 1. That would make it easier for the end user to spot the differences when the dose amount is changed. So we know that RO is going to be between 0 and 1.
So now I can click on Run to just test it and make sure that this behaves as intended. And now you'll see that the thresholds, just clicking on this threshold, that this is not moving. So that's really great. So we could use App Designer and develop pretty quickly a very simple app. And this is indeed a simple app, but you might want to add other features and make it obviously more interactive, more complicated.
App Designer is a great tool for that, but there's more to MATLAB that makes it really a great framework for team-based app development, because as the app is getting bigger, you might want to work as a team on this application as well. So what has MATLAB to offer?
So first, it has the possibility to write classes, so it's object-oriented. That allows you to write your own components that you can reuse between apps that makes it easier also for you to get internally maybe a library of components you think are useful and might be reused in different applications. And also, that makes it easier for everyone to work on different components so you can reduce the merge conflicts. So everyone is going to work on the specific component on its own and on the app at the end, you would put them together to build the application. So componentization is here definitely a great asset, and you can use things like listeners and events.
The other feature is the project management. So MATLAB includes MATLAB projects that allows you to organize the files in your app, and you have tools like project-specific MATLAB paths. You can do a dependency analysis. You have tools like the class diagram viewer to see how your components depend on each other. And it integrates with source control, like Git and SVN.
So of course, if you work like this and have different components and you might want to update also this app over time, you want to make sure that you're not breaking anything in the app while adding a new feature. So you might want to write tests to make sure that the app is behaving as intended.
So for this, you might want to use the unit testing frameworks, and MATLAB includes unit testing frameworks including an app unit testing framework that allows you to write code to simulate interactivity-- for instance, clicking a checkbox or moving a slider or adding text to a text box. And then you can write tests to make sure that the result is as expected.
So you can automate, really, those tests. You can trigger those tests manually. But you could also use continuous integration so that those tests are triggered automatically when you commit new code using source control. So MATLAB supports Jenkins, Azure Pipelines, Travis CI, CircleCI, GitLab CI. So there's really a lot of different possibilities for you to do this and use continuous integration.
So once you have your application, you will want to package this application to a MATLAB Web App. And this is what you would do with the MATLAB Compiler. So it brings you a web app compiler app, where you can specify the app file. It would look for dependencies-- for instance, it would for the MAT file that we are using-- and you could click package to package it into a .ctf, and this is what's needed to host the web app. So that's really great and easy to use.
I also like to do this on the command line. So the reason why I like to do this on the command line is because the SimFunction, if I accelerate it, SimBiology is going to create mixed files that contain the C code that is compiled, and those files are going to be saved in a temporary folder. So I might want to add those files to my application as well to make sure that the simulations are going to run the accelerated SimFunction.
So I specify those dependencies, along with my MAT file, programmatically with this one line of code here on line 8, and this one line of code is going to create my CTF that contains the app, the MAT file, as well as the dependencies of my SimFunction. So this is now my web app. This is what I need to host on my server.
So let's talk now about the hosting, and this is powered by the MATLAB Web App Server. That is a product that was released first in '20a, and this is a server software that enables you to host and share your custom MATLAB apps and SimBiology simulations as browser-based web apps. It has really all the IT features you would expect.
So it's called MATLAB Web App Server, but it's not hosted by MathWorks. It's hosted by your organization where you want it to be hosted, so it can be hosted on premise or it can be hosted in the cloud as well. There is no limitations in the number of apps or users for that server. So there's one single license that is instance-based. So one license for each instance, no matter how many apps are installed on the server and no matter how many users are accessing these apps.
It supports apps developed in multiple MATLAB versions. So you can have on the Web App Server from the '21a release apps that have been developed in '20a and apps that have been running in '20b. And last but not least, it includes mechanisms to secure and control the access to applications, and I'd like to talk more about this now.
So the first thing is that there is a server-level access control. So the MATLAB Web App Server integrates with your existing authentication servers, like LDAP or Azure AD, for instance. That allows you to assign roles to users. So they could be authors, and those authors can upload, delete, and run apps, and they could be users that can only run the apps.
So how does this look like? So if you go to the MATLAB Web Server home page, you will need to sign in using your credentials. And in this specific instance, I'm an author. So the web server knows that. And I get here a button to manage my apps and upload new apps. So I can select a folder and click on Upload App. Look for my CTF file I've just compiled, and it's going to be uploaded to my Web App Server.
Once this is done, the app is available now to anyone who has access to it. So they can click here, or mostly they would probably go through the home page and they would have a look at the category they're interested in and click on the app to open it in a new tab. And this is going to open the app, this exact same app we were running in MATLAB previously. And it's now running in the browser on the server without having to install anything locally, and it behaves exactly the same.
There is also an app-level access control. This is something that has been added to the web server in '21a, and it allows you to apply app-level policies to control the access of individual apps or folders. So it can really organize and group your apps into folder and configure the access of individual apps or complete folders so that people can only see the apps that they have really access to.
So how does it look like? So again, you will need to sign in on the web server first. So that the web server knows who we are. And here we have three categories that are really three folders on my Web App Server. That's where my apps are installed. So Team A would, for instance, only see the Team A category, so they would see the three apps contained in that folder. But I could also say that a specific member could only see the first app in that folder, and he or she would only see the blood pressure app here, for instance.
So now back to wrap up. Let's come back briefly to the previous workflow, where Sarah was trying to share a model using the sbproj file with Hiro. So it was difficult for everyone involved here. A lot of communications and difficulties, and no one really knew what to do and how to get information from the other.
Here, the MATLAB Web Server helps you really streamline this sharing workflow. So Klaus can now focus on the installation of the web server and is going to maintain the web server. He's going to probably add access to specific users if needed, so he's going to control the access. But this is done on the server, and there's nothing else to install.
Sarah on her computer would develop the SimBiology model. She might also develop the app and might compile it to a web app. And because she's an author on the web server, she will be able to upload that CTF file to the web server, and then it would be available to any end users who would be able to access the web apps. There's nothing for them to install on their local computer. They could even use an iPad as well, since it's supported as a client for the web server.
And the great thing is now Sarah is an author, so she can develop another app. And because she's an author, she can upload it to the web server and Klaus does not have to be involved anymore.
So I'd like to provide you some more info now about how to get started. So the first thing might be a training. So we have dedicated training for building attractive applications in MATLAB, for instance. And there's also an advanced MATLAB Web App application development course because it's really great to build modular applications using object-oriented programming.
And the next thing that might be very interesting for you to get started is consulting. So we have consultants with a lot of experience in building modular and robust apps. So these consultants will get the requirements from you. They would work with you on the app. They would develop it also on their own, but they will explain you how this app is being done. They will coach you and teach you how to extend this app and create new apps in the future as well.
So I'd just like to refer to those apps, gPKPDSim and gQSPSim. Those apps were developed by Genentech together with our consulting department, and they are really focusing and tailored to a specific workflow and developed in MATLAB. So that's the kind of applications that could be done by our consulting.
Thanks a lot for listening. And if you'd like to discuss your project, if you have any questions, feel free to drop me a line. Thank you.