Interactive Parameters

As indicated by the documentation for Parameters and Parameter Trees, a Parameter is commonly used to expose a value to the user without burdening developers with GUI representations. The interact method and friends extend such support to arbitrary Python functions. [1] Before reading further, make sure to read existing Parameter documentation to become familiar with common extra options, creation techniques, and so on.

Basic Use

Consider a function a whose arguments should be tweakable by the user to immediately update some result. Without using interact, you might do something like this:

from pyqtgraph.Qt import QtWidgets
import pyqtgraph as pg
from pyqtgraph.parametertree import Parameter, ParameterTree, parameterTypes as ptypes

def a(x=5, y=6):
   QtWidgets.QMessageBox.information(None, 'Hello World', f'X is {x}, Y is {y}')

# -----------
# discussion is from here:
params = Parameter.create(name='"a" parameters', type='group', children=[
   dict(name='x', type='int', value=5),
   dict(name='y', type='int', value=6)
])

def onChange(_param, _value):
   a(**params)

for child in params.children():
   child.sigValueChanged.connect(onChange)
# to here
# -----------

app = pg.mkQApp()
tree = ParameterTree()
tree.setParameters(params)
tree.show()
pg.exec()

Notice in the ----- comment block, lots of boilerplate and value duplication takes place. If an argument name changes, or the default value changes, the parameter definition must be independently updated as well. In (very common) cases like these, use interact instead (the code below is functionally equivalent to above):

from pyqtgraph.Qt import QtWidgets
import pyqtgraph as pg
from pyqtgraph.parametertree import Parameter, ParameterTree, interact

def a(x=5, y=6):
   QtWidgets.QMessageBox.information(None, 'Hello World', f'X is {x}, Y is {y}')

# One line of code, no name/value duplication
params = interact(a)

app = pg.mkQApp()
tree = ParameterTree()
tree.setParameters(params)
tree.show()
pg.exec()

There are several caveats, but this is one of the most common scenarios for function interaction.

runOptions

Often, an interact-ed function shouldn’t run until multiple parameter values are changed. Or, the function should be run every time a value is changing, not just changed. In these cases, modify the runOptions parameter.

from pyqtgraph.parametertree import interact, RunOptions

# Will add a button named "Run". When clicked, the function will run
params = interact(a, runOptions=RunOptions.ON_ACTION)
# Will run on any `sigValueChanging` signal
params = interact(a, runOptions=RunOptions.ON_CHANGING)
# Runs on `sigValueChanged` or when "Run" is pressed
params = interact(a, runOptions=[RunOptions.ON_CHANGED, RunOptions.ON_ACTION])
# Any combination of RUN_* options can be used

The default run behavior can also be modified. If several functions are being interacted at once, and all should be with a “Run” button, simply use the provided context manager:

from pyqtgraph.parametertree import interact
# `runOptions` can be set to any combination of options as demonstrated above, too
with interact.optsContext(runOptions=RunOptions.ON_ACTION):
    # All will have `runOptions` set to ON_ACTION
    p1 = interact(aFunc)
    p2 = interact(bFunc)
    p3 = interact(cFunc)
# After the context, `runOptions` is back to the previous default

If the default for all interaction should be changed, you can directly call interactDefaults.setOpts (but be warned - anyone who imports your module will have it modified for them, too. So use the context manager whenever possible). Thus, it is highly advised to make your own Interactor object in these cases. The previous options set will be returned for easy resetting afterward:

from pyqtgraph.parametertree import Interactor
myInteractor = Interactor()
oldOpts = myInteractor.setOpts(runOptions=RunOptions.ON_ACTION)
# Can also directly create interactor with these opts:
# myInteractor = Interactor(runOptions=RunOptions.ON_ACTION)

# ... do some things...
# Unset option
myInteractor.setOpts(**oldOpts)

ignores

When interacting with a function where some arguments should appear as parameters and others should be hidden, use ignores:

from pyqtgraph.parametertree import interact

def a(x=5, y=6):
    print(x, y)

# Only 'x' will show up in the parameter
params = interact(a, ignores=['y'])

closures

Sometimes, values that should be passed to the interact-ed function should come from a different scope (or “closure”), i.e. a variable definition that should be propagated from somewhere else. In these cases, wrap that argument in a function and pass it into closures like so. Note that an InteractiveFunction object is needed as descibed in a later section.

from skimage import morphology as morph
import numpy as np
from pyqtgraph.parametertree import interact, InteractiveFunction, ParameterTree
import pyqtgraph as pg


def dilateImage(image, radius=3):
    image = morph.dilation(image, morph.disk(radius))
    view.setImage(image)

app = pg.mkQApp()
view = pg.ImageView()
# Simulate a grayscale image
image = np.random.randint(0, 256, size=(512, 512))
dilate_interact = InteractiveFunction(dilateImage, closures={'image': lambda: image})
params = interact(dilate_interact)
# As the 'image' variable changes, the new value will be used during parameter interaction
view.show()
tree = ParameterTree()
tree.setParameters(params)
tree.show()
image = 255 - image # Even though 'image' is reassigned, it will be used by the parameter
pg.exec()

parent

Often, one parameter tree is used to represent several different interactive functions. When this is the case, specify the existing parameter as the parent. In all but simple cases, it is usually easier to leverage the decorator version.

from pyqtgraph.parametertree import Parameter
def aFunc(x=5, y=6):
    QtWidgets.QMessageBox.information(None, 'Hello World', f'X is {x}, Y is {y}')
def bFunc(first=5, second=6):
    QtWidgets.QMessageBox.information(None, 'Hello World', f'first is {first}, second is {second}')
def cFunc(uno=5, dos=6):
    QtWidgets.QMessageBox.information(None, 'Hello World', f'uno is {uno}, dos is {dos}')

params = Parameter.create(name='Parameters', type='group')
# All interactions are in the same parent
interact(aFunc, parent=params)
interact(bFunc, parent=params)
interact(cFunc, parent=params)

nest

In all examples so far, interact makes a GroupParameter which houses another GroupParameter inside. The inner group contains the parameter definitions for the function arguments. If these arguments should be directly inside the parent, use nest=False:

def a(x=5, y=6):
    return x + y

# 'x' and 'y' will be returned in a list, not nested inside another GroupParameter
# If `parent=...` was specified in the `interact` call, `x` and `y` will be inserted
# directly as children of `parent`
params = interact(a, nest=False)

runActionTemplate

When the runOptions argument is set to (or contains) RunOptions.ON_ACTION, a button will be added next to the parameter group which can be clicked to run the function with the current parameter values. The button’s options can be customized through passing a dictionary to runActionTemplate. The dictionary can contain any key accepted as an action parameter option. For instance, to run a function either by pressing the button or a shortcut, you can interact like so:

def a(x=5, y=6):
    return x + y

# The button will be labeled "Run" and will run the function when clicked or when
# the shortcut "Ctrl+R" is pressed
params = interact(a, runActionTemplate={'shortcut': 'Ctrl+R'})

# Alternatively, add an icon to the button
params = interact(a, runActionTemplate={'icon': 'run.png'})

# Why not both?
params = interact(a, runActionTemplate={'icon': 'run.png', 'shortcut': 'Ctrl+R'})

existOk

When nest=False, there can be overlap when several function arguments share the same name. In these cases, the result is an error unless existOk=True (the default).

def a(x=5, y=6):
    return x + y
def b(x=5, another=6):
    return x + another
params = interact(a, nest=False)

# Will raise an error, since 'x' was already in the parameter from interacting with 'a'
interact(b, nest=False, parent=params, existOk=False)

overrides

In all examples so far, additional parameter arguments such as limits were ignored. Return to the closures example and observe what happens when radius is < 0:

ValueError: All-zero footprint is not supported.

To prevent such cases, overrides can contain additional parameter specifications (or default values) that will update the created parameter:

# Cannot go lower than 0
# These are bound to the 'radius' parameter
params = interact(dilate_interact, radius={'limits': [1, None]})

Now, the user is unable to set the spinbox to a value < 1.

Similar options can be provided when the parameter type doesn’t match the default value (list is a common case):

def chooseOne(which='a'):
    print(which)

params = interact(chooseOne, which={'type': 'list', 'limits': list('abc')})

Any value accepted in Parameter.create can be used in the override for a parameter.

Also note that overrides can consist of raw values, in the case where just the value should be adjusted or when there is no default:

def printAString(string):
    print(string)

params = interact(printAString, string='anything')

Functions with **kwargs

Functions who allow **kwargs can accept additional specified overrides even if they don’t match argument names:

def a(**canBeNamedAnything):
    print(canBeNamedAnything)
# 'one' and 'two' will be int parameters that appear
params = interact(a, one=1, two=2)

If additional overrides are provided when the function doesn’t accept keywords in this manner, they are ignored.

The Decorator Version

To simplify the process of interacting with multiple functions using the same parameter, a decorator is provided:

from pyqtgraph.parametertree import Interactor, interact
params = Parameter.create(name='Parameters', type='group')
interactor = Interactor(parent=params) # Same parent for all `interact` calls

info = QtWidgets.QMessageBox.information

@interactor.decorate()
def aFunc(x=5, y=6):
    info(None, 'Hello World', f'X is {x}, Y is {y}')

@interactor.decorate()
def bFunc(first=5, second=6):
    info(None, 'Hello World', f'first is {first}, second is {second}')

@interactor.decorate()
def cFunc(uno=5, dos=6):
    info(None, 'Hello World', f'uno is {uno}, dos is {dos}')

# Alternatively, the default interactor can be used if you don't need to
# make your own `Interactor` instance.
@interact.decorate(parent=params)
def anotherFunc(one="one"):
    print(one)

# All interactions are in the same parent

Any value accepted by interact can be passed to the decorator.

Title Formatting

If functions should have formatted titles, specify this in the titleFormat parameter:

def my_snake_case_function(a=5):
    print(a)

def titleFormat(name):
    return name.replace('_', ' ').title()

# The title in the parameter tree will be "My Snake Case Function"
params = interact(my_snake_case_function, titleFormat=titleFormat)

Using InteractiveFunction

In all versions of interact described so far, it is not possible to temporarily stop an interacted function from triggering on parameter changes. Normally, one can disconnect the hooked-up signals, but since the actually connected functions are out of scope, this is not possible when using interact. Additionally, it is not possible to change overrides or closures arguments after the fact. Finally, it is not possible to easily call an interacted function with parameter arguments/defaults through normal interact use. If any of these needs arise, use an InteractiveFunction instead during registration. This provides disconnect() and reconnect() methods, and object accessors to closures arguments.

from pyqtgraph.parametertree import InteractiveFunction, interact, Parameter, RunOptions

def myfunc(a=5):
    print(a)

useFunc = InteractiveFunction(myfunc)
param = interact(useFunc, runOptions=RunOptions.ON_CHANGED)
param['a'] = 6
# Will print 6
useFunc.disconnect()
param['a'] = 5
# Won't print anything
useFunc.reconnect()
param['a'] = 10
# Will print 10

Note that in cases like these, where simple wrapping of a function must take place, you can use InteractiveFunction like a decorator:

from pyqtgraph.parametertree import InteractiveFunction, interact, Parameter, RunOptions

@InteractiveFunction
def myfunc(a=5):
    print(a)

# myfunc is now an InteractiveFunction that can be used as above
# Also, calling `myfunc` will preserve parameter arguments
param = interact(myfunc, RunOptions.ON_ACTION)
param['a'] = 6

myfunc()
# will print '6' since this is the parameter value

[1]

Functions defined in C or whose definitions cannot be parsed by inspect.signature cannot be used here. However, in these cases a dummy function can be wrapped and passed instead. Note that all values are passed as keywords, so if positional arguments are expected it will not work.