Running Meerkat Interfaces
Running Meerkat Interfaces¶
Meerkat interfaces can be run as standalone applications or embedded in Jupyter notebooks. This page describes the different ways to run Meerkat interfaces.
Running Interfaces in Scripts¶
The easiest way to run Meerkat interfaces is to use the
mk command line tool. This comes pre-installed with the Meerkat Python package, and can be used to run scripts that create Meerkat interfaces.
To run a script, use the
mk run command:
By default, the
mk run command runs in development (
dev) mode. This means that the
script is re-run every time you save a change to the script (live-reloading).
To run in production (
prod) mode, use the
Requirements. The only requirement is that the script create an
Page object that is assigned to a variable. In other words, your script should look something like this:
import meerkat as mk # .... page = mk.gui.Page(...)
Meerkat assumes that this variable is called
page by default. If you use a different variable name, pass it as an argument to the
mk run command:
mk run command does a few things behind the scenes:
It creates a FastAPI server that runs the script, and serves the backend API.
It creates a frontend server to serve the web interface.
It pipes the outputs of your script, and the logs of the servers to the terminal.
Interfaces in Jupyter Notebooks¶
Meerkat interfaces can also be run in Jupyter notebooks. This is useful if you want to view one or more interfaces in output cells, (e.g., to view a multimodal dataset or produce an interesting visualization).
To run an interface in a Jupyter notebook, Meerkat provides the
start function in the
meerkat.gui module. This function takes care of setting up the necessary servers.
# Do this once at the top of your notebook import meerkat as mk mk.gui.start()
Then, whenever you want to run an interface, simply create an
Interface object in a code cell, and it will be displayed in the output cell.
interface = mk.gui.Interface(...)
Meerkat DataFrames come built in with a
gui namespace that contains a collection of
useful interfaces for notebooks. For example, to view a DataFrame in a notebook as a
table, simply call the
To view it as a gallery, call the
Interactions with interfaces in output cells affect the state of the notebook. This is good to keep in mind when running interfaces for labeling or otherwise modifying data.
start Function for Scripting¶
start function can also be used to run Meerkat interfaces in scripts. While we recommend using the
mk run command in most cases, there are a few situations where you might want to use
You want to set breakpoints in your script for debugging.
mk rundoes not support this.
You want to have access to a Python interpreter while the script is running. By default,
startwill block the current thread, and keep a Python interpreter running so you can interact with the script.
To use this method, call the
start function in your script before creating an interface.
import meerkat as mk # .... mk.gui.start() interface = mk.gui.Interface(...)
To run the script, use the
python command directly (not
start does not support live-reloading. If you want to use live-reloading, use the
mk run command instead.