swarmsim.metrics.JinjaMetric#

class swarmsim.metrics.JinjaMetric(name='JinjaMetric', history=None, metric=None, metrics=None, template=None, expression=None, eval_condition=None, save_condition=None, default='__unset__', default_aggregation=None)[source]#

Combine multiple metrics programmatically using a Jinja expression.

Evaluation Order on JinjaMetric.calculate():

  1. Evaluate the template and eval_condition and return if False.

  2. Call Metric.calculate() on the submetrics.

  3. Render the template and save the context.

  4. Evaluate the expression.

  5. Evaluate the save_condition and return if False.

  6. Call Metric.set_value().

You may reference self, world, metric, and metrics in the template, expression, eval_condition, and save_condition.. Additionally, any variables set in the template will be available in the expressions.

Note that metrics in world.metrics are calculated in order (i.e. the order specified/added). Thus, any metrics before this JinjaMetric will be up-to-date when this metric is calculated, but any metrics ordered afterwards may be at least one time step behind.

Parameters:

  • name (str) – The name of the JinjaMetric.

  • metric (Metric | dict) – A Metric or a dict that can be used to initialize a Metric. Not added to world.metrics. Can be referenced as self.metric or metric in the Jinja expression.

  • metrics (Iterable[Metric | dict]) – Additional metrics to use in the Jinja expression. Not added to world.metrics. This becomes a list which can be referenced as self.metrics or metrics in the Jinja expression.

  • template (str) – A Jinja template that can be used to set variables that can be used in the expression. The rendered result of the template is not used. The template is always evaluated, so variables exported can be used in expression, eval_condition, and save_condition.

  • expression (str) – The Jinja expression to use. The return value becomes the value of the metric.

  • eval_condition (Callable | str | None) – A Callable or Jinja expression that evaluates to a boolean. If the condition evaluates to False, the submetrics and self.expression will not be evaluated. If None, the Jinja expression will always be evaluated.

  • save_condition (Callable | str | None) – A Callable or Jinja expression that evaluates to a boolean. If the condition evaluates to False, self.set_value will not be called and the result of self.expression will not be saved. If None, the metric will always be saved.

  • default (Any, default='__unset__') – The initial value of the metric. If '__unset__', the value will be inherited from Metric.

  • default_aggregation (str) – The default aggregation to use for the metric.

Attributes:
average
default_aggregation
module
value

Methods

as_config_dict

attach_world

calculate

calculate_submetrics

draw

eval_template

make_module

out_average

out_current

reset

set_value

setup_submetrics
__init__(name='JinjaMetric', history=None, metric=None, metrics=None, template=None, expression=None, eval_condition=None, save_condition=None, default='__unset__', default_aggregation=None)[source]#

Methods

__init__([name, history, metric, metrics, ...])

as_config_dict()

attach_world(world)

calculate()

calculate_submetrics()

draw(screen[, zoom])

eval_template(expression)

make_module(**kwargs)

out_average()

out_current()

reset()

set_value(value)

setup_submetrics()

Attributes

average

default_aggregation

module

value