.. _parameterized_pipelines: # Customizing your own model parameters This page delves into some of the more powerful things you can do with pipelines. It is aimed at people who have already completed the :ref:`advanced_pipelines` tutorial. ## Pipeline model parameters You should be aware that each pipeline _step_ has parameters, but the pipeline _model_ itself can also have its own parameters. Unlike step parameters, you have complete control over defining the model parameters yourself. The model parameters are essentially custom variables that get replaced at run-time. These variables are denoted by a `$` in the pipeline file. The model parameters can customize the behaviour of the model across _all_ input data. Model parameters can encapsulate an assumption you are making about your model, which you may want to vary. As a simple example, say we only wanted to run our model for one particular construction type at a time. But we wanted to be able to _vary_ that construction type easily, without editing the pipeline file each time. We can turn the construction type we filter on into a `construction` parameter, e.g. ```none input('assets.csv', name: 'asset') -> filter(filter: asset.construction = $construction) ``` When we run our model, we can then specify what specific construction type we are interested in, e.g. ```none riskscape model run my_pipeline --param "construction='steel'" ``` You can define the default values for your parameters in your model's INI definition. Just use `param. = `, e.g. ```ini [model my_pipeline] framework = pipeline location = my_pipeline.txt param.construction = 'timber' ``` .. _parameter_properties: ## Parameter properties When you want to share a model with other users, you can restrict what sort of values the user can specify for certain parameters. For example, you could specify that a parameter called `damage_ratio` always had to be a *numeric*, or always had to be within a certain range, such as 0.0 to 1.0. You can specify what *properties* a parameter is expected to have in your `project.ini` file. For example, the `damage_ratio` parameter would look like this: ``` param.damage_ratio.properties = numeric, min: 0.0, max: 1.0 ``` If the user tries to enter anything that is *not* a numerical value between 0.0 and 1.0, then they will get an error when they try to run the model. The parameter properties supported on the RiskScape CLI include: *bookmark*, *integer*, *list*, *min*, *max*, *numeric*, and *text*. .. tip:: Specifying the ``text`` or ``bookmark`` properties means that the user no longer needs to use ``''`` single-quotes when entering a new parameter value. .. _function_parameters: ### Function parameters Model parameters also work if the assumption you are making is in your _function_. You simply need to pass the model parameter through to your function. To do this you add an extra argument to your function. The new argument will be a `Struct` and contain the attributes you want to vary. For example, say our Kaijū function was making an assumption on how resilient timber buildings are to Kaijū attacks. We can modify our function to take an additional 'options' argument, which is a `Struct` with a `timber_resilience` attribute. The (abridged) function would look like this: ```python from nz.org.riskscape.engine.types import Types from nz.org.riskscape.engine.types import Struct ID = 'kaiju_stomp' DESCRIPTION = 'Models damage from a Kaiju stomping a building' ARGUMENT_TYPES = ['building', 'kaiju_attack', \ Struct.of('timber_resilience', Types.INTEGER) ] RETURN_TYPE = 'building_attack_outcome' def function(building, stomp, options): if building.get('construction') == 'timber': # the resilience for timber buildings can be passed # into our function, making it easier to vary it resilience = options.get('timber_resilience') elif building.get('construction') == 'concrete': # whereas the resilience for concrete buildings is # still hard-coded in the function itself resilience = 5 # ... ``` Then to call our function from our pipeline code, we create a new `Struct` with a `timber_resilience` attribute. In this case, the value for `timber_resilience` is a model parameter that we can now change on the fly whenever we run our model. ```none select({*, kaiju_stomp(asset, hazard, { timber_resilience: $timber_resilience }) as damage ) as compute consequence ``` The 'options' `Struct` could hold many different attributes, if there are many assumptions in your function that you want to vary. ## A working example Click [Here](../pipeline-parameters.zip) to download a working example of a parameterized pipeline. Open the `pipeline.txt` and `project.ini` files and familiarize yourself with them. You can see that the model defines 'resilience' parameters for the three construction materials of interest. These parameters then get passed directly to the `kaiju_stomp` function. To run the model with default parameter values, use the command: ```none riskscape model run demo ``` ### Reproducible models Model parameters can make it harder to tell later what actual parameter values were used to produce a certain set of results. Fortunately, RiskScape always saves the _actual_ parameter values it used in the output directory. Have a look at the output directory created by the last 'model run' command. It should contain a `pipeline.txt` file - this contains the pipeline code with the `$` parameters replaced with the actual values used by the 'model run' command. Any piece of raw pipeline code (i.e. without parameters) can be executed using the `riskscape pipeline eval` command. So you can use the `pipeline.txt` file in the output directory to re-run the exact same pipeline again in the future, e.g. ```none riskscape pipeline eval ``` Try this now and check you get the same results. ### Parameter INI files When your model has several different parameters, rather than specifying each parameter on the command line, you can just specify _one_ INI file that contains all the parameter values you want to use. To pass the INI file to the 'model run' command, use the `--parameters` CLI option (note the 's' on the end). For example: ```none riskscape model run demo --parameters stronger-resilience.ini ``` Using INI files can be helpful if you want to vary several different assumptions in a related way. For example, this project contains two different INI files that make different assumptions about a building's resilience: `stronger-resilience.ini` and `weaker-resilience.ini`. Try running the model with each of these INI files and see what difference it makes to the overall damage.