Using MATLAB with Python

Hi, I'm Heather. I'm a product manager from MATLAB specializing in data science. And I'm a longtime user and enthusiast of both MATLAB and Python, which is what we're talking about today.

And I'm really happy to show you how to use both languages together. Amazing applications are built using MATLAB. Many of you are building them. Often you're not using MATLAB alone.

You may be using MATLAB or Simulink to prototype an algorithm, and then deploying it to be used on devices or integrated into applications, or even collaborating with colleagues using C++, Java, or Python. So in this presentation, we're going to focus on using MATLAB and Python together, like we mentioned.

We'll show how to call MATLAB from Python, Python from MATLAB, and we'll answer a lot of common questions and share resources to really help you get started. We'll use an example building a sentiment analysis algorithm. The code is available here to follow along at this link.

Suppose a person says they really loved a movie. The algorithm looks at the text and returns the sentiment or intent of the person speaking. In this case, the sentiment would be positive. If the person instead says it's a terrible movie, the sentiment would be negative.

Overall, the example looks like this, speak into a microphone, convert the speech to text, and then classify the sentiment of the text. Of course, we might not be working on this algorithm alone. We're often working with a team, especially if we're building really large applications like this.

So here, we're developing the sentiment recognition part in MATLAB, but one of our colleagues already has Python code for the speech to text conversion. When instead of rewriting the code or trying to find a different solution, we can just use the Python code for speech to text and do the remaining work in MATLAB. And then suppose we're ultimately trying to integrate the MATLAB sentiment algorithm into a larger Python application.

We can use the MATLAB code for sentiment analysis, since we already have that built, and use Python for the rest of the application. So you can see from this example, there are several reasons you'd want to call Python from MATLAB and vise versa, even all in the same example.

And for this reason, there are different options depending on your goal. You can call Python libraries and functionality from MATLAB. And there are multiple approaches for calling MATLAB code for Python, which we'll see.

You can use the MATLAB engine API for Python, which requires a MATLAB installation. You could also use MATLAB Compiler SDK to compile a Python package. And this doesn't require users to have a MATLAB installed.

And finally, you could access your code in a production environment using MATLAB production server, and this can be accessed through a RESTful call or a Python client. It actually makes sense to use all the options in our case to test each part of the algorithm as we build up the application. And so we'll talk through each step, and any questions that may come up.

Let's start by using the Python speech recognition code in MATLAB. What do we need to get started? Well you need a MATLAB installation, which is kind of obvious in this case. And the Python integration was introduced in MATLAB r2014b. The later releases have nicer features.

There's always advancements, so I definitely recommend the later, the better. But it's possible as of r2014b. You'll need a recent version of Python or 2.7. Even though it's being sunset, it's still used in production.

And you can see all these requirements listed in the documentation. And actually, step one is really to bookmark a few pages in the doc for all this. Seriously, the doc will be your friend. There are some great examples and tips to help you out.

And I'll point out some more useful pages as we go along through the example. So if we go into MATLAB, we can use the pyenv function to ensure the Python interpreter can be reached. In this case, you can see the version in the location.

You can also change this information through the pi end function. All right, we can access it. Let's call some functions. We'll start with something simple just to get the hang of the syntax.

We'll use the Python square root function in the math library. And this is how you would call it in Python. Note that you don't need to import the math library like you would in Python. You just call it like this.

MATLAB automatically loads Python when you type pi dot command. And it keeps it loaded afterwards. And this is also true for modules. You can also reload the modules if changes are made. And there's more information in the doc about this, too.

Let's take a look at the output. It returned to double and where possible, it's going to try to do the conversion automatically. But you can also easily convert it, if not. And we'll see more of this in our example.

Let's try another simple function. We'll print a statement using the Python print function. The function looks like this in Python.

And this is how we would code in MATLAB. See this function accepts keyword arguments for the separator and the end line and things like that. This is another important syntax difference when you're calling Python from MATLAB. Because the equals sign in the function call like this, would error in MATLAB. So we can use the pyargs function to pass the keyword in value as a name value pair that MATLAB likes.

So now we have our print statement. Hello, world. Now let's do something more interesting and work on our sentiment example. Let's first look at our Python code.

We have a module that uses the speech recognition package and the Pocketsphinx software from Carnegie Mellon University. In this package, there's an audio to text function. And this accepts the audio signal along with sampling information, and returns the text and a flag indicating whether it was successful or not.

Here's a MATLAB live script showing the entire sentiment analysis process. Here we're adding the module to the Python path. This is important to remember, just like when you're working independently in either language, you want all of the code you're working with to be accessible by both Python and MATLAB paths. We'll use the built in audio recorder function in MATLAB to listen to the microphone and display the audio signal.

For example, it was the worst of times. Now that we have the audio data, it's time to call the Python code. With this line of code, I'm instructing MATLAB to call the audio to text function from the my speech recognizer Python package. And the syntax is really similar to what we saw before. The output's a Python list object.

We can easily convert this to a suitable MATLAB data type. And we'll talk a lot more about data types in a minute, and as we go along the example. Now we've converted our data and have the recognized text in MATLAB.

So now we'll call our MATLAB function to perform the sentiment analysis. As you can see, the predicted sentiment is negative, which seems correct. And if you're wondering what's in this function, this is a built-in sentiment analysis algorithm called, VADER, from the text analytics tool box.

Let's try another phrase to test a positive sentiment. We have a test script that we can use to repeat the process again. I really love that movie.

Great. This is positive. So the algorithm seems to be working.

Let's look more closely at what we did with the outputs from the Python code. We extracted the output data from the returned list, and then converted it to MATLAB types. We can work with a Python list object directly. We can use it in additional Python functions, or extract data from the list like this.

There are many data types in both MATLAB and Python, so you might be thinking about some others. Here are some examples of the common conversions and default data type mappings. And there's a lot more info in the dock on data types and the conversions between MATLAB and Python for all of the different data types that you might think of.

Cool. Now we've been able to call our Python code for MATLAB. So let's try it the other way around. In our example, the goal is to integrate this MATLAB code in a Python application. And this is why we're showing all these options, as they're really useful for prototyping and testing in cases like this.

Now we know the MATLAB sentiment code is able to use the Python speech to text code. So now let's make sure we can call the MATLAB sentiment analysis from Python. First in this scenario, we need to have MATLAB installed. And we also need to install the MATLAB engine API through the Python package that's actually included in MATLAB setup.py.

And of course, we can check out the documentation for more information on how to go through these steps. And once installed, we can call our favorite MATLAB functions. Let's go to our example. This is a notebook to demonstrate the sentiment analysis using the MATLAB engine API for Python.

First we'll import the speech recognition module for example, and the MATLAB engine module. OK, let's start the engine. This starts a new MATLAB process and returns an object so you can communicate with the process.

Like before, we'll start with a simple function to get the hang of it. The MATLAB functions are called with their need of syntax, but like we showed before, there are some fundamental differences that we'll see in our example. We mentioned the data types before on the output. But this is also really important to note on the input.

Let's see I type the square root function like this. The MATLAB function expects a double or a float into Python, and we can easily convert this. But you've also just witnessed a really important point, error handling. And you can see that both the MATLAB and Python errors are thrown to help debugging and collaboration really.

The error text might look complicated, but when the error's from MATLAB, you'll see MATLAB execution error followed by the text that you'd see in MATLAB. And Python errors in MATLAB are identified by Python error. So it really should be as clear as possible.

So definitely in this case, it's clear there's a data type error, and we can easily fix it. There are other great options for exception handling. Check out the documentation for more examples on this.

Now that we're getting the idea, let's get back to your example. We'll use the speech to text function in our module to record the microphone and display the text. For example, I really love that movie.

Now that we have the text, we'll call the MATLAB code. Here, we're telling MATLAB to call the sentiment analysis VADER function, just like we saw before. In MATLAB, the code returns multiple outputs, but the syntax for this is different in Python. So we need to tell Python on the number of output arguments expected. In this case, two.

It looks like the sentiment is positive again. And these are actually the same results returned by the MATLAB code, since I said the same thing. So you can see how this can be really helpful for testing.

And once we're done running the MATLAB code, we can shut down the session. Let's look at the syntax differences that we saw. One important difference is when the MATLAB code has multiple arguments. Then we specify nargout, like we saw in our example, with nargout equals 2.

Also, if your MATLAB function returns no outputs-- let's say your function writes to a file, you still need to pass nargout equals 0. Otherwise, it would actually error. Another note is when you're trying to use operators like plus, greater than, or the famous backslash operator, you actually need to use the MATLAB function names instead of the operator itself.

So this kind of reviews some of the syntax differences that you'll see as you're trying to call your MATLAB code from Python. Now we've got our application working. But let's say we're ready to share this more broadly without requiring a MATLAB installation. This is really common in deployment and application building. And you want to compile a Python package from the MATLAB code.

Let's look at our example. We can go to the apps tab in MATLAB and open the library compiler app. You can see a number of options here.

In our case, we'll select an output type of Python package. And we'll add our function, the sentiment analysis VADER function. The app will detect any dependencies in your code, and we can also add anything else manually.

We can fill out some useful information. But here are a couple of options worth noting. We can select whether the MATLAB runtime will be included.

Once we package all of this, our users can run the compiled package using the MATLAB runtime, which you can directly include within the package here. Or could be downloaded for free from The MathWorks website. Let's take a look at the sample section.

You can actually provide sample code that calls your exported functions, and the app will automatically generate examples for Python to show you how to call a package. Let's add the test script that calls our function, just using the MATLAB code. Now we can select package.

When this is done, output folders are created with the components, the sample using our test script, and setup code and information. And this is really helpful for the person implementing in Python. Before running this code in Python, both the compiled package and MATLAB runtime need to be installed.

A setup.py is included with the outputs, and can be easily installed. We'll actually show this since installation is a common question. It's really similar to the process for installing the MATLAB engine API. But in that case, we're using this setup.py that's provided with MATLAB. And here, we're using the one generated from our package.

We can open a command window and call Python setup.py. It didn't find it since I was actually in the wrong directory. Of course, in reality you'd want to copy setup.py to wherever you'd like to install this.

I'm just installing here for the sake of example. So hopefully this shows how easy it is to make mistakes and figure them out. Going back to Python, here's a notebook performing the sentiment analysis, but this time using the MATLAB package.

We'll first import the speech recognition module and the package we just generated. And this matches the name that we typed into the app. Then we call the initialize function of the compiled package to start a MATLAB runtime. We'll use the speech to text Python function and the sentiment analysis VADER function just like before. But this time, through the compiled MATLAB package.

For example, that was a terrible movie. The sentiment is negative this time, so it seems the MATLAB code is working. And furthermore, the Python and MATLAB code are working together.

When we're finished, we'll terminate the MATLAB runtime. This is great. We should be really happy with our sentiment algorithm. Things are working well, and now we want to share it with the world.

Clearly, there are many options for sharing your MATLAB code. Users can run it by having access to MATLAB in some way, either through a MATLAB installation or the free runtime when you're sharing in the MATLAB package. But what if we want to host our algorithm on the web? And then we'd have thousands of people accessing the code at once, maybe millions. How can we manage this?

We could actually call the functions through MATLAB production server, which provides load management and other server options for scaling like this. You access functions that are deployed in a MATLAB production server instance. Then the client communicates with server instances without needing the MATLAB runtime.

You use an app to package everything, and then it can be called through either a REST API or a Python client. The app also includes a test server, which is really helpful for testing your code in the production environment. Let's actually show this since it's really valuable. We'll complete our sentiment example by calling the MATLAB function from Python through the RESTful API.

We'll go into MATLAB and go to the apps tab to find our app of choice. This time, it's the production server compiler app. Select CTF, which is the output file type for the deployed archive we're creating.

Now we'll select our function file. We could have multiple if we want, but in our example, we'll just focus on the sentiment analysis function. The app will detect dependencies. And we can include any supporting files we need like text files, mat files, or even Java or Python components.

We'll update the name to sentiment analysis production. And this is what we're going to use to identify it from Python. Now select test.

This provides a test server for exactly that-- testing our MATLAB code in a production environment. This is how we'll access our function. And we'll show how to do this shortly from Python. One thing that's really useful is setting breakpoints for your MATLAB functions.

Here we can have a break in the MATLAB code anytime there's an error. Now start the test server. Notice the server log, which is available to help you monitor requests in any activity. If we go to Python, I have a short notebook here to show calling our function.

First, we import the urllib and JSON modules for communicating with the server and then the module for our speech to text example. Here we're calling our speech to text function, and then passing the output text to our MATLAB function. Here you can see the server address, which is exactly the same as we saw on the app. The name that we created, and then the name of our function.

We need to pass inputs to our MATLAB function as JSON. So here we're preparing the inputs. Nargout is the number of outputs expected, and RHS represents the inputs, or right hand side.

This is how we'll pass the text to our MATLAB function. Now, the message body of the request contains the information and we can send it to the server. The response is JSON and contains the results, or an error flag if something went wrong.

Now let's give it a try. Wow, this is so cool. This is great. It looked like it worked. It says it's positive here in the result variable.

The outputs can be accessed like this from MW data and LHS, being left hand side. Let's check out what's happening in our app. We can see the request was completed successfully.

If you click on it, you can actually see the inputs and outputs, including the types and sizes that you would see in MATLAB. We didn't have any errors, so you didn't get to see one of my favorite features, the breakpoints. But let's set it to break on function entry, so we can inspect the inputs to our function and then step through.

We'll go back to our notebook, clear the results, and then call our function again. OK, let's try this again, I wonder what will happen.

And now we see our sentiment analysis function, and we're actually in the function workspace. Let's look at the input text. This is really valuable, especially since this is going to be passed to our MATLAB function. And when you're working on a team, you may not be as familiar with all the workings of the rest of the system.

So hopefully you can see why this is one of my favorite features, since it's so useful when you're building these kinds of applications. So let's continue, and we'll check the results. Cool. It's succeeded and predicted a neutral sentiment this time.

Once we're satisfied with our testing, we could go ahead and hit package from our app. This creates directories, which contain the deployable archive file and a read me to help out the person implementing. We showed the test part. In order to take the next step and run it in production, you would just need to install MATLAB production server, or you could use the reference architectures available on GitHub to host on Azure AWS easily.

Then you just need to start the server, copy our output file to the instance, and update any configuration needed on the server side, depending on your setup and preferences. And as always, the documentation will walk you through step by step. So this should give you a great sense of the opportunities you have to integrate and really test your code in these applications now that we've really seen our example in action

Now let's talk about a few more questions that often come up. If you're looking to integrate the two languages for deep learning networks, you can use importers and exporters for tensor flow models, and something like the open neural network exchange. And this allows you to easily share models directly, especially if you don't need to integrate the code that creates the models.

So if you're passing just the models back and forth, this is a great way to do that without having to do any further implementation. There's a lot more information at this link, including links to a lot of the common models used in the community. We mentioned some options for data type conversions and showed some of the great info in the doc. This causes a lot of questions, really. And if you don't see the data types supported natively, you can always convert.

But sometimes this isn't the best option, especially if you're passing larger data back and forth. If you're working with tabular data, you can use Apache Arrow to more efficiently pass data and memory between MATLAB and Python. You can read and write from each language efficiently, and so this is a great option for that case.

Of course, there's more info in the doc, and there's a lot more on the GitHub submission as well. We showed an example earlier regarding the error messages. Both errors are thrown when you're using the integration to help you out. But there are times when you want more sophisticated error handling, especially when you're working with deployment.

So it's possible to catch exceptions from both languages, throw errors in your code, and all kinds of good stuff. So definitely check out the documentation. There are good examples. And don't forget, of course, you can always call tech support, especially if you're having trouble getting set up or with troubleshooting.

And as always, don't hesitate to ask MATLAB answers, and really take advantage of the knowledge in the community if you're getting stuck and have some questions. Of course, I've said it 100 times you can see the documentation for a lot more details and examples on all of this. And there are great resources at this first link for videos and additional tutorials.

In this presentation, we discussed options for integrating our MATLAB and Python code. We also showed an example, which illustrated calling Python from MATLAB and several options for calling MATLAB from Python, to really help enable collaboration and help you take advantage of the great work in both communities. I hope you enjoyed the presentation, and will find this helpful in your work Thank you.