Model¶

Generally, models are created through the Model class. Model takes the argument run and the optional arguments postprocess, adaptive and labels.

model = un.Model(run=example_model,
                 postprocess=example_postprocess,
                 interpolate=True,
                 labels=["xlabel", "ylabel"])

The run argument must be a Python function that runs a simulation on a specific model for a given set of model parameters, and returns the simulation output. We call such a function for a model function. The postprocess argument is a Python function used to postprocess the model output if required. We go into details on the requirements of the postprocess and model functions below. interpolate specifies whether the model should be interpolated to a regular form. This is required for for example models with adaptive time steps. For adaptive models, Uncertainpy automatically interpolates the output to a regular form (the same number of points for each model evaluation). Finally, labels allows the user to specify a list of labels to be used on the axes when plotting the results.

Defining a model function¶

As explained above, the run argument is a Python function that runs a simulation on a specific model for a given set of model parameters, and returns the simulation output. An example outline of a model function is:

def example_model(parameter_1, parameter_2):
    # An algorithm for the model, or a script that runs
    # an external model, using the given input parameters.

    # Returns the model output and model time
    # along with the optional info object.
    return time, values, info

Such a model function has the following requirements:

Input. The model function takes a number of arguments which define the uncertain parameters of the model.

Run the model. The model must then be run using the parameters given as arguments.

Output. The model function must return at least two objects, the model time (or equivalent, if applicable) and model output. Additionally, any number of optional info objects can be returned. In Uncertainpy, we refer to the time object as time, the model output object as values, and the remaining objects as info.

Time (time). The time can be interpreted as the x-axis of the model. It is used when interpolating (see below), and when certain features are calculated. We can return None if the model has no time associated with it.

Model output (values). The model output must either be regular, or it must be possible to interpolate or postprocess the output (see Features) to a regular form.

Additional info (info). Some of the methods provided by Uncertainpy, such as the later defined model postprocessing, feature preprocessing, and feature calculations, require additional information from the model (e.g., the time a neuron receives an external stimulus). We recommend to use a single dictionary as info object, with key-value pairs for the information, to make debugging easier. Uncertainpy always uses a single dictionary as the info object. Certain features require that specific keys are present in this dictionary.

The model itself does not need to be implemented in Python. Any simulator can be used, as long as we can control the model parameters and retrieve the simulation output via Python. We can as a shortcut pass a model function to the model argument in UncertaintyQuantification, instead of first having to create a Model instance.

Defining a postprocess function¶

The postprocess function is used to postprocess the model output before it is used in the uncertainty quantification. Postprocessing does not change the model output sent to the feature calculations. This is useful if we need to transform the model output This is useful if we need to transform the model output to a regular result for the uncertainty quantification, but still need to preserve the original model output to reliably detect the model features.

This figure illustrates how the objects returned by the model function are sent to both model postprocess, and feature preprocess (see Features). Functions associated with the model are in red while functions associated with features are in green.

An example outline of the postprocess function is:

def example_postprocess(time, values, info):
    # Postprocess the result to a regular form using time,
    # values, and info returned by the model function.

    # Return the postprocessed model output and time.
    return time_postprocessed, values_postprocessed

The only time postprocessing is required for Uncertainpy to work, is when the model produces output that can not be interpolated to a regular form by Uncertainpy. Postprocessing is for example required for network models that give output in the form of spike trains, i.e. time values indicating when a given neuron fires. It should be noted that postprocessing of spike trains is already implemented in Uncertainpy, in the NestModel. For most purposes user defined postprocessing will not be necessary.

The requirements for the postprocess function are:

Input. postprocess must take the objects returned by the model function as input arguments.

Postprocessing. The model time (time) and output (values) must be postprocessed to a regular form, or to a form that can be interpolated to a regular form by Uncertainpy. If additional information is needed from the model, it can be passed along in the info object.

Output. The postprocess function must return two objects:

Model time (time_postprocessed). The first object is the postprocessed time (or equivalent) of the model. We can return None if the model has no time. Note that the automatic interpolation of the postprocessed time can only be performed if a postprocessed time is returned (if an interpolation is required).

Model output (values_postprocessed). The second object is the postprocessed model output.

API Reference¶

class uncertainpy.models.Model(run=None, interpolate=False, labels=[], postprocess=None, ignore=False, suppress_graphics=False, logger_level=u'info', **model_kwargs)[source]¶

Class for storing the model to perform uncertainty quantification and sensitivity analysis on.

The run method must either be implemented or set to a function, and is responsible for running the model. If you want to calculate features directly from the original model results, but still need to postprocess the model results to perform the uncertainty quantification, you can implement the postprocessing in the postprocess method.

Parameters:

run ({None, callable}, optional) – A function that implements the model. See the run method for requirements of the function. Default is None.
interpolate (bool, optional) – True if the model is irregular, meaning it has a varying number of return values between different model evaluations, and an interpolation of the results is performed. Default is False.
labels (list, optional) – A list of label names for the axes when plotting the model. On the form ["x-axis", "y-axis", "z-axis"], with the number of axes that is correct for the model output. Default is an empty list.
postprocess ({None, callable}, optional) – A function that implements the postprocessing of the model. See the postprocess method for requirements of the function. Default is None.
ignore (bool, optional) – Ignore the model results when calculating uncertainties, which means the uncertainty is not calculated for the model. Default is False.
suppress_graphics (bool, optional) – Suppress all graphics created by the model. Default is False.
logger_level ({“info”, “debug”, “warning”, “error”, “critical”, None}, optional) – Set the threshold for the logging level. Logging messages less severe than this level is ignored. If None, no logging to file is performed. Default logger level is “info”.
**model_kwargs – Any number of arguments passed to the model function when it is run.

Variables:

labels (list) – A list of label names for the axes when plotting the model. On the form ["x-axis", "y-axis", "z-axis"], with the number of axes that is correct for the model output.
interpolate (bool) – True if the model is irregular, meaning it has a varying number of return values between different model evaluations, and an interpolation of the results is performed. Default is False.
name (str) – Name of the model. Either the name of the class or the name of the function set as run.
suppress_graphics (bool) – Suppress all graphics created by the model.
ignore (bool) – Ignore the model results when calculating uncertainties, which means the uncertainty is not calculated for the model. The model results are still postprocessed if a postprocessing is implemented. Default is False.

evaluate(**parameters)[source]¶

Run the model with parameters and default model_kwargs options, and validate the result.

Parameters: **parameters (A number of named arguments (name=value).) – The parameters of the model. These parameters must be assigned to the model, either setting them with Python, or assigning them to the simulator.

Returns:

time ({None, numpy.nan, array_like}) – Time values of the model, if no time values returns None or numpy.nan.
values (array_like) – Result of the model. Note that values myst either be regular (have the same number of points for different paramaters) or be able to be interpolated.
info, optional – Any number of info objects that is passed on to feature calculations. It is recommended to use a single dictionary with the information stored as key-value pairs. This is what the implemented features requires, as well as require that specific keys to be present.

See also

uncertainpy.models.Model.run(): Requirements for the model run function.

postprocess¶

Postprocessing of the time and results from the model.

No postprocessing is performed, and the direct model results are currently returned. If postprocessing is needed it should follow the below format.

Parameters:

*model_result – Variable length argument list. Is the values that run returns. It contains time and values, and then any number of optional info values.
time ({None, numpy.nan, array_like}) – Time values of the model. If no time values the model should return None or numpy.nan.
values (array_like) – Result of the model.
info, optional – Any number of info objects that is passed on to feature calculations. It is recommended to use a single dictionary with the information stored as key-value pairs. This is what the implemented features requires, as well as require that specific keys to be present.

Returns:

time ({None, numpy.nan, array_like}) – Time values of the model, if no time values returns None or numpy.nan.
values (array_like) – The postprocessed model results, values must either be regular (have the same number of points for different paramaters) or be able to be interpolated.

Notes

Perform a postprocessing of the model results before they are sent to the uncertainty quantification. The model results must either be regular or be able to be interpolated. This is because the uncertainty quantification methods needs results with the same number of points for each set of parameters to be able to perform the uncertainty quantification.

postprocess is implemented to make the model results regular, or on a form that can be interpolated. The results from the postprocessing is not used to calculate features, and is therefore used if you want to calculate features directly from the original model results, but still need to postprocess the model results to perform the uncertainty quantification.

The requirements for a postprocess function are:

Input. postprocess must take the objects returned by the model function as input arguments.
Postprocessing. The model time (time) and output (values) must be postprocessed to a regular form, or to a form that can be interpolated to a regular form by Uncertainpy. If additional information is needed from the model, it can be passed along in the info object.
Output. The postprocess function must return two objects:
1. Model time (time_postprocessed). The first object is the postprocessed time (or equivalent) of the model. We can return None if the model has no time. Note that the automatic interpolation of the postprocessed time can only be performed if a postprocessed time is returned (if an interpolation is required).
2. Model output (values_postprocessed). The second object is the postprocessed model output.

run¶

Run the model and return time and model result.

This method must either be implemented or set to a function and is responsible for running the model. See Notes for requirements.

Parameters:	*parameters (A number of named arguments (name=value).*) – The parameters of the model. These parameters must be assigned to the model, either setting them with Python, or assigning them to the simulator.
Returns:	time ({None, numpy.nan, array_like}) – Time values of the model, if no time values returns None or numpy.nan. values (array_like) – Result of the model. Note that values myst either be regular (have the same number of points for different paramaters) or be able to be interpolated. info, optional – Any number of info objects that is passed on to feature calculations. It is recommended to use a single dictionary with the information stored as key-value pairs. This is what the implemented features requires, as well as require that specific keys to be present.
Raises:	`NotImplementedError` – If no run method have been implemented or set to a function.

Notes

The run method must either be implemented or set to a function. Both options have the following requirements:

Input. The model function takes a number of arguments which define the uncertain parameters of the model.
Run the model. The model must then be run using the parameters given as arguments.
Output. The model function must return at least two objects, the model time (or equivalent, if applicable) and model output. Additionally, any number of optional info objects can be returned. In Uncertainpy, we refer to the time object as time, the model output object as values, and the remaining objects as info. Note that while we refer to these objects as time, values and info in Uncertainpy, it does not matter what you call the objects returned by the run function.
1. Time (time). The time can be interpreted as the x-axis of the model. It is used when interpolating (see below), and when certain features are calculated. We can return None if the model has no time associated with it.
2. Model output (values). The model output must either be regular, or it must be possible to interpolate or postprocess the output to a regular form.
3. Additional info (info). Some of the methods provided by Uncertainpy, such as the later defined model postprocessing, feature preprocessing, and feature calculations, require additional information from the model (e.g., the time a neuron receives an external stimulus). We recommend to use a single dictionary as info object, with key-value pairs for the information, to make debugging easier. Uncertainpy always uses a single dictionary as the info object. Certain features require that specific keys are present in this dictionary.

The model does not need to be implemented in Python, you can use any model/simulator as long as you are able to set the model parameters of the model from the run method Python and return the results from the model into the run method.

If you want to calculate features directly from the original model results, but still need to postprocess the model results to perform the uncertainty quantification, you can implement the postprocessing in the postprocess method.

See also

uncertainpy.features

uncertainpy.features.Features.preprocess: Preprocessing of model results before feature calculation
uncertainpy.model.Model.postprocess: Postprocessing of model result.

set_parameters(**parameters)[source]¶

Set all named arguments as attributes of the model class.

Parameters:	*parameters (A number of named arguments (name=value).*) – All set as attributes of the class.

validate_postprocess(postprocess_result)[source]¶

Validate the results from postprocess.

This method ensures that postprocess returns time and values.

Parameters:	model_results – Any type of postprocessed model results returned by `postprocess`.
Raises:	`ValueError` – If the postprocessed model result does not fit the requirements. `TypeError` – If the postprocessed model result does not fit the requirements.

Notes

Tries to verify that time and values are returned from postprocess. postprocess must return two objects on the format: return time, values, where:

time_postprocessed : {None, numpy.nan, array_like}.

The first object is the postprocessed time (or equivalent) of the model. We can return None if the model has no time. Note that the automatic interpolation of the postprocessed time can only be performed if a postprocessed time is returned (if an interpolation is required).
values_postprocessed : array_like.

The second object is the postprocessed model output.

Both of these must be regular or on a form that can be interpolated.

validate_run(model_result)[source]¶

Validate the results from run.

This method ensures run returns time, values, and optional info objects.

Parameters:	model_results – Any type of model results returned by `run`.
Raises:	`ValueError` – If the model result does not fit the requirements. `TypeError` – If the model result does not fit the requirements.

Notes

Tries to verify that at least, time and values are returned from run. model_result should follow the format: return time, values, info_1, info_2, .... Where:

time : {None, numpy.nan, array_like}. Time values of the model. If no time values it should return None or numpy.nan.
values : array_like Result of the model.
info, optional. Any number of info objects that is passed on to feature calculations. It is recommended to use a single dictionary with the information stored as key-value pairs. This is what the implemented features requires, as well as require that specific keys to be present.

See also

uncertainpy.models.Model.run()