Reference 〉 Function

Params.add(namestr, titlestr, typestr, dfltstr|bool|num|list, optsdict|list{}, runtimeboolTrue, callbackfuncNone, perstrNone, descstrNone, getterfunc(name, model)None, primstrNone)

Registers a global parameter to be displayed in the control panel. Depending on the required data, possible parameter types include menus, sliders, checkboxes, checkentries, or checkgrids. The current value of the parameter can be retrieved with model.param().

This function also replaces the previous model.addGoodParam() and model.addBreedParam() methods. Use the per argument instead to register per-good and per-breed parameters.

Parameters

  • name — str, required

    A slug-type string to be used to refer back to the parameter in other functions.

  • title — str, required

    The title of the parameter, to be displayed in the GUI.

  • type — str, required

    What type of control to display. Possible values are 'menu', 'check', 'slider', 'checkentry', 'checkgrid', or 'hidden'.

  • dflt — str|bool|num|list, required

    The default value of the parameter. A menu should have a string here, a check a boolean, a slider a number, a checkentry a bool, int, or string, and a checkgrid a list of strings.

  • opts — dict|list, optional

    Options for the parameter type.

    • A slider should have a dict with keys 'low', 'high', and 'step', with numeric values, corresponding to the max and min values and the slider's increment. Alternatively opts can take a list of integers for a slider that slides over defined values.
    • A menu should have key-value pairs corresponding to menu items, with the key the value returned by the parameter, and the value the label displayed in the GUI.
    • A checkgrid takes either a list of strings, or a dict with a name-label pair to describe each check. The label can also be entered as a two-item tuple, with the label as the first item and the tooltip text as the second.
    • Checks, checkentries, or hidden parameters do not need an opts parameter.

    Default value: {}

  • runtime — bool, optional

    Whether the parameter can be changed during the model's runtime. If set to False, the parameter will be disabled while the model is running.

    Default value: True

  • callback — func, optional

    An optional function that will execute when the parameter changes. The function takes three arguments: model, the model object; var, the name of the parameter (the first argument of model.addParameter); and val, the new value of the parameter (with the exception of CheckGrid parameters, which pass a tuple ('checkName', val) to indicate which item was clicked).

    Default value: None

  • per — str, optional

    None for a global parameter, 'breed' for a per-breed parameter, or 'good' for a per-good parameter. Note that per='breed' requires the prim argument to be specified if more than one primitive has been added. Note also that type='checkgrid' cannot be used as a per-item parameter.

    Default value: None

  • desc — str, optional

    A long description to display as a tooltip.

    Default value: None

  • getter — func(name, model), optional

    A function to replace the parameter's own getter with open-ended code. The function can return None in order to pass to the default getter.

    Default value: None

  • setter — func(val, name, model), optional

    A function to replace the parameter's own setter with open-ended code. The function can return something besides None in order to pass to the default setter.

    Default value: None

  • prim — str, optional

    If per='breed' and more than one primitive has been added, this argument is required to specify which primitive's breeds to attach the parameters to.

    Default value: None

Return Value — Param

The newly created Param object.

Notes and Examples

  1. charwick

    Mar 22, 2020 at 4:41

    This example adds three parameters to the model, a checkbox, a menu, and a slider, along with callbacks to push the updated values to the relevant place in the model. Note the different options passed in the opts parameter in the first two.

    #Adds a checkbox parameter that returns True or False
heli.params.add('ngdpTarget', 'NGDP Target', 'check', dflt=False)

#Adds a menu parameter that returns 'prop', 'lump', or 'omo'
#This parameter cannot be changed once the model has initialized
heli.params.add('dist', 'Distribution', 'menu', dflt='prop', opts={
	'prop': 'Helicopter/Proportional',
	'lump': 'Helicopter/Lump Sum',
	'omo': 'Open Market Operation'
}, runtime=False, callback=bankChecks, desc="The rule used to distribute changes in the money supply")

#Adds a slider parameter that returns a numerical value
heli.params.add('pSmooth', 'Price Smoothness', 'slider', dflt=1.5, opts={'low': 1, 'high': 3, 'step': 0.05}, callback=storeUpdater)


#CALLBACK FUNCTIONS FOR THE THREE PARAMETERS

#Change the enabled state of the textchecks for the 'debt', 'rr', and 'i' plots
#depending on the value of the 'dist' parameter
def bankChecks(model, var, val):
	for i in ['debt', 'rr', 'i']:
		model.gui.checks[i].disabled(val!='omo')

#If the model is running, update a property of all 'store'-primitive agents with the value of the parameter.
def storeUpdater(model, var, val):
	if model.hasModel:
		for s in model.agents['store']:
			setattr(s, var, val)

    This will display in the control panel like this:

    1

  2. charwick

    Mar 23, 2020 at 1:06

    This example creates three per-breed parameters: a slider, a check, and a menu, each of which will take a separate value for each breed of the specified primitive. In this case there are two breeds, so we have two values for each parameter.

    heli.addBreed('hobbit', '#D73229', prim='agent')
heli.addBreed('dwarf', '#2D8DBE', prim='agent')

heli.params.add('rbd', 'Demand for Real Balances', 'slider', per='breed', dflt={'hobbit':7, 'dwarf': 35}, opts={'low':1, 'high': 50, 'step': 1}, prim='agent', callback=rbalUpdater)
heli.params.add('active', 'Active?', 'check', per='breed', dflt=True, prim='agent')
heli.params.add('mode', 'Mode of Interaction', 'menu', per='breed', opts={
	'a': 'Aggressive',
	'c': 'Cooperative',
	's': 'Spiteful'
}, dflt='a', prim='agent')

    This will display in the control panel like this. Note the separate defaults on the slider parameter, as we passed a dict for the dflt parameter rather than a number.

  3. charwick

    Oct 20, 2020 at 21:28

    In this example, the user has an option of creating a square of a particular dimension or specifying an arbitrary height and width. In order to have the 'x' and 'y' parameters available regardless of whether square==True, we can use the setter and getter arguments to alias the 'dimension' parameter.

    if square:
	model.params.add('dimension', 'Map Size', 'slider', dflt=x, opts={'low': 1, 'high': x, 'step': 1}, runtime=False)
	def dimget(name, model): return model.param('dimension')
	def dimset(val, name, model): model.param('dimension', val)
	model.params.add('x', 'Map Width ', 'hidden', dflt=x, setter=dimset, getter=dimget)
	model.params.add('y', 'Map Height', 'hidden', dflt=x, setter=dimset, getter=dimget)
else:
	model.params.add('x', 'Map Width ', 'slider', dflt=x, opts={'low': 1, 'high': x, 'step': 1}, runtime=False)
	model.params.add('y', 'Map Height', 'slider', dflt=y, opts={'low': 1, 'high': y, 'step': 1}, runtime=False)

  4. charwick

    Apr 12, 2021 at 20:26

    The callback parameter can be used to constrain two variables to each other. In this case, when the checkbox is checked, it locks the value of two sliders together.

    def constrain(model, var, val):
	if model.param('city'):
		if var=='fixed': model.param('rent', .3099+.4598*val)
		elif var=='rent': model.param('fixed', 2.1748486*val-.67398869)

heli.params.add('city', 'City?', 'check', True, desc='Whether agents have the possibility of moving to the city')
heli.params.add('rent', 'Variable cost (ρ)', 'slider', dflt=.2, opts={'low':0.1, 'high': 1, 'step': 0.1}, desc='Per-period cost-of-living, proportional to human capital', callback=constrain)
heli.params.add('fixed', 'Fixed cost (χ)', 'slider', dflt=.2, opts={'low':0, 'high': 1, 'step': 0.1}, desc='Per-period cost-of-living', callback=constrain)

    Constrained sliders

  5. Contribute a Note

    Your email address will not be published. Required fields are marked *

    You may use limited HTML for formatting. Please embed blocks of code in <pre><code> </code></pre> tags.

History