Introduction¶

Param is a library providing Parameters:

Python attributes extended to have features such as

type and range checking
dynamically generated values
documentation strings
default values
events

Param enables you to write robust and powerful applications in just a few lines of code.

Param is free, open source, small, and has no external dependencies, so that it can easily be included as part of other projects.

Example: A Parameterized Class¶

The Pythagorean Theorem is one of the world's most famous equations.

We will illustrate how powerful Param is by building a model of the Pythagorean Theorem.

Pythagorean Theorem Class¶

In [ ]:

import param, math, time

In [ ]:

class PythagoreanTheorem(param.Parameterized):
    """Model of the Pythagorean Theorem"""

    a = param.Number(default=0, bounds=(0,None), doc="Length of side a")
    b = param.Number(default=0, bounds=(0,None), doc="Length of side b")
    c = param.Number(default=0, bounds=(0,None), doc="Length of the hypotenuse c",
                     constant=True)


    def __init__(self, **params):
        super().__init__(**params) # Sets values a and b if provided in the params
        
        self._update_hypotenuse() # Sets the value c


    @param.depends("a", "b", watch=True) # Triggers a run of the function whenever a or b is changed
    def _update_hypotenuse(self):
        """Updates the length of the hypotenuse"""
        with param.edit_constant(self):
            self.c = math.sqrt(self.a**2+self.b**2)

Pythagorean Theorem Object¶

Lets try to use the model

In [ ]:

pythagoras = PythagoreanTheorem(a=3, b=4)     # create an object with initial values for the parameters a and b
pythagoras.c                                  # print the result for c

Using the Parameters¶

We will now take a closer look at what these few lines of code provide us:

Param Provides Parameter Validation¶

In [ ]:

# check admissible parameter values
try:
    pythagoras1 = PythagoreanTheorem(a=-1, b=4)
except Exception as ex:
    print(ex)

In [ ]:

# check parameter types
try:
    pythagoras2 = PythagoreanTheorem(a="length is 3", b=4)
except Exception as ex:
    print(ex)

Param contains a wide range of useful parameter types, including

String
Integer
Float
Bool
DataFrame

Param Provides Constant Parameters¶

In [ ]:

# constant values cannot be changed
try:
    pythagoras.c = 3
except Exception as ex:
    print(ex)

Param Provides Default Values¶

In [ ]:

print( f"{pythagoras.param.a.name} = {pythagoras.param.a.default}")

Param Provides Documentation¶

In [ ]:

?pythagoras

In [ ]:

# more extensive documentation
help(pythagoras)

Param Provides Events¶

You can use events to react to parameter changes.

We have already reacted to events by using the @param.depends("a", "b", watch=True) annotation
$\quad$ to react to a or b changing by updating the calculated hypotenuse.

Here we will use the alternative param.watch to just watch for changes to the hypotenuse c and print the event raised.

In [ ]:

def print_event(event):
    print(event, end='\n\n')

watcher = pythagoras.param.watch(print_event, "c")

In [ ]:

for _ in range(3):
    pythagoras.b += 1
    time.sleep(1)

We can also stop watching again:

In [ ]:

pythagoras.param.unwatch(watcher)

Param Makes it Easy to Create GUIs¶

On top of param you can quickly build interactive applications and graphical user interfaces.

The whole HoloViz ecosystem is built in this way!

Let's use Panel to illustrate how powerful this is.

In [ ]:

import panel as pn
pn.extension()

In [ ]:

pn.Param(pythagoras)

Visit the Param Website¶

Please visit Param's website for more information like official releases, installation instructions, documentation, and examples.

And join the community on the HoloViz Discourse.