Parameters¶

Base Classes¶

class syd.parameters.Parameter(name: str, value: T)[source]¶

Base class for all parameter types. Parameters are the building blocks for creating interactive GUI elements.

Each parameter has a name and a value, and ensures the value stays valid through validation rules.

Parameters:

name (str) – The name of the parameter, used as a label in the GUI
value (T) – The current value of the parameter

Notes

This is an abstract base class - you should use one of the concrete parameter types like TextParameter, BooleanParameter, etc. instead of using this directly.

abstractmethod __init__(name: str, value: T)[source]¶

update(updates: Dict[str, Any]) → None[source]¶

Safely update multiple parameter attributes at once.

Parameters:: updates (dict) – Dictionary of attribute names and their new values
Raises:: ParameterUpdateError – If any of the updates are invalid

Examples

>>> param = FloatParameter("temperature", 20.0, min=0, max=100)
>>> param.update({"value": 25.0, "max": 150})

property value: T¶

Get the current value of the parameter.

Returns:: The current value
Return type:: T

Parameter Types¶

class syd.parameters.TextParameter(name: str, value: str | NoInitialValue)[source]¶

Bases: Parameter[str]

Parameter for text input.

Creates a text box in the GUI that accepts any string input. See add_text() and update_text() for usage.

Parameters:

name (str) – The name of the parameter
value (Union[str, NoInitialValue]) – The initial text value

Examples

>>> name_param = TextParameter("username", "Alice")
>>> name_param.value
'Alice'
>>> name_param.update({"value": "Bob"})
>>> name_param.value
'Bob'

class syd.parameters.BooleanParameter(name: str, value: bool | NoInitialValue)[source]¶

Bases: Parameter[bool]

Parameter for boolean values.

Creates a checkbox in the GUI that can be toggled on/off. See add_boolean() and update_boolean() for usage.

Parameters:

name (str) – The name of the parameter
value (Union[bool, NoInitialValue]) – The initial state (default is True)

Examples

>>> active = BooleanParameter("is_active", True)
>>> active.value
True
>>> active.update({"value": False})
>>> active.value
False

class syd.parameters.SelectionParameter(name: str, value: Any | NoInitialValue, options: List | Tuple)[source]¶

Bases: Parameter[Any]

Parameter for single selection from a list of options.

Creates a dropdown menu in the GUI where users can select one option. See add_selection() and update_selection() for usage.

Parameters:

name (str) – The name of the parameter
value (Union[Any, NoInitialValue]) – The initially selected value (must be one of the options)
options (sequence) – List, tuple, or 1D numpy array of valid choices that can be selected

Examples

>>> color = SelectionParameter("color", "red", options=["red", "green", "blue"])
>>> color.value
'red'
>>> color.update({"value": "blue"})
>>> color.value
'blue'
>>> color.update({"value": "yellow"})  # This will raise an error
>>> # With numpy array
>>> import numpy as np
>>> numbers = SelectionParameter("number", 1, options=np.array([1, 2, 3]))
>>> numbers.value
1

class syd.parameters.MultipleSelectionParameter(name: str, value: List[Any] | NoInitialValue, options: List | Tuple)[source]¶

Bases: Parameter[List[Any]]

Parameter for multiple selections from a list of options.

Creates a set of checkboxes or multi-select dropdown in the GUI. See add_multiple_selection() and update_multiple_selection() for usage.

Parameters:

name (str) – The name of the parameter
value (Union[List[Any], NoInitialValue]) – List of initially selected values (must all be from options, can be empty)
options (sequence) – List, tuple, or 1D numpy array of valid choices that can be selected

Examples

>>> toppings = MultipleSelectionParameter("pizza_toppings",
...     value=["cheese", "mushrooms"],
...     options=["cheese", "mushrooms", "pepperoni", "olives"])
>>> toppings.value
['cheese', 'mushrooms']
>>> # With numpy array
>>> import numpy as np
>>> numbers = MultipleSelectionParameter("numbers",
...     value=[1, 3],
...     options=np.array([1, 2, 3, 4]))
>>> numbers.value
[1, 3]

Numeric Parameters¶

class syd.parameters.IntegerParameter(name: str, value: int | NoInitialValue, min: int, max: int)[source]¶

Bases: Parameter[int]

Parameter for bounded integer values.

Creates a slider in the GUI for selecting whole numbers between bounds. See add_integer() and update_integer() for usage.

Parameters:

name (str) – The name of the parameter
value (Union[int, NoInitialValue]) – Initial value (will be clamped to fit between min and max)
min (int) – Minimum allowed value
max (int) – Maximum allowed value

Examples

>>> age = IntegerParameter("age", value=25, min=0, max=120)
>>> age.value
25
>>> age.update({"value": 150})  # Will be clamped to max
>>> age.value
120
>>> age.update({"value": -10})  # Will be clamped to min
>>> age.value
0

class syd.parameters.FloatParameter(name: str, value: float | NoInitialValue, min: float, max: float, step: float = 0.001)[source]¶

Bases: Parameter[float]

Parameter for bounded decimal numbers.

Creates a slider in the GUI for selecting numbers between bounds. See add_float() and update_float() for usage.

Parameters:

name (str) – The name of the parameter
value (Union[float, NoInitialValue]) – Initial value (will be clamped to fit between min and max)
min (float) – Minimum allowed value
max (float) – Maximum allowed value
step (float, optional) – Size of each increment (default is 0.001)

Examples

>>> temp = FloatParameter("temperature", value=98.6,
...     min=95.0, max=105.0, step=0.1)
>>> temp.value
98.6
>>> temp.update({"value": 98.67})  # Will be rounded to nearest step
>>> temp.value
98.7
>>> temp.update({"value": 110.0})  # Will be clamped to max
>>> temp.value
105.0

Notes

The step parameter determines how finely you can adjust the value. For example: - step=0.1 allows values like 1.0, 1.1, 1.2, etc. - step=0.01 allows values like 1.00, 1.01, 1.02, etc. - step=5.0 allows values like 0.0, 5.0, 10.0, etc.

class syd.parameters.IntegerRangeParameter(name: str, value: Tuple[int, int] | NoInitialValue, min: int, max: int)[source]¶

Bases: Parameter[Tuple[int, int]]

Parameter for a range of bounded integer values.

Creates a range slider in the GUI for selecting a range of whole numbers. See add_integer_range() and update_integer_range() for usage.

Parameters:

name (str) – The name of the parameter
value (Union[Tuple[int, int], NoInitialValue]) – Initial (low, high) values
min (int) – Minimum allowed value for both low and high
max (int) – Maximum allowed value for both low and high

Examples

>>> age_range = IntegerRangeParameter("age_range",
...     value=(25, 35), min=18, max=100)
>>> age_range.value
(25, 35)
>>> age_range.update({"value": (35, 25)})  # Values will be swapped
>>> age_range.value
(25, 35)
>>> age_range.update({"value": (15, 40)})  # Low will be clamped
>>> age_range.value
(18, 40)

class syd.parameters.FloatRangeParameter(name: str, value: Tuple[float, float] | NoInitialValue, min: float, max: float, step: float = 0.001)[source]¶

Bases: Parameter[Tuple[float, float]]

Parameter for a range of bounded decimal numbers.

Creates a range slider in the GUI for selecting a range of numbers. See add_float_range() and update_float_range() for usage.

Parameters:

name (str) – The name of the parameter
value (Union[Tuple[float, float], NoInitialValue]) – Initial (low, high) values
min (float) – Minimum allowed value for both low and high
max (float) – Maximum allowed value for both low and high
step (float, optional) – Size of each increment (default is 0.001)

Examples

>>> temp_range = FloatRangeParameter("temperature_range",
...     value=(98.6, 100.4), min=95.0, max=105.0, step=0.1)
>>> temp_range.value
(98.6, 100.4)
>>> temp_range.update({"value": (98.67, 100.0)})  # Low will be rounded
>>> temp_range.value
(98.7, 100.0)
>>> temp_range.update({"value": (101.0, 99.0)})  # Values will be swapped
>>> temp_range.value
(99.0, 101.0)

Notes

The step parameter determines how finely you can adjust the values. For example: - step=0.1 allows values like 1.0, 1.1, 1.2, etc. - step=0.01 allows values like 1.00, 1.01, 1.02, etc. - step=5.0 allows values like 0.0, 5.0, 10.0, etc.

class syd.parameters.UnboundedIntegerParameter(name: str, value: int | NoInitialValue)[source]¶

Bases: Parameter[int]

Parameter for optionally bounded integer values.

Creates a text input box in the GUI for entering whole numbers. See add_unbounded_integer() and update_unbounded_integer() for usage.

Parameters:

name (str) – The name of the parameter
value (Union[int, NoInitialValue]) – Initial value

Examples

>>> count = UnboundedIntegerParameter("count", value=10)
>>> count.value
10
>>> count.update({"value": 1000000})  # No maximum, so this is allowed
>>> count.value
1000000

Notes

Use this instead of IntegerParameter when you: - Don’t have any reason to bound the value - Need to allow very large numbers that would be impractical with a slider

class syd.parameters.UnboundedFloatParameter(name: str, value: float | NoInitialValue, step: float | None = None)[source]¶

Bases: Parameter[float]

Parameter for optionally bounded decimal numbers.

Creates a text input box in the GUI for entering numbers. See add_unbounded_float() and update_unbounded_float() for usage.

Parameters:

name (str) – The name of the parameter
value (Union[float, NoInitialValue]) – Initial value
step (float, optional) – Size of each increment (default is None, meaning no rounding)

Examples

>>> price = UnboundedFloatParameter("price", value=19.99)
>>> price.value
19.99
>>> price.update({"value": 19.987})  # Will be rounded to step
>>> price.value
19.99

Notes

Use this instead of FloatParameter when you: - Don’t know a reasonable maximum value - Need to allow very large or precise numbers that would be impractical with a slider

If step is provided, values will be rounded: - step=0.1 rounds to 1.0, 1.1, 1.2, etc. - step=0.01 rounds to 1.00, 1.01, 1.02, etc. - step=5.0 rounds to 0.0, 5.0, 10.0, etc.

Action Parameters¶

class syd.parameters.ButtonAction(name: str, label: str | NoInitialValue, callback: Callable, replot: bool = True)[source]¶

Bases: Parameter[None]

Parameter for creating clickable buttons with callbacks.

Creates a button in the GUI that executes a callback function when clicked. See add_button() and update_button() for usage.

Parameters:

name (str) – The name of the parameter
label (Union[str, NoInitialValue]) – Text to display on the button (default is the button’s name)
callback (callable) – Function to execute when the button is clicked
replot (bool, optional) – Whether to replot the figure after the callback is called. (default: True)

Examples

>>> def print_hello():
...     print("Hello!")
>>> button = ButtonAction("greeting", label="Say Hello", callback=print_hello, replot=False)
>>> button.callback()  # Simulates clicking the button
Hello!
>>> # Update the button's label and callback
>>> def print_goodbye():
...     print("Goodbye!")
>>> button.update({"label": "Say Goodbye", "callback": print_goodbye})
>>> button.callback()
Goodbye!

Notes

Unlike other Parameter types, ButtonAction: - Has no value (always None, therefore cannot be updated through the value property - Executes code directly rather than storing state - Has an option to turn off replotting after the callback is called for cases where you want to access the last figure only.

value: None = None¶